Files
hyperframes/packages/core/src/runtime/applyVariableBindings.ts
T
Miguel Ángel cb8e7995a2 perf(runtime): swap edited scenes into the running preview from a rebuilt document (#4502)
* perf(runtime): swap edited scenes in place from a rebuilt preview document

window.__hfSwapScenes(html) compares the preview manifests. When the rebuilt document differs
only inside existing scenes, it replaces each changed scene's host, styles and scripts, drops
the old scene timelines (nested ones included), reruns the passes boot runs on scene DOM,
releases the old media, rebinds and keeps the playhead. Anything else rejects before touching
the film, so the caller does its full reload.

* fix(runtime): refuse unsafe scene swaps and redraw the swapped scene like a seek

The swap now refuses scenes marked unswappable or with more than one
host, keeps the style order, lets adapters find the new scene, redraws
through the transport seek and rejects when torn down mid-swap.

* fix(runtime): scope swap caption overrides to the swapped scene and swap only manifest pages

Other scenes kept re-dimmed caption words after a swap, and pages without
a scene manifest offered a swap that could only be refused.

* fix(runtime): repaint caption colours that were overridden after their tween rendered

A swapped scene, or a film reloaded mid-way, rendered its caption tweens
before the overrides rewrote their colours, so words kept the old colour.

* fix(runtime): repaint caption colours of a swapped scene the playhead has passed

* refactor(core): cut scene swap comments to what names and types do not say

* fix(runtime): a scene swap keeps other media loaded and waits for new media by reloading

* fix(runtime): a scene swap resolves bound and proxied media before refusing

The new-media check compared the new scene raw src against the live DOM, which variable
bindings and the media proxy have already rewritten. A scene with a customised data-var-src
logo, or a proxied video, was refused on every edit. Both sides now resolve src the same way:
the bound variable value, else the src attribute before any proxy swap, which the proxy now
records where it rewrites the src.

* fix(runtime): a scene swap binds variables only in the swapped scene, before media setup

The swap re-ran variable bindings over the whole document after binding media, so a proxied
video in any scene got its original, undecodable src back and a bound text in an untouched
scene was rewritten. Bindings now run only inside the swapped hosts and before media binding,
as boot does, and the src guard compares against the src the element had before its proxy.

* fix(runtime): a scene swap keeps unchanged video and audio playing

A text edit beside a video rebuilt the video from scratch, so it went blank until it loaded
again. A video or audio in the edited scene whose src matches one in the old scene (same src,
same order among those) is now the old element, moved into the new scene and given the new
element attributes and children, except src and the runtime-owned preload.

* fix(runtime): a scene swap refuses more new-media forms and names the scene

The new-media check missed uppercase URL(), image-set() and @import strings, SVG image href
and xlink:href, and object data, so a new asset could pop in after the swap. Its refusal now
says the media is new to this scene, which is what it checks. The existing inline style url(),
poster and srcset checks get tests of their own.

* fix(runtime): a scene swap loads caption overrides before changing the page

The swap wrote the new scene first and only then fetched caption-overrides.json, so a stalled
request left the preview half swapped when the caller gave up and reloaded. The overrides are
now fetched before the first write and applied from the fetched data. A swap that another swap
finished first while it waited now refuses, since its document is the older one.

* refactor(runtime): keep the proxy src record within the comment share

* fix(runtime): a scene swap keeps media only when the edit left it as written and ungraded

Keeping a live video or audio and copying the new attributes onto it was not the same as a
fresh load: muted only sets the initial state, and a graded video left its grading canvas in
the discarded scene, so it went black. The swap now keeps an element only when its authored
markup, captured before the runtime writes to it, equals the new one, and the grading runtime
says it is not graded. Anything else is rebuilt fresh; the attribute copy is gone.

* fix(runtime): a waiting scene swap refuses after any other swap changed the page

The check compared the scene manifest, which misses a scene changed and changed back while a
captioned swap waited for its overrides; that swap then went on with stale elements and wrote a
wrong manifest. A generation count the swap owns now moves on every page change by a swap, so
any intervening swap makes the waiting one refuse.

* fix(runtime): a scene swap warns about a non-media data-var-src once, as a load does

The new-media scan resolved every bound src through the warning path, so each swap logged the
ignored data-var-src again for the old and the new element. The scan now resolves silently and
only the bindings pass warns, once for the new element.

* refactor(runtime): keep the grading query within the comment share

* fix(runtime): a scene swap replaces each of a scene's styles in its own place

The bundle can now give one scene several style runs separated by another scene's, when its
nested scene comes later in source order. The swap put all new styles before the first old one,
so a later same-named @keyframes moved ahead of the other scene's and the cascade differed from a
fresh load and the render. Each new style now replaces its old counterpart in place, and a scene
whose style count differs is refused before any write.

* test(core): check the bundled stylesheets, not the inlined runtime, for a leftover @import

* fix(runtime): a video kept through a scene swap starts its new tweens from its authored values

* fix(runtime): a from() caption colour tween with an override still lights its word up

* fix(runtime): a scene swap reverts the old timelines, so a kept video shows the edited CSS

* fix(runtime): a caption word with a dim-colour override still lights up when spoken

* fix(runtime): a word whose colour override lands late still looks dim before it is spoken

* fix(runtime): a caption override keeps class highlights and resolves var() colours per word
2026-09-26 13:18:17 +00:00

196 lines
8.1 KiB
TypeScript

/**
* 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));
}
}