Skip to content

Write HTML. Render video. Built for agents.

fix(lint): flag static composition hosts without opt-out (#3763)

QiuLG9a4b2a2d74d3
diff --git a/docs/reference/html-schema.mdx b/docs/reference/html-schema.mdx
index 7c12049073..5127957bcc 100644
--- a/docs/reference/html-schema.mdx
+++ b/docs/reference/html-schema.mdx
@@ -297,6 +297,13 @@ A composition using GSAP must:
HyperFrames controls seeking. Composition code describes how the visual state
looks at a given time.
+Every element with `data-composition-id` participates in timeline readiness.
+For a static nested section, use an ordinary `id` instead, or add
+`data-no-timeline` to declare that no timeline will be registered. Otherwise,
+the renderer waits up to the player-ready timeout for that element's timeline.
+`hyperframes lint` reports bare composition hosts that have neither a matching
+timeline registration nor an explicit opt-out as `missing_data_no_timeline`.
+
## Validate
```bash
diff --git a/packages/lint/src/project.test.ts b/packages/lint/src/project.test.ts
index 4dc8669eb1..5080dbc137 100644
--- a/packages/lint/src/project.test.ts
+++ b/packages/lint/src/project.test.ts
@@ -47,6 +47,26 @@ afterEach(() => {
dirs = [];
});
+describe("missing_data_no_timeline", () => {
+ it("surfaces bare nested composition hosts through project lint", async () => {
+ const project = makeProject(`<!doctype html><html><body>
+ <div data-composition-id="root" data-width="1920" data-height="1080" data-start="0" data-duration="5">
+ <section id="alpha" data-composition-id="alpha"></section>
+ <section id="beta" data-composition-id="beta"></section>
+ </div>
+ <script>window.__timelines["root"] = gsap.timeline({ paused: true });</script>
+</body></html>`);
+
+ const { results, totalWarnings } = await lintProject(project);
+ const findings = results[0]?.result.findings.filter(
+ (finding) => finding.code === "missing_data_no_timeline",
+ );
+
+ expect(totalWarnings).toBe(2);
+ expect(findings?.map((finding) => finding.elementId)).toEqual(["alpha", "beta"]);
+ });
+});
+
describe("external symlink assets", () => {
it("does not report a shared asset addressed through an in-project symlink", async () => {
const project = makeProject(
diff --git a/packages/lint/src/rules/composition.test.ts b/packages/lint/src/rules/composition.test.ts
index 552626e73a..494f78dc68 100644
--- a/packages/lint/src/rules/composition.test.ts
+++ b/packages/lint/src/rules/composition.test.ts
@@ -912,18 +912,121 @@ describe("composition rules", () => {
expect(result.findings.find((f) => f.code === "missing_data_no_timeline")).toBeUndefined();
});
- it("does not warn when a script registers window.__timelines[id]", async () => {
+ it.each([
+ 'window.__timelines["c1"] = gsap.timeline({ paused: true });',
+ "window.__timelines.c1 = gsap.timeline({ paused: true });",
+ "window.__timelines = { c1: gsap.timeline({ paused: true }) };",
+ 'window.__timelines = { "c1": gsap.timeline({ paused: true }) };',
+ 'const spec = { id: "c1" }; window.__timelines[spec.id] = gsap.timeline({ paused: true });',
+ 'window.__timelines["c1"] ??= gsap.timeline({ paused: true });',
+ 'window.__timelines["c1"] ||= gsap.timeline({ paused: true });',
+ 'const ids = ["c1"]; window.__timelines[ids[0]] = gsap.timeline({ paused: true });',
+ ])("does not warn when a script registers a timeline: %s", async (registration) => {
const html = `<!DOCTYPE html><html><body>
<div data-composition-id="c1" data-width="320" data-height="180" data-duration="5"></div>
<script>
window.__timelines = window.__timelines || {};
- window.__timelines["c1"] = gsap.timeline({ paused: true });
+ ${registration}
+ </script>
+</body></html>`;
+ const result = await lintHyperframeHtml(html);
+ expect(result.findings.find((f) => f.code === "missing_data_no_timeline")).toBeUndefined();
+ });
+
+ it("warns for each bare nested composition id without a timeline or opt-out", async () => {
+ const html = `<!DOCTYPE html><html><body>
+ <div data-composition-id="root" data-width="320" data-height="180" data-duration="5">
+ <section id="alpha" data-composition-id="alpha"></section>
+ <section id="beta" data-composition-id="beta"></section>
+ </div>
+ <script>window.__timelines["root"] = gsap.timeline({ paused: true });</script>
+</body></html>`;
+ const result = await lintHyperframeHtml(html);
+ const findings = result.findings.filter((f) => f.code === "missing_data_no_timeline");
+
+ expect(findings).toHaveLength(2);
+ expect(findings.map((finding) => finding.elementId)).toEqual(["alpha", "beta"]);
+ expect(findings[0]?.message).toContain('Composition host "alpha"');
+ expect(findings[0]?.fixHint).toContain("plain `id`");
+ });
+
+ it("ignores a timeline registration that only appears in a script comment", async () => {
+ const html = `<!DOCTYPE html><html><body>
+ <div data-composition-id="root" data-width="320" data-height="180" data-duration="5">
+ <section data-composition-id="static"></section>
+ </div>
+ <script>
+ window.__timelines["root"] = gsap.timeline({ paused: true });
+ // window.__timelines["static"] = timeline;
+ </script>
+</body></html>`;
+ const result = await lintHyperframeHtml(html);
+
+ expect(result.findings.find((f) => f.code === "missing_data_no_timeline")?.message).toContain(
+ 'Composition host "static"',
+ );
+ });
+
+ it("accepts nested hosts with registrations, sources, or explicit opt-outs", async () => {
+ const html = `<!DOCTYPE html><html><body>
+ <div data-composition-id="root" data-width="320" data-height="180" data-duration="5">
+ <section data-composition-id="registered"></section>
+ <section data-composition-id="static" data-no-timeline></section>
+ <section data-composition-id="source" data-composition-src="source.html"></section>
+ <section data-composition-id="compiled" data-composition-file="compiled.html"></section>
+ </div>
+ <script>
+ window.__timelines.root = gsap.timeline({ paused: true });
+ window.__timelines.registered = gsap.timeline({ paused: true });
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
+
expect(result.findings.find((f) => f.code === "missing_data_no_timeline")).toBeUndefined();
});
+ it("does not guess which host a computed timeline key registers", async () => {
+ const html = `<!DOCTYPE html><html><body>
+ <div data-composition-id="root" data-width="320" data-height="180" data-duration="5">
+ <section data-composition-id="scene"></section>
+ </div>
+ <script>
+ const compositionId = "scene";
+ window.__timelines[compositionId] = (gsap.timeline({ paused: true }));
+ </script>
+</body></html>`;
+ const result = await lintHyperframeHtml(html);
+
+ expect(result.findings.find((f) => f.code === "missing_data_no_timeline")).toBeUndefined();
+ });
+
+ it("checks bare nested hosts inside a sub-composition file", async () => {
+ const html = `<template>
+ <div data-composition-id="scene" data-width="320" data-height="180" data-duration="5">
+ <section data-composition-id="static-part"></section>
+ </div>
+</template>`;
+ const result = await lintHyperframeHtml(html, { isSubComposition: true });
+
+ expect(result.findings.find((f) => f.code === "missing_data_no_timeline")?.message).toContain(
+ 'Composition host "static-part"',
+ );
+ });
+
+ it.each([
+ "window.__timelines = {};",
+ '// window.__timelines["c1"] = gsap.timeline({ paused: true });',
+ ])("still warns when a script does not register a timeline: %s", async (script) => {
+ const html = `<!DOCTYPE html><html><body>
+ <div data-composition-id="c1" data-width="320" data-height="180" data-duration="5"></div>
+ <script>${script}</script>
+</body></html>`;
+ const result = await lintHyperframeHtml(html);
+ expect(result.findings.find((f) => f.code === "missing_data_no_timeline")).toMatchObject({
+ severity: "warning",
+ });
+ });
+
it("does not warn when there is no root composition-id", async () => {
const html = `<!DOCTYPE html><html><body><p>hello</p></body></html>`;
const result = await lintHyperframeHtml(html);
diff --git a/packages/lint/src/rules/composition.ts b/packages/lint/src/rules/composition.ts
index 179f9e75df..81d28a0907 100644
--- a/packages/lint/src/rules/composition.ts
+++ b/packages/lint/src/rules/composition.ts
@@ -1,6 +1,7 @@
import type { LintContext, HyperframeLintFinding, ExtractedBlock, OpenTag } from "../context";
import {
findHtmlTag,
+ extractTimelineRegistryKeys,
readAttr,
readDecodedAttr,
readJsonAttr,
@@ -71,6 +72,8 @@ const HEAVY_OVERLAY_EXEMPT_TAGS = new Set([
const HEAVY_OVERLAY_CSS_PATTERN =
/(?:filter\s*:[^;}]*\bblur\s*\()|(?:clip-path\s*:(?!\s*(?:none|inherit|initial|unset)\b)\s*[^;}]+)|(?:radial-gradient\s*\()/i;
const INLINE_STYLE_DISPLAY_NONE_PATTERN = /(?:^|;)\s*display\s*:\s*none\b/i;
+const COMPUTED_TIMELINE_REGISTRATION_PATTERN =
+ /window\.__timelines\s*\[(?!\s*["'])(?:[^\r\n[\]]|\[[^\r\n\]]*\])+\]\s*(?:\?\?|\|\||&&)?=/;
function readTagTiming(rawTag: string) {
return readClipTiming({ getAttribute: (name) => readAttr(rawTag, name) });
@@ -559,6 +562,38 @@ function negativeZIndexFinding(
};
}
+function hasComputedTimelineRegistration(scripts: readonly ExtractedBlock[]): boolean {
+ return scripts.some((script) =>
+ COMPUTED_TIMELINE_REGISTRATION_PATTERN.test(stripJsCode(script.content)),
+ );
+}
+
+// A mounted source registers its own timeline.
+function mountsSource(tag: OpenTag): boolean {
+ return Boolean(
+ readAttr(tag.raw, "data-composition-src") || readAttr(tag.raw, "data-composition-file"),
+ );
+}
+
+function missingTimelineFinding(
+ tag: OpenTag,
+ compositionId: string,
+ isRoot: boolean,
+): HyperframeLintFinding {
+ return {
+ code: "missing_data_no_timeline",
+ severity: "warning",
+ message: isRoot
+ ? "This composition has no `window.__timelines` registration but is missing `data-no-timeline`. The producer polls for timeline registration for up to 45 seconds before timing out, adding 45 s to every render."
+ : `Composition host "${compositionId}" has neither a matching \`window.__timelines\` registration nor \`data-no-timeline\`. The producer waits up to 45 seconds for every \`data-composition-id\` before rendering.`,
+ elementId: readAttr(tag.raw, "id") || undefined,
+ fixHint: isRoot
+ ? 'Add `data-no-timeline` to the root element to skip the poll: `<div data-composition-id="..." data-no-timeline ...>`.'
+ : "If this is a static section, use a plain `id` instead of `data-composition-id`, or add `data-no-timeline`. Otherwise, register its timeline or mount it with `data-composition-src`.",
+ snippet: truncateSnippet(tag.raw),
+ };
+}
+
export const compositionRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
// duplicate_composition_id catches meta-tag/root collisions that create duplicate composition entries.
({ tags }) => {
@@ -914,39 +949,30 @@ export const compositionRules: Array<(ctx: LintContext) => HyperframeLintFinding
},
// missing_data_no_timeline
- // The producer polls window.__timelines[id] with a 45-second timeout waiting
- // for GSAP timeline registration. Compositions that never call
- // window.__timelines[id] = tl stall for 45 s every render. Adding
- // data-no-timeline to the root element tells the producer to skip the poll.
- ({ rootTag, rootCompositionId, scripts, rawSource, options }) => {
- if (options.isSubComposition) return [];
+ // The producer polls window.__timelines[id] for every composition id in the
+ // rendered document. A timeline-free root or bare nested composition host
+ // therefore spends the full 45-second readiness budget unless it explicitly
+ // opts out with data-no-timeline.
+ ({ rootTag, rootCompositionId, tags, scripts, rawSource, options }) => {
if (!rootCompositionId || !rootTag) return [];
- // readAttr only matches valued attrs (attr="..."); data-no-timeline is
- // typically boolean (no value). Strip quoted attribute values first to
- // avoid matching attr names that appear inside other values
- // (e.g. title="add data-no-timeline here"), then check with a boundary
- // that rejects hyphenated variants (data-no-timeline-start has '-' next,
- // not a word-break char).
- const tagNoValues = rootTag.raw.replace(/"[^"]*"|'[^']*'/g, '""');
- if (/(?:^|\s)data-no-timeline(?=[\s>=/]|$)/i.test(tagNoValues)) return [];
// Can't scan external script files for timeline registration; skip to avoid
// false positives on compositions that register via a bundled JS file.
if (/<script\b[^>]*\bsrc\s*=/i.test(rawSource)) return [];
- const registersTimeline = scripts.some((s) => s.content.includes("window.__timelines["));
- if (registersTimeline) return [];
- return [
- {
- code: "missing_data_no_timeline",
- severity: "warning",
- message:
- "This composition has no `window.__timelines` registration but is missing `data-no-timeline`. " +
- "The producer polls for timeline registration for up to 45 seconds before timing out, " +
- "adding 45 s to every render.",
- fixHint:
- 'Add `data-no-timeline` to the root element to skip the poll: `<div data-composition-id="..." data-no-timeline ...>`.',
- snippet: truncateSnippet(rootTag.raw),
- },
- ];
+ // A computed key may map to any authored id. When static analysis cannot
+ // resolve that key, stay silent rather than claim a registration is absent.
+ if (hasComputedTimelineRegistration(scripts)) return [];
+
+ const registeredIds = new Set(
+ scripts.flatMap((script) => extractTimelineRegistryKeys(stripJsComments(script.content))),
+ );
+ return tags.flatMap((tag) => {
+ const compositionId = readDecodedAttr(tag.raw, "data-composition-id");
+ if (!compositionId || registeredIds.has(compositionId)) return [];
+ const isRoot = tag.index === rootTag.index;
+ if (isRoot ? options.isSubComposition : isInsideInertTemplate(tag, tags)) return [];
+ if (readDecodedAttr(tag.raw, "data-no-timeline") !== null || mountsSource(tag)) return [];
+ return [missingTimelineFinding(tag, compositionId, isRoot)];
+ });
},
// negative_z_index
diff --git a/packages/lint/src/utils.ts b/packages/lint/src/utils.ts
index a34397ae6c..1896a93d0f 100644
--- a/packages/lint/src/utils.ts
+++ b/packages/lint/src/utils.ts
@@ -44,7 +44,7 @@ export const WINDOW_TIMELINE_ASSIGN_PATTERN =
export const INVALID_SCRIPT_CLOSE_PATTERN = /<script[^>]*>[\s\S]*?<\s*\/\s*script(?!>)/i;
const TIMELINE_REGISTRY_KEY_PATTERN =
- /window\.__timelines(?:\[\s*["']([^"']+)["']\s*\]|\.\s*([A-Za-z_$][\w$]*))\s*=/g;
+ /window\.__timelines(?:\[\s*["']([^"']+)["']\s*\]|\.\s*([A-Za-z_$][\w$]*))\s*(?:\?\?|\|\||&&)?=/g;
// The `window.__timelines = { ... }` object-literal body (group 1), captured so its
// `key: value` entries can be scanned for registered keys.