Skip to content

Commit 13af554

Browse files
feat(lint): warn when a sub-composition slot blanks before the host (#1542)
A sub-composition mount whose data-duration ends before the host composition's window leaves its slot blank for the remainder. The runtime behavior is correct (data-duration is the slot's visible window and takes precedence), but a full-bleed sub-composition shorter than the composition is almost always an authoring mistake that fails silently (issue #1540). Add the subcomposition_blanks_before_host rule, scoped narrowly to the high-signal shape — a sole/dominant external mount starting at ~0 whose window ends before the host's — so it stays silent on intentional short clips. Document the slot-window semantics in the sub-compositions reference, distinguishing the hold-through-slot case (#911/#917) from the blank-when-shorter-than-host case.
1 parent 015529e commit 13af554

3 files changed

Lines changed: 180 additions & 0 deletions

File tree

‎packages/core/src/lint/rules/composition.test.ts‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -820,4 +820,115 @@ describe("composition rules", () => {
820820
expect(finding).toBeUndefined();
821821
});
822822
});
823+
824+
describe("subcomposition_blanks_before_host", () => {
825+
const find = (findings: Array<{ code: string }>) =>
826+
findings.find((f) => f.code === "subcomposition_blanks_before_host");
827+
828+
it("fires on the issue #1540 shape (child shorter than host)", async () => {
829+
const html = `<html><body>
830+
<div id="root" data-composition-id="main" data-start="0" data-duration="331.224" data-width="1920" data-height="1080">
831+
<div id="decision-tree-comp" data-composition-id="decision-tree" data-composition-src="compositions/decision_tree.html" data-start="0" data-duration="15"></div>
832+
</div>
833+
</body></html>`;
834+
const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
835+
const finding = find(result.findings);
836+
expect(finding).toBeDefined();
837+
expect(finding?.severity).toBe("warning");
838+
expect(finding?.message).toContain("blank");
839+
expect(finding?.message).toContain("331.224");
840+
});
841+
842+
it("fires when the mount starts within the start tolerance", async () => {
843+
const html = `<html><body>
844+
<div id="root" data-composition-id="main" data-start="0" data-duration="60">
845+
<div data-composition-id="sub" data-composition-src="compositions/sub.html" data-start="0.3" data-duration="15"></div>
846+
</div>
847+
</body></html>`;
848+
const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
849+
expect(find(result.findings)).toBeDefined();
850+
});
851+
852+
it("fires at exactly the start tolerance boundary (start=0.5)", async () => {
853+
const html = `<html><body>
854+
<div id="root" data-composition-id="main" data-start="0" data-duration="60">
855+
<div data-composition-id="sub" data-composition-src="compositions/sub.html" data-start="0.5" data-duration="15"></div>
856+
</div>
857+
</body></html>`;
858+
const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
859+
expect(find(result.findings)).toBeDefined();
860+
});
861+
862+
it("stays silent on an intentional short intro followed by another clip", async () => {
863+
const html = `<html><body>
864+
<div id="root" data-composition-id="main" data-start="0" data-duration="60">
865+
<div data-composition-id="intro" data-composition-src="compositions/intro.html" data-start="0" data-duration="15"></div>
866+
<div data-composition-id="body" data-composition-src="compositions/body.html" data-start="15" data-duration="45"></div>
867+
</div>
868+
</body></html>`;
869+
const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
870+
expect(find(result.findings)).toBeUndefined();
871+
});
872+
873+
it("stays silent when the child matches the host window", async () => {
874+
const html = `<html><body>
875+
<div id="root" data-composition-id="main" data-start="0" data-duration="15">
876+
<div data-composition-id="sub" data-composition-src="compositions/sub.html" data-start="0" data-duration="15"></div>
877+
</div>
878+
</body></html>`;
879+
const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
880+
expect(find(result.findings)).toBeUndefined();
881+
});
882+
883+
it("stays silent when the child is longer than the host", async () => {
884+
const html = `<html><body>
885+
<div id="root" data-composition-id="main" data-start="0" data-duration="15">
886+
<div data-composition-id="sub" data-composition-src="compositions/sub.html" data-start="0" data-duration="30"></div>
887+
</div>
888+
</body></html>`;
889+
const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
890+
expect(find(result.findings)).toBeUndefined();
891+
});
892+
893+
it("stays silent for a non-sub-composition timed element", async () => {
894+
const html = `<html><body>
895+
<div id="root" data-composition-id="main" data-start="0" data-duration="60">
896+
<div class="clip" data-start="0" data-duration="15"></div>
897+
</div>
898+
</body></html>`;
899+
const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
900+
expect(find(result.findings)).toBeUndefined();
901+
});
902+
903+
it("stays silent when the root has no numeric data-duration", async () => {
904+
const html = `<html><body>
905+
<div id="root" data-composition-id="main" data-start="0">
906+
<div data-composition-id="sub" data-composition-src="compositions/sub.html" data-start="0" data-duration="15"></div>
907+
</div>
908+
</body></html>`;
909+
const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
910+
expect(find(result.findings)).toBeUndefined();
911+
});
912+
913+
it("stays silent for a late-starting clip", async () => {
914+
const html = `<html><body>
915+
<div id="root" data-composition-id="main" data-start="0" data-duration="60">
916+
<div data-composition-id="sub" data-composition-src="compositions/sub.html" data-start="40" data-duration="5"></div>
917+
</div>
918+
</body></html>`;
919+
const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
920+
expect(find(result.findings)).toBeUndefined();
921+
});
922+
923+
it("stays silent when an unknown-duration sibling covers the tail", async () => {
924+
const html = `<html><body>
925+
<div id="root" data-composition-id="main" data-start="0" data-duration="60">
926+
<div data-composition-id="sub" data-composition-src="compositions/sub.html" data-start="0" data-duration="15"></div>
927+
<div class="clip" data-start="0"></div>
928+
</div>
929+
</body></html>`;
930+
const result = await lintHyperframeHtml(html, { filePath: "/project/index.html" });
931+
expect(find(result.findings)).toBeUndefined();
932+
});
933+
});
823934
});

