Files
hyperframes/packages/core/src/runtime/captionOverrides.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

282 lines
10 KiB
TypeScript

/**
* Caption Overrides — applies per-word style overrides from a JSON data file.
*
* Strategy: wrap each overridden word span in an inline-block wrapper span,
* then apply transforms to the wrapper. The inner span keeps all its original
* GSAP animations (entrance, karaoke, exit) untouched. No tweens are killed.
*
* Matching (in priority order):
* 1. `wordId` — matches by element ID (document.getElementById)
* 2. `wordIndex` — fallback, DOM traversal order across .caption-group > span
*/
import { isHtmlElement } from "./domRealm";
interface CaptionOverride {
wordId?: string;
wordIndex?: number;
x?: number;
y?: number;
scale?: number;
rotation?: number;
/** Color when the word is being spoken (karaoke active state) */
activeColor?: string;
/** Color before and after the word is spoken (dim/inactive state) */
dimColor?: string;
opacity?: number;
fontSize?: number;
fontWeight?: number;
fontFamily?: string;
}
function isCaptionOverride(value: unknown): value is CaptionOverride {
return typeof value === "object" && value !== null && !Array.isArray(value);
}
function parseCaptionOverridePayload(value: unknown): CaptionOverride[] {
if (!Array.isArray(value)) {
throw new Error("expected a JSON array");
}
if (!value.every(isCaptionOverride)) {
throw new Error("every array entry must be an object");
}
return value;
}
interface GsapTween {
vars: Record<string, unknown>;
startTime(): number;
invalidate?(): void;
}
interface GsapStatic {
set: (target: Element, vars: Record<string, unknown>) => void;
killTweensOf: (target: Element, props: string) => void;
getTweensOf: (target: Element) => GsapTween[];
}
/**
* The caption state a composition DECLARES for a colour tween, if any.
*
* Authored as `data: { captionState: "dim" | "active" }` in the tween's vars. GSAP passes unknown
* vars through untouched, so this costs a declaring composition nothing at runtime.
*
* It exists because the fallback below has to GUESS. Classifying by colour equality breaks outright
* when a composition's two states share a colour: every tween matches the rest colour, and the
* active override is silently dropped. A declaration is the composition telling us what it built,
* rather than us inferring it from what it happens to look like.
*/
function declaredCaptionState(tween: GsapTween): "dim" | "active" | undefined {
const data = tween.vars.data as { captionState?: unknown } | undefined;
const state = data?.captionState;
return state === "dim" || state === "active" ? state : undefined;
}
function resolveCaptionWordElement(el: Element | null): HTMLElement | null {
if (!isHtmlElement(el)) return null;
if (el.dataset.captionWrapper !== "true") return el;
const inner = el.querySelector<HTMLElement>(":scope > span");
return inner ?? null;
}
function getCaptionWordElements(): HTMLElement[] {
const wordEls: HTMLElement[] = [];
const groups = document.querySelectorAll(".caption-group");
for (const group of groups) {
for (const child of group.children) {
if (!isHtmlElement(child)) continue;
const wordEl =
child.dataset.captionWrapper === "true"
? child.querySelector<HTMLElement>(":scope > span")
: child.tagName === "SPAN"
? child
: null;
if (wordEl) wordEls.push(wordEl);
}
}
return wordEls;
}
function getOrCreateCaptionWrapper(el: HTMLElement): HTMLElement {
const parent = el.parentElement;
if (parent?.dataset.captionWrapper === "true") return parent;
const wrapper = document.createElement("span");
wrapper.style.display = "inline-block";
wrapper.dataset.captionWrapper = "true";
el.parentNode?.insertBefore(wrapper, el);
wrapper.appendChild(el);
return wrapper;
}
const gsapOf = () => (window as unknown as { gsap?: GsapStatic }).gsap;
const fetchOverridesPayload = (): Promise<unknown> =>
fetch("caption-overrides.json").then((r) => (r.ok ? r.json() : null));
const parseOverrides = (data: unknown): readonly CaptionOverride[] =>
data === null ? [] : parseCaptionOverridePayload(data);
function logInvalidOverrides(error: unknown): void {
const message = error instanceof Error ? error.message : String(error);
console.error(`[HyperFrames] Invalid caption-overrides.json: ${message}`);
}
/** The page's caption overrides; empty when there are none or no GSAP to apply them with. */
export function fetchCaptionOverrides(): Promise<readonly CaptionOverride[]> {
if (!gsapOf()) return Promise.resolve([]);
return fetchOverridesPayload()
.then(parseOverrides)
.catch((error: unknown) => {
logInvalidOverrides(error);
return [];
});
}
export function applyCaptionOverrides(
within?: readonly Element[],
beforeRewrite?: () => void,
): Promise<void> {
if (!gsapOf()) return Promise.resolve();
// Only fetch overrides if the composition has caption groups
if (document.querySelectorAll(".caption-group").length === 0) return Promise.resolve();
return fetchOverridesPayload()
.then((data) => applyFetchedCaptionOverrides(parseOverrides(data), within, beforeRewrite))
.catch(logInvalidOverrides);
}
function findOverrideTarget(override: CaptionOverride, wordEls: HTMLElement[]): HTMLElement | null {
const byId = override.wordId
? resolveCaptionWordElement(document.getElementById(override.wordId))
: null;
return byId ?? (override.wordIndex !== undefined ? (wordEls[override.wordIndex] ?? null) : null);
}
function definedProps(override: CaptionOverride, keys: (keyof CaptionOverride)[]) {
return Object.fromEntries(
keys.filter((key) => override[key] !== undefined).map((key) => [key, override[key]]),
);
}
// The colour the browser paints on `el` with `color` inline, so any spelling compares equal.
// An empty `color` reads the stylesheet colour past whatever GSAP has rendered inline.
function paintedColor(el: HTMLElement, color: string): string {
const inline = el.style.color;
el.style.color = color;
const painted = getComputedStyle(el).color;
el.style.color = inline;
return painted;
}
// What the word shows before it is spoken: its first colour tween's start colour (a fromTo()),
// else its stylesheet colour.
function restColorOf(el: HTMLElement, colorTweens: GsapTween[]): string {
const startAt = colorTweens[0]?.vars.startAt as { color?: unknown } | undefined;
return paintedColor(el, startAt?.color === undefined ? "" : String(startAt.color));
}
// A declaration wins, per tween; otherwise a tween back to the word's rest colour is dim.
// `painted` caches resolutions for one apply: tween colours repeat, and each forces a style recalc.
function tweenState(
tw: GsapTween,
el: HTMLElement,
rest: string,
painted: Map<string, string>,
): "dim" | "active" {
const declared = declaredCaptionState(tw);
if (declared) return declared;
const color = String(tw.vars.color);
// var() and currentColor resolve per word, so only plain colours are shared.
if (/var\(|currentcolor/i.test(color)) return paintedColor(el, color) === rest ? "dim" : "active";
if (!painted.has(color)) painted.set(color, paintedColor(el, color));
return painted.get(color) === rest ? "dim" : "active";
}
// What the invalidated tweens re-read their start from, wherever the playhead has been. A from()
// recorded its own start, and a word with no colour tween keeps its classes' colours.
function restPaintOf(
override: CaptionOverride,
colorTweens: GsapTween[],
rest: string,
): string | undefined {
if (override.dimColor) return override.dimColor;
if (colorTweens.length === 0 || colorTweens.some((tw) => tw.vars.runBackwards)) return undefined;
return rest;
}
function rewriteColorTweens(
gsap: GsapStatic,
el: HTMLElement,
override: CaptionOverride,
painted: Map<string, string>,
): void {
const colorTweens = gsap
.getTweensOf(el)
.filter((tw) => tw.vars.color !== undefined)
.sort((a, b) => a.startTime() - b.startTime());
const rest = restColorOf(el, colorTweens);
for (const tw of colorTweens) {
const state = tweenState(tw, el, rest, painted);
const color = state === "dim" ? override.dimColor : override.activeColor;
if (color) tw.vars.color = color;
// Each re-reads its start from the word as repainted below, rewritten or not.
// A from() re-read that way would end on that colour instead.
if (!tw.vars.runBackwards) tw.invalidate?.();
}
const restPaint = restPaintOf(override, colorTweens, rest);
if (restPaint) gsap.set(el, { color: restPaint });
}
function applyWordOverride(
gsap: GsapStatic,
el: HTMLElement,
override: CaptionOverride,
painted: Map<string, string>,
): void {
// Split into transform props (wrapper) and style props (word span)
const transformProps = definedProps(override, ["x", "y", "scale", "rotation"]);
const styleProps = definedProps(override, ["opacity", "fontWeight", "fontFamily"]);
if (override.fontSize !== undefined) styleProps.fontSize = `${override.fontSize}px`;
if (override.activeColor || override.dimColor) rewriteColorTweens(gsap, el, override, painted);
// Apply non-color style props
if (Object.keys(styleProps).length > 0) {
gsap.set(el, styleProps);
}
// Wrap the word in an inline-block span and apply transforms to the wrapper.
// This preserves all GSAP entrance/exit/karaoke animations on the inner span.
if (Object.keys(transformProps).length > 0) {
const wrapper = getOrCreateCaptionWrapper(el);
gsap.set(wrapper, transformProps);
}
}
export function applyFetchedCaptionOverrides(
overrides: readonly CaptionOverride[],
within?: readonly Element[],
beforeRewrite: () => void = () => {},
): void {
const gsap = gsapOf();
if (!gsap || overrides.length === 0) return;
beforeRewrite();
// Build word element index for wordIndex fallback
const wordEls = getCaptionWordElements();
const painted = new Map<string, string>();
for (const override of overrides) {
const el = findOverrideTarget(override, wordEls);
if (!el || (within && !within.some((root) => root.contains(el)))) continue;
applyWordOverride(gsap, el, override, painted);
}
}