Skip to content

Commit 13bee74

Browse files
fix(lint): warn when a clip ends past the root composition duration (#4633)
1 parent fa044a8 commit 13bee74

7 files changed

Lines changed: 95 additions & 6 deletions

File tree

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ const STRUCTURE_CODES = new Set([
99
"timeline_element_missing_timing",
1010
"caption_track_kind_missing",
1111
"multiple_caption_tracks",
12+
"clip_ends_past_root_duration",
1213
]);
1314

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

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

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ const STRUCTURE = new Set([
1414
"timeline_element_missing_timing",
1515
"caption_track_kind_missing",
1616
"multiple_caption_tracks",
17+
"clip_ends_past_root_duration",
1718
]);
1819
const has = (found: Awaited<ReturnType<typeof codes>>, code: string) =>
1920
found.some((f) => f.code === code);
@@ -138,3 +139,60 @@ describe("caption rules", () => {
138139
expect(has(await codes(mixed), "multiple_caption_tracks")).toBe(false);
139140
});
140141
});
142+
143+
describe("clip_ends_past_root_duration", () => {
144+
const PAST = "clip_ends_past_root_duration";
145+
it("names a direct clip that ends past the root, with its end and the root duration", async () => {
146+
const [finding, ...rest] = await codes(
147+
'<div id="outro" class="clip" data-start="8" data-duration="4">x</div>',
148+
);
149+
expect(rest).toEqual([]);
150+
expect(finding).toMatchObject({ code: PAST, severity: "warning", elementId: "outro" });
151+
expect(finding?.message).toContain('<div id="outro"> runs from 8s to 12s');
152+
expect(finding?.message).toContain("data-duration of 10s");
153+
expect(finding?.fixHint).toBe(
154+
'Extend the root data-duration to 12, or make <div id="outro"> end at or before 10s.',
155+
);
156+
});
157+
it("passes a clip ending at the root or within the shared tolerance past it", async () => {
158+
expect(await codes('<div class="clip" data-start="6" data-duration="4">x</div>')).toEqual([]);
159+
expect(await codes('<div class="clip" data-start="4" data-duration="6.04">x</div>')).toEqual(
160+
[],
161+
);
162+
expect(await codes('<div class="clip" data-start="4" data-duration="6.05">x</div>')).toEqual(
163+
[],
164+
);
165+
const [finding] = await codes('<div class="clip" data-start="4" data-duration="6.06">x</div>');
166+
expect(finding?.message).toContain("runs from 4s to 10.06s");
167+
});
168+
it("reads a legacy data-end, and skips a start that references another clip", async () => {
169+
const [finding] = await codes('<div class="clip" data-start="8" data-end="12">x</div>');
170+
expect(finding).toMatchObject({ code: PAST });
171+
expect(finding?.message).toContain("runs from 8s to 12s");
172+
expect(
173+
await codes('<div class="clip" data-start="intro + 2" data-duration="20">x</div>'),
174+
).toEqual([]);
175+
});
176+
it("judges a sub-composition by its host, not its inner clips", async () => {
177+
const [finding] = await codes(
178+
'<div id="scene" data-composition-src="compositions/scene.html" data-start="7" data-duration="5"></div>',
179+
);
180+
expect(finding).toMatchObject({ code: PAST, elementId: "scene" });
181+
expect(finding?.message).toContain("runs from 7s to 12s");
182+
const inline =
183+
'<div id="inner" data-composition-id="inner" data-start="0" data-duration="5">' +
184+
'<div class="clip" data-start="0" data-duration="20">x</div></div>';
185+
expect(await codes(inline)).toEqual([]);
186+
});
187+
it("skips media whose length only the file knows", async () => {
188+
expect(await codes('<video src="a.mp4" data-start="9"></video>')).toEqual([]);
189+
});
190+
it("leaves a root with no data-duration to the missing-duration rules", async () => {
191+
const html = page('<div class="clip" data-start="8" data-duration="4">x</div>').replace(
192+
' data-duration="10"',
193+
"",
194+
);
195+
const { findings } = await lintHyperframeHtml(html);
196+
expect(findings.filter((f) => f.code === PAST)).toEqual([]);
197+
});
198+
});

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

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,14 @@
11
import type { LintContext, HyperframeLintFinding, OpenTag } from "../context";
2-
import { readDecodedAttr } from "../utils";
2+
import { readDecodedAttr, truncateSnippet } from "../utils";
33
import {
44
isSubCompositionHost,
55
topLevelElements,
66
trackKindOf,
77
type StructureNode,
88
} from "@hyperframes/parsers/top-level-elements";
9+
import { readClipTiming } from "@hyperframes/parsers/composition-contract";
10+
import { readDataDurationSeconds } from "@hyperframes/parsers/media-duration";
11+
import { TIMING_TOLERANCE_SECONDS } from "@hyperframes/parsers/composition-duration";
912

1013
interface TagNode extends StructureNode<TagNode> {
1114
children: TagNode[];
@@ -167,6 +170,29 @@ function captionFindings(rows: TagNode[], severity: Severity): HyperframeLintFin
167170
return findings;
168171
}
169172

