Skip to content

Commit eab6ca1

Browse files
fix(cli): timeline lists clips nested in a timed element and lint flags ones that never show (#5732)
* fix(cli): timeline lists clips nested in a timed element and lint flags ones that never show * docs(lint): wrap the nested-clip entries * docs(skills): format the nested-clip note and refresh the skills manifest * fix(cli): keep timeline edits from colliding with a clip's own wrapper * fix(cli): cut clips nested in a wrapper at their sub-composition's in-point * refactor(lint): split the nested-clip visibility checks to keep the audit green * style(cli): restore the timeline test's formatting
1 parent 4e6ee6d commit eab6ca1

14 files changed

Lines changed: 226 additions & 19 deletions

File tree

‎docs/reference/lint-rules.mdx‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,8 @@ Severities:
2020

2121
Source: `packages/lint/src/rules/structure.ts`.
2222

23-
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.
23+
The five codes marked **Warning or error** are warnings when the CLI lints a project, and errors when Studio
24+
lints the file it is editing.
2425

2526
### `nested_structure_needs_subcomposition`
2627

@@ -52,6 +53,15 @@ The four codes marked **Warning or error** are warnings when the CLI lints a pro
5253

5354
**Fix:** Extend the root `data-duration`, or make the clip end at or before it.
5455

56+
### `nested_clip_never_visible`
57+
58+
**Warning or error.** A timed clip sits inside another timed element, and its time window never overlaps that
59+
element's, so it never appears. A nested clip's `data-start` counts from the composition's start, not from the
60+
element around it. Runs in sub-composition files too.
61+
62+
**Fix:** Give the clip a `data-start` inside its parent's window, in composition time, or move it out of the
63+
parent.
64+
5565
## Composition contract
5666

5767
Source: `packages/lint/src/rules/composition.ts`.

‎packages/cli/src/audio/analysis/targets.test.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ function row(
2020
host: null,
2121
hostRow: null,
2222
children: [],
23+
parentRow: null,
2324
trackIndex: 0,
2425
src: "audio/a.wav",
2526
sourceFile: null,

‎packages/cli/src/timeline/a2Shared.ts‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,19 @@ export function diff(before: string, after: string): string {
137137
return output.length <= 8_000 ? output : `${output.slice(0, 7_997)}...`;
138138
}
139139

140+
function isAncestorOf(ancestor: TimelineRow, row: TimelineRow, timeline: ProjectTimeline): boolean {
141+
for (let pointer = row.parentRow; pointer; ) {
142+
const parent = rowAt(timeline, pointer);
143+
if (parent === ancestor) return true;
144+
pointer = parent.parentRow;
145+
}
146+
return false;
147+
}
148+
149+
function sameLineage(a: TimelineRow, b: TimelineRow, timeline: ProjectTimeline): boolean {
150+
return isAncestorOf(a, b, timeline) || isAncestorOf(b, a, timeline);
151+
}
152+
140153
function overlap(
141154
row: TimelineRow,
142155
timeline: ProjectTimeline,
@@ -146,6 +159,7 @@ function overlap(
146159
return allRows(timeline).find(
147160
(candidate) =>
148161
candidate !== row &&
162+
!sameLineage(candidate, row, timeline) &&
149163
candidate.file === row.file &&
150164
candidate.trackIndex === row.trackIndex &&
151165
spansShareTime(start, end, candidate.start, candidate.end),
@@ -429,6 +443,7 @@ export function mutationConflict(
429443
if (verb === "duplicate") {
430444
const conflict = allRows(timeline).find(
431445
(candidate) =>
446+
!sameLineage(candidate, row, timeline) &&
432447
candidate.file === row.file &&
433448
candidate.trackIndex === row.trackIndex &&
434449
isInsideSpan(nextStart, candidate.start, candidate.end),

‎packages/cli/src/timeline/describeProject.inPoint.test.ts‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,12 +18,12 @@ const SCENE = `<template id="scene-template"><div data-composition-id="scene" da
1818
beforeAll(ensureDOMParser);
1919

2020
/** The video rows of a project made of `index` and `compositions/scene.html`. */
21-
async function videoRows(index: string, prefix: string) {
21+
async function videoRows(index: string, prefix: string, scene = SCENE) {
2222
const dir = mkdtempSync(join(tmpdir(), prefix));
2323
onTestFinished(() => rmSync(dir, { recursive: true, force: true }));
2424
mkdirSync(join(dir, "compositions"));
2525
writeFileSync(join(dir, "index.html"), index);
26-
writeFileSync(join(dir, "compositions", "scene.html"), SCENE);
26+
writeFileSync(join(dir, "compositions", "scene.html"), scene);
2727
const timeline = await describeProject(join(dir, "index.html"));
2828
return timeline.tracks.find((t) => t.kind === "video")!.rows;
2929
}
@@ -43,6 +43,17 @@ describe("a sub-composition's in-point", () => {
4343
]);
4444
});
4545

46+
it("cuts a clip nested in a timed wrapper like the wrapper's own clips", async () => {
47+
const videos = await videoRows(
48+
`<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>`,
49+
"hf-timeline-inpoint-nested-",
50+
`<div data-composition-id="scene" data-duration="12"><div id="w" data-start="0" data-duration="12">
51+
<video id="n" src="../sample.mp4" muted data-start="4" data-duration="4" data-media-start="5"></video></div></div>`,
52+
);
53+
54+
expect(videos.map((r) => [r.id, r.absStart, r.absEnd, r.mediaStart])).toEqual([["n", 5, 8, 6]]);
55+
});
56+
4657
it("moves each cut clip's media in-point by the part the cut skips", async () => {
4758
const videos = await videoRows(SPLIT_INDEX, "hf-timeline-inpoint-media-");
4859

‎packages/cli/src/timeline/describeProject.test.ts‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,44 @@ describe("describeProject", () => {
116116
]);
117117
});
118118

119+
it("lists clips nested in a timed wrapper at their playback time and says when one never shows", async () => {
120+
const { rows, text } = await rowsOf(`<html><body>
121+
<div data-composition-id="main" data-width="1920" data-height="1080" data-duration="10">
122+
<div id="shot2" data-start="5" data-duration="5" data-track-index="0">
123+
<h1 id="seen" data-start="6" data-duration="2">In</h1>
124+
<h1 id="lost" data-start="0" data-duration="2">Out</h1>
125+
</div>
126+
</div></body></html>`);
127+
const byId = (id: string) => rows.find((r) => r.id === id)!;
128+
const at = (p: { kind: string; index: number }) =>
129+
rows.find((r) => r.trackKind === p.kind && r.index === p.index)!.id;
130+
131+
expect(byId("shot2").children.map(at).sort()).toEqual(["lost", "seen"]);
132+
expect(byId("seen")).toMatchObject({ absStart: 6, absEnd: 8, warnings: [], nested: false });
133+
expect(at(byId("seen").parentRow!)).toBe("shot2");
134+
expect(byId("lost").warnings).toEqual([
135+
"never visible: plays 0-2s, but #shot2 only shows 5-10s; a nested data-start counts from the composition, not from #shot2",
136+
]);
137+
expect(text).toContain("#lost lost 0-2s warning: never visible");
138+
expect(text).not.toContain("no stable name");
139+
});
140+
141+
it("lists a sub-composition mounted inside a timed wrapper with every clip it holds", async () => {
142+
const { rows } = await rowsOf(`<html><body>
143+
<div data-composition-id="main" data-width="1920" data-height="1080" data-duration="10">
144+
<div id="shot" data-start="0" data-duration="5" data-track-index="0">
145+
<div id="scene" data-composition-src="compositions/title.html" data-start="0" data-duration="5"></div>
146+
</div>
147+
</div></body></html>`);
148+
const childIds = (id: string) =>
149+
rows
150+
.find((r) => r.id === id)!
151+
.children.map((p) => rows.find((r) => r.trackKind === p.kind && r.index === p.index)?.id);
152+
153+
expect(childIds("shot")).toEqual(["scene"]);
154+
expect(childIds("scene")).toEqual(["t1", "t2"]);
155+
});
156+
119157
it("reports each half's out-of-sync offset from its source pair, at the project fps", async () => {
120158
const { rows, text } = await rowsOf(`<html><body>
121159
<div data-composition-id="main" data-duration="10" data-fps="24">

‎packages/cli/src/timeline/describeProject.ts‎

Lines changed: 46 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ import {
1919
type MediaTag,
2020
} from "@hyperframes/parsers/media-duration";
2121
import {
22+
isSubCompositionHost,
2223
topLevelElements,
2324
trackKindOf,
2425
type StructureNode,
@@ -67,8 +68,10 @@ export interface TimelineRow extends ClipFact {
6768
host: string | null;
6869
/** Where that host row is (its kind's `rows[index]`), for hosts whose id is missing or repeated. */
6970
hostRow: RowPointer | null;
70-
/** Where this row's sub-composition clips are (one level only); each is a full row in its kind's `rows`. */
71+
/** Rows directly inside this one: its sub-composition's clips, or timed elements nested in it. */
7172
children: RowPointer[];
73+
/** The timed row in the same file that contains this clip; `null` at a file's top level. */
74+
parentRow: RowPointer | null;
7275
/** Signed frames from its `data-sync-origin` partner (+ = late); `null` unpaired or rates differ. */
7376
syncOffsetFrames: number | null;
7477
mediaStart: number | null;
@@ -80,10 +83,14 @@ export interface RowPointer {
8083
}
8184

8285
/** A row before flattening: children are still row objects and refs are not assigned. */
83-
type ClipDraft = Omit<TimelineRow, "index" | "nested" | "host" | "hostRow" | "children"> & {
86+
type ClipDraft = Omit<
87+
TimelineRow,
88+
"index" | "nested" | "host" | "hostRow" | "children" | "parentRow"
89+
> & {
8490
elementId: string | null;
8591
hfId: string | null;
8692
children: ClipDraft[];
93+
inside: ClipDraft[];
8794
};
8895

8996
export interface TimelineTrack {
@@ -276,6 +283,7 @@ interface RowTiming {
276283
authored: number | null;
277284
absStart: number;
278285
children: ClipDraft[];
286+
inside: ClipDraft[];
279287
duration: DurationResolution;
280288
}
281289

@@ -291,11 +299,14 @@ async function resolveRowTiming(scope: DocScope, node: DomNode, depth: number):
291299
host && depth === 0
292300
? await readSubComposition(host, scope, compositionOriginSeconds(absStart, el), slots)
293301
: [];
302+
const inside = isSubCompositionHost(node)
303+
? []
304+
: await Promise.all(topLevelElements(node).map((inner) => describeRow(scope, inner, depth)));
294305
const kind = el.tagName.toLowerCase();
295306
const duration = MEDIA_TAG.test(kind)
296307
? await resolveMediaRowDuration(scope, el, kind as MediaTag, authored)
297308
: resolveContainerDuration(authored, children);
298-
return { start, authored, absStart, children, duration };
309+
return { start, authored, absStart, children, inside, duration };
299310
}
300311

301312
function describeRowFields(scope: DocScope, node: DomNode, timing: RowTiming): ClipDraft {
@@ -326,6 +337,7 @@ function describeRowFields(scope: DocScope, node: DomNode, timing: RowTiming): C
326337
durationSource: timing.duration.durationSource,
327338
pendingReason: timing.duration.pendingReason,
328339
children: timing.children,
340+
inside: timing.inside,
329341
ref: "",
330342
warnings: [],
331343
elementId: el.id || null,
@@ -384,7 +396,8 @@ function cutRow(row: ClipDraft, slots: readonly HostSlot[]): ClipDraft[] {
384396
if (kept.end === kept.start && row.absEnd > row.absStart) return [];
385397
const skipped = (kept.start - row.absStart) * (row.playbackRate ?? 1);
386398
const mediaStart = row.mediaStart === null ? null : roundMs(row.mediaStart + skipped);
387-
return [{ ...row, absStart: roundMs(kept.start), absEnd: roundMs(kept.end), mediaStart }];
399+
const inside = row.inside.flatMap((inner) => cutRow(inner, slots));
400+
return [{ ...row, absStart: roundMs(kept.start), absEnd: roundMs(kept.end), mediaStart, inside }];
388401
}
389402

390403
/** 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 {
401414

402415
/** One flat, `absStart`-ordered list per kind holding every clip once; `children` become refs into those lists. */
403416
function flatten(top: ClipDraft[]): TimelineTrack[] {
404-
const entries = [
405-
...top.map((clip) => ({ clip, host: null })),
406-
...top.flatMap((host) => host.children.map((clip) => ({ clip, host }))),
407-
];
417+
type Entry = { clip: ClipDraft; host: ClipDraft | null; parent: ClipDraft | null };
418+
const entries: Entry[] = [];
419+
const add = (clip: ClipDraft, host: ClipDraft | null, parent: ClipDraft | null) => {
420+
entries.push({ clip, host, parent });
421+
for (const inner of clip.inside) add(inner, host, clip);
422+
for (const child of clip.children) add(child, clip, null);
423+
};
424+
for (const clip of top) add(clip, null, null);
408425
const byKind = TRACK_ORDER.map((kind) => ({
409426
kind,
410427
entries: entries
@@ -426,19 +443,21 @@ function flatten(top: ClipDraft[]): TimelineTrack[] {
426443
}
427444
return byKind.map(({ kind, entries: kindEntries }) => ({
428445
kind,
429-
rows: kindEntries.map(({ clip, host }, index) => {
446+
rows: kindEntries.map(({ clip, host, parent }, index) => {
430447
const uniqueId = clip.elementId && fileIds.get(clip.file)?.get(clip.elementId) === 1;
431448
const ref = uniqueId
432449
? `#${clip.elementId}`
433450
: clip.hfId
434451
? `hf:${clip.hfId}`
435452
: `${kind}/${index}`;
436-
const warnings =
437-
uniqueId || clip.hfId
453+
const warnings = [
454+
...(uniqueId || clip.hfId
438455
? []
439456
: [
440457
'row has no stable name; add id="<name>" to the element in this file, then retry with #<name>',
441-
];
458+
]),
459+
...neverVisibleWarning(clip, parent),
460+
];
442461
return {
443462
...clip,
444463
index,
@@ -447,12 +466,26 @@ function flatten(top: ClipDraft[]): TimelineTrack[] {
447466
nested: host !== null,
448467
host: host && host.id,
449468
hostRow: host && at(host),
450-
children: clip.children.map(at),
469+
children: [...clip.children, ...clip.inside].map(at),
470+
parentRow: parent && at(parent),
451471
};
452472
}),
453473
}));
454474
}
455475

476+
/** The runtime shows a nested clip only inside its parent's window, and its data-start counts from the composition. */
477+
export const NEVER_VISIBLE = "never visible";
478+
479+
function neverVisibleWarning(clip: ClipDraft, parent: ClipDraft | null): string[] {
480+
if (!parent || clip.kind === "audio") return [];
481+
if (clip.absEnd <= clip.absStart || parent.absEnd <= parent.absStart) return [];
482+
if (clip.absEnd > parent.absStart && clip.absStart < parent.absEnd) return [];
483+
const name = parent.elementId ? `#${parent.elementId}` : `its parent <${parent.kind}>`;
484+
return [
485+
`${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}`,
486+
];
487+
}
488+
456489
function projectFps(source: string): number {
457490
const parsed = parseFpsWithDefault(readCompositionFps(source) ?? undefined);
458491
return fpsToNumber(parsed.ok ? parsed.value : { num: 30, den: 1 });

‎packages/cli/src/timeline/formatTimeline.ts‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,9 @@
1-
import type { ProjectTimeline, TimelineRow, TimelineTrack } from "./describeProject.js";
1+
import {
2+
NEVER_VISIBLE,
3+
type ProjectTimeline,
4+
type TimelineRow,
5+
type TimelineTrack,
6+
} from "./describeProject.js";
27

38
const BAR_WIDTH = 40;
49
const n = (v: number) => String(Math.round(v * 1000) / 1000);
@@ -48,6 +53,7 @@ function details(row: TimelineRow): string {
4853
row.sourceFile && !row.children.length && "children=unread",
4954
row.laneError && `lanes unreadable: ${row.laneError}`,
5055
...lanes,
56+
...row.warnings.filter((w) => w.startsWith(NEVER_VISIBLE)).map((w) => `warning: ${w}`),
5157
]
5258
.filter(Boolean)
5359
.join(" ");
@@ -63,7 +69,7 @@ function line(row: TimelineRow, total: number): string {
6369
}
6470

6571
function header({ kind, rows }: TimelineTrack): string {
66-
const nested = rows.filter((r) => r.nested).length;
72+
const nested = rows.filter((r) => r.nested || r.parentRow).length;
6773
const split = nested ? `: ${rows.length - nested} top-level, ${nested} nested` : "";
6874
return `${kind} (${rows.length}${split})`;
6975
}

‎packages/cli/src/timeline/timeExpr.test.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ const row: TimelineRow = {
2020
host: null,
2121
hostRow: null,
2222
children: [],
23+
parentRow: null,
2324
trackIndex: 0,
2425
src: null,
2526
sourceFile: null,

‎packages/cli/src/timeline/timeline.e2e.test.ts‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -248,6 +248,27 @@ describe("timeline edit command", () => {
248248
};
249249
const endOf = (html: string, id: string) =>
250250
Number(clip(html, id).start) + Number(clip(html, id).duration);
251+
252+
it.each([
253+
["moves a hidden clip into its wrapper's window", ["move", "#lost", "8"], "lost", "8"],
254+
["moves a wrapper without colliding with its own clips", ["move", "#shot2", "4"], "shot2", "4"],
255+
["duplicates a clip inside its wrapper", ["duplicate", "#seen"], "seen", "6"],
256+
])("%s", (_name, args, id, start) => {
257+
const dir = mkdtempSync(join(tmpdir(), "hf-timeline-nested-"));
258+
writeFileSync(
259+
join(dir, "index.html"),
260+
`<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>`,
261+
);
262+
try {
263+
const result = run(dir, ...args);
264+
expect(result.stderr).not.toContain("overlap");
265+
expect(result.status).toBe(0);
266+
expect(clip(readFileSync(join(dir, "index.html"), "utf8"), id).start).toBe(start);
267+
} finally {
268+
rmSync(dir, { recursive: true, force: true });
269+
}
270+
});
271+
251272
const visibleAt = (html: string, time: number, ids: string[]) =>
252273
ids.filter((id) => isClipVisibleAt(time, Number(clip(html, id).start), endOf(html, id), 40));
253274

‎packages/lint/src/rules/structure.catalog.test.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ const STRUCTURE_CODES = new Set([
1010
"caption_track_kind_missing",
1111
"multiple_caption_tracks",
1212
"clip_ends_past_root_duration",
13+
"nested_clip_never_visible",
1314
]);
1415

1516
function htmlFiles(dir: string): string[] {

0 commit comments

Comments
 (0)