Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
/**
* Declarative variable bindings — the no-script consumption channel for
* composition variables (values are fixed for the page's lifetime, so this is
* seek-safe and deterministic):
*
* - `data-var-src="id"` — sets the element's `src` from the variable value
* (a URL string or an image value `{url}`). Only allowed on media elements
* (img/video/audio/source) and only for safe URL protocols — a src on a
* script-executing tag or a `javascript:`/`data:text/html` value is refused.
* The authored src stays as the fallback when the variable resolves to nothing.
* - `data-var-text="id"` — sets the element's OWN text from a scalar variable
* value. Elements with element children keep them: only the direct text
* node is replaced, mirroring the SDK's setOwnText semantics — a text
* binding must never delete nested clips or animation targets.
* - Every scalar variable (and a font value's family name) is applied as a
* `--{id}` CSS custom property on its composition root, so CSS bindings
* like `color: var(--accent)` respond to render/preview overrides instead
* of only the persisted default.
*
* Values resolve against the element's owning composition — the same scope
* chain the color-grading runtime uses: `__hfVariablesByComp[compId]` for
* inlined sub-compositions, then the top-level merged `getVariables()`.
*
* Applied at init AND re-applied after the composition loader inlines
* external / template sub-compositions (their DOM and per-instance scoped
* values don't exist at init). Idempotent: re-applying writes the same
* values.
*/
import { readVariablesForElement } from "./variableScope";
import {
isScalarVariableValue as isScalar,
isSafeMediaUrl,
} from "@hyperframes/parsers/composition";
import { isHtmlElement } from "./domRealm";
import { unproxiedSrc } from "./proxySrc";
// data-var-src only rebinds media `src` on media elements. A user-controlled
// variable value assigned to a src is an XSS surface on tags whose src executes
// (`<iframe src="javascript:…">`, `<script src="data:…">`, `<embed>`), so the
// binding is scoped to elements where `src` is purely a media reference.
const VAR_SRC_TAGS = new Set(["img", "video", "audio", "source"]);
function resolveUrl(value: unknown): string | null {
if (typeof value === "string" && value.length > 0) return value;
if (value !== null && typeof value === "object") {
const url = (value as { url?: unknown }).url;
if (typeof url === "string" && url.length > 0) return url;
}
return null;
}
/**
* Strip characters that could smuggle additional declarations or markup out of
* a var() substitution site. A scalar value folded into `background: var(--x)`
* or `background-image: url(var(--x))` must not be able to close the declaration
* and inject a new one (`red; background: url(//evil?data=…)`) — none of these
* characters is legal in a scalar variable value (string, number, color, font
* family), so removing them is lossless for real inputs and neutralizes the
* declaration/URL-exfiltration channel.
*
* Exported because the static compiler bakes the same scalars into a stylesheet
* at build time and has to reach the same result: a value that the runtime
* strips but a compile-time emit passes through would make the rendered MP4
* differ from the preview, which is the more dangerous of the two directions.
*/
export function sanitizeCssValue(value: string): string {
return value.replace(/[;{}<>\r\n]/g, "");
}
/** CSS custom-property value for a variable, or null when not CSS-applicable. */
function cssValueFor(value: unknown): string | null {
if (isScalar(value)) return String(value);
if (value !== null && typeof value === "object") {
// Font values apply their family name; the face itself must be loaded by
// the composition (or the media pipeline).
const name = (value as { name?: unknown }).name;
if (typeof name === "string" && name.length > 0) return name;
}
return null;
}
/**
* Per-run memo of scope element → resolved values, so N bound elements in
* one scope pay for one resolution (the top-level path re-parses the
* declarations attribute on every getVariables() call).
*/
type ScopeValuesCache = Map<Element | null, Record<string, unknown>>;
function valuesForElement(el: Element, cache: ScopeValuesCache): Record<string, unknown> {
const scope = el.closest("[data-composition-id]");
const cached = cache.get(scope);
if (cached) return cached;
const values = readVariablesForElement(el);
cache.set(scope, values);
return values;
}
/**
* Replace the element's own text while preserving element children (nested
* clips, animation-target spans). Mirrors the SDK's setOwnText: write the
* first direct text node, clear the others; append when none exists.
*/
function setOwnTextPreservingChildren(el: Element, text: string): void {
if (el.childElementCount === 0) {
el.textContent = text;
return;
}
let written = false;
for (const node of Array.from(el.childNodes)) {
if (node.nodeType !== Node.TEXT_NODE) continue;
node.nodeValue = written ? "" : text;
written = true;
}
if (!written) {
el.insertBefore(el.ownerDocument.createTextNode(text), el.firstChild);
}
}
/**
* Composition root, matching the SDK's findRoot chain exactly — the SDK
* persists `--{id}` defaults on this element, so the runtime must write
* overrides to the SAME element or an inline default on a descendant would
* shadow an override applied higher up.
*/
function findTopRoot(doc: Document): Element | null {
return (
doc.querySelector("[data-hf-root]") ??
doc.getElementById("stage") ??
doc.body?.firstElementChild ??
doc.body
);
}
// Custom props inherit, so each composition root carries its own scope's values.
function applyCssCustomProperties(roots: Iterable<Element>, cache: ScopeValuesCache): void {
for (const root of new Set(roots)) {
const values = valuesForElement(root, cache);
for (const [id, value] of Object.entries(values)) {
const css = cssValueFor(value);
if (css !== null && isHtmlElement(root)) {
root.style.setProperty(`--${id}`, sanitizeCssValue(css));
}
}
}
}
function variableSrcFor(el: Element, cache: ScopeValuesCache, warn = true): string | null {
const id = el.getAttribute("data-var-src")?.trim();
if (!id) return null;
// Only media elements may take a variable-driven src (see VAR_SRC_TAGS) — a
// src on <iframe>/<script>/<embed> is a code-execution sink, not a media ref.
if (!VAR_SRC_TAGS.has(el.tagName.toLowerCase())) {
if (warn)
console.warn(
`[hyperframes] Ignoring data-var-src on <${el.tagName.toLowerCase()}>: variable-bound src is only allowed on ${Array.from(VAR_SRC_TAGS).join("/")}.`,
);
return null;
}
const url = resolveUrl(valuesForElement(el, cache)[id]);
if (url === null) return null;
if (!isSafeMediaUrl(url)) {
if (warn) console.warn(`[hyperframes] Ignoring data-var-src="${id}": unsafe URL protocol.`);
return null;
}
return url;
}
/** The src an element loads, preview proxy aside: its bound variable's value, else its attribute. */
export function unproxiedMediaSrc(el: Element): string | null {
return variableSrcFor(el, new Map(), false) ?? unproxiedSrc(el);
}
/** Applies the bindings in `doc`, or only those inside `within` and `within` itself. */
export function applyVariableBindings(doc: Document, within?: Element): void {
const cache: ScopeValuesCache = new Map();
const all = (selector: string): Element[] =>
within
? [...(within.matches(selector) ? [within] : []), ...within.querySelectorAll(selector)]
: Array.from(doc.querySelectorAll(selector));
const topRoot = within ? null : findTopRoot(doc);
applyCssCustomProperties([...(topRoot ? [topRoot] : []), ...all("[data-composition-id]")], cache);
for (const el of all("[data-var-src]")) {
const url = variableSrcFor(el, cache);
if (url !== null && unproxiedSrc(el) !== url) el.setAttribute("src", url);
}
for (const el of all("[data-var-text]")) {
const id = el.getAttribute("data-var-text")?.trim();
if (!id) continue;
const value = valuesForElement(el, cache)[id];
if (isScalar(value)) setOwnTextPreservingChildren(el, String(value));
}
}