‎packages/core/src/lint/rules/composition.ts‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -514,4 +514,66 @@ export const compositionRules: Array<(ctx: LintContext) => HyperframeLintFinding
514514
}
515515
return findings;
516516
},
517+
518+
// subcomposition_blanks_before_host
519+
// Warns when a full-bleed sub-composition slot ends before the host composition
520+
// does, leaving the slot blank for the remainder (issue #1540). Scoped narrowly to
521+
// the high-signal shape — a sole/dominant external mount starting at ~0 — so it
522+
// stays silent on intentional short clips (an intro followed by other clips that
523+
// carry the timeline forward).
524+
// fallow-ignore-next-line complexity
525+
({ tags, rootTag }) => {
526+
if (!rootTag) return [];
527+
const rootDuration = Number(readAttr(rootTag.raw, "data-duration"));
528+
if (!Number.isFinite(rootDuration) || rootDuration <= 0) return [];
529+
530+
// Two independent knobs that happen to share a 0.5s magnitude. Tuned for
531+
// real hosts (tens to hundreds of seconds); on a very short host (~6s) the
532+
// EPSILON slack would let a ~10% blank tail pass unflagged — acceptable
533+
// because the silent-blank trap this rule targets only matters at scale.
534+
const EPSILON = 0.5; // seconds; tolerance for "ends/covers near the host end"
535+
const START_TOLERANCE = 0.5; // seconds; "starts at the composition start"
536+
const round3 = (n: number) => Math.round(n * 1000) / 1000;
537+
538+
// Timed children of the root. An element with data-start but no usable
539+
// data-duration is treated as covering the tail (end = Infinity), so an
540+
// unknown-length sibling suppresses the warning rather than triggering it.
541+
const timed = tags
542+
.filter((tag) => tag.index !== rootTag.index && readAttr(tag.raw, "data-start") !== null)
543+
.map((tag) => {
544+
const start = Number(readAttr(tag.raw, "data-start")) || 0;
545+
const dur = Number(readAttr(tag.raw, "data-duration"));
546+
const end = Number.isFinite(dur) && dur > 0 ? start + dur : Infinity;
547+
return { tag, start, end };
548+
});
549+
550+
// `tags` is a flat list (no nesting depth), so a timed element nested
551+
// *inside* a candidate slot is treated as a tail-covering sibling rather
552+
// than a descendant. Acceptable: external src mounts are empty by
553+
// convention (content is loaded from the linked file), so the only
554+
// false-negative path is rare and matches the flat-tag scope of the
555+
// sibling rules in this file.
556+
const tailCovered = (exceptIndex: number) =>
557+
timed.some((t) => t.tag.index !== exceptIndex && t.end >= rootDuration - EPSILON);
558+
559+
const findings: HyperframeLintFinding[] = [];
560+
for (const t of timed) {
561+
if (readAttr(t.tag.raw, "data-composition-src") === null) continue; // external slot only
562+
if (t.start > START_TOLERANCE) continue; // must start at the composition start
563+
if (!Number.isFinite(t.end)) continue; // known, finite slot length
564+
if (t.end >= rootDuration - EPSILON) continue; // already fills the host window
565+
if (tailCovered(t.tag.index)) continue; // another clip covers the tail — not full-bleed
566+
const elementId = readAttr(t.tag.raw, "id") || undefined;
567+
const gap = round3(rootDuration - t.end);
568+
findings.push({
569+
code: "subcomposition_blanks_before_host",
570+
severity: "warning",
571+
message: `<${t.tag.name}${elementId ? ` id="${elementId}"` : ""}> sub-composition ends at ${round3(t.end)}s but the composition runs to ${round3(rootDuration)}s — its slot will be blank for ~${gap}s.`,
572+
elementId,
573+
fixHint: `data-duration is the slot's visible window. Set this sub-composition's data-duration to ${round3(rootDuration - t.start)} to fill the host window, or add another clip to cover the remaining ~${gap}s.`,
574+
snippet: truncateSnippet(t.tag.raw),
575+
});
576+
}
577+
return findings;
578+
},
517579
];

