Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix(cli): timeline lists clips nested in a timed element and lint flags ones that never show (#5732)
Miguel Ángeleab6ca15b1af
diff --git a/docs/reference/lint-rules.mdx b/docs/reference/lint-rules.mdxindex 4a099df1a4..150a7e3c26 100644--- a/docs/reference/lint-rules.mdx+++ b/docs/reference/lint-rules.mdx@@ -20,7 +20,8 @@ Severities:Source: `packages/lint/src/rules/structure.ts`.-The four codes marked **Warning or error** are warnings when the CLI lints a project, and errors when Studio lints the file it is editing.+The five codes marked **Warning or error** are warnings when the CLI lints a project, and errors when Studio+lints the file it is editing.### `nested_structure_needs_subcomposition`@@ -52,6 +53,15 @@ The four codes marked **Warning or error** are warnings when the CLI lints a pro**Fix:** Extend the root `data-duration`, or make the clip end at or before it.+### `nested_clip_never_visible`++**Warning or error.** A timed clip sits inside another timed element, and its time window never overlaps that+element's, so it never appears. A nested clip's `data-start` counts from the composition's start, not from the+element around it. Runs in sub-composition files too.++**Fix:** Give the clip a `data-start` inside its parent's window, in composition time, or move it out of the+parent.+## Composition contractSource: `packages/lint/src/rules/composition.ts`.diff --git a/packages/cli/src/audio/analysis/targets.test.ts b/packages/cli/src/audio/analysis/targets.test.tsindex cefc9b442f..1e02812ed2 100644--- a/packages/cli/src/audio/analysis/targets.test.ts+++ b/packages/cli/src/audio/analysis/targets.test.ts@@ -20,6 +20,7 @@ function row(host: null,hostRow: null,children: [],+ parentRow: null,trackIndex: 0,src: "audio/a.wav",sourceFile: null,diff --git a/packages/cli/src/timeline/a2Shared.ts b/packages/cli/src/timeline/a2Shared.tsindex 44ddd5e6d2..44bab9d666 100644--- a/packages/cli/src/timeline/a2Shared.ts+++ b/packages/cli/src/timeline/a2Shared.ts@@ -137,6 +137,19 @@ export function diff(before: string, after: string): string {return output.length <= 8_000 ? output : `${output.slice(0, 7_997)}...`;}+function isAncestorOf(ancestor: TimelineRow, row: TimelineRow, timeline: ProjectTimeline): boolean {+ for (let pointer = row.parentRow; pointer; ) {+ const parent = rowAt(timeline, pointer);+ if (parent === ancestor) return true;+ pointer = parent.parentRow;+ }+ return false;+}++function sameLineage(a: TimelineRow, b: TimelineRow, timeline: ProjectTimeline): boolean {+ return isAncestorOf(a, b, timeline) || isAncestorOf(b, a, timeline);+}+function overlap(row: TimelineRow,timeline: ProjectTimeline,@@ -146,6 +159,7 @@ function overlap(return allRows(timeline).find((candidate) =>candidate !== row &&+ !sameLineage(candidate, row, timeline) &&candidate.file === row.file &&candidate.trackIndex === row.trackIndex &&spansShareTime(start, end, candidate.start, candidate.end),@@ -429,6 +443,7 @@ export function mutationConflict(if (verb === "duplicate") {const conflict = allRows(timeline).find((candidate) =>+ !sameLineage(candidate, row, timeline) &&candidate.file === row.file &&candidate.trackIndex === row.trackIndex &&isInsideSpan(nextStart, candidate.start, candidate.end),diff --git a/packages/cli/src/timeline/describeProject.inPoint.test.ts b/packages/cli/src/timeline/describeProject.inPoint.test.tsindex 1caf194d04..79b95c3cd1 100644--- a/packages/cli/src/timeline/describeProject.inPoint.test.ts+++ b/packages/cli/src/timeline/describeProject.inPoint.test.ts@@ -18,12 +18,12 @@ const SCENE = `<template id="scene-template"><div data-composition-id="scene" dabeforeAll(ensureDOMParser);/** The video rows of a project made of `index` and `compositions/scene.html`. */-async function videoRows(index: string, prefix: string) {+async function videoRows(index: string, prefix: string, scene = SCENE) {const dir = mkdtempSync(join(tmpdir(), prefix));onTestFinished(() => rmSync(dir, { recursive: true, force: true }));mkdirSync(join(dir, "compositions"));writeFileSync(join(dir, "index.html"), index);- writeFileSync(join(dir, "compositions", "scene.html"), SCENE);+ writeFileSync(join(dir, "compositions", "scene.html"), scene);const timeline = await describeProject(join(dir, "index.html"));return timeline.tracks.find((t) => t.kind === "video")!.rows;}@@ -43,6 +43,17 @@ describe("a sub-composition's in-point", () => {]);});+ it("cuts a clip nested in a timed wrapper like the wrapper's own clips", async () => {+ const videos = await videoRows(+ `<div data-composition-id="main" data-duration="9"><div data-playback-start="5" id="half" data-composition-src="compositions/scene.html" data-start="5" data-duration="4"></div></div>`,+ "hf-timeline-inpoint-nested-",+ `<div data-composition-id="scene" data-duration="12"><div id="w" data-start="0" data-duration="12">+<video id="n" src="../sample.mp4" muted data-start="4" data-duration="4" data-media-start="5"></video></div></div>`,+ );++ expect(videos.map((r) => [r.id, r.absStart, r.absEnd, r.mediaStart])).toEqual([["n", 5, 8, 6]]);+ });+it("moves each cut clip's media in-point by the part the cut skips", async () => {const videos = await videoRows(SPLIT_INDEX, "hf-timeline-inpoint-media-");diff --git a/packages/cli/src/timeline/describeProject.test.ts b/packages/cli/src/timeline/describeProject.test.tsindex 586fb1b6c9..2585a110ca 100644--- a/packages/cli/src/timeline/describeProject.test.ts+++ b/packages/cli/src/timeline/describeProject.test.ts@@ -116,6 +116,44 @@ describe("describeProject", () => {]);});+ it("lists clips nested in a timed wrapper at their playback time and says when one never shows", async () => {+ const { rows, text } = await rowsOf(`<html><body>+<div data-composition-id="main" data-width="1920" data-height="1080" data-duration="10">+ <div id="shot2" data-start="5" data-duration="5" data-track-index="0">+ <h1 id="seen" data-start="6" data-duration="2">In</h1>+ <h1 id="lost" data-start="0" data-duration="2">Out</h1>+ </div>+</div></body></html>`);+ const byId = (id: string) => rows.find((r) => r.id === id)!;+ const at = (p: { kind: string; index: number }) =>+ rows.find((r) => r.trackKind === p.kind && r.index === p.index)!.id;++ expect(byId("shot2").children.map(at).sort()).toEqual(["lost", "seen"]);+ expect(byId("seen")).toMatchObject({ absStart: 6, absEnd: 8, warnings: [], nested: false });+ expect(at(byId("seen").parentRow!)).toBe("shot2");+ expect(byId("lost").warnings).toEqual([+ "never visible: plays 0-2s, but #shot2 only shows 5-10s; a nested data-start counts from the composition, not from #shot2",+ ]);+ expect(text).toContain("#lost lost 0-2s warning: never visible");+ expect(text).not.toContain("no stable name");+ });++ it("lists a sub-composition mounted inside a timed wrapper with every clip it holds", async () => {+ const { rows } = await rowsOf(`<html><body>+<div data-composition-id="main" data-width="1920" data-height="1080" data-duration="10">+ <div id="shot" data-start="0" data-duration="5" data-track-index="0">+ <div id="scene" data-composition-src="compositions/title.html" data-start="0" data-duration="5"></div>+ </div>+</div></body></html>`);+ const childIds = (id: string) =>+ rows+ .find((r) => r.id === id)!+ .children.map((p) => rows.find((r) => r.trackKind === p.kind && r.index === p.index)?.id);++ expect(childIds("shot")).toEqual(["scene"]);+ expect(childIds("scene")).toEqual(["t1", "t2"]);+ });+it("reports each half's out-of-sync offset from its source pair, at the project fps", async () => {const { rows, text } = await rowsOf(`<html><body><div data-composition-id="main" data-duration="10" data-fps="24">diff --git a/packages/cli/src/timeline/describeProject.ts b/packages/cli/src/timeline/describeProject.tsindex efffc30bb0..cfb356b76e 100644--- a/packages/cli/src/timeline/describeProject.ts+++ b/packages/cli/src/timeline/describeProject.ts@@ -19,6 +19,7 @@ import {type MediaTag,} from "@hyperframes/parsers/media-duration";import {+ isSubCompositionHost,topLevelElements,trackKindOf,type StructureNode,@@ -67,8 +68,10 @@ export interface TimelineRow extends ClipFact {host: string | null;/** Where that host row is (its kind's `rows[index]`), for hosts whose id is missing or repeated. */hostRow: RowPointer | null;- /** Where this row's sub-composition clips are (one level only); each is a full row in its kind's `rows`. */+ /** Rows directly inside this one: its sub-composition's clips, or timed elements nested in it. */children: RowPointer[];+ /** The timed row in the same file that contains this clip; `null` at a file's top level. */+ parentRow: RowPointer | null;/** Signed frames from its `data-sync-origin` partner (+ = late); `null` unpaired or rates differ. */syncOffsetFrames: number | null;mediaStart: number | null;@@ -80,10 +83,14 @@ export interface RowPointer {}/** A row before flattening: children are still row objects and refs are not assigned. */-type ClipDraft = Omit<TimelineRow, "index" | "nested" | "host" | "hostRow" | "children"> & {+type ClipDraft = Omit<+ TimelineRow,+ "index" | "nested" | "host" | "hostRow" | "children" | "parentRow"+> & {elementId: string | null;hfId: string | null;children: ClipDraft[];+ inside: ClipDraft[];};export interface TimelineTrack {@@ -276,6 +283,7 @@ interface RowTiming {authored: number | null;absStart: number;children: ClipDraft[];+ inside: ClipDraft[];duration: DurationResolution;}@@ -291,11 +299,14 @@ async function resolveRowTiming(scope: DocScope, node: DomNode, depth: number):host && depth === 0? await readSubComposition(host, scope, compositionOriginSeconds(absStart, el), slots): [];+ const inside = isSubCompositionHost(node)+ ? []+ : await Promise.all(topLevelElements(node).map((inner) => describeRow(scope, inner, depth)));const kind = el.tagName.toLowerCase();const duration = MEDIA_TAG.test(kind)? await resolveMediaRowDuration(scope, el, kind as MediaTag, authored): resolveContainerDuration(authored, children);- return { start, authored, absStart, children, duration };+ return { start, authored, absStart, children, inside, duration };}function describeRowFields(scope: DocScope, node: DomNode, timing: RowTiming): ClipDraft {@@ -326,6 +337,7 @@ function describeRowFields(scope: DocScope, node: DomNode, timing: RowTiming): CdurationSource: timing.duration.durationSource,pendingReason: timing.duration.pendingReason,children: timing.children,+ inside: timing.inside,ref: "",warnings: [],elementId: el.id || null,@@ -384,7 +396,8 @@ function cutRow(row: ClipDraft, slots: readonly HostSlot[]): ClipDraft[] {if (kept.end === kept.start && row.absEnd > row.absStart) return [];const skipped = (kept.start - row.absStart) * (row.playbackRate ?? 1);const mediaStart = row.mediaStart === null ? null : roundMs(row.mediaStart + skipped);- return [{ ...row, absStart: roundMs(kept.start), absEnd: roundMs(kept.end), mediaStart }];+ const inside = row.inside.flatMap((inner) => cutRow(inner, slots));+ return [{ ...row, absStart: roundMs(kept.start), absEnd: roundMs(kept.end), mediaStart, inside }];}/** The file's real path when it is a regular file inside the project (symlinks resolved), else null. */@@ -401,10 +414,14 @@ function realFileInside(projectDir: string, path: string): string | null {/** One flat, `absStart`-ordered list per kind holding every clip once; `children` become refs into those lists. */function flatten(top: ClipDraft[]): TimelineTrack[] {- const entries = [- ...top.map((clip) => ({ clip, host: null })),- ...top.flatMap((host) => host.children.map((clip) => ({ clip, host }))),- ];+ type Entry = { clip: ClipDraft; host: ClipDraft | null; parent: ClipDraft | null };+ const entries: Entry[] = [];+ const add = (clip: ClipDraft, host: ClipDraft | null, parent: ClipDraft | null) => {+ entries.push({ clip, host, parent });+ for (const inner of clip.inside) add(inner, host, clip);+ for (const child of clip.children) add(child, clip, null);+ };+ for (const clip of top) add(clip, null, null);const byKind = TRACK_ORDER.map((kind) => ({kind,entries: entries@@ -426,19 +443,21 @@ function flatten(top: ClipDraft[]): TimelineTrack[] {}return byKind.map(({ kind, entries: kindEntries }) => ({kind,- rows: kindEntries.map(({ clip, host }, index) => {+ rows: kindEntries.map(({ clip, host, parent }, index) => {const uniqueId = clip.elementId && fileIds.get(clip.file)?.get(clip.elementId) === 1;const ref = uniqueId? `#${clip.elementId}`: clip.hfId? `hf:${clip.hfId}`: `${kind}/${index}`;- const warnings =- uniqueId || clip.hfId+ const warnings = [+ ...(uniqueId || clip.hfId? []: ['row has no stable name; add id="<name>" to the element in this file, then retry with #<name>',- ];+ ]),+ ...neverVisibleWarning(clip, parent),+ ];return {...clip,index,@@ -447,12 +466,26 @@ function flatten(top: ClipDraft[]): TimelineTrack[] {nested: host !== null,host: host && host.id,hostRow: host && at(host),- children: clip.children.map(at),+ children: [...clip.children, ...clip.inside].map(at),+ parentRow: parent && at(parent),};}),}));}+/** The runtime shows a nested clip only inside its parent's window, and its data-start counts from the composition. */+export const NEVER_VISIBLE = "never visible";++function neverVisibleWarning(clip: ClipDraft, parent: ClipDraft | null): string[] {+ if (!parent || clip.kind === "audio") return [];+ if (clip.absEnd <= clip.absStart || parent.absEnd <= parent.absStart) return [];+ if (clip.absEnd > parent.absStart && clip.absStart < parent.absEnd) return [];+ const name = parent.elementId ? `#${parent.elementId}` : `its parent <${parent.kind}>`;+ return [+ `${NEVER_VISIBLE}: plays ${clip.absStart}-${clip.absEnd}s, but ${name} only shows ${parent.absStart}-${parent.absEnd}s; a nested data-start counts from the composition, not from ${name}`,+ ];+}+function projectFps(source: string): number {const parsed = parseFpsWithDefault(readCompositionFps(source) ?? undefined);return fpsToNumber(parsed.ok ? parsed.value : { num: 30, den: 1 });diff --git a/packages/cli/src/timeline/formatTimeline.ts b/packages/cli/src/timeline/formatTimeline.tsindex 99481dac0f..564436dfc2 100644--- a/packages/cli/src/timeline/formatTimeline.ts+++ b/packages/cli/src/timeline/formatTimeline.ts@@ -1,4 +1,9 @@-import type { ProjectTimeline, TimelineRow, TimelineTrack } from "./describeProject.js";+import {+ NEVER_VISIBLE,+ type ProjectTimeline,+ type TimelineRow,+ type TimelineTrack,+} from "./describeProject.js";const BAR_WIDTH = 40;const n = (v: number) => String(Math.round(v * 1000) / 1000);@@ -48,6 +53,7 @@ function details(row: TimelineRow): string {row.sourceFile && !row.children.length && "children=unread",row.laneError && `lanes unreadable: ${row.laneError}`,...lanes,+ ...row.warnings.filter((w) => w.startsWith(NEVER_VISIBLE)).map((w) => `warning: ${w}`),].filter(Boolean).join(" ");@@ -63,7 +69,7 @@ function line(row: TimelineRow, total: number): string {}function header({ kind, rows }: TimelineTrack): string {- const nested = rows.filter((r) => r.nested).length;+ const nested = rows.filter((r) => r.nested || r.parentRow).length;const split = nested ? `: ${rows.length - nested} top-level, ${nested} nested` : "";return `${kind} (${rows.length}${split})`;}diff --git a/packages/cli/src/timeline/timeExpr.test.ts b/packages/cli/src/timeline/timeExpr.test.tsindex dadc9eed52..363579f8f2 100644--- a/packages/cli/src/timeline/timeExpr.test.ts+++ b/packages/cli/src/timeline/timeExpr.test.ts@@ -20,6 +20,7 @@ const row: TimelineRow = {host: null,hostRow: null,children: [],+ parentRow: null,trackIndex: 0,src: null,sourceFile: null,diff --git a/packages/cli/src/timeline/timeline.e2e.test.ts b/packages/cli/src/timeline/timeline.e2e.test.tsindex 5055690b7a..feec81d936 100644--- a/packages/cli/src/timeline/timeline.e2e.test.ts+++ b/packages/cli/src/timeline/timeline.e2e.test.ts@@ -248,6 +248,27 @@ describe("timeline edit command", () => {};const endOf = (html: string, id: string) =>Number(clip(html, id).start) + Number(clip(html, id).duration);++ it.each([+ ["moves a hidden clip into its wrapper's window", ["move", "#lost", "8"], "lost", "8"],+ ["moves a wrapper without colliding with its own clips", ["move", "#shot2", "4"], "shot2", "4"],+ ["duplicates a clip inside its wrapper", ["duplicate", "#seen"], "seen", "6"],+ ])("%s", (_name, args, id, start) => {+ const dir = mkdtempSync(join(tmpdir(), "hf-timeline-nested-"));+ writeFileSync(+ join(dir, "index.html"),+ `<div data-composition-id="main" data-duration="12"><div id="shot2" data-hf-id="shot2" data-start="5" data-duration="5" data-track-index="0"><div id="seen" data-hf-id="seen" data-start="6" data-duration="2">In</div><div id="lost" data-hf-id="lost" data-start="0" data-duration="2">Out</div></div></div>`,+ );+ try {+ const result = run(dir, ...args);+ expect(result.stderr).not.toContain("overlap");+ expect(result.status).toBe(0);+ expect(clip(readFileSync(join(dir, "index.html"), "utf8"), id).start).toBe(start);+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+ });+const visibleAt = (html: string, time: number, ids: string[]) =>ids.filter((id) => isClipVisibleAt(time, Number(clip(html, id).start), endOf(html, id), 40));diff --git a/packages/lint/src/rules/structure.catalog.test.ts b/packages/lint/src/rules/structure.catalog.test.tsindex 686308a956..dd6ac4ca4a 100644--- a/packages/lint/src/rules/structure.catalog.test.ts+++ b/packages/lint/src/rules/structure.catalog.test.ts@@ -10,6 +10,7 @@ const STRUCTURE_CODES = new Set(["caption_track_kind_missing","multiple_caption_tracks","clip_ends_past_root_duration",+ "nested_clip_never_visible",]);function htmlFiles(dir: string): string[] {diff --git a/packages/lint/src/rules/structure.test.ts b/packages/lint/src/rules/structure.test.tsindex e08fcd5789..618e102726 100644--- a/packages/lint/src/rules/structure.test.ts+++ b/packages/lint/src/rules/structure.test.ts@@ -15,10 +15,34 @@ const STRUCTURE = new Set(["caption_track_kind_missing","multiple_caption_tracks","clip_ends_past_root_duration",+ "nested_clip_never_visible",]);const has = (found: Awaited<ReturnType<typeof codes>>, code: string) =>found.some((f) => f.code === code);+describe("nested_clip_never_visible", () => {+ const shot = (clipStart: number) =>+ `<div id="shot2" class="clip" data-start="5" data-duration="5"><video id="v1" class="clip" src="a.mp4" data-start="${clipStart}" data-duration="2"></video></div>`;+ const neverVisible = (found: Awaited<ReturnType<typeof codes>>) =>+ found.filter((f) => f.code === "nested_clip_never_visible");++ it("flags a nested clip whose window misses its parent's", async () => {+ const [finding] = neverVisible(await codes(shot(0)));+ expect(finding).toMatchObject({ elementId: "v1", severity: "warning" });+ expect(finding?.message).toContain("only shows from 5s to 10s");+ });+ it("leaves a nested clip that plays inside its parent's window", async () => {+ expect(neverVisible(await codes(shot(6)))).toEqual([]);+ });+ it("leaves nested audio alone: it plays whether or not its parent shows", async () => {+ const body = `<div id="shot2" class="clip" data-start="5" data-duration="5"><audio id="a1" class="clip" src="a.mp3" data-start="0" data-duration="2"></audio></div>`;+ expect(neverVisible(await codes(body))).toEqual([]);+ });+ it("checks sub-composition files too", async () => {+ expect(neverVisible(await codes(shot(0), { isSubComposition: true }))).toHaveLength(1);+ });+});+describe("nested_structure_needs_subcomposition", () => {it("flags a timed div that contains another div", async () => {const found = await codes(diff --git a/packages/lint/src/rules/structure.ts b/packages/lint/src/rules/structure.tsindex 7479bf5505..6b37443a51 100644--- a/packages/lint/src/rules/structure.ts+++ b/packages/lint/src/rules/structure.ts@@ -61,6 +61,7 @@ const NODE_ATTRS = ["data-track-kind","data-composition-id","data-composition-src",+ "data-hf-media-start-basis",];function toNode(open: OpenTag): TagNode {@@ -193,6 +194,40 @@ function clipsPastRootFindings(root: TagNode, rows: TagNode[]): HyperframeLintFi});}+function followsParentVisibility(clip: TagNode): boolean {+ return clip.tag !== "audio" && clip.attrs["data-hf-media-start-basis"] !== "global";+}++function isTimed(timing: {+ start: number | null;+ end: number | null;+}): timing is { start: number; end: number } {+ return timing.start !== null && timing.end !== null;+}++/** The runtime shows a nested clip only while its parent shows, and both data-starts count from the composition. */+function neverVisibleNestedFindings(parent: TagNode, severity: Severity): HyperframeLintFinding[] {+ const window = readClipTiming({ getAttribute: (name) => parent.attrs[name] ?? null });+ return topLevelElements(parent).flatMap((clip) => {+ const inner = isSubCompositionHost(clip) ? [] : neverVisibleNestedFindings(clip, severity);+ const own = readClipTiming({ getAttribute: (name) => clip.attrs[name] ?? null });+ if (!followsParentVisibility(clip) || !isTimed(window) || !isTimed(own)) return inner;+ if (own.end > window.start && own.start < window.end) return inner;+ const shows = `${hundredths(window.start)}s to ${hundredths(window.end)}s`;+ return [+ {+ code: "nested_clip_never_visible",+ severity,+ message: `${describe(clip)} plays from ${hundredths(own.start)}s to ${hundredths(own.end)}s, but it sits inside ${describe(parent)}, which only shows from ${shows}, so it never appears. A nested data-start counts from the composition's start, not from ${describe(parent)}.`,+ elementId: clip.attrs.id,+ fixHint: `Give ${describe(clip)} a data-start between ${shows} in composition time, or move it out of ${describe(parent)}.`,+ snippet: truncateSnippet(clip.open.raw),+ },+ ...inner,+ ];+ });+}+export const structureRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [(ctx) => {// The timeline shows the root composition's rows; a sub-composition file is the leaf where layout lives.@@ -208,4 +243,12 @@ export const structureRules: Array<(ctx: LintContext) => HyperframeLintFinding[]...clipsPastRootFindings(root, rows),];},+ (ctx) => {+ const root = buildTree(ctx);+ if (!root) return [];+ const severity = ctx.options.host === "studio" ? "error" : "warning";+ return topLevelElements(root)+ .filter((row) => !isSubCompositionHost(row))+ .flatMap((row) => neverVisibleNestedFindings(row, severity));+ },];diff --git a/skills-manifest.json b/skills-manifest.jsonindex a877996429..b35d232477 100644--- a/skills-manifest.json+++ b/skills-manifest.json@@ -34,7 +34,7 @@"files": 11},"hyperframes-core": {- "hash": "010a65915fc7b45e",+ "hash": "66fc3e623a910923","files": 11},"hyperframes-creative": {diff --git a/skills/hyperframes-core/SKILL.md b/skills/hyperframes-core/SKILL.mdindex 97e68da11f..3f6c6d1cd4 100644--- a/skills/hyperframes-core/SKILL.md+++ b/skills/hyperframes-core/SKILL.md@@ -87,6 +87,9 @@ Surfaced here; full rationale in the linked reference. Do not violate:- Match existing composition IDs and timeline keys.- Adding a clip: set its `data-start`/`data-duration` intentionally against the clips around it. `data-track-index` is a Studio display lane, not a timing constraint, so it does not need to be free.- A clip that ends past the root `data-duration` is cut off: extend the root `data-duration` to the clip's end in the same edit (`lint` warns `clip_ends_past_root_duration`).+- A clip nested inside another timed element counts its `data-start` from the composition, not from that+ element, and shows only while that element shows. `timeline` lists it under its parent and warns+ `never visible` when the windows miss (`lint` reports `nested_clip_never_visible`).- `data-hidden` on any composition element hides it in BOTH preview and render, overriding its time window; it is non-destructive/reversible and toggled by Studio's timeline eye icon.- Adding a sub-composition: verify its internal `data-composition-id` before wiring the host.