Files
hyperframes/packages/core/src/runtime/positionEdits.ts
T
Miguel Ángel 080d2c7445 fix(runtime): make the preview's scene swap safe before Studio turns it on (#4542)
* fix(runtime): a scene swap refuses when an animation outside the scene moves its elements

* test(runtime): pin the scene swap volume re-probe, host CSS variables and diagnostics-free swap

* fix(runtime): a scene swap keeps a video its scene script animates instead of reloading it

* fix(runtime): a scene swap stops every animation the old scene script started

* fix(runtime): record scene script animations only on pages a scene swap can act on

* docs(core): reword the scene animation recording comment

* fix(runtime): watch media as the page parses only on pages a scene swap can act on

* perf(runtime): a scene swap checks for outside tweens in one pass over the film's tweens

* test(runtime): pin the single revert and the cleared animation record of a scene swap

* fix(runtime): a scene swap rebuilds media when the edit changes the scene script

* fix(runtime): a scene swap undoes the sets a scene script made

* fix(runtime): a scene swap rechecks outside tweens and runs new scripts after every host

* test(runtime): pin that a tween started during the caption wait leaves the page untouched

* fix(runtime): a scene swap refuses when its script set a value on an element the swap keeps

* docs(core): say the scene recording drops a finished tween that the timeline would keep when paused

* fix(runtime): a scene swap refuses when two of its animations write to an element it keeps

* fix(runtime): a scene swap resets kept media and refuses animations outside the scene

* fix(runtime): a scene swap keeps a moved video in place and swaps tweens on plain objects

* chore(core): regenerate the inlined position-edits script for the kept-video move reapply

* fix(runtime): a scene swap checks the timeline registry as it is after the caption wait

* fix(runtime): a scene swap refuses when a scene changed during the wait or a revert re-registers

* fix(runtime): a scene swap stops every animation a revert chain registers and rechecks its hosts

* fix(runtime): a scene swap refuses a moved host or a cancelled swap and stops at a shortened end

* fix(runtime): a scene swap refuses when a scene leaves its place or the film during the wait

* fix(runtime): a scene swap checks only its host's place, so a later body append does not refuse it

* fix(runtime): a scene swap refuses when the film's scene layout changed during the wait

* fix(runtime): a scene swap refuses when the order around a scene changed during the wait

* test(runtime): pin that a scene swap checks the film root order when every scene is wrapped

* fix(runtime): a scene swap gives kept media the mute, rate and loop a fresh load gives it

* fix(runtime): a scene swap rebuilds media a script wrote attributes on, keeping the rest

* fix(runtime): a scene swap keeps media carrying the runtime classes or reordered attributes

* fix(runtime): a scene swap resets a kept video's volume as a load does, not through the volume probe
2026-09-28 08:49:12 +00:00

343 lines
14 KiB
TypeScript