‎skills/hyperframes-core/references/sub-compositions.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -157,6 +157,13 @@ For the runtime end-to-end check (a fast `snapshot` pass + per-scene frame eyeba
157157

158158
**Do not** manually `master.add(child)` a sub-composition timeline into the host timeline. HyperFrames already drives them independently — nesting them in GSAP causes double-seeks.
159159

160+
### The host clip's `data-duration` is the slot's visible window
161+
162+
`data-duration` on the host clip defines **how long the slot is visible**, and it takes precedence over the sub-composition's internal GSAP timeline length. Two consequences follow:
163+
164+
- **Internal timeline shorter than the slot → the slot holds.** If the sub-composition's GSAP timeline finishes before `data-duration` elapses, the slot keeps showing its final frame for the rest of the window. You do **not** need to pad the timeline with empty tweens.
165+
- **`data-duration` shorter than the host composition → the slot ends (and goes blank) when its own `data-duration` elapses.** This is intended: the clip is a fixed-length window on the timeline, not "fill until the composition ends." To keep a sub-composition visible for the whole composition, set its `data-duration` to span the host window (or add another clip to cover the remaining time). Leaving a single full-bleed sub-composition shorter than the composition is almost always a mistake — the linter flags it as `subcomposition_blanks_before_host`.
166+
160167
## Animations Inside Sub-Compositions
161168

162169
Prefer `gsap.fromTo()` over `gsap.from()` for entrance tweens. The host re-seeks the sub-composition every time its clip becomes visible; `gsap.from()` records the starting state at registration and can desync on seek-back, while `gsap.fromTo()` declares both endpoints explicitly and replays cleanly.

0 commit comments

Comments
 (0)