Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix(lint): flag static composition hosts without opt-out (#3763)
QiuLG9a4b2a2d74d3
diff --git a/docs/reference/html-schema.mdx b/docs/reference/html-schema.mdxindex 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 statelooks 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```bashdiff --git a/packages/lint/src/project.test.ts b/packages/lint/src/project.test.tsindex 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.tsindex 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.tsindex 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_indexdiff --git a/packages/lint/src/utils.ts b/packages/lint/src/utils.tsindex 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.