173+
const hundredths = (seconds: number) => Math.round(seconds * 100) / 100;
174+
175+
function clipsPastRootFindings(root: TagNode, rows: TagNode[]): HyperframeLintFinding[] {
176+
if (root.attrs["data-composition-id"] === undefined) return [];
177+
const rootDuration = readDataDurationSeconds((name) => root.attrs[name]);
178+
if (rootDuration === null) return [];
179+
const limit = hundredths(rootDuration);
180+
return rows.flatMap((row) => {
181+
const { start, end } = readClipTiming({ getAttribute: (name) => row.attrs[name] ?? null });
182+
if (start === null || end === null || end <= rootDuration + TIMING_TOLERANCE_SECONDS) return [];
183+
return [
184+
{
185+
code: "clip_ends_past_root_duration",
186+
severity: "warning",
187+
message: `${describe(row)} runs from ${hundredths(start)}s to ${hundredths(end)}s, past the root composition's data-duration of ${limit}s, so it is cut off in previews, posters and renders.`,
188+
elementId: row.attrs.id,
189+
fixHint: `Extend the root data-duration to ${hundredths(end)}, or make ${describe(row)} end at or before ${limit}s.`,
190+
snippet: truncateSnippet(row.open.raw),
191+
},
192+
];
193+
});
194+
}
195+
170196
export const structureRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
171197
(ctx) => {
172198
// The timeline shows the root composition's rows; a sub-composition file is the leaf where layout lives.
@@ -179,6 +205,7 @@ export const structureRules: Array<(ctx: LintContext) => HyperframeLintFinding[]
179205
...nestedStructureFindings(rows, severity),
180206
...missingDurationFindings(rows, severity),
181207
...captionFindings(rows, severity),
208+
...clipsPastRootFindings(root, rows),
182209
];
183210
},
184211
];

‎packages/parsers/src/compositionDuration.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@ export interface ResolveCompositionDurationInput {
1818
clipEndsSeconds: readonly (number | null)[];
1919
}
2020

21+
export const TIMING_TOLERANCE_SECONDS = 0.05;
22+
2123
const isPositiveFinite = (value: number | null): value is number =>
2224
value !== null && Number.isFinite(value) && value > 0;
2325

‎packages/parsers/src/timingMismatches.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
import { parseHTML } from "linkedom";
22
import { parseGsapScriptAcorn } from "./gsapParserAcorn.js";
33
import type { GsapAnimation } from "./gsapSerialize.js";
4+
import { TIMING_TOLERANCE_SECONDS } from "./compositionDuration.js";
45
import { isSubCompositionHost, topLevelElements } from "./topLevelElements.js";
56
import type { StructureNode } from "./topLevelElements.js";
67

7-
const EPSILON = 0.05;
88
const NON_RENDERED = new Set(["script", "style", "template", "noscript", "link", "meta"]);
99

1010
export type TimingFinding =
@@ -94,8 +94,8 @@ function windowFinding(
9494
const duration = attrNumber(el, "data-duration");
9595
if (dataStart === null) return null;
9696
const dataEnd = duration === null ? null : dataStart + duration;
97-
const beforeStart = anim.method !== "set" && start < dataStart - EPSILON;
98-
const afterEnd = dataEnd !== null && start > dataEnd + EPSILON;
97+
const beforeStart = anim.method !== "set" && start < dataStart - TIMING_TOLERANCE_SECONDS;
98+
const afterEnd = dataEnd !== null && start > dataEnd + TIMING_TOLERANCE_SECONDS;
9999
if (!beforeStart && !afterEnd) return null;
100100
const elementId = el.getAttribute("id");
101101
return {
@@ -183,7 +183,7 @@ export function timingMismatches(html: string): TimingMismatchReport {
183183
const timelineEnd = Math.max(0, ...ends.filter((e): e is number => e !== null));
184184

185185
const rootDuration = attrNumber(root, "data-duration");
186-
if (rootDuration !== null && timelineEnd > rootDuration + EPSILON) {
186+
if (rootDuration !== null && timelineEnd > rootDuration + TIMING_TOLERANCE_SECONDS) {
187187
report.findings.push({ kind: "timeline-exceeds-root-duration", rootDuration, timelineEnd });
188188
}
189189
return report;

‎skills-manifest.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@
3434
"files": 11
3535
},
3636
"hyperframes-core": {
37-
"hash": "bc03be27ef68003b",
37+
"hash": "b632d12d11eb54e8",
3838
"files": 11
3939
},
4040
"hyperframes-creative": {

‎skills/hyperframes-core/SKILL.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,7 @@ Surfaced here; full rationale in the linked reference. Do not violate:
8686
- To know what is on a project's timeline (tracks, clips, starts, ends, what plays), run `npx hyperframes timeline [--json]` instead of reading `index.html` and every sub-composition file.
8787
- Match existing composition IDs and timeline keys.
8888
- 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.
89+
- 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`).
8990
- `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.
9091
- Adding a sub-composition: verify its internal `data-composition-id` before wiring the host.
9192

0 commit comments

Comments
 (0)