// fallow-ignore-file code-duplication
// (splitTopLevelWhitespace intentionally mirrors the studio-side copies in
// manualEditsDom.ts / manualEditsRenderScript.ts — this module ships inside
// the self-contained runtime bundle and cannot import studio code.)
/**
* Editor position edits (SDK `moveElement`) applied at render time.
*
* The SDK's `moveElement` writes `data-x` / `data-y` plus a captured baseline
* (`data-hf-edit-base-x` / `data-hf-edit-base-y` — the values before the first
* edit). The runtime renders the edit as the DELTA between the two, via the
* independent CSS `translate` longhand, so it composes additively with any
* position the composition itself produces (GSAP tweens, `tl.set`, CSS).
*
* Why `translate` and why after timeline bind: GSAP folds a `translate` that
* is present when it FIRST parses an element into its cached transform (and
* an absolute tween then discards it on the animated axis — the per-axis loss
* bug). A `translate` set AFTER that parse is never read, cleared, or baked
* by GSAP 3.x on subsequent seeks, so a single application at bind time holds
* for the whole timeline. Before the first apply, the element's transform
* parse is primed (gsap.getProperty) so tweens and positioned set()s that
* first RENDER later reuse the cache instead of folding the edit. Known
* limitation: if GSAP itself loads only after the apply ran, a later tween's
* first parse still folds the edit (the fold guard then skips re-apply and
* emits position_edit_fold_skipped instead of double-applying).
*/
import { emitAnalyticsEvent } from "./analytics";
import { isStylableElement } from "./domRealm";
export const EDIT_BASE_X_ATTR = "data-hf-edit-base-x";
export const EDIT_BASE_Y_ATTR = "data-hf-edit-base-y";
export const EDIT_ORIGINAL_TRANSLATE_ATTR = "data-hf-edit-original-translate";
/**
* Elements a position edit can apply to: HTML elements AND SVG graphics (authored `<text>` labels,
* shapes, groups). Both expose `.style` and honor the CSS `translate` longhand in modern Chrome, so
* the same delta→translate compose logic works for either. (SVG was previously excluded by an
* `instanceof HTMLElement`-only guard, which silently dropped every move on an SVG element.)
*/
type StylableElement = HTMLElement | SVGElement;
const num = (value: string | null): number => {
const n = parseFloat(value ?? "");
return Number.isFinite(n) ? n : 0;
};
/** Split "10px 20px" / "calc(1px + 2px) 3px" on top-level whitespace only. */
const splitTopLevelWhitespace = (value: string): string[] => {
const parts: string[] = [];
let depth = 0;
let current = "";
for (const char of value.trim()) {
if (char === "(") depth += 1;
if (char === ")") depth = Math.max(0, depth - 1);
if (/\s/.test(char) && depth === 0) {
if (current) parts.push(current);
current = "";
} else {
current += char;
}
}
if (current) parts.push(current);
return parts;
};
const PX_VALUE = /^-?(?:\d+(?:\.\d+)?|\.\d+)px$/;
/** Sum two lengths — numerically when both are plain px, via calc() otherwise. */
const addLengths = (a: string, b: string): string => {
if (PX_VALUE.test(a) && PX_VALUE.test(b)) return `${parseFloat(a) + parseFloat(b)}px`;
return `calc(${a} + ${b})`;
};
/** Compose the edit delta with the element's pre-edit translate value. */
export const composeTranslate = (original: string, x: string, y: string): string => {
if (!original || original === "none") return `${x} ${y}`;
const [ox, oy, oz] = splitTopLevelWhitespace(original);
if (ox === undefined) return `${x} ${y}`;
if (oy === undefined) return `${addLengths(ox, x)} ${y}`;
const z = oz === undefined ? "" : ` ${oz}`;
return `${addLengths(ox, x)} ${addLengths(oy, y)}${z}`;
};
/**
* Force GSAP (when present) to parse and cache the element's transform BEFORE
* the edit translate is written. GSAP folds a CSS `translate` it sees at an
* element's first parse into its cached transform (losing it per-axis on
* absolute tweens); once the cache exists, later tweens and positioned set()s
* reuse it and never read the translate again. gsap.getProperty parses
* without mutating the element. Best-effort — absent or failing GSAP is fine.
*/
const primeGsapTransformCache = (el: StylableElement): void => {
try {
const view = el.ownerDocument.defaultView as
| (Window & { gsap?: { getProperty?: (t: Element, p: string) => unknown } })
| null;
view?.gsap?.getProperty?.(el, "x");
} catch {
// parse priming is an optimization, never a requirement
}
};
/** The element's effective translate: inline if set, computed otherwise ("" = none). */
export const readCurrentTranslate = (el: StylableElement): string => {
const inline = el.style.getPropertyValue("translate").trim();
if (inline) return inline === "none" ? "" : inline;
try {
const view = el.ownerDocument.defaultView;
const computed = view ? view.getComputedStyle(el).getPropertyValue("translate").trim() : "";
return computed === "none" ? "" : computed;
} catch {
return "";
}
};
/**
* The translate value this module last wrote per element. When a re-apply
* (timeline rebind) finds the element's inline translate no longer matching,
* something else consumed it — in practice GSAP folding it into the cached
* transform when a lazily-created tween first-parsed the element. Re-setting
* it then would DOUBLE the offset on every axis the tween doesn't animate, so
* the non-forced path skips instead (degrading to the documented fold-loss).
*/
const lastAppliedTranslate = new WeakMap<StylableElement, string>();
/** For an element whose inline style was reset: its next application runs as the first did. */
export function forgetPositionEdit(el: StylableElement): void {
lastAppliedTranslate.delete(el);
}
/**
* Apply one element's position edit. Idempotent — the pre-edit translate is
* captured exactly once (into EDIT_ORIGINAL_TRANSLATE_ATTR, empty string
* meaning "none") on first application, and every application recomputes from
* that baseline.
*
* `force` re-applies even when the previously written translate was clobbered
* externally — used by editor commits, where the current inline translate is
* the draft-composed one and must be overwritten.
*/
export function applyPositionEditToElement(el: StylableElement, opts?: { force?: boolean }): void {
const previous = lastAppliedTranslate.get(el);
if (
!opts?.force &&
previous !== undefined &&
el.style.getPropertyValue("translate") !== previous
) {
// Observable signal for the documented degradation — without it, a
// fold-loss surfaces to users only as "my edit didn't stick".
emitAnalyticsEvent("position_edit_fold_skipped", {
hfId: el.getAttribute("data-hf-id"),
});
return;
}
const dx = num(el.getAttribute("data-x")) - num(el.getAttribute(EDIT_BASE_X_ATTR));
const dy = num(el.getAttribute("data-y")) - num(el.getAttribute(EDIT_BASE_Y_ATTR));
if (!el.hasAttribute(EDIT_ORIGINAL_TRANSLATE_ATTR)) {
el.setAttribute(EDIT_ORIGINAL_TRANSLATE_ATTR, readCurrentTranslate(el));
}
if (previous === undefined) primeGsapTransformCache(el);
const original = el.getAttribute(EDIT_ORIGINAL_TRANSLATE_ATTR) ?? "";
const value = composeTranslate(original, `${dx}px`, `${dy}px`);
el.style.setProperty("translate", value);
lastAppliedTranslate.set(el, el.style.getPropertyValue("translate"));
}
/**
* Apply all pending position edits in the document. Returns the number of
* elements updated.
*
* Runs the RESET path first: an element still carrying the captured pre-edit
* translate marker (EDIT_ORIGINAL_TRANSLATE_ATTR) but NO base attrs had its
* edit undone — the attrs were removed, so it no longer matches the apply
* selector, and the inline translate written by an earlier application would
* stay orphaned (the element visually displaced after its edit was reverted).
* Restore the captured translate and clear the marker so a later redo
* re-captures a clean baseline.
*
* `force` forwards to applyPositionEditToElement: re-apply even when the
* previously written translate was clobbered externally. Hosts replaying
* undo/redo should force — after a reset the fold-guard's bookkeeping no
* longer matches and the non-forced path would silently skip the redo.
*/
export function applyPositionEdits(doc: Document, opts?: { force?: boolean }): number {
// `isStylableElement` covers HTML **and** SVG (SVG `<text>`/shapes are positioned via the same
// CSS `translate` longhand; an HTML-only check silently dropped every SVG move), and it is
// realm-independent, which this needs to be twice over: `doc` is frequently an iframe's document
// (the SDK's edit preview, a host embedding a composition), AND its elements are not necessarily
// from that iframe's realm either — see domRealm.ts.
const orphaned = doc.querySelectorAll(
`[${EDIT_ORIGINAL_TRANSLATE_ATTR}]:not([${EDIT_BASE_X_ATTR}]):not([${EDIT_BASE_Y_ATTR}])`,
);
for (let i = 0; i < orphaned.length; i++) {
const el = orphaned[i];
if (el === undefined || !isStylableElement(el)) continue;
const original = el.getAttribute(EDIT_ORIGINAL_TRANSLATE_ATTR) ?? "";
if (original === "") {
el.style.removeProperty("translate");
} else {
el.style.setProperty("translate", original);
}
el.removeAttribute(EDIT_ORIGINAL_TRANSLATE_ATTR);
lastAppliedTranslate.delete(el);
}
const marked = doc.querySelectorAll(`[${EDIT_BASE_X_ATTR}], [${EDIT_BASE_Y_ATTR}]`);
let applied = 0;
for (let i = 0; i < marked.length; i++) {
const el = marked[i];
if (el === undefined || !isStylableElement(el)) continue;
applyPositionEditToElement(el, opts);
applied += 1;
}
return applied;
}
const SEEK_REAPPLY_WRAPPED = "__hfPositionEditsSeekReapplyWrapped";
type SeekFunction = (...args: unknown[]) => unknown;
const wrappedSeekFunctions = new WeakSet<SeekFunction>();
const observedSeekProperties = new WeakMap<object, Set<string>>();
const observedGlobalProperties = new WeakMap<object, Set<string>>();
type SeekWindow = Window &
typeof globalThis & {
__hf?: { seek?: (...args: unknown[]) => unknown };
__player?: { renderSeek?: (...args: unknown[]) => unknown };
};
/** Reapply SDK position edits after every render seek, including late-bound seeks. */
export function installPositionEditsSeekReapply(win: Window & typeof globalThis): void {
const target = win as SeekWindow;
const reapply = (): void => {
try {
applyPositionEdits(target.document);
} catch {
// A position edit must never break the render seek path.
}
};
const isWrapped = (fn: unknown): fn is SeekFunction =>
typeof fn === "function" &&
(wrappedSeekFunctions.has(fn as SeekFunction) ||
Boolean((fn as { [SEEK_REAPPLY_WRAPPED]?: boolean })[SEEK_REAPPLY_WRAPPED]));
const markWrapped = (fn: SeekFunction): void => {
wrappedSeekFunctions.add(fn);
try {
Object.defineProperty(fn, SEEK_REAPPLY_WRAPPED, { value: true });
} catch {
// The WeakSet keeps frozen functions from being wrapped repeatedly.
}
};
const wrapFunction = (fn: unknown): unknown => {
if (typeof fn !== "function" || isWrapped(fn)) return fn;
const wrapped: SeekFunction = function (this: unknown, ...args: unknown[]): unknown {
const result = fn.apply(this, args);
reapply();
return result;
};
markWrapped(wrapped);
return wrapped;
};
const observeSeekProperty = (container: object, property: string): boolean => {
let observed = observedSeekProperties.get(container);
if (observed?.has(property)) return true;
const descriptor = Object.getOwnPropertyDescriptor(container, property);
if (descriptor?.configurable === false) {
const current = (container as Record<string, unknown>)[property];
if (typeof current === "function") {
(container as Record<string, unknown>)[property] = wrapFunction(current);
reapply();
}
return false;
}
let current = (container as Record<string, unknown>)[property];
const originalSetter = descriptor?.set;
Object.defineProperty(container, property, {
configurable: true,
enumerable: descriptor?.enumerable ?? true,
get: () => current,
set: (value: unknown) => {
current = wrapFunction(value);
originalSetter?.call(container, value);
},
});
current = wrapFunction(current);
observed ??= new Set<string>();
observed.add(property);
observedSeekProperties.set(container, observed);
reapply();
return true;
};
const observeGlobalContainer = (
name: "__hf" | "__player",
property: "seek" | "renderSeek",
): boolean => {
let globals = observedGlobalProperties.get(target);
const descriptor = Object.getOwnPropertyDescriptor(target, name);
if (!globals?.has(name)) {
if (descriptor?.configurable === false) {
const current = target[name];
return current ? observeSeekProperty(current, property) : false;
}
let value = target[name];
Object.defineProperty(target, name, {
configurable: true,
enumerable: descriptor?.enumerable ?? true,
get: () => value,
set: (next: unknown) => {
value = next as typeof value;
if (value) observeSeekProperty(value, property);
},
});
globals ??= new Set<string>();
globals.add(name);
observedGlobalProperties.set(target, globals);
}
const current = target[name];
return current ? observeSeekProperty(current, property) : false;
};
const wrapAll = (): boolean => {
const hfObserved = observeGlobalContainer("__hf", "seek");
const playerObserved = observeGlobalContainer("__player", "renderSeek");
return hfObserved && playerObserved;
};
if (wrapAll()) return;
let remaining = 120;
const interval = target.setInterval(() => {
if (wrapAll()) {
target.clearInterval(interval);
return;
}
remaining -= 1;
if (remaining <= 0) target.clearInterval(interval);
}, 50);
}