Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix(cli): keyframes --shot on a compositions/ file mounts the scene in its project (#5401)
Miguel Ángel4225fba3a4fe
diff --git a/packages/core/src/compiler/htmlBundler.test.ts b/packages/core/src/compiler/htmlBundler.test.tsindex abbdafe8f3..ec2795986c 100644--- a/packages/core/src/compiler/htmlBundler.test.ts+++ b/packages/core/src/compiler/htmlBundler.test.ts@@ -192,6 +192,32 @@ describe("bundleToSingleHtml", () => {expect(bundled).toContain(".direct-scene { color: rgb(1, 2, 3); }");});+ it("bundles a template scene entry inside the index that mounts it", async () => {+ const dir = makeTempProject({+ "index.html": `<!doctype html><html><head><script src="vendor/gsap.js"></script></head><body>+ <div data-composition-id="root" data-width="320" data-height="180" data-duration="9">+ <div data-composition-id="intro" data-composition-src="compositions/intro.html" data-start="0" data-duration="3"></div>+ <div data-composition-id="scene" data-composition-src="./compositions/scene.html" data-start="3" data-duration="6"></div>+ </div>+ </body></html>`,+ "vendor/gsap.js": "window.ROOT_GSAP_LOADED = true;",+ "compositions/intro.html": `<template><div data-composition-id="intro">intro scene</div></template>`,+ "compositions/scene.html": `<template><div data-composition-id="scene" data-duration="6">+ <h1 id="title">mounted scene</h1></div></template>`,+ });++ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});+ const bundled = await bundleToSingleHtml(dir, { entryFile: "compositions/scene.html" });+ const guardWarnings = warn.mock.calls.filter(([m]) => String(m).includes("[StaticGuard]"));+ warn.mockRestore();++ expect(guardWarnings).toEqual([]);+ expect(bundled).toContain("window.ROOT_GSAP_LOADED = true;");+ expect(bundled).toContain('data-composition-id="root"');+ expect(bundled).toContain("mounted scene");+ expect(bundled).not.toContain("intro scene");+ });+it("rebases direct-entry authored asset paths before inlining", async () => {const spriteSvg = '<svg xmlns="http://www.w3.org/2000/svg"><circle r="4"/></svg>';const bgSvg = '<svg xmlns="http://www.w3.org/2000/svg"><rect width="8" height="8"/></svg>';diff --git a/packages/core/src/compiler/htmlBundler.ts b/packages/core/src/compiler/htmlBundler.tsindex e51c48a875..fd900e438b 100644--- a/packages/core/src/compiler/htmlBundler.ts+++ b/packages/core/src/compiler/htmlBundler.ts@@ -30,6 +30,7 @@ import { AsyncLocalStorage } from "async_hooks";import { readFileSync, existsSync, statSync } from "fs";import { parse as parseJs } from "acorn";import { resolve, relative, dirname, isAbsolute, sep } from "path";+import { extractStandaloneEntryFromIndex, isTemplateEntry } from "./standaloneEntry";import {decodeCssEscapes,decodeWellFormedEscapes,@@ -1004,13 +1005,29 @@ export function bundleToSingleHtml(projectDir: string, options?: BundleOptions):return options?.onRead ? bundleReads.run(options.onRead, bundle) : bundle();}+// A <template> scene has no root or GSAP of its own: bundle it inside the index that mounts it, as render does.+function readMountedSceneShell(+ projectDir: string,+ entryFile: string,+ entryHtml: string,+): string | null {+ if (!isTemplateEntry(entryHtml)) return null;+ const indexHtml = safeReadFile(resolve(projectDir, "index.html"));+ return indexHtml === null+ ? null+ : extractStandaloneEntryFromIndex(indexHtml, entryFile, entryHtml);+}+async function bundleProject(projectDir: string, options?: BundleOptions): Promise<string> {const entryFile = options?.entryFile ?? "index.html";const indexPath = resolveWithinProject(projectDir, entryFile);if (!indexPath || !existsSync(indexPath)) {throw new Error(`${entryFile} not found in project directory`);}- const sourceDir = dirname(indexPath);+ noteRead(indexPath);+ const entryHtml = readFileSync(indexPath, "utf-8");+ const mountedShell = readMountedSceneShell(projectDir, entryFile, entryHtml);+ const sourceDir = mountedShell ? projectDir : dirname(indexPath);const resolveEntryPath = (relativePath: string): string | null => {const resolved = resolve(sourceDir, relativePath);return isSafePath(projectDir, resolved) ? resolved : null;@@ -1019,11 +1036,10 @@ async function bundleProject(projectDir: string, options?: BundleOptions): Promiconst resolveEntryUrl = (url: string): string | null => resolveEntryPath(decodedUrlPath(url));const readSource = options?.stampHfIds ? ensureHfIds : (html: string) => html;- noteRead(indexPath);- const rawHtml = readSource(readFileSync(indexPath, "utf-8"));+ const rawHtml = readSource(mountedShell ?? entryHtml);const compiled = await compileHtml(rawHtml, sourceDir, options?.probeMediaDuration);- if (options?.staticGuard !== false) {+ if (options?.staticGuard !== false && !mountedShell) {const staticGuard = await validateHyperframeHtmlContract(compiled);if (!staticGuard.isValid) {console.warn(diff --git a/packages/core/src/compiler/index.ts b/packages/core/src/compiler/index.tsindex c8fda718af..4d83ee660f 100644--- a/packages/core/src/compiler/index.ts+++ b/packages/core/src/compiler/index.ts@@ -97,6 +97,7 @@ export {type InlineSubCompositionsOptions,type InlineSubCompositionsResult,} from "./inlineSubCompositions";+export { extractStandaloneEntryFromIndex, isTemplateEntry } from "./standaloneEntry";// Sub-composition usability check (shared between the inliner, lint, and the// render pre-flight abort) — single source of truth for "is thisdiff --git a/packages/core/src/compiler/standaloneEntry.test.ts b/packages/core/src/compiler/standaloneEntry.test.tsnew file mode 100644index 0000000000..448f427c40--- /dev/null+++ b/packages/core/src/compiler/standaloneEntry.test.ts@@ -0,0 +1,115 @@+import { describe, expect, it } from "vitest";+import { extractStandaloneEntryFromIndex } from "./standaloneEntry";++describe("extractStandaloneEntryFromIndex", () => {+ it("reuses the index wrapper and keeps only the requested composition host", () => {+ const indexHtml = `<!DOCTYPE html>+<html>+<head>+ <meta charset="utf-8">+ <style>body { background: #111; }</style>+</head>+<body>+ <div id="main" data-composition-id="root" data-width="1920" data-height="1080">+ <div id="intro" data-composition-id="intro" data-composition-src="compositions/intro.html" data-start="5"></div>+ <div id="outro" data-composition-id="outro" data-composition-src="compositions/outro.html" data-start="12"></div>+ </div>+</body>+</html>`;++ const extracted = extractStandaloneEntryFromIndex(indexHtml, "compositions/outro.html");++ expect(extracted).toContain('data-composition-id="root"');+ expect(extracted).toContain('id="outro"');+ expect(extracted).toContain('data-composition-src="compositions/outro.html"');+ expect(extracted).toContain('data-start="0"');+ expect(extracted).not.toContain('id="intro"');+ expect(extracted).toContain("<style>body { background: #111; }</style>");+ });++ it("keeps the index's body library scripts ahead of the scene and drops its inline scripts", () => {+ const indexHtml = `<!DOCTYPE html><html><head></head><body>+ <div id="main" data-composition-id="root" data-width="1920" data-height="1080">+ <div id="scene" data-composition-id="scene" data-composition-src="compositions/scene.html"></div>+ </div>+ <script src="https://cdn.example/gsap.min.js"></script>+ <script>window.__timelines = { root: gsap.timeline() };</script>+</body></html>`;++ const extracted = extractStandaloneEntryFromIndex(indexHtml, "compositions/scene.html") ?? "";++ expect(extracted).toContain('<script src="https://cdn.example/gsap.min.js"></script>');+ expect(extracted.indexOf("gsap.min.js")).toBeLessThan(extracted.indexOf('id="scene"'));+ expect(extracted).not.toContain("window.__timelines = { root");+ });++ it("matches normalized data-composition-src paths", () => {+ const indexHtml = `<!DOCTYPE html>+<html>+<body>+ <div data-composition-id="root" data-width="1920" data-height="1080">+ <div id="intro" data-composition-id="intro" data-composition-src="./compositions/intro.html" data-start="3"></div>+ </div>+</body>+</html>`;++ const extracted = extractStandaloneEntryFromIndex(indexHtml, "compositions/intro.html");++ expect(extracted).not.toBeNull();+ expect(extracted).toContain('data-start="0"');+ expect(extracted).toContain('data-composition-src="./compositions/intro.html"');+ });++ it("returns null when index.html does not mount the requested entry file", () => {+ const indexHtml = `<!DOCTYPE html>+<html>+<body>+ <div data-composition-id="root" data-width="1920" data-height="1080">+ <div id="intro" data-composition-id="intro" data-composition-src="compositions/intro.html"></div>+ </div>+</body>+</html>`;++ const extracted = extractStandaloneEntryFromIndex(indexHtml, "compositions/outro.html");++ expect(extracted).toBeNull();+ });++ it("re-points the wrapper duration at the scene's own, not the master's", () => {+ const indexHtml = `<!DOCTYPE html>+<html>+<body>+ <div data-composition-id="master" data-width="640" data-height="360" data-duration="12">+ <div id="scene1" data-composition-id="scene1" data-composition-src="compositions/scene1.html" data-start="0" data-duration="2"></div>+ </div>+</body>+</html>`;+ const sceneHtml = `<template id="scene1-template"><div data-composition-id="scene1" data-width="640" data-height="360" data-duration="3"></div></template>`;++ const extracted = extractStandaloneEntryFromIndex(+ indexHtml,+ "compositions/scene1.html",+ sceneHtml,+ );++ // The extracted standalone advertises the scene file's 3s, not the mount's 2s or master's 12s.+ expect(extracted).toContain('data-duration="3"');+ expect(extracted).not.toContain('data-duration="12"');+ });++ it("falls back to the mount's data-duration when the scene file isn't supplied", () => {+ const indexHtml = `<!DOCTYPE html>+<html>+<body>+ <div data-composition-id="master" data-width="640" data-height="360" data-duration="12">+ <div id="scene1" data-composition-id="scene1" data-composition-src="compositions/scene1.html" data-start="0" data-duration="2"></div>+ </div>+</body>+</html>`;++ const extracted = extractStandaloneEntryFromIndex(indexHtml, "compositions/scene1.html");++ expect(extracted).toContain('data-duration="2"');+ expect(extracted).not.toContain('data-duration="12"');+ });+});diff --git a/packages/core/src/compiler/standaloneEntry.ts b/packages/core/src/compiler/standaloneEntry.tsnew file mode 100644index 0000000000..b03435ac79--- /dev/null+++ b/packages/core/src/compiler/standaloneEntry.ts@@ -0,0 +1,87 @@+import { parseHTML } from "linkedom";++export function isTemplateEntry(html: string): boolean {+ return html.trimStart().startsWith("<template");+}++function normalizeCompositionSrcPath(srcPath: string): string {+ return srcPath.replace(/\\/g, "/").replace(/^\.\//, "");+}++// linkedom has no inert <template> content, so the template's innerHTML is re-parsed.+function readSceneRootDuration(entryHtml: string | undefined): string | null {+ if (!entryHtml) return null;+ const { document } = parseHTML(entryHtml);+ const template = document.querySelector("template");+ const scope = template ? parseHTML(template.innerHTML).document : document;+ const root = scope.querySelector("[data-composition-id]") as Element | null;+ return root?.getAttribute("data-duration") ?? null;+}++function createStandaloneEntryRenderClone(+ root: Element,+ host: Element,+ sceneDuration: string | null,+): Element {+ const hostClone = host.cloneNode(true) as Element;+ hostClone.setAttribute("data-start", "0");++ if (root === host) return hostClone;++ const rootClone = root.cloneNode(false) as Element;+ // The wrapper takes the scene's length, not the whole project's; with none declared+ // it derives from its single child.+ if (sceneDuration != null) {+ rootClone.setAttribute("data-duration", sceneDuration);+ } else {+ rootClone.removeAttribute("data-duration");+ }+ rootClone.appendChild(hostClone);+ return rootClone;+}++// Library scripts (GSAP and the like) may live in <body>; they stay, ahead of the scene that needs them.+function replaceBodyWithRenderClone(body: HTMLElement, renderClone: Element): void {+ const libraries = (Array.from(body.children) as Element[]).filter(+ (child) => child.tagName === "SCRIPT" && child.hasAttribute("src"),+ );+ while (body.firstChild) {+ body.removeChild(body.firstChild);+ }+ for (const library of libraries) body.appendChild(library);+ body.appendChild(renderClone);+}++export function extractStandaloneEntryFromIndex(+ indexHtml: string,+ entryFile: string,+ entryHtml?: string,+): string | null {+ const normalizedEntryFile = normalizeCompositionSrcPath(entryFile);+ const { document } = parseHTML(indexHtml);+ const body = document.querySelector("body");+ if (!body) return null;++ // linkedom types these lists as any/NodeList, hence the Element[] casts.+ const hosts = Array.from(document.querySelectorAll("[data-composition-src]")) as Element[];+ const host = hosts.find(+ (candidate) =>+ normalizeCompositionSrcPath(candidate.getAttribute("data-composition-src") || "") ===+ normalizedEntryFile,+ );+ if (!host) return null;++ const root =+ (Array.from(body.children) as Element[]).find((candidate) =>+ candidate.hasAttribute("data-composition-id"),+ ) ?? null;+ if (!root) return null;++ // The scene file owns its duration; the mount's window is the fallback.+ const sceneDuration = readSceneRootDuration(entryHtml) ?? host.getAttribute("data-duration");++ const renderClone = createStandaloneEntryRenderClone(root, host, sceneDuration);+ replaceBodyWithRenderClone(body, renderClone);++ return document.toString();+}diff --git a/packages/producer/src/services/renderOrchestrator.test.ts b/packages/producer/src/services/renderOrchestrator.test.tsindex 4a3d8b851d..9cbbbaf7a4 100644--- a/packages/producer/src/services/renderOrchestrator.test.ts+++ b/packages/producer/src/services/renderOrchestrator.test.ts@@ -28,7 +28,6 @@ import {explainStreamingEncodeGate,collectVideoMetadataHints,collectVideoReadinessSkipIds,- extractStandaloneEntryFromIndex,findMissingFrameRanges,getNextRetryWorkerCount,isRecoverableParallelCaptureError,@@ -101,103 +100,6 @@ describe("resolveRenderWorkDirPrefix", () => {});});-describe("extractStandaloneEntryFromIndex", () => {- it("reuses the index wrapper and keeps only the requested composition host", () => {- const indexHtml = `<!DOCTYPE html>-<html>-<head>- <meta charset="utf-8">- <style>body { background: #111; }</style>-</head>-<body>- <div id="main" data-composition-id="root" data-width="1920" data-height="1080">- <div id="intro" data-composition-id="intro" data-composition-src="compositions/intro.html" data-start="5"></div>- <div id="outro" data-composition-id="outro" data-composition-src="compositions/outro.html" data-start="12"></div>- </div>-</body>-</html>`;-- const extracted = extractStandaloneEntryFromIndex(indexHtml, "compositions/outro.html");-- expect(extracted).toContain('data-composition-id="root"');- expect(extracted).toContain('id="outro"');- expect(extracted).toContain('data-composition-src="compositions/outro.html"');- expect(extracted).toContain('data-start="0"');- expect(extracted).not.toContain('id="intro"');- expect(extracted).toContain("<style>body { background: #111; }</style>");- });-- it("matches normalized data-composition-src paths", () => {- const indexHtml = `<!DOCTYPE html>-<html>-<body>- <div data-composition-id="root" data-width="1920" data-height="1080">- <div id="intro" data-composition-id="intro" data-composition-src="./compositions/intro.html" data-start="3"></div>- </div>-</body>-</html>`;-- const extracted = extractStandaloneEntryFromIndex(indexHtml, "compositions/intro.html");-- expect(extracted).not.toBeNull();- expect(extracted).toContain('data-start="0"');- expect(extracted).toContain('data-composition-src="./compositions/intro.html"');- });-- it("returns null when index.html does not mount the requested entry file", () => {- const indexHtml = `<!DOCTYPE html>-<html>-<body>- <div data-composition-id="root" data-width="1920" data-height="1080">- <div id="intro" data-composition-id="intro" data-composition-src="compositions/intro.html"></div>- </div>-</body>-</html>`;-- const extracted = extractStandaloneEntryFromIndex(indexHtml, "compositions/outro.html");-- expect(extracted).toBeNull();- });-- it("re-points the wrapper duration at the scene's own, not the master's", () => {- const indexHtml = `<!DOCTYPE html>-<html>-<body>- <div data-composition-id="master" data-width="640" data-height="360" data-duration="12">- <div id="scene1" data-composition-id="scene1" data-composition-src="compositions/scene1.html" data-start="0" data-duration="2"></div>- </div>-</body>-</html>`;- const sceneHtml = `<template id="scene1-template"><div data-composition-id="scene1" data-width="640" data-height="360" data-duration="3"></div></template>`;-- const extracted = extractStandaloneEntryFromIndex(- indexHtml,- "compositions/scene1.html",- sceneHtml,- );-- // The extracted standalone advertises the scene file's 3s, not the mount's 2s or master's 12s.- expect(extracted).toContain('data-duration="3"');- expect(extracted).not.toContain('data-duration="12"');- });-- it("falls back to the mount's data-duration when the scene file isn't supplied", () => {- const indexHtml = `<!DOCTYPE html>-<html>-<body>- <div data-composition-id="master" data-width="640" data-height="360" data-duration="12">- <div id="scene1" data-composition-id="scene1" data-composition-src="compositions/scene1.html" data-start="0" data-duration="2"></div>- </div>-</body>-</html>`;-- const extracted = extractStandaloneEntryFromIndex(indexHtml, "compositions/scene1.html");-- expect(extracted).toContain('data-duration="2"');- expect(extracted).not.toContain('data-duration="12"');- });-});-describe("captureAttemptMadeProgress", () => {it("resets completed frames before a fallback attempt starts", () => {const job = { framesRendered: 900 };diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.tsindex 0e73cc855f..e30e15f46a 100644--- a/packages/producer/src/services/renderOrchestrator.ts+++ b/packages/producer/src/services/renderOrchestrator.ts@@ -43,7 +43,6 @@ import {appendFileSync,} from "fs";import { tmpdir } from "node:os";-import { parseHTML } from "linkedom";import {type CanvasResolution,type Fps,@@ -58,6 +57,7 @@ import {toFps,} from "@hyperframes/core";import { HF_AUDIO_GROUP_TAG } from "@hyperframes/core/audio-groups";+import { extractStandaloneEntryFromIndex, isTemplateEntry } from "@hyperframes/core/compiler";import { HTML_BODY_CSS_HEIGHT_FIRST_RE, HTML_BODY_CSS_WIDTH_FIRST_RE } from "@hyperframes/parsers";import {type EngineConfig,@@ -1427,62 +1427,6 @@ export function createRenderJob(config: RenderConfigInput): RenderJob {};}-function normalizeCompositionSrcPath(srcPath: string): string {- return srcPath.replace(/\\/g, "/").replace(/^\.\//, "");-}--/**- * Read the `data-duration` off a scene file's `<template>` root — the scene's- * own authored length. linkedom does not implement inert `<template>` content,- * so we re-parse `template.innerHTML` (the pattern htmlBundler uses) to reach- * the composition root inside it. Returns null when the file has no template- * or the root declares no duration.- */-function readSceneRootDuration(entryHtml: string | undefined): string | null {- if (!entryHtml) return null;- const { document } = parseHTML(entryHtml);- const template = document.querySelector("template");- const scope = template ? parseHTML(template.innerHTML).document : document;- const root = scope.querySelector("[data-composition-id]") as Element | null;- return root?.getAttribute("data-duration") ?? null;-}--function createStandaloneEntryRenderClone(- root: Element,- host: Element,- sceneDuration: string | null,-): Element {- // linkedom's cloneNode returns `any` (not `Node`), so the Element cast- // is needed to access setAttribute/appendChild without losing type safety.- const hostClone = host.cloneNode(true) as Element;- hostClone.setAttribute("data-start", "0");-- if (root === host) return hostClone;-- const rootClone = root.cloneNode(false) as Element;- // The standalone composition IS the mounted scene, not the master shell that- // wraps it. A shallow clone of the master root otherwise keeps the master's- // data-duration (the whole project's length), so `render -c <scene>` rendered- // the scene for the entire project duration — or threw "Composition has zero- // duration" when the master derived its length from siblings now removed.- // Re-point the wrapper's duration at the scene's own; drop it (derive from the- // single child) only when the scene declared none.- if (sceneDuration != null) {- rootClone.setAttribute("data-duration", sceneDuration);- } else {- rootClone.removeAttribute("data-duration");- }- rootClone.appendChild(hostClone);- return rootClone;-}--function replaceBodyWithRenderClone(body: HTMLElement, renderClone: Element): void {- while (body.firstChild) {- body.removeChild(body.firstChild);- }- body.appendChild(renderClone);-}-export type StreamingEncodeGateReason =| "disabled_by_config"| "format_excluded"@@ -2780,46 +2724,6 @@ export function shouldDiscardProbeSessionForPageSideCompositing(args: {* Main render pipeline*/-export function extractStandaloneEntryFromIndex(- indexHtml: string,- entryFile: string,- entryHtml?: string,-): string | null {- const normalizedEntryFile = normalizeCompositionSrcPath(entryFile);- const { document } = parseHTML(indexHtml);- const body = document.querySelector("body");- if (!body) return null;-- // linkedom's querySelectorAll returns `any` on Document and `NodeList` on- // the ParentNode mixin. Neither types the elements as `Element`, so the- // cast is required to call getAttribute / hasAttribute without `any`.- const hosts = Array.from(document.querySelectorAll("[data-composition-src]")) as Element[];- const host = hosts.find(- (candidate) =>- normalizeCompositionSrcPath(candidate.getAttribute("data-composition-src") || "") ===- normalizedEntryFile,- );- if (!host) return null;-- // linkedom's `children` is typed as `NodeList` (not `HTMLCollection<Element>`),- // so the Element[] cast is needed.- const root =- (Array.from(body.children) as Element[]).find((candidate) =>- candidate.hasAttribute("data-composition-id"),- ) ?? null;- if (!root) return null;-- // The scene file is the source of truth for its own duration; fall back to the- // mount's data-duration (its window in the master timeline) when the scene- // file content isn't supplied.- const sceneDuration = readSceneRootDuration(entryHtml) ?? host.getAttribute("data-duration");-- const renderClone = createStandaloneEntryRenderClone(root, host, sceneDuration);- replaceBodyWithRenderClone(body, renderClone);-- return document.toString();-}-/*** Telemetry fields a drawElement self-verify failure contributes to the* fallback record. Shared by the streaming and parallel-disk verify catches@@ -3090,7 +2994,7 @@ async function executeRenderPipeline(input: {// index.html shell and isolate the matching host instead of fabricating// a new standalone document.const rawEntry = readFileSync(htmlPath, "utf-8");- if (entryFile !== "index.html" && rawEntry.trimStart().startsWith("<template")) {+ if (entryFile !== "index.html" && isTemplateEntry(rawEntry)) {const wrapperPath = join(workDir, "standalone-entry.html");const projectIndexPath = join(projectDir, "index.html");if (!existsSync(projectIndexPath)) {