Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { existsSync, readFileSync } from "node:fs";
import { join } from "node:path";
import { parseHTML } from "linkedom";
import {
rewriteAssetPaths,
rewriteCssAssetUrls,
rewriteInlineStyleAssetUrls,
} from "@hyperframes/core";
import {
deferScriptsUntilFonts,
RUNTIME_BOOTSTRAP_ATTR,
stripEmbeddedRuntimeScripts,
} from "@hyperframes/core/compiler";
import { isFullHtmlDocument } from "@hyperframes/core/compiler/html-document";
import { gsapCdnDist } from "@hyperframes/core/gsap-cdn";
/**
* Rewrite relative asset paths in a parsed DOM tree. Shared across all
* three dispatch branches (template, full-doc, fragment) to avoid drift.
*
* The preview page borrows the project-root `<base>`, so a composition at
* `design/styleframes/frame-01.html` referencing its sibling `_shared.css` was
* requested as `/preview/_shared.css` (404). The frame then rendered unstyled,
* which the thumbnailer's transparent-body fallback painted dark navy — the
* "illegible styleframe thumbnail" bug. The `assetExists` probe re-points such
* refs at the composition's own directory; see `rewriteAssetPath`.
*/
function rewriteRelativePaths(root: ParentNode, compPath: string, projectDir: string): void {
const assetExists = (path: string) => existsSync(join(projectDir, path));
rewriteAssetPaths(
root.querySelectorAll("[src], [href]"),
compPath,
(el: Element, attr: string) => el.getAttribute(attr),
(el: Element, attr: string, value: string) => el.setAttribute(attr, value),
assetExists,
);
rewriteInlineStyleAssetUrls(
root.querySelectorAll("[style]"),
compPath,
(el: Element) => el.getAttribute("style"),
(el: Element, value: string) => el.setAttribute("style", value),
assetExists,
);
for (const styleEl of root.querySelectorAll("style")) {
styleEl.textContent = rewriteCssAssetUrls(styleEl.textContent || "", compPath, assetExists);
}
}
/**
* Escape a CSS identifier whose first character is a digit so it is a valid
* selector. A CSS ident cannot start with a digit, so it must be written as an
* escaped code point: `01-foo` → `\30 1-foo` (leading `0` → `\30 `, rest kept).
*
* Only the leading digit needs escaping (per CSS Syntax Level 3 §4.3.11): once
* the parser consumes the `\<hex> ` escape, the rest of the ident continues
* normally, so `123-scene` → `\31 23-scene` is valid (the `23-scene` tail is
* consumed as identifier continuation). The trailing space terminates the hex
* escape so a following hex digit isn't folded into the code point.
*/
function escapeLeadingDigitIdent(id: string): string {
return `\\${id.charCodeAt(0).toString(16)} ${id.slice(1)}`;
}
const REGEXP_SPECIALS = /[.*+?^${}()|[\]\\]/g;
/**
* Fix `#<digit-leading-id>` selectors in the tree's `<style>` blocks.
*
* CSS identifiers cannot start with a digit, so an authored rule like
* `#01-wall-pushes-back { width: 1920px; height: 1080px; background: #F0EBDE }`
* is an invalid selector and the browser silently drops the WHOLE rule — taking
* the root's size and background with it. In a full composition the frame is
* stretched/painted by its `data-composition-src` host so the collapse is
* masked, but a standalone preview has no host: the root falls back to
* `height: 0` + transparent and the frame renders blank (black).
*
* Rewrite each such selector to its escaped, valid form (`#\30 1-wall-pushes-back`,
* which still matches `id="01-wall-pushes-back"`) so the rule applies and the
* whole declaration block — size, background, position, container-type — comes
* back. Scoped to ids that are actually present on elements in the content and
* matched only as `#id` not followed by another ident char, so hex colors
* (`#1F2BE0`) and other values are never touched (they are not element ids).
*/
function fixDigitLeadingIdSelectors(root: ParentNode): void {
const digitIds = new Set<string>();
for (const el of root.querySelectorAll("[id]")) {
const id = el.getAttribute("id");
if (id && /^\d/.test(id)) digitIds.add(id);
}
if (digitIds.size === 0) return;
for (const styleEl of root.querySelectorAll("style")) {
let css = styleEl.textContent || "";
for (const id of digitIds) {
const pattern = new RegExp(`#${id.replace(REGEXP_SPECIALS, "\\$&")}(?![\\w-])`, "g");
css = css.replace(pattern, `#${escapeLeadingDigitIdent(id)}`);
}
styleEl.textContent = css;
}
}
/**
* Parse a full HTML document and extract its head elements and body
* content separately, so they can be reassembled into a clean standalone
* page without nesting `<html>` inside `<body>`.
*
* Extracts the full innerHTML of `<head>` — this preserves `<style>`,
* `<script>`, `<link>`, `<meta>`, and any other head-level tags the
* composition declares. Dropping `<link rel="stylesheet">` or `<meta>`
* would cause silent rendering failures for compositions that ship with
* external CSS or viewport-dependent meta.
*
* `<html>` and `<body>` attributes (lang, class, data-*) are extracted
* so callers can forward them to the assembled page.
*/
function extractFullDocumentParts(
rawHtml: string,
compPath: string,
projectDir: string,
): {
headContent: string;
bodyContent: string;
htmlAttrs: string;
bodyAttrs: string;
} {
const { document: doc } = parseHTML(rawHtml);
const rewriteTargets = [doc.head, doc.body].filter(Boolean);
for (const target of rewriteTargets) {
rewriteRelativePaths(target, compPath, projectDir);
}
// Run on the whole document: ids live in <body> but their rules may live in
// a <head> <style>, so the scope must span both.
fixDigitLeadingIdSelectors(doc);
const headContent = doc.head?.innerHTML ?? "";
const bodyContent = doc.body?.innerHTML ?? "";
const htmlEl = doc.documentElement;
const htmlAttrs = extractElementAttrs(htmlEl);
const bodyAttrs = doc.body ? extractElementAttrs(doc.body) : "";
return { headContent, bodyContent, htmlAttrs, bodyAttrs };
}
/**
* Extract the inner HTML of the composition's wrapping `<template>` element, or
* `null` if the source has no `<template>`.
*
* Located via the DOM rather than a regex. A greedy
* `/<template[^>]*>([\s\S]*)<\/template>/` can latch onto a literal
* `"<template>"` that appears inside an HTML comment — e.g. a head note such as
* "the HF runtime clones ONLY <template> contents" — and mis-slice the capture,
* leaving the real composition content re-wrapped in an inert `<template>` in
* the output. That template is never rendered by the browser, so the standalone
* preview has no `[data-composition-id]` element and no registered timeline, and
* renders blank. `querySelector("template")` only ever matches a real element
* node, so comment text can't fool it.
*/
function extractTemplateInnerHtml(rawComp: string): string | null {
const { document: doc } = parseHTML(rawComp);
const template = doc.querySelector("template");
return template ? template.innerHTML : null;
}
/** Attribute values read from the DOM are decoded — re-escape on rebuild or
* quote-bearing values (data-composition-variables is a JSON array) shred
* the wrapper's markup into bogus attributes. */
function escapeAttrValue(value: string): string {
return value.replace(/&/g, "&").replace(/"/g, """);
}
function extractElementAttrs(el: Element): string {
const parts: string[] = [];
for (let i = 0; i < el.attributes.length; i++) {
const attr = el.attributes[i]!;
if (attr.value === "") {
parts.push(attr.name);
} else {
parts.push(`${attr.name}="${escapeAttrValue(attr.value)}"`);
}
}
return parts.join(" ");
}
const NON_RENDERED_TAGS = new Set(["SCRIPT", "STYLE", "LINK", "META", "TEMPLATE", "NOSCRIPT"]);
/**
* Carry the `<template>`'s `data-composition-id` onto the content's root
* rendered element when the author declared it only on the `<template>` tag.
*
* In a full composition, each sub-composition is mounted under a wrapper
* element (the `data-composition-src` host) that carries the composition id,
* which is how the runtime binds `window.__timelines[id]` into the player's
* master timeline. A standalone preview has no such wrapper, so it relies on
* the frame's own root element carrying `data-composition-id`. If the id lives
* only on the inert `<template>` tag (a common authoring pattern), the rendered
* body has no `[data-composition-id]` element — the runtime then never selects
* a root composition, the registered GSAP timeline stays unbound, and seeking
* does nothing. The frame renders at its pre-animation state (GSAP `fromTo`
* pins `opacity:0`), producing a blank preview/thumbnail.
*
* This is a no-op when the content already exposes a `[data-composition-id]`
* element (e.g. the id is authored on the root div), so compositions that
* already render correctly are untouched.
*/
function promoteTemplateCompositionId(rawComp: string, body: Element): void {
// Two-step match instead of one `[^>]*\s…` regex: the single-pattern form
// backtracks polynomially on crafted input (CodeQL js/polynomial-redos).
// Step 1 grabs each <template …> open tag (linear); step 2 finds the attr
// within that short tag text.
let templateCompositionId: string | undefined;
for (const tag of rawComp.matchAll(/<template\b[^>]*/gi)) {
const id = /\bdata-composition-id\s*=\s*["']([^"']+)["']/i.exec(tag[0] ?? "")?.[1];
if (id) {
templateCompositionId = id;
break;
}
}
if (!templateCompositionId) return;
if (body.querySelector("[data-composition-id]")) return;
const root = Array.from(body.children).find((el) => !NON_RENDERED_TAGS.has(el.tagName));
root?.setAttribute("data-composition-id", templateCompositionId);
}
/**
* Add `data-composition-file="<compPath>"` to the comp's root composition
* element (the first `[data-composition-id]` that lacks the attribute), so the
* studio resolves its top-level elements to the right source file. Idempotent;
* a no-op when no composition element is present.
*/
function tagRootCompositionFile(bodyHtml: string, compPath: string): string {
const match = bodyHtml.match(/<[a-zA-Z][^>]*\bdata-composition-id=/);
if (match?.index == null) return bodyHtml;
const tagEnd = bodyHtml.indexOf(">", match.index);
if (tagEnd === -1) return bodyHtml;
if (bodyHtml.slice(match.index, tagEnd).includes("data-composition-file")) return bodyHtml;
return (
bodyHtml.slice(0, tagEnd) + ` data-composition-file="${compPath}"` + bodyHtml.slice(tagEnd)
);
}
export function rootHeadContent(rootHtml: string): string {
return rootHtml.match(/<head[^>]*>([\s\S]*?)<\/head>/i)?.[1] ?? "";
}
/**
* Build a standalone HTML page for a sub-composition.
*
* Uses the project's own index.html `<head>` so all dependencies (GSAP, fonts,
* Lottie, reset styles, runtime) are preserved — instead of building a minimal
* page from scratch that would miss important scripts/styles.
*
* Three dispatch modes, tried in order:
* 1. `<template>` wrapper → extract template content (existing compositions)
* 2. Full HTML document → parse and extract head/body separately (registry blocks)
* 3. Raw fragment → wrap in a minimal document
*
* For full-doc mode, the composition's own `<head>` content (styles, scripts,
* links, meta) is appended AFTER the project's index.html head. When both
* declare the same dependency (e.g. GSAP CDN), the composition's copy wins
* by last-write-wins script execution order — this is intentional so the
* composition can pin a specific version.
*/
export function buildSubCompositionHtml(
projectDir: string,
compPath: string,
runtimeUrl: string,
baseHref?: string,
rawOverride?: string,
): string | null {
const compFile = join(projectDir, compPath);
if (!existsSync(compFile)) return null;
// rawOverride lets the preview route thread the hf-id-stamped content in
// directly, so the build uses ids minted from the raw file, which is never
// written by serving.
const rawComp = rawOverride ?? readFileSync(compFile, "utf-8");
let compHeadContent = "";
let rewrittenContent: string;
let htmlAttrs = "";
let bodyAttrs = "";
const templateInner = extractTemplateInnerHtml(rawComp);
if (templateInner != null) {
const { document: contentDoc } = parseHTML(
`<!DOCTYPE html><html><head></head><body>${templateInner}</body></html>`,
);
rewriteRelativePaths(contentDoc, compPath, projectDir);
fixDigitLeadingIdSelectors(contentDoc);
promoteTemplateCompositionId(rawComp, contentDoc.body);
rewrittenContent = contentDoc.body.innerHTML || templateInner;
} else if (isFullHtmlDocument(rawComp)) {
const parts = extractFullDocumentParts(rawComp, compPath, projectDir);
compHeadContent = parts.headContent;
rewrittenContent = parts.bodyContent;
htmlAttrs = parts.htmlAttrs;
bodyAttrs = parts.bodyAttrs;
} else {
const { document: contentDoc } = parseHTML(
`<!DOCTYPE html><html><head></head><body>${rawComp}</body></html>`,
);
rewriteRelativePaths(contentDoc, compPath, projectDir);
fixDigitLeadingIdSelectors(contentDoc);
rewrittenContent = contentDoc.body.innerHTML || rawComp;
}
// A composition file may ship a baked inline runtime (from a prior export:
// data-hyperframes-runtime / __hyperframeRuntime…). The studio injects its own
// preview runtime below, so strip the baked one from the body — otherwise it's
// double-loaded AND the baked inline copy can fail to parse inline (the
// "Unexpected token '<'" SyntaxError seen on comps with a baked runtime).
rewrittenContent = stripEmbeddedRuntimeScripts(rewrittenContent);
const { document: scriptsDoc } = parseHTML(
`<!DOCTYPE html><html><head></head><body>${rewrittenContent}</body></html>`,
);
deferScriptsUntilFonts(scriptsDoc as unknown as Document);
rewrittenContent = scriptsDoc.body.innerHTML;
// The comp's root carries data-composition-id but (unlike inlined sub-comps,
// which inlineSubCompositions tags) no data-composition-file. Without it the
// studio can't resolve which file this comp's top-level elements live in and
// falls back to "index.html" — so the GSAP panel parses the project root (which
// may be a multi-timeline master) and wrongly reports "multiple timelines",
// disabling editing for a single-timeline comp. Tag the root with its own path.
rewrittenContent = tagRootCompositionFile(rewrittenContent, compPath);
// Use the project's index.html <head> to preserve all dependencies
const indexPath = join(projectDir, "index.html");
let headContent = "";
if (existsSync(indexPath)) headContent = rootHeadContent(readFileSync(indexPath, "utf-8"));
// Inject <base> for relative asset resolution (before other tags)
if (baseHref && !hasBaseElement(headContent)) {
headContent = `<base href="${baseHref}">\n${headContent}`;
}
// Append the sub-composition's own <head> content so its CSS, scripts,
// links, and meta tags are preserved. Placed after the project head so
// the composition's deps take precedence (last-write-wins for scripts).
if (compHeadContent) headContent += `\n${compHeadContent}`;
// Strip any baked runtime the borrowed index/comp <head> carried, for the same
// reason as the body above — done before injecting the preview runtime so the
// injected tag (added next) is never removed.
headContent = stripEmbeddedRuntimeScripts(headContent);
headContent += `\n<script ${RUNTIME_BOOTSTRAP_ATTR}="1" src="${runtimeUrl}"></script>`;
// Fallback: if no index.html head was found, add minimal deps
if (!headContent.includes("gsap")) {
headContent += `\n<script src="${gsapCdnDist()}gsap.min.js"></script>`;
}
const htmlOpen = htmlAttrs ? `<html ${htmlAttrs}>` : "<html>";
const bodyOpen = bodyAttrs ? `<body ${bodyAttrs}>` : "<body>";
return `<!DOCTYPE html>
${htmlOpen}
<head>
${headContent}
</head>
${bodyOpen}
<script>window.__timelines=window.__timelines||{};</script>
${rewrittenContent}
</body>
</html>`;
}
/** True for a real `<base>` element; the text "<base" inside a script or comment does not count. */
export function hasBaseElement(html: string): boolean {
return parseHTML(html).document.querySelector("base") !== null;
}