Skip to content

Write HTML. Render video. Built for agents.

fix(runtime): make the preview's scene swap safe before Studio turns it on (#4542)

Miguel Ángel080d2c7445e6
diff --git a/packages/core/src/compiler/compositionScoping.test.ts b/packages/core/src/compiler/compositionScoping.test.ts
index af89545bde..9c6e82d547 100644
--- a/packages/core/src/compiler/compositionScoping.test.ts
+++ b/packages/core/src/compiler/compositionScoping.test.ts
@@ -439,6 +439,75 @@ window.__timelines.scene = tl;
expect(gsapTargets).toEqual([["Scene"], ["Scene"]]);
});
+ it.each([
+ ["records", `<meta name="hf-scene-parts" content="{}">`, true],
+ ["on a page no scene swap can act on, records nothing of", "", false],
+ ])(
+ "%s what a script starts on GSAP's global timeline, however it reaches GSAP",
+ (_, head, records) => {
+ const { document } = parseHTML(
+ `<html><head>${head}</head><body><div data-composition-id="scene"><p>x</p></div></body></html>`,
+ );
+ const children: object[] = [{ startedBefore: true }];
+ const start = () => {
+ const animation = { to: () => animation };
+ children.push(animation);
+ return animation;
+ };
+ const gsap = {
+ globalTimeline: { getChildren: () => [...children] },
+ timeline: start,
+ to: start,
+ };
+ const fakeWindow: Record<string, unknown> = { document, __timelines: {}, gsap };
+ const wrapped = wrapScopedCompositionScript(
+ `
+gsap.timeline().to("p", { x: 1 });
+const g = gsap; g.to("p", { x: 1 });
+gsap["to"]("p", { x: 1 });
+window.gsap.to("p", { x: 1 });
+globalThis.gsap.to("p", { x: 1 });
+`,
+ "scene",
+ );
+ vi.stubGlobal("gsap", gsap);
+ try {
+ new Function("window", "gsap", wrapped)(fakeWindow, gsap);
+ } finally {
+ vi.unstubAllGlobals();
+ }
+ expect(children).toHaveLength(6);
+ expect(fakeWindow.__hfSceneAnimations ?? null).toEqual(
+ records ? { scene: children.slice(1) } : null,
+ );
+ },
+ );
+
+ it("records a set, which completes as it is made, without leaving it on GSAP's global timeline", () => {
+ const { document } = parseHTML(
+ `<html><head><meta name="hf-scene-parts" content="{}"></head><body><div data-composition-id="scene"><p>x</p></div></body></html>`,
+ );
+ const children: object[] = [];
+ // As the library does: the global timeline drops each animation the moment it completes.
+ const globalTimeline = {
+ autoRemoveChildren: true,
+ getChildren: () => [...children],
+ remove: (child: object) => void children.splice(children.indexOf(child), 1),
+ };
+ const set = () => {
+ const tween = { totalProgress: () => 1 };
+ if (!globalTimeline.autoRemoveChildren) children.push(tween);
+ return tween;
+ };
+ const gsap = { globalTimeline, set };
+ const fakeWindow: Record<string, unknown> = { document, __timelines: {}, gsap };
+ const wrapped = wrapScopedCompositionScript(`gsap.set("p", { opacity: 0 });`, "scene");
+ new Function("window", "gsap", wrapped)(fakeWindow, gsap);
+ expect(fakeWindow.__hfSceneAnimations).toEqual({ scene: [expect.any(Object)] });
+ expect(children).toEqual([]);
+ expect(globalTimeline.autoRemoveChildren).toBe(true);
+ });
+
it("scopes each selector in a GSAP target array to the composition root", () => {
const { document } = parseHTML(`
<div data-composition-id="scene">
diff --git a/packages/core/src/compiler/compositionScoping.ts b/packages/core/src/compiler/compositionScoping.ts
index 235ee63460..5cfc34dfd0 100644
--- a/packages/core/src/compiler/compositionScoping.ts
+++ b/packages/core/src/compiler/compositionScoping.ts
@@ -1,4 +1,5 @@
import postcss, { type AtRule, type Node, type Rule } from "postcss";
+import { SCENE_PARTS_META } from "../sceneParts";
const AUTHORED_ROOT_ID_ATTR = "data-hf-authored-id";
const INNER_ROOT_ATTR = "data-hf-inner-root";
@@ -694,8 +695,33 @@ ${source.replace(/<\/(script)/gi, "<\\/$1")}
console.error(__hfErrorLabel, __hfCompId, _err);
}
};
+ // What the script started on the global gsap timeline, by any route, for a scene swap to revert.
+ // Only a page with a scene manifest can swap; elsewhere the first script stores null and none records.
+ var __hfRecordAnimations = function(run) {
+ if (window.__hfSceneAnimations === undefined) {
+ window.__hfSceneAnimations = window.document.querySelector(${jsonScriptLiteral(`meta[name="${SCENE_PARTS_META}"]`)})
+ ? {}
+ : null;
+ }
+ var byComp = window.__hfSceneAnimations;
+ var globalTimeline = __hfBaseGsap && __hfBaseGsap.globalTimeline;
+ if (!byComp || !globalTimeline || !__hfTimelineCompId) return run();
+ var before = globalTimeline.getChildren(false);
+ // A set completes as it is made and would leave the timeline before the diff below.
+ var autoRemove = globalTimeline.autoRemoveChildren;
+ globalTimeline.autoRemoveChildren = false;
+ run();
+ globalTimeline.autoRemoveChildren = autoRemove;
+ var recorded = (byComp[__hfTimelineCompId] = byComp[__hfTimelineCompId] || []);
+ globalTimeline.getChildren(false).forEach(function(animation) {
+ if (before.indexOf(animation) >= 0) return;
+ recorded.push(animation);
+ // Dropped as the timeline drops a finished tween (it keeps a paused one); moved back, a tween re-adds itself.
+ if (autoRemove && !animation.getChildren && animation.totalProgress() === 1) globalTimeline.remove(animation);
+ });
+ };
__hfFindRoot();
- __hfRun();
+ __hfRecordAnimations(__hfRun);
})();`;
}
diff --git a/packages/core/src/generated/position-edits-render-inline.ts b/packages/core/src/generated/position-edits-render-inline.ts
index c5a2e45243..0ac371ffd0 100644
--- a/packages/core/src/generated/position-edits-render-inline.ts
+++ b/packages/core/src/generated/position-edits-render-inline.ts
@@ -1,6 +1,6 @@
// AUTO-GENERATED by scripts/build-position-edits-render.ts - do not edit
const POSITION_EDITS_RENDER_IIFE: string =
- '"use strict";(()=>{function T(){return globalThis}function P(e,t){if(typeof window>"u")return;let o=T(),r=o.__hf?.onSwallowed;if(r)try{r({label:e,error:t})}catch(s){}(o.__hfDebug||o.__HYPERFRAMES_DEBUG)&&console.debug(`[hyperframes] ${e} swallowed:`,t)}var x=null;function R(e,t){if(x)try{x({source:"hf-preview",type:"analytics",event:e,properties:t??{}})}catch(o){P("runtime.analytics.site1",o)}}var W="http://www.w3.org/1999/xhtml";function N(e){return e!=null&&e.nodeType===1}function _(e){return N(e)&&(e.namespaceURI===W||e.namespaceURI==="http://www.w3.org/2000/svg")}var w="data-hf-edit-base-x",y="data-hf-edit-base-y",m="data-hf-edit-original-translate",k=e=>{let t=parseFloat(e??"");return Number.isFinite(t)?t:0},O=e=>{let t=[],o=0,r="";for(let s of e.trim())s==="("&&(o+=1),s===")"&&(o=Math.max(0,o-1)),/\\s/.test(s)&&o===0?(r&&t.push(r),r=""):r+=s;return r&&t.push(r),t},L=/^-?(?:\\d+(?:\\.\\d+)?|\\.\\d+)px$/,b=(e,t)=>L.test(e)&&L.test(t)?`${parseFloat(e)+parseFloat(t)}px`:`calc(${e} + ${t})`,V=(e,t,o)=>{if(!e||e==="none")return`${t} ${o}`;let[r,s,a]=O(e);if(r===void 0)return`${t} ${o}`;if(s===void 0)return`${b(r,t)} ${o}`;let i=a===void 0?"":` ${a}`;return`${b(r,t)} ${b(s,o)}${i}`},j=e=>{try{e.ownerDocument.defaultView?.gsap?.getProperty?.(e,"x")}catch{}},G=e=>{let t=e.style.getPropertyValue("translate").trim();if(t)return t==="none"?"":t;try{let o=e.ownerDocument.defaultView,r=o?o.getComputedStyle(e).getPropertyValue("translate").trim():"";return r==="none"?"":r}catch{return""}},E=new WeakMap;function B(e,t){let o=E.get(e);if(!t?.force&&o!==void 0&&e.style.getPropertyValue("translate")!==o){R("position_edit_fold_skipped",{hfId:e.getAttribute("data-hf-id")});return}let r=k(e.getAttribute("data-x"))-k(e.getAttribute(w)),s=k(e.getAttribute("data-y"))-k(e.getAttribute(y));e.hasAttribute(m)||e.setAttribute(m,G(e)),o===void 0&&j(e);let a=e.getAttribute(m)??"",i=V(a,`${r}px`,`${s}px`);e.style.setProperty("translate",i),E.set(e,e.style.getPropertyValue("translate"))}function S(e,t){let o=e.querySelectorAll(`[${m}]:not([${w}]):not([${y}])`);for(let a=0;a<o.length;a++){let i=o[a];if(i===void 0||!_(i))continue;let g=i.getAttribute(m)??"";g===""?i.style.removeProperty("translate"):i.style.setProperty("translate",g),i.removeAttribute(m),E.delete(i)}let r=e.querySelectorAll(`[${w}], [${y}]`),s=0;for(let a=0;a<r.length;a++){let i=r[a];i===void 0||!_(i)||(B(i,t),s+=1)}return s}var $="__hfPositionEditsSeekReapplyWrapped",D=new WeakSet,M=new WeakMap,H=new WeakMap;function F(e){let t=e,o=()=>{try{S(t.document)}catch{}},r=n=>typeof n=="function"&&(D.has(n)||!!n[$]),s=n=>{D.add(n);try{Object.defineProperty(n,$,{value:!0})}catch{}},a=n=>{if(typeof n!="function"||r(n))return n;let l=function(...u){let d=n.apply(this,u);return o(),d};return s(l),l},i=(n,l)=>{let u=M.get(n);if(u?.has(l))return!0;let d=Object.getOwnPropertyDescriptor(n,l);if(d?.configurable===!1){let c=n[l];return typeof c=="function"&&(n[l]=a(c),o()),!1}let p=n[l],f=d?.set;return Object.defineProperty(n,l,{configurable:!0,enumerable:d?.enumerable??!0,get:()=>p,set:c=>{p=a(c),f?.call(n,c)}}),p=a(p),u??(u=new Set),u.add(l),M.set(n,u),o(),!0},g=(n,l)=>{let u=H.get(t),d=Object.getOwnPropertyDescriptor(t,n);if(!u?.has(n)){if(d?.configurable===!1){let c=t[n];return c?i(c,l):!1}let f=t[n];Object.defineProperty(t,n,{configurable:!0,enumerable:d?.enumerable??!0,get:()=>f,set:c=>{f=c,f&&i(f,l)}}),u??(u=new Set),u.add(n),H.set(t,u)}let p=t[n];return p?i(p,l):!1},v=()=>{let n=g("__hf","seek"),l=g("__player","renderSeek");return n&&l};if(v())return;let h=120,A=t.setInterval(()=>{if(v()){t.clearInterval(A);return}h-=1,h<=0&&t.clearInterval(A)},50)}function I(){document.querySelector(`[${w}], [${y}]`)&&(S(document),F(window))}document.readyState==="loading"?document.addEventListener("DOMContentLoaded",I,{once:!0}):I();})();\n';
+ '"use strict";(()=>{function T(){return globalThis}function P(e,t){if(typeof window>"u")return;let o=T(),r=o.__hf?.onSwallowed;if(r)try{r({label:e,error:t})}catch(s){}(o.__hfDebug||o.__HYPERFRAMES_DEBUG)&&console.debug(`[hyperframes] ${e} swallowed:`,t)}var x=null;function R(e,t){if(x)try{x({source:"hf-preview",type:"analytics",event:e,properties:t??{}})}catch(o){P("runtime.analytics.site1",o)}}var W="http://www.w3.org/1999/xhtml";function N(e){return e!=null&&e.nodeType===1}function _(e){return N(e)&&(e.namespaceURI===W||e.namespaceURI==="http://www.w3.org/2000/svg")}var w="data-hf-edit-base-x",y="data-hf-edit-base-y",m="data-hf-edit-original-translate",k=e=>{let t=parseFloat(e??"");return Number.isFinite(t)?t:0},O=e=>{let t=[],o=0,r="";for(let s of e.trim())s==="("&&(o+=1),s===")"&&(o=Math.max(0,o-1)),/\\s/.test(s)&&o===0?(r&&t.push(r),r=""):r+=s;return r&&t.push(r),t},L=/^-?(?:\\d+(?:\\.\\d+)?|\\.\\d+)px$/,E=(e,t)=>L.test(e)&&L.test(t)?`${parseFloat(e)+parseFloat(t)}px`:`calc(${e} + ${t})`,V=(e,t,o)=>{if(!e||e==="none")return`${t} ${o}`;let[r,s,a]=O(e);if(r===void 0)return`${t} ${o}`;if(s===void 0)return`${E(r,t)} ${o}`;let i=a===void 0?"":` ${a}`;return`${E(r,t)} ${E(s,o)}${i}`},j=e=>{try{e.ownerDocument.defaultView?.gsap?.getProperty?.(e,"x")}catch{}},G=e=>{let t=e.style.getPropertyValue("translate").trim();if(t)return t==="none"?"":t;try{let o=e.ownerDocument.defaultView,r=o?o.getComputedStyle(e).getPropertyValue("translate").trim():"";return r==="none"?"":r}catch{return""}},b=new WeakMap;function B(e,t){let o=b.get(e);if(!t?.force&&o!==void 0&&e.style.getPropertyValue("translate")!==o){R("position_edit_fold_skipped",{hfId:e.getAttribute("data-hf-id")});return}let r=k(e.getAttribute("data-x"))-k(e.getAttribute(w)),s=k(e.getAttribute("data-y"))-k(e.getAttribute(y));e.hasAttribute(m)||e.setAttribute(m,G(e)),o===void 0&&j(e);let a=e.getAttribute(m)??"",i=V(a,`${r}px`,`${s}px`);e.style.setProperty("translate",i),b.set(e,e.style.getPropertyValue("translate"))}function S(e,t){let o=e.querySelectorAll(`[${m}]:not([${w}]):not([${y}])`);for(let a=0;a<o.length;a++){let i=o[a];if(i===void 0||!_(i))continue;let g=i.getAttribute(m)??"";g===""?i.style.removeProperty("translate"):i.style.setProperty("translate",g),i.removeAttribute(m),b.delete(i)}let r=e.querySelectorAll(`[${w}], [${y}]`),s=0;for(let a=0;a<r.length;a++){let i=r[a];i===void 0||!_(i)||(B(i,t),s+=1)}return s}var $="__hfPositionEditsSeekReapplyWrapped",D=new WeakSet,M=new WeakMap,H=new WeakMap;function F(e){let t=e,o=()=>{try{S(t.document)}catch{}},r=n=>typeof n=="function"&&(D.has(n)||!!n[$]),s=n=>{D.add(n);try{Object.defineProperty(n,$,{value:!0})}catch{}},a=n=>{if(typeof n!="function"||r(n))return n;let l=function(...u){let d=n.apply(this,u);return o(),d};return s(l),l},i=(n,l)=>{let u=M.get(n);if(u?.has(l))return!0;let d=Object.getOwnPropertyDescriptor(n,l);if(d?.configurable===!1){let c=n[l];return typeof c=="function"&&(n[l]=a(c),o()),!1}let p=n[l],f=d?.set;return Object.defineProperty(n,l,{configurable:!0,enumerable:d?.enumerable??!0,get:()=>p,set:c=>{p=a(c),f?.call(n,c)}}),p=a(p),u??(u=new Set),u.add(l),M.set(n,u),o(),!0},g=(n,l)=>{let u=H.get(t),d=Object.getOwnPropertyDescriptor(t,n);if(!u?.has(n)){if(d?.configurable===!1){let c=t[n];return c?i(c,l):!1}let f=t[n];Object.defineProperty(t,n,{configurable:!0,enumerable:d?.enumerable??!0,get:()=>f,set:c=>{f=c,f&&i(f,l)}}),u??(u=new Set),u.add(n),H.set(t,u)}let p=t[n];return p?i(p,l):!1},v=()=>{let n=g("__hf","seek"),l=g("__player","renderSeek");return n&&l};if(v())return;let h=120,A=t.setInterval(()=>{if(v()){t.clearInterval(A);return}h-=1,h<=0&&t.clearInterval(A)},50)}function I(){document.querySelector(`[${w}], [${y}]`)&&(S(document),F(window))}document.readyState==="loading"?document.addEventListener("DOMContentLoaded",I,{once:!0}):I();})();\n';
/** Returns the pre-built position-edits render IIFE as a string constant. */
export function getPositionEditsRenderScript(): string {
diff --git a/packages/core/src/runtime/entry.ts b/packages/core/src/runtime/entry.ts
index 58c86985c0..cd8cf63196 100644
--- a/packages/core/src/runtime/entry.ts
+++ b/packages/core/src/runtime/entry.ts
@@ -1,4 +1,4 @@
-import { initSandboxRuntimeModular } from "./init";
+import { initSandboxRuntimeModular, installAuthoredMediaCapture } from "./init";
import { installAuthoredOpacityCapture } from "./colorGrading";
import { hideTimedClipsUntilFirstPass } from "./timedClipHide";
import { fitTextFontSize } from "../text/fitTextFontSize";
@@ -28,6 +28,7 @@ type HyperframeWindow = Window & {
// composition's animation scripts (and the grading hide) mutate it — must run
// at script evaluation time, while the document is still parsing.
installAuthoredOpacityCapture();
+installAuthoredMediaCapture();
hideTimedClipsUntilFirstPass();
diff --git a/packages/core/src/runtime/init.swapScenes.test.ts b/packages/core/src/runtime/init.swapScenes.test.ts
index e26e1f13ed..246e5981da 100644
--- a/packages/core/src/runtime/init.swapScenes.test.ts
+++ b/packages/core/src/runtime/init.swapScenes.test.ts
@@ -1,8 +1,12 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { initSandboxRuntimeModular } from "./init";
+import { initSandboxRuntimeModular, installAuthoredMediaCapture } from "./init";
import type { RuntimeTimelineLike } from "./types";
import { resetRuntimeDataForTests } from "./runtimeData";
+import { WebAudioTransport } from "./webAudioTransport";
import { probeAndCacheElementVolume } from "./mediaVolumeEnvelope.js";
+import { wrapScopedCompositionScript } from "../compiler/compositionScoping";
vi.mock("./mediaVolumeEnvelope.js", async (importOriginal) => {
const actual = await importOriginal<typeof import("./mediaVolumeEnvelope.js")>();
@@ -20,6 +24,17 @@ vi.mock("./colorGrading", async (importOriginal) => {
};
});
+// The library itself, the repo's vendored 3.15.0, for what a stand-in would only assume.
+const vendoredGsap = () =>
+ join(
+ dirname(expect.getState().testPath!),
+ "../../../../skills/music-to-video/references/motion-primitives/assets/gsap.min.js",
+ );
+type RealGsap = {
+ ticker: { sleep: () => void };
+ getProperty: (target: Element, property: string) => unknown;
+};
+
type Tl = RuntimeTimelineLike & { kill: ReturnType<typeof vi.fn>; label: string };
function tl(label: string, duration = 2): Tl {
@@ -67,6 +82,7 @@ interface Scene {
label: string;
hash: string;
extraAttrs?: string;
+ script?: string;
}
function preview(scenes: Scene[], shared = "s1", sharedMarkup = "") {
@@ -87,7 +103,10 @@ function preview(scenes: Scene[], shared = "s1", sharedMarkup = "") {
.join("") +
`</div>` +
scenes
- .map((s) => `<script data-hf-scene="${s.id}">${sceneScript(s.id, s.label)}</script>`)
+ .map(
+ (s) =>
+ `<script data-hf-scene="${s.id}">${sceneScript(s.id, s.label)}${s.script ?? ""}</script>`,
+ )
.join("");
return {
head,
@@ -114,7 +133,7 @@ const B: Scene = {
};
const A2: Scene = { ...A1, body: "<p>A two</p>", css: ".a{color:green}", label: "a2", hash: "ha2" };
-function boot(scenes: Scene[], root: Tl, editHead = (head: string) => head) {
+function mount(scenes: Scene[], root: Tl, editHead = (head: string) => head) {
const { head, body } = preview(scenes);
document.head.innerHTML = editHead(head);
document.body.innerHTML = body;
@@ -128,6 +147,10 @@ function boot(scenes: Scene[], root: Tl, editHead = (head: string) => head) {
new Function(node.textContent ?? "")();
return node;
};
+}
+
+function boot(scenes: Scene[], root: Tl, editHead = (head: string) => head) {
+ mount(scenes, root, editHead);
initSandboxRuntimeModular();
}
@@ -151,18 +174,19 @@ const cssText = () =>
[...document.head.querySelectorAll("style")].map((s) => s.textContent).join("");
// Boots A1 and B, then starts swapping in a captioned A whose caption overrides have not arrived.
-async function bootWithPendingCaptions() {
+async function bootWithPendingCaptions(signal?: AbortSignal, arrange = () => {}, others = [B]) {
const { root } = trackingRoot();
(window as unknown as { gsap: unknown }).gsap = { set: () => {} };
let answer: (r: Response) => void = () => {};
vi.spyOn(globalThis, "fetch").mockImplementation(
() => new Promise<Response>((resolve) => (answer = resolve)),
);
- boot([A1, B], root);
+ boot([A1, ...others], root);
await tick();
+ arrange();
const before = document.documentElement.innerHTML;
const captions: Scene = { ...A2, body: '<div class="caption-group"><span>w</span></div>' };
- const swap = window.__hfSwapScenes!(preview([captions, B]).html);
+ const swap = window.__hfSwapScenes!(preview([captions, ...others]).html, signal);
return { swap, before, answer: (r: Response) => answer(r) };
}
@@ -187,6 +211,8 @@ describe("__hfSwapScenes", () => {
document.body.innerHTML = "";
delete scoped.__hfVariablesByComp;
delete window.__HF_MEDIA_CODEC_MAP__;
+ delete window.__hfSceneAnimations;
+ vi.unstubAllGlobals();
vi.restoreAllMocks();
});
@@ -449,36 +475,310 @@ describe("__hfSwapScenes", () => {
expect(video?.getAttribute("preload")).toBe("auto");
});
+ it("does not watch a page without a scene manifest as it parses", () => {
+ const observe = vi.spyOn(MutationObserver.prototype, "observe");
+ installAuthoredMediaCapture();
+ expect(observe).not.toHaveBeenCalled();
+ });
+
+ it("stops watching the page it parses once the runtime starts", () => {
+ const observe = vi.spyOn(MutationObserver.prototype, "observe");
+ const disconnect = vi.spyOn(MutationObserver.prototype, "disconnect");
+ document.head.innerHTML = preview([A1, B]).head;
+ installAuthoredMediaCapture();
+ const watcher = observe.mock.contexts[0];
+ boot([A1, B], trackingRoot().root);
+ expect(watcher).toBeDefined();
+ expect(disconnect.mock.contexts).toContain(watcher);
+ });
+
+ it("keeps a video a scene script wrote to while the page parsed", async () => {
+ const { root } = trackingRoot();
+ quietMedia();
+ const scene = (text: string, hash: string): Scene => ({
+ ...A1,
+ hash,
+ body: `<p>${text}</p><video src="clip.mp4"></video>`,
+ });
+ document.head.innerHTML = preview([A1, B]).head;
+ installAuthoredMediaCapture();
+ mount([scene("A one", "ha1"), B], root);
+ await tick();
+ const video = sceneHost("a").querySelector("video")!;
+ // A tl.from() in the scene script writes its start value when the timeline is built.
+ video.style.opacity = "0";
+ initSandboxRuntimeModular();
+ await tick();
+ await window.__hfSwapScenes!(preview([scene("A two", "ha2"), B]).html);
+ expect(sceneHost("a").querySelector("video")).toBe(video);
+ });
+
+ it("records a video's <source> children that the parser adds after the video itself", async () => {
+ const { root } = trackingRoot();
+ quietMedia();
+ const scene = (text: string, hash: string): Scene => ({
+ ...A1,
+ hash,
+ body: `<p>${text}</p><video><source src="clip.mp4"></video>`,
+ });
+ document.head.innerHTML = preview([A1, B]).head;
+ installAuthoredMediaCapture();
+ mount([scene("A one", "ha1"), B], root);
+ const video = sceneHost("a").querySelector("video")!;
+ const source = video.querySelector("source")!;
+ // The parser yields with the video's children still to come.
+ source.remove();
+ await tick();
+ video.appendChild(source);
+ await tick();
+ initSandboxRuntimeModular();
+ await tick();
+ await window.__hfSwapScenes!(preview([scene("A two", "ha2"), B]).html);
+ expect(sceneHost("a").querySelector("video")).toBe(video);
+ });
+
+ it("keeps a rebuilt video through the next edit though its scene script writes to it", async () => {
+ const { root } = trackingRoot();
+ quietMedia();
+ const scene = (text: string, attrs: string, hash: string): Scene => ({
+ ...A1,
+ hash,
+ body: `<p>${text}</p><video src="clip.mp4" ${attrs}></video>`,
+ script: `document.querySelector('[data-hf-scene="a"] video').style.opacity = "0";`,
+ });
+ boot([scene("A one", "", "ha1"), B], root);
+ await tick();
+ await window.__hfSwapScenes!(preview([scene("A two", "muted", "ha2"), B]).html);
+ const rebuilt = sceneHost("a").querySelector("video");
+ await window.__hfSwapScenes!(preview([scene("A three", "muted", "ha3"), B]).html);
+ expect(sceneHost("a").querySelector("video")).toBe(rebuilt);
+ });
+
+ it("rebuilds a video whose scene script the edit changed, dropping what the old script wrote to it", async () => {
+ const { root } = trackingRoot();
+ quietMedia();
+ const write = `const v = document.querySelector('[data-hf-scene="a"] video'); v.style.opacity = "0"; v.muted = true;`;
+ const scene = (text: string, script: string, hash: string): Scene => ({
+ ...A1,
+ hash,
+ body: `<p>${text}</p><video src="clip.mp4"></video>`,
+ script,
+ });
+ boot([scene("A one", write, "ha1"), B], root);
+ new Function(document.querySelector('script[data-hf-scene="a"]')!.textContent!)();
+ await tick();
+ await window.__hfSwapScenes!(preview([scene("A two", "", "ha2"), B]).html);
+ const video = sceneHost("a").querySelector("video")!;
+ expect([video.style.opacity, video.muted]).toEqual(["", false]);
+ });
+
+ const writesOnlyOverTheFirstHeading = (write: string) =>
+ `{ const scene = document.querySelector('[data-hf-scene="a"]:not(style):not(script)');` +
+ `const video = scene.querySelector('video');` +
+ `if (scene.querySelector('p').textContent === 'A one') ${write}; }`;
+ const bootWithHeadingScript = (write: string, video = '<video src="clip.mp4"></video>') => {
+ const scene = (text: string, hash: string): Scene => ({
+ ...A1,
+ hash,
+ body: `<p>${text}</p>${video}`,
+ script: writesOnlyOverTheFirstHeading(write),
+ });
+ boot([scene("A one", "ha1"), B], trackingRoot().root);
+ const fresh = sceneHost("a").querySelector("video")!.outerHTML;
+ new Function(document.querySelector('script[data-hf-scene="a"]')!.textContent!)();
+ return { html: preview([scene("A two", "ha2"), B]).html, fresh };
+ };
+
+ it.each([
+ ["muted", "video.muted = true", false],
+ ["volume", "video.volume = 0.2", 1],
+ ["playbackRate", "video.playbackRate = 2", 1],
+ ["defaultPlaybackRate", "video.defaultPlaybackRate = 2", 1],
+ ["preservesPitch", "video.preservesPitch = false", true],
+ ] as const)(
+ "gives a kept video the %s a fresh load gives it when its unchanged script wrote it only over the old text",
+ async (property, write, fresh) => {
+ quietMedia();
+ const { html } = bootWithHeadingScript(write);
+ await tick();
+ const video = sceneHost("a").querySelector("video")!;
+ expect(video[property]).not.toBe(fresh);
+ await window.__hfSwapScenes!(html);
+ expect(sceneHost("a").querySelector("video")).toBe(video);
+ expect(video[property]).toBe(fresh);
+ },
+ );
+
+ it("gives a kept video its authored data-volume back when its unchanged script wrote volume only over the old text", async () => {
+ quietMedia();
+ const { html } = bootWithHeadingScript(
+ "video.volume = 0.2",
+ '<video src="clip.mp4" data-volume="0.5"></video>',
+ );
+ await tick();
+ const video = sceneHost("a").querySelector("video")!;
+ expect(video.volume).toBe(0.2);
+ await window.__hfSwapScenes!(html);
+ expect(sceneHost("a").querySelector("video")).toBe(video);
+ expect(video.volume).toBe(0.5);
+ });
+
+ it.each([
+ "video.className = 'dim'",
+ "video.hidden = true",
+ "video.dataset.volume = '0.1'",
+ "video.setAttribute('data-playback-rate', '2')",
+ "video.poster = 'p.png'",
+ "video.loop = true",
+ "video.append(document.createElement('track'))",
+ ])(
+ "rebuilds a video as a fresh load has it when its unchanged script ran `%s` only over the old text",
+ async (write) => {
+ quietMedia();
+ const { html, fresh } = bootWithHeadingScript(write);
+ await tick();
+ const video = sceneHost("a").querySelector("video")!;
+ expect(video.outerHTML).not.toBe(fresh);
+ await window.__hfSwapScenes!(html);
+ const rebuilt = sceneHost("a").querySelector("video")!;
+ expect(rebuilt).not.toBe(video);
+ expect(rebuilt.outerHTML).toBe(fresh);
+ },
+ );
+
+ it("keeps a video through a text edit when its unchanged script writes nothing to it", async () => {
+ quietMedia();
+ const { html } = bootWithHeadingScript("void video");
+ await tick();
+ const video = sceneHost("a").querySelector("video")!;
+ await window.__hfSwapScenes!(html);
+ expect(sceneHost("a").querySelector("video")).toBe(video);
+ });
+
it.each([
- ["rewinds and kills an old timeline that cannot revert", false, "1", 1],
+ ["preload", '<video src="clip.mp4" preload="metadata"></video>', () => {}],
+ ["a proxied src", '<video src="clip.mov"></video>', () => void proxyHostile()],
+ [
+ "a variable-bound src",
+ '<video data-var-src="clip" src="placeholder.mp4"></video>',
+ () => {
+ scoped.__hfVariablesByComp = { a: { clip: "clip.mp4" } };
+ },
+ ],
+ ["the opacity stamp", '<video src="clip.mp4"></video>', () => {}, "data-hf-authored-opacity"],
+ ])("keeps a video on which the runtime wrote %s", async (_, video, arrange, stamp?: string) => {
+ quietMedia();
+ arrange();
+ const { html } = bootWithHeadingScript("void video", video);
+ await tick();
+ const kept = sceneHost("a").querySelector("video")!;
+ if (stamp) kept.setAttribute(stamp, "");
+ expect(kept.outerHTML).not.toBe(video);
+ await window.__hfSwapScenes!(html);
+ expect(sceneHost("a").querySelector("video")).toBe(kept);
+ });
+
+ it.each([
+ ["the edit flash", "__hf-flash"],
+ ["the picker's hover", "__hf-pick-highlight"],
+ ])("keeps a video that carries %s class at the swap", async (_, name) => {
+ quietMedia();
+ const { html } = bootWithHeadingScript(
+ "void video",
+ '<video class="clip" src="clip.mp4"></video>',
+ );
+ await tick();
+ const video = sceneHost("a").querySelector("video")!;
+ video.classList.add(name);
+ await window.__hfSwapScenes!(html);
+ expect(sceneHost("a").querySelector("video")).toBe(video);
+ });
+
+ it("keeps a video that carries the edit flash as its only class at the swap", async () => {
+ quietMedia();
+ const { html } = bootWithHeadingScript("void video");
+ await tick();
+ const video = sceneHost("a").querySelector("video")!;
+ video.classList.add("__hf-flash");
+ await window.__hfSwapScenes!(html);
+ expect(sceneHost("a").querySelector("video")).toBe(video);
+ });
+
+ it("keeps a video whose unchanged script removes an attribute and puts it back as it was", async () => {
+ quietMedia();
+ const { html } = bootWithHeadingScript(
+ "video.removeAttribute('title'), video.setAttribute('title', 'clip')",
+ '<video title="clip" data-id="v" src="clip.mp4"></video>',
+ );
+ await tick();
+ const video = sceneHost("a").querySelector("video")!;
+ expect(video.getAttributeNames().at(-1)).toBe("title");
+ await window.__hfSwapScenes!(html);
+ expect(sceneHost("a").querySelector("video")).toBe(video);
+ });
+
+ it("unmutes a kept video though stopping Web Audio puts back the mute it saved from the old script", async () => {
+ quietMedia();
+ const { html } = bootWithHeadingScript("video.muted = true");
+ await tick();
+ const video = sceneHost("a").querySelector("video")!;
+ // Web Audio captured the video while the old script had it muted, and restores that on its next stop.
+ vi.spyOn(WebAudioTransport.prototype, "stopAll").mockImplementationOnce(() => {
+ video.muted = true;
+ });
+ await window.__hfSwapScenes!(html);
+ expect(sceneHost("a").querySelector("video")).toBe(video);
+ expect(video.muted).toBe(false);
+ });
+
+ it.each([
+ ["a stream", "srcObject", {}],
+ ["an output device", "sinkId", "speakers"],
+ ["a key session", "mediaKeys", {}],
+ ])(
+ "rebuilds a video a script gave %s, which a fresh load does not have",
+ async (_, key, value) => {
+ quietMedia();
+ const { html } = bootWithHeadingScript("void video");
+ await tick();
+ const video = sceneHost("a").querySelector("video")!;
+ Object.defineProperty(video, key, { value });
+ await window.__hfSwapScenes!(html);
+ expect(sceneHost("a").querySelector("video")).not.toBe(video);
+ },
+ );
+
+ it.each([
+ ["rewinds and kills an old timeline that cannot revert", false, "", 1],
["reverts an old timeline that can, dropping the inline values it wrote", true, "", 0],
])(
"%s, so a kept video carries none of its tweens' values",
async (_, canRevert, opacity, kills) => {
const { root } = trackingRoot();
quietMedia();
- const scene = (text: string, label: string, hash: string): Scene => ({
+ const scene = (text: string, hash: string): Scene => ({
...A1,
- label,
hash,
body: `<p>${text}</p><video src="clip.mp4" data-start="1">one</video>`,
});
- boot([scene("A one", "a1", "ha1"), B], root);
+ boot([scene("A one", "ha1"), B], root);
await tick();
const video = sceneHost("a").querySelector("video")!;
- const seek = made.a1!.totalTime.bind(made.a1);
+ const old = made.a1!;
+ const seek = old.totalTime.bind(old);
const fadeOverTwentySeconds = (t?: number) => (
t !== undefined && (video.style.opacity = String(1 - t / 20)), seek(t)
);
- made.a1!.totalTime = fadeOverTwentySeconds as Tl["totalTime"];
- if (canRevert)
- Object.assign(made.a1!, { revert: () => video.style.removeProperty("opacity") });
- made.a1!.totalTime(10);
- await window.__hfSwapScenes!(preview([scene("A two", "a2", "ha2"), B]).html);
+ old.totalTime = fadeOverTwentySeconds as Tl["totalTime"];
+ if (canRevert) Object.assign(old, { revert: () => video.style.removeProperty("opacity") });
+ old.totalTime(10);
+ // The same script registers a fresh timeline.
+ made.a1 = made.a2!;
+ await window.__hfSwapScenes!(preview([scene("A two", "ha2"), B]).html);
expect(sceneHost("a").querySelector("video")).toBe(video);
expect(video.style.opacity).toBe(opacity);
// GSAP's revert() kills the timeline itself; a second kill() fires its onInterrupt again.
- expect(made.a1!.kill).toHaveBeenCalledTimes(kills);
+ expect(old.kill).toHaveBeenCalledTimes(kills);
},
);
@@ -531,6 +831,50 @@ describe("__hfSwapScenes", () => {
probe.mockReset();
});
+ it("re-probes the volume of media kept through the swap against the new timeline", async () => {
+ const { root } = trackingRoot();
+ quietMedia();
+ const withAudio = (s: Scene, text: string): Scene => ({
+ ...s,
+ body: `<p>${text}</p><audio src="music.mp3" data-start="1" data-duration="2"></audio>`,
+ });
+ const probe = vi.mocked(probeAndCacheElementVolume);
+ probe.mockImplementation((el, _timeline, _duration, cache) => void cache.set(el, []));
+ boot([withAudio(A1, "A one"), B], root);
+ await tick();
+ const audio = sceneHost("a").querySelector("audio")!;
+ const probedAudio = () => probe.mock.calls.filter(([el]) => el === audio).length;
+ expect(probedAudio()).toBeGreaterThan(0);
+ probe.mockClear();
+ await window.__hfSwapScenes!(preview([withAudio({ ...A1, hash: "ha2" }, "A two"), B]).html);
+ expect(sceneHost("a").querySelector("audio")).toBe(audio);
+ expect(probedAudio()).toBeGreaterThan(0);
+ probe.mockReset();
+ });
+
+ it("gives the swapped scene's host its per-instance CSS variables", async () => {
+ const { root } = trackingRoot();
+ scoped.__hfVariablesByComp = { a: { accent: "#ff0000" } };
+ boot([A1, B], root);
+ await tick();
+ await window.__hfSwapScenes!(preview([A2, B]).html);
+ expect((sceneHost("a") as HTMLElement).style.getPropertyValue("--accent")).toBe("#ff0000");
+ });
+
+ it("adds no asset error listener to the swapped scene, which would keep it after it is swapped out", async () => {
+ const { root } = trackingRoot();
+ const withImage = (s: Scene): Scene => ({ ...s, body: `${s.body}<img src="logo.png">` });
+ boot([withImage(A1), B], root);
+ await tick();
+ const listen = vi.spyOn(EventTarget.prototype, "addEventListener");
+ await window.__hfSwapScenes!(preview([withImage(A2), B]).html);
+ const img = sceneHost("a").querySelector("img");
+ const onImg = listen.mock.contexts.filter(
+ (el, i) => el === img && listen.mock.calls[i]![0] === "error",
+ );
+ expect(onImg).toHaveLength(0);
+ });
+
it("re-applies a moved element's position edit after the swap", async () => {
const { root } = trackingRoot();
boot([A1, B], root);
@@ -541,6 +885,24 @@ describe("__hfSwapScenes", () => {
expect(p.style.translate).toContain("30");
});
+ it("keeps a moved video where it was moved, as a fresh load puts it, through an edit beside it", async () => {
+ const { root } = trackingRoot();
+ quietMedia();
+ const moved = 'data-x="40" data-y="7" data-hf-edit-base-x="0" data-hf-edit-base-y="0"';
+ const scene = (text: string, hash: string): Scene => ({
+ ...A1,
+ hash,
+ body: `<p>${text}</p><video src="clip.mp4" ${moved}></video>`,
+ });
+ boot([scene("A one", "ha1"), B], root);
+ await tick();
+ const video = sceneHost("a").querySelector("video")!;
+ expect(video.style.getPropertyValue("translate")).toBe("40px 7px");
+ await window.__hfSwapScenes!(preview([scene("A two", "ha2"), B]).html);
+ expect(sceneHost("a").querySelector("video")).toBe(video);
+ expect(video.style.getPropertyValue("translate")).toBe("40px 7px");
+ });
+
it("rejects a scene the bundler marked as not swappable, naming why", async () => {
const { root } = trackingRoot();
const marked = (s: Scene): Scene => ({
@@ -555,6 +917,227 @@ describe("__hfSwapScenes", () => {
expect(made.a1!.kill).not.toHaveBeenCalled();
});
+ it.each([
+ ["the root timeline", "host", (root: Tl) => root],
+ ["the root timeline", "text", (root: Tl) => root],
+ ["another scene's timeline", "text", () => made.b],
+ ])("refuses, changing nothing, when %s tweens the scene's %s", async (_, target, owner) => {
+ const { root } = trackingRoot();
+ const tweened = () => (target === "host" ? sceneHost("a") : sceneHost("a").querySelector("p"));
+ const tween = { parent: owner(root), targets: () => [tweened()] };
+ (window as unknown as { gsap: unknown }).gsap = {
+ set: () => {},
+ globalTimeline: { getChildren: () => [tween] },
+ };
+ boot([A1, B], root);
+ await tick();
+ const before = document.documentElement.innerHTML;
+ await expect(window.__hfSwapScenes!(preview([A2, B]).html)).rejects.toThrow(
+ "scene a cannot be swapped: an animation outside it moves its elements",
+ );
+ expect(document.documentElement.innerHTML).toBe(before);
+ expect(made.a1!.kill).not.toHaveBeenCalled();
+ });
+
+ it("swaps a scene whose elements only its own and its nested scenes' timelines tween", async () => {
+ const { root } = trackingRoot();
+ const nested = (s: Scene): Scene => ({
+ ...s,
+ body: `${s.body}<div data-composition-id="n"><i>n</i></div>`,
+ });
+ const own = { parent: made.a1, targets: () => [sceneHost("a")] };
+ const inNested = { parent: { parent: made.n1 }, targets: () => [sceneHost("a")] };
+ const elsewhere = { parent: root, targets: () => [sceneHost("b")] };
+ (window as unknown as { gsap: unknown }).gsap = {
+ set: () => {},
+ globalTimeline: { getChildren: () => [own, inNested, elsewhere] },
+ };
+ boot([nested(A1), B], root);
+ window.__timelines!.n = made.n1;
+ await tick();
+ await window.__hfSwapScenes!(preview([nested(A2), B]).html);
+ expect(sceneHost("a").querySelector("p")?.textContent).toBe("A two");
+ });
+
+ it.each([
+ ["a timeline it never registers", `gsap.timeline().to("p", { x: 100 });`],
+ ["gsap under another name", `const g = gsap; g.to("p", { x: 100 });`],
+ ["gsap by a computed key", `gsap["to"]("p", { x: 100 });`],
+ ["the unscoped global", `globalThis.gsap.to("p", { x: 100 });`],
+ ])(
+ "stops what the old scene script started through %s, so one copy runs after the swap",
+ async (_, source) => {
+ const { root } = trackingRoot();
+ const running = new Set<object>();
+ const globalTimeline = { getChildren: () => [...running] };
+ const start = () => {
+ const p = sceneHost("a").querySelector("p");
+ const animation = {
+ parent: globalTimeline,
+ targets: () => [p],
+ to: () => animation,
+ revert: () => void running.delete(animation),
+ };
+ running.add(animation);
+ return animation;
+ };
+ vi.stubGlobal("gsap", {
+ set: () => {},
+ globalTimeline,
+ timeline: start,
+ to: start,
+ });
+ const scene = (s: Scene): Scene => ({
+ ...s,
+ script: wrapScopedCompositionScript(source, "a"),
+ });
+ boot([scene(A1), B], root);
+ new Function(document.querySelector('script[data-hf-scene="a"]')!.textContent!)();
+ await tick();
+ expect(running.size).toBe(1);
+ await window.__hfSwapScenes!(preview([scene(A2), B]).html);
+ expect(running.size).toBe(1);
+ expect(window.__hfSceneAnimations?.a).toHaveLength(1);
+ },
+ );
+
+ it("reverts a scene's timeline once though its script also recorded it", async () => {
+ const { root } = trackingRoot();
+ const revert = vi.fn();
+ Object.assign(made.a1!, { revert });
+ boot([A1, B], root);
+ await tick();
+ window.__hfSceneAnimations = { a: [made.a1!] };
+ await window.__hfSwapScenes!(preview([A2, B]).html);
+ expect(revert).toHaveBeenCalledTimes(1);
+ });
+
+ it("reverts a scene's recorded animations newest first, so each restores what the one before it wrote", async () => {
+ const { root } = trackingRoot();
+ const order: string[] = [];
+ const animation = (name: string) => ({ revert: () => void order.push(name) });
+ Object.assign(made.a1!, animation("timeline"));
+ boot([A1, B], root);
+ await tick();
+ window.__hfSceneAnimations = { a: [made.a1!, animation("first set"), animation("second set")] };
+ await window.__hfSwapScenes!(preview([A2, B]).html);
+ expect(order).toEqual(["second set", "first set", "timeline"]);
+ });
+
+ const writesOutside = "scene a cannot be swapped: its animations write outside the scene";
+ const asFresh = "swapped, as a fresh load, video kept";
+ const thenFrom = `tl.from(k, { x: 0, duration: 1 });`;
+ const shapes = {
+ "a free from()": `gsap.from(k, { x: "+=50", duration: 1 }); ${thenFrom}`,
+ "a free fromTo()": `gsap.fromTo(k, { x: "+=50" }, { x: "+=0", duration: 1 }); ${thenFrom}`,
+ "a tween moved to its end": `gsap.to(k, { x: "+=50", duration: 0.5 }).progress(1); ${thenFrom}`,
+ "a second timeline's from()": `gsap.timeline({ paused: true }).from(k, { x: "+=50", duration: 1 }); ${thenFrom}`,
+ "a relative set": `gsap.set(k, { x: "+=50" }); ${thenFrom}`,
+ "a nested timeline's to() before its from()": `tl.add(gsap.timeline().to(k, { x: 10, duration: 0.5 }).from(k, { x: 0, duration: 1 }), 0);`,
+ };
+ it.each([
+ ...Object.entries(shapes).flatMap(([shape, body]) => [
+ [shape, "video", body, asFresh],
+ [shape, "#kept", body, writesOutside],
+ ]),
+ [
+ "a to() before a from() on one property",
+ "video",
+ `tl.to(k, { opacity: 0.5, duration: 0.5 }, 0).from(k, { opacity: 0, duration: 1 }, 0.5);`,
+ asFresh,
+ ],
+ [
+ "a fade in, then out",
+ "video",
+ `tl.from(k, { opacity: 0, duration: 1 }, 0).to(k, { opacity: 0, duration: 1 }, 1.5);`,
+ asFresh,
+ ],
+ ["a lone set", "video", `gsap.set(k, { x: 50 });`, asFresh],
+ ["a lone timeline from()", "video", `tl.from(k, { x: 50, duration: 1 });`, asFresh],
+ [
+ "a set on its text and a timeline from()",
+ "video",
+ `gsap.set("p", { x: 20 }); tl.from(k, { x: 50, duration: 1 });`,
+ asFresh,
+ ],
+ [
+ "one timeline moving it twice",
+ "video",
+ `tl.from(k, { x: 50, duration: 1 }).to(k, { x: "+=30", duration: 1 });`,
+ asFresh,
+ ],
+ ["a lone timeline to()", "#kept", `tl.to(k, { x: 10, duration: 1 });`, writesOutside],
+ [
+ "a padding tween on an empty object",
+ "video",
+ `tl.to({}, { duration: 2 }); tl.from(k, { x: 50, duration: 1 }, 0);`,
+ asFresh,
+ ],
+ [
+ "a counter on a local object",
+ "video",
+ `const state = { n: 0 }; tl.to(state, { n: 10, duration: 1, onUpdate: () => void (k.dataset.n = String(Math.round(state.n))) }); tl.from(k, { x: 50, duration: 1 }, 0);`,
+ // The attribute its callback writes is not in the markup, so the video is rebuilt.
+ "swapped, as a fresh load",
+ ],
+ [
+ "a move the record missed, as a callback's",
+ "video",
+ `globalThis.__missed = () => gsap.set(k, { x: 30 }); tl.from(k, { opacity: 0, duration: 1 });`,
+ asFresh,
+ ],
+ ])("a scene script with %s on %s", async (_, el, body, expected) => {
+ const exports: { gsap?: RealGsap } = {};
+ // Its ticker takes the frame callback as it loads, and this file's runs at once: give it one that never ticks.
+ const frame = window.requestAnimationFrame;
+ window.requestAnimationFrame = () => 0;
+ new Function("exports", "module", readFileSync(vendoredGsap(), "utf8"))(exports, { exports });
+ window.requestAnimationFrame = frame;
+ const gsap = exports.gsap!;
+ vi.stubGlobal("gsap", gsap);
+ quietMedia();
+ const source = `const k = globalThis.document.querySelector(${JSON.stringify(el)});
+const tl = gsap.timeline({ paused: true });
+${body}
+window.__timelines.a = tl;`;
+ const scene = (text: string, hash: string): Scene => ({
+ ...A1,
+ hash,
+ body: `<p>${text}</p><video src="clip.mp4" style="opacity: 0.5"></video>`,
+ script: wrapScopedCompositionScript(source, "a"),
+ });
+ boot([scene("A one", "ha1"), B], trackingRoot().root);
+ document.body.insertAdjacentHTML("beforeend", '<div id="kept"></div>');
+ new Function(document.querySelector('script[data-hf-scene="a"]')!.textContent!)();
+ // The old page is a fresh load of the same script.
+ const along = () => {
+ const timeline = window.__timelines!.a!;
+ const k = document.querySelector(el)!;
+ return [0, 0.25, 0.5, 0.75, 1]
+ .map((at) => {
+ timeline.totalTime!(at * timeline.duration());
+ return `${gsap.getProperty(k, "x")}/${gsap.getProperty(k, "opacity")}`;
+ })
+ .join(" ");
+ };
+ const fresh = along();
+ (globalThis as { __missed?: () => void }).__missed?.();
+ const video = sceneHost("a").querySelector("video");
+ const swapped = await window.__hfSwapScenes!(preview([scene("A two", "ha2"), B]).html).then(
+ () => {
+ const values = along();
+ const kept = sceneHost("a").querySelector("video") === video ? ", video kept" : "";
+ return values === fresh
+ ? `swapped, as a fresh load${kept}`
+ : `swapped: ${values} against ${fresh}`;
+ },
+ (error: Error) => error.message,
+ );
+ gsap.ticker.sleep();
+ delete (globalThis as { __missed?: () => void }).__missed;
+ expect(swapped).toBe(expected);
+ });
+
it("rejects a scene with more than one host rather than dropping one", async () => {
const { root } = trackingRoot();
boot([A1, B], root);
@@ -653,6 +1236,354 @@ describe("__hfSwapScenes", () => {
expect(made.a1!.kill).not.toHaveBeenCalled();
});
+ it("refuses a swap when an outside animation starts on the scene while its caption overrides load", async () => {
+ const { swap, before, answer } = await bootWithPendingCaptions();
+ const tween = { targets: () => [sceneHost("a")] };
+ Object.assign(window.gsap!, { globalTimeline: { getChildren: () => [tween] } });
+ answer(new Response("null", { status: 404 }));
+ await expect(swap).rejects.toThrow("an animation outside it moves its elements");
+ expect(document.documentElement.innerHTML).toBe(before);
+ expect(made.a1!.kill).not.toHaveBeenCalled();
+ });
+
+ it("checks the timeline registry as it is after the caption wait, which a data handler may replace", async () => {
+ const { swap, before, answer } = await bootWithPendingCaptions();
+ const movesB = { targets: () => [sceneHost("b")], getChildren: () => [] };
+ // As a runtime-data handler may: a new registry object, whose scene-a timeline moves scene b.
+ window.__timelines = { ...window.__timelines, a: movesB as unknown as RuntimeTimelineLike };
+ answer(new Response("null", { status: 404 }));
+ await expect(swap).rejects.toThrow("its animations write outside the scene");
+ expect(document.documentElement.innerHTML).toBe(before);
+ });
+
+ it("refuses a swap whose scene was replaced while its caption overrides loaded", async () => {
+ const { swap, answer } = await bootWithPendingCaptions();
+ const live = sceneHost("a");
+ live.replaceWith(live.cloneNode(true));
+ const manifest = () =>
+ document.querySelector('meta[name="hf-scene-parts"]')?.getAttribute("content");
+ const before = manifest();
+ answer(new Response("null", { status: 404 }));
+ await expect(swap).rejects.toThrow("a scene changed while this swap waited");
+ expect(manifest()).toBe(before);
+ });
+
+ it("refuses a swap whose scene host moved to another parent while its caption overrides loaded", async () => {
+ const { swap, answer } = await bootWithPendingCaptions();
+ const manifest = () =>
+ document.querySelector('meta[name="hf-scene-parts"]')?.getAttribute("content");
+ const before = manifest();
+ // As a runtime-data handler may: the host stays in the page, outside the film.
+ document.body.appendChild(sceneHost("a"));
+ answer(new Response("null", { status: 404 }));
+ await expect(swap).rejects.toThrow("a scene changed while this swap waited");
+ expect(manifest()).toBe(before);
+ });
+
+ it("refuses a swap whose scene's wrapper left the film while its caption overrides loaded", async () => {
+ const wrapper = document.createElement("div");
+ const wrap = () => {
+ sceneHost("a").before(wrapper);
+ wrapper.append(sceneHost("a"));
+ };
+ const { swap, answer } = await bootWithPendingCaptions(undefined, wrap);
+ // The host keeps its parent; the parent leaves the film.
+ document.body.appendChild(wrapper);
+ answer(new Response("null", { status: 404 }));
+ await expect(swap).rejects.toThrow("a scene changed while this swap waited");
+ });
+
+ const filmRoot = () => document.querySelector<HTMLElement>("[data-root]")!;
+ const wrapA = () => {
+ const wrapper = document.createElement("div");
+ sceneHost("a").before(wrapper);
+ wrapper.append(sceneHost("a"));
+ return wrapper;
+ };
+
+ it("refuses a swap whose scene's wrapper moved past the next scene while its caption overrides loaded", async () => {
+ let wrapper!: HTMLElement;
+ const { swap, answer } = await bootWithPendingCaptions(
+ undefined,
+ () => void (wrapper = wrapA()),
+ );
+ // A keeps its parent and its next sibling (none) and stays in the film; only the order changes.
+ sceneHost("b").after(wrapper);
+ answer(new Response("null", { status: 404 }));
+ await expect(swap).rejects.toThrow("a scene changed while this swap waited");
+ });
+
+ it("refuses a swap whose scene moved with its neighbour as a pair while its caption overrides loaded", async () => {
+ const C: Scene = { id: "c", start: 5, body: "<p>C</p>", css: ".c{}", label: "n2", hash: "hc" };
+ const { swap, answer } = await bootWithPendingCaptions(undefined, undefined, [B, C]);
+ // A's next sibling is still B; the pair now comes after C.
+ filmRoot().append(sceneHost("a"), sceneHost("b"));
+ answer(new Response("null", { status: 404 }));
+ await expect(swap).rejects.toThrow("a scene changed while this swap waited");
+ });
+
+ it("refuses a swap whose scene's wrapper moved into another container in the film while its caption overrides loaded", async () => {
+ let wrapper!: HTMLElement;
+ const container = document.createElement("div");
+ const arrange = () => {
+ wrapper = wrapA();
+ wrapper.after(container);
+ };
+ const { swap, answer } = await bootWithPendingCaptions(undefined, arrange);
+ // Same order, same parent and next sibling for A, still in the film: only its ancestors changed.
+ container.append(wrapper);
+ answer(new Response("null", { status: 404 }));
+ await expect(swap).rejects.toThrow("a scene changed while this swap waited");
+ });
+
+ it("refuses a swap whose scene moved before a background in the film while its caption overrides loaded", async () => {
+ const background = document.createElement("div");
+ const { swap, answer } = await bootWithPendingCaptions(undefined, () =>
+ filmRoot().prepend(background),
+ );
+ // Scene order and ancestors are unchanged; A now sits under the background instead of over it.
+ background.before(sceneHost("a"));
+ answer(new Response("null", { status: 404 }));
+ await expect(swap).rejects.toThrow("a scene changed while this swap waited");
+ });
+
+ it("swaps a scene beside which the runtime inserted one of its own elements while its caption overrides loaded", async () => {
+ const { swap, answer } = await bootWithPendingCaptions();
+ // As colour grading does for a graded video beside the scene.
+ const canvas = document.createElement("canvas");
+ canvas.setAttribute("data-hf-ignore", "");
+ sceneHost("a").after(canvas);
+ answer(new Response("null", { status: 404 }));
+ await swap;
+ expect(sceneHost("a").querySelector(".caption-group")).not.toBeNull();
+ });
+
+ it("refuses a swap whose scene moved as a block with both its neighbours while its caption overrides loaded", async () => {
+ const [p, q, r, s] = ["p", "q", "r", "s"].map(() => document.createElement("div"));
+ // The film reads P, a, Q, R, S, b.
+ const arrange = () => {
+ sceneHost("a").before(p!);
+ sceneHost("a").after(q!, r!, s!);
+ };
+ const { swap, answer } = await bootWithPendingCaptions(undefined, arrange);
+ // Now R, P, a, Q, S, b: every neighbour, the scene order and the ancestors are unchanged.
+ r!.after(p!, sceneHost("a"), q!);
+ answer(new Response("null", { status: 404 }));
+ await expect(swap).rejects.toThrow("a scene changed while this swap waited");
+ });
+
+ it("refuses a swap whose scene's wrapper left the film with no other scene beside it while its caption overrides loaded", async () => {
+ let wrapper!: HTMLElement;
+ const [before, after] = [document.createElement("div"), document.createElement("div")];
+ // The film reads X, [a], Y, b: the wrapper's neighbours are plain elements.
+ const arrange = () => {
+ wrapper = wrapA();
+ wrapper.before(before);
+ wrapper.after(after);
+ };
+ const { swap, answer } = await bootWithPendingCaptions(undefined, arrange);
+ document.body.appendChild(wrapper);
+ answer(new Response("null", { status: 404 }));
+ await expect(swap).rejects.toThrow("a scene changed while this swap waited");
+ });
+
+ it("refuses a swap whose scene's wrapper moved before a background in the film while both scenes are wrapped", async () => {
+ const background = document.createElement("div");
+ let wrapper!: HTMLElement;
+ // The film reads background, [a], [b]: no scene is a direct child of the film root.
+ const arrange = () => {
+ wrapper = wrapA();
+ const other = document.createElement("div");
+ sceneHost("b").before(other);
+ other.append(sceneHost("b"));
+ filmRoot().prepend(background);
+ };
+ const { swap, answer } = await bootWithPendingCaptions(undefined, arrange);
+ // Each wrapper still holds its scene alone; only the film root's order changed.
+ background.before(wrapper);
+ answer(new Response("null", { status: 404 }));
+ await expect(swap).rejects.toThrow("a scene changed while this swap waited");
+ });
+
+ it("refuses a swap whose scene style moved to another parent while its caption overrides loaded", async () => {
+ const { swap, answer } = await bootWithPendingCaptions();
+ // The new style would take the moved one's place, out of cascade order.
+ document.body.appendChild(document.querySelector('style[data-hf-scene="a"]')!);
+ answer(new Response("null", { status: 404 }));
+ await expect(swap).rejects.toThrow("a scene changed while this swap waited");
+ });
+
+ it("refuses a swap whose scene moved to another place in its parent while its caption overrides loaded", async () => {
+ const { swap, answer } = await bootWithPendingCaptions();
+ sceneHost("a").parentElement!.appendChild(sceneHost("a"));
+ answer(new Response("null", { status: 404 }));
+ await expect(swap).rejects.toThrow("a scene changed while this swap waited");
+ });
+
+ it("swaps a scene whose script is last in the page though something is appended after it during the wait", async () => {
+ // As after an earlier swap of the scene, which appends its new script at the end of the page.
+ const lastScript = () =>
+ document.body.appendChild(document.querySelector('script[data-hf-scene="a"]')!);
+ const { swap, answer } = await bootWithPendingCaptions(undefined, lastScript);
+ document.body.appendChild(document.createElement("div"));
+ answer(new Response("null", { status: 404 }));
+ await swap;
+ expect(sceneHost("a").querySelector(".caption-group")).not.toBeNull();
+ });
+
+ it("refuses a swap whose signal was aborted before the call, changing nothing", async () => {
+ const { root } = trackingRoot();
+ boot([A1, B], root);
+ await tick();
+ const before = document.documentElement.innerHTML;
+ const cancel = new AbortController();
+ cancel.abort();
+ await expect(window.__hfSwapScenes!(preview([A2, B]).html, cancel.signal)).rejects.toThrow(
+ "the swap was cancelled",
+ );
+ expect(document.documentElement.innerHTML).toBe(before);
+ });
+
+ it("refuses a swap the caller cancelled while its caption overrides loaded, changing nothing", async () => {
+ const cancel = new AbortController();
+ const { swap, before, answer } = await bootWithPendingCaptions(cancel.signal);
+ cancel.abort();
+ answer(new Response("null", { status: 404 }));
+ await expect(swap).rejects.toThrow("the swap was cancelled");
+ expect(document.documentElement.innerHTML).toBe(before);
+ expect(made.a1!.kill).not.toHaveBeenCalled();
+ });
+
+ it("refuses when stopping a scene's timeline replaces the registry with one moving another scene", async () => {
+ const { root } = trackingRoot();
+ (window as unknown as { gsap: unknown }).gsap = { set: () => {} };
+ const movesB = { targets: () => [sceneHost("b")], getChildren: () => [] };
+ // As an onInterrupt that revert() fires can: a new registry whose scene-a timeline moves scene b.
+ const replaceRegistry = () =>
+ void (window.__timelines = {
+ ...window.__timelines,
+ a: movesB as unknown as RuntimeTimelineLike,
+ });
+ Object.assign(made.a1!, { revert: replaceRegistry });
+ boot([A1, B], root);
+ await tick();
+ await expect(window.__hfSwapScenes!(preview([A2, B]).html)).rejects.toThrow(
+ "its animations write outside the scene",
+ );
+ delete (window as unknown as { gsap?: unknown }).gsap;
+ });
+
+ it("stops, too, what stopping a scene's timeline registers, however deep the chain", async () => {
+ const { root } = trackingRoot();
+ (window as unknown as { gsap: unknown }).gsap = { set: () => {} };
+ const reverted: number[] = [];
+ // Each revert registers a fresh scene-a timeline, three levels deep, as chained onInterrupt callbacks can.
+ const chained = (level: number): RuntimeTimelineLike =>
+ ({
+ getChildren: () => [],
+ revert: () => {
+ reverted.push(level);
+ if (level < 3) window.__timelines = { ...window.__timelines, a: chained(level + 1) };
+ },
+ }) as unknown as RuntimeTimelineLike;
+ Object.assign(made.a1!, {
+ revert: () => void (window.__timelines = { ...window.__timelines, a: chained(1) }),
+ });
+ boot([A1, B], root);
+ await tick();
+ await window.__hfSwapScenes!(preview([A2, B]).html);
+ expect(reverted).toEqual([1, 2, 3]);
+ delete (window as unknown as { gsap?: unknown }).gsap;
+ });
+
+ it("refuses when stopping a scene's timeline replaces that scene's host", async () => {
+ const { root } = trackingRoot();
+ (window as unknown as { gsap: unknown }).gsap = { set: () => {} };
+ const replaceHost = () => {
+ const live = sceneHost("a");
+ live.replaceWith(live.cloneNode(true));
+ };
+ Object.assign(made.a1!, { revert: replaceHost });
+ boot([A1, B], root);
+ await tick();
+ await expect(window.__hfSwapScenes!(preview([A2, B]).html)).rejects.toThrow(
+ "a scene changed while this swap waited",
+ );
+ delete (window as unknown as { gsap?: unknown }).gsap;
+ });
+
+ it("refuses when stopping a scene's timeline moves that scene's host to another parent", async () => {
+ const { root } = trackingRoot();
+ (window as unknown as { gsap: unknown }).gsap = { set: () => {} };
+ Object.assign(made.a1!, { revert: () => void document.body.appendChild(sceneHost("a")) });
+ boot([A1, B], root);
+ await tick();
+ await expect(window.__hfSwapScenes!(preview([A2, B]).html)).rejects.toThrow(
+ "a scene changed while this swap waited",
+ );
+ delete (window as unknown as { gsap?: unknown }).gsap;
+ });
+
+ it("refuses when stopping a scene's timeline moves the scene's wrapper out of the film", async () => {
+ const { root } = trackingRoot();
+ (window as unknown as { gsap: unknown }).gsap = { set: () => {} };
+ const wrapper = document.createElement("div");
+ Object.assign(made.a1!, { revert: () => void document.body.appendChild(wrapper) });
+ boot([A1, B], root);
+ await tick();
+ sceneHost("a").before(wrapper);
+ wrapper.append(sceneHost("a"));
+ await expect(window.__hfSwapScenes!(preview([A2, B]).html)).rejects.toThrow(
+ "a scene changed while this swap waited",
+ );
+ delete (window as unknown as { gsap?: unknown }).gsap;
+ });
+
+ it("stops a playing film at its new end when the edit shortens it to before the playhead", async () => {
+ const { root } = trackingRoot();
+ let length = 6;
+ root.duration = () => length;
+ boot([A1, B], root);
+ // An auto-duration film: its length follows the timeline.
+ document.querySelector("[data-root]")!.removeAttribute("data-duration");
+ await tick();
+ window.__player!.seek(5.5);
+ window.__player!.play();
+ expect(window.__player!.isPlaying()).toBe(true);
+ length = 5;
+ await window.__hfSwapScenes!(preview([A2, B]).html);
+ expect([window.__player!.isPlaying(), window.__player!.getTime()]).toEqual([false, 5]);
+ });
+
+ it("runs the new scene scripts once every edited scene is replaced, so none binds to one still to go", async () => {
+ const { root } = trackingRoot();
+ const bound: Element[] = [];
+ (window as unknown as { __bind: () => void }).__bind = () => bound.push(sceneHost("b"));
+ boot([A1, B], root);
+ await tick();
+ const B2: Scene = { ...B, body: "<p>B two</p>", hash: "hb2" };
+ await window.__hfSwapScenes!(preview([{ ...A2, script: "window.__bind?.();" }, B2]).html);
+ expect(bound.map((el) => el.isConnected)).toEqual([true]);
+ });
+
+ it("refuses, for the caller's reload, when stopping one scene starts an animation on another it swaps", async () => {
+ const { root } = trackingRoot();
+ const running: object[] = [];
+ (window as unknown as { gsap: unknown }).gsap = {
+ set: () => {},
+ globalTimeline: { getChildren: () => [...running] },
+ };
+ // As the old timeline's onInterrupt can when revert() interrupts it.
+ const startOnB = () => void running.push({ targets: () => [sceneHost("b")] });
+ Object.assign(made.a1!, { revert: startOnB });
+ boot([A1, B], root);
+ await tick();
+ const B2: Scene = { ...B, body: "<p>B two</p>", hash: "hb2" };
+ await expect(window.__hfSwapScenes!(preview([A2, B2]).html)).rejects.toThrow(
+ "scene b cannot be swapped",
+ );
+ });
+
it("rejects a swap another swap overtook while its caption overrides loaded", async () => {
const { swap, answer } = await bootWithPendingCaptions();
const B2: Scene = { ...B, body: "<p>B two</p>", label: "n1", hash: "hb2" };
diff --git a/packages/core/src/runtime/init.ts b/packages/core/src/runtime/init.ts
index 2571701f00..b345b74559 100644
--- a/packages/core/src/runtime/init.ts
+++ b/packages/core/src/runtime/init.ts
@@ -69,7 +69,13 @@ import {
SCENE_PARTS_META,
type SceneParts,
} from "../sceneParts";
-import { applyPositionEdits, installPositionEditsSeekReapply } from "./positionEdits";
+import {
+ applyPositionEdits,
+ EDIT_ORIGINAL_TRANSLATE_ATTR,
+ forgetPositionEdit,
+ installPositionEditsSeekReapply,
+} from "./positionEdits";
+import { unproxiedSrc } from "./proxySrc";
import { applyVariableBindings, unproxiedMediaSrc } from "./applyVariableBindings";
import { createColorGradingRuntime, type RuntimeColorGradingApi } from "./colorGrading";
import { COLOR_GRADING_AUTHORED_OPACITY_ATTR } from "../colorGrading";
@@ -97,6 +103,7 @@ import type {
RuntimeSeekOptions,
RuntimeTimelineChildLike,
RuntimeTimelineLike,
+ SceneAnimation,
} from "./types";
import type { PlayerAPI } from "../core.types";
import { swallow } from "./diagnostics";
@@ -246,6 +253,63 @@ const authoredShape = (el: Element): string =>
el.innerHTML,
]);
+// What the runtime writes on a video or audio: style (reset on a kept one), preload, the opacity stamp, a moved
+// element's original translate and its own __hf- classes. A proxied src is compared as written; a bound one is not.
+const RUNTIME_MEDIA_ATTRS = new Set([
+ "style",
+ "preload",
+ "src",
+ COLOR_GRADING_AUTHORED_OPACITY_ATTR,
+ EDIT_ORIGINAL_TRANSLATE_ATTR,
+]);
+const ownClasses = (value: string) =>
+ value
+ .split(/\s+/)
+ .filter((c) => c && !c.startsWith("__hf-"))
+ .join(" ");
+const writtenShape = (el: Element): string =>
+ JSON.stringify([
+ Array.from(el.attributes, ({ name, value }) => [
+ name,
+ name === "class" ? ownClasses(value) : value,
+ ])
+ .filter(([name, value]) => !RUNTIME_MEDIA_ATTRS.has(name!) && !(name === "class" && !value))
+ .sort(([a], [b]) => (a! < b! ? -1 : 1)),
+ el.hasAttribute("data-var-src") ? null : unproxiedSrc(el),
+ el.innerHTML,
+ ]);
+
+// Each video and audio as written, recorded as the page parses: a scene script can write to it before init.
+const authoredMedia = new WeakMap<Element, string>();
+const isMedia = (el: Element) => el.localName === "video" || el.localName === "audio";
+const recordAuthoredMedia = (node: Node) => {
+ if (!isElementNode(node)) return;
+ // The parser adds one childless element at a time, so most nodes stop at the first check.
+ const media = isMedia(node)
+ ? [node]
+ : node.firstElementChild
+ ? node.querySelectorAll("video, audio")
+ : [];
+ for (const el of media) if (!authoredMedia.has(el)) authoredMedia.set(el, authoredShape(el));
+};
+let authoredMediaObserver: MutationObserver | null = null;
+
+/** On a page with a scene manifest, records media as it parses, before scene scripts run; init stops it. */
+export function installAuthoredMediaCapture(): void {
+ if (typeof MutationObserver === "undefined" || !readSceneParts(document)) return;
+ recordAuthoredMedia(document.documentElement);
+ authoredMediaObserver = new MutationObserver((records) => {
+ for (const record of records) {
+ record.addedNodes.forEach(recordAuthoredMedia);
+ // The parser can yield inside a <video>, so its <source> children may arrive after it.
+ const { target } = record;
+ if (isElementNode(target) && isMedia(target))
+ authoredMedia.set(target, authoredShape(target));
+ }
+ });
+ authoredMediaObserver.observe(document.documentElement, { childList: true, subtree: true });
+}
+
// URL attributes a scene swap checks besides src, poster and srcset, by tag.
const MEDIA_URL_ATTRS = new Map([
["image", ["href", "xlink:href"]],
@@ -264,12 +328,9 @@ function pageAnimationsForOnePass(): () => Animation[] {
export function initSandboxRuntimeModular(): void {
const state = createRuntimeState();
- // Each video and audio as written, captured before the runtime writes to it; a swap keeps only these.
- const authoredMedia = new WeakMap<Element, string>();
- if (readSceneParts(document)) {
- for (const el of document.querySelectorAll("video, audio"))
- authoredMedia.set(el, authoredShape(el));
- }
+ authoredMediaObserver?.disconnect();
+ authoredMediaObserver = null;
+ if (readSceneParts(document)) recordAuthoredMedia(document.documentElement);
// Runtime-data handlers may replace the timeline object they mutate. Keep the
// reconciliation callback late-bound because the reporter is installed before
// the timeline resolver/binder is declared below. Delivery cannot complete
@@ -2359,16 +2420,19 @@ export function initSandboxRuntimeModular(): void {
}
};
+ const authoredMediaVolume = (el: HTMLMediaElement): number | null => {
+ const parsed = Number.parseFloat(el.dataset.volume ?? "");
+ return Number.isFinite(parsed) ? Math.max(0, Math.min(1, parsed)) : null;
+ };
+
const bindMediaMetadataListeners = () => {
if (state.tornDown) return;
const mediaEls = Array.from(document.querySelectorAll("video, audio")) as HTMLMediaElement[];
for (const mediaEl of mediaEls) {
if (metadataBoundMedia.has(mediaEl)) continue;
metadataBoundMedia.add(mediaEl);
- const parsedVolume = Number.parseFloat(mediaEl.dataset.volume ?? "");
- if (Number.isFinite(parsedVolume)) {
- mediaEl.volume = Math.max(0, Math.min(1, parsedVolume));
- }
+ const volume = authoredMediaVolume(mediaEl);
+ if (volume !== null) mediaEl.volume = volume;
mediaEl.addEventListener("loadedmetadata", scheduleMetadataDurationHydration);
mediaEl.addEventListener("durationchange", scheduleMetadataDurationHydration);
// Web Audio eligibility, reported at DISCOVERY rather than only at
@@ -3243,23 +3307,87 @@ export function initSandboxRuntimeModular(): void {
return urls;
};
let sceneSwapGeneration = 0;
- // A video or audio the edit left as written keeps playing: the old element takes its copy's place.
- const keepUnchangedMedia = (oldHost: Element, host: Element) => {
+ // A video or audio the edit left as written keeps playing, unless the scene's scripts changed: what the
+ // old script wrote to it directly is unknown. A rebuilt one is recorded from the new markup.
+ const keepUnchangedMedia = (oldHost: Element, host: Element, sameScripts: boolean) => {
const byShape = new Map<string, Element[]>();
- for (const el of oldHost.querySelectorAll("video, audio")) {
+ for (const el of sameScripts ? oldHost.querySelectorAll("video, audio") : []) {
const shape = authoredMedia.get(el);
// Its grading canvas sits beside it in the old scene and cannot follow it.
if (!shape || colorGradingRuntime?.isGraded(el)) continue;
+ // A stream, output device or key session a script gave it is not in the markup.
+ const { srcObject, sinkId, mediaKeys } = el as HTMLMediaElement;
+ if (srcObject || sinkId || mediaKeys) continue;
byShape.set(shape, [...(byShape.get(shape) ?? []), el]);
}
for (const el of host.querySelectorAll("video, audio")) {
- const kept = byShape.get(authoredShape(el))?.shift();
- if (kept) el.replaceWith(kept);
+ const shape = authoredShape(el);
+ const kept = byShape.get(shape)?.shift();
+ // Anything a script wrote on it, under the old markup or not, is not in a fresh load's copy.
+ if (!kept || writtenShape(kept) !== writtenShape(el)) {
+ authoredMedia.set(el, shape);
+ continue;
+ }
+ el.replaceWith(kept);
+ // Back as written, the tween cache emptied, so the new script's tweens read what a fresh load's do.
+ window.gsap?.set?.(kept, { clearProps: "all" });
+ const style = el.getAttribute("style");
+ if (style === null) kept.removeAttribute("style");
+ else kept.setAttribute("style", style);
+ // The swap's closing pass puts its move back, as a load's first pass does.
+ forgetPositionEdit(kept as HTMLElement);
+ // Properties no attribute shows, as a load sets them.
+ const media = kept as HTMLMediaElement;
+ media.volume = authoredMediaVolume(media) ?? 1;
+ media.muted = state.bridgeMuted || state.mediaOutputMuted || media.defaultMuted;
+ media.defaultPlaybackRate = 1;
+ media.playbackRate = state.playbackRate;
+ media.preservesPitch = true;
+ }
+ };
+ const compositionIdsIn = (host: Element) =>
+ [host, ...host.querySelectorAll("[data-composition-id]")].flatMap(
+ (el) => el.getAttribute("data-composition-id") || [],
+ );
+ // gsap binds a tween to elements, so one from outside the scene would go on moving the replaced copy.
+ const refuseOutsideTweens = (
+ name: string,
+ host: Element,
+ timelines: Record<string, RuntimeTimelineLike | undefined>,
+ sceneAnimations: Record<string, SceneAnimation[]>,
+ ) => {
+ const own = new Set<unknown>(
+ compositionIdsIn(host).flatMap((id) => [timelines[id], ...(sceneAnimations[id] ?? [])]),
+ );
+ const inScene = new Set<unknown>([host, ...host.querySelectorAll("*")]);
+ for (const tween of window.gsap?.globalTimeline?.getChildren?.(true, true, false) ?? []) {
+ if (!tween.targets?.().some((target) => inScene.has(target))) continue;
+ let owner: RuntimeTimelineChildLike | undefined = tween;
+ while (owner && !own.has(owner)) owner = owner.parent;
+ if (!owner) {
+ throw new Error(
+ `scene ${name} cannot be swapped: an animation outside it moves its elements`,
+ );
+ }
+ }
+ // A revert can leave a value on what the swap keeps; kept media are reset, page nodes outside are refused.
+ const outside = (target: unknown) =>
+ typeof (target as Node | null)?.nodeType === "number" && !inScene.has(target);
+ for (const animation of own as Set<SceneAnimation | undefined>) {
+ for (const tween of animation
+ ? [animation, ...(animation.getChildren?.(true, true, false) ?? [])]
+ : []) {
+ if (tween.targets?.().some(outside)) {
+ throw new Error(
+ `scene ${name} cannot be swapped: its animations write outside the scene`,
+ );
+ }
+ }
}
};
// Swap edited scenes in place from a rebuilt preview document. Refuses before changing anything unless
// the documents differ only inside existing scenes; a later failure is left to the caller's reload.
- const swapScenes = async (html: string): Promise<void> => {
+ const swapScenes = async (html: string, signal?: AbortSignal): Promise<void> => {
const generation = sceneSwapGeneration;
const next = new DOMParser().parseFromString(html, "text/html");
const liveParts = readSceneParts(document);
@@ -3306,40 +3434,108 @@ export function initSandboxRuntimeModular(): void {
if (styleCount(oldParts) !== styleCount(newParts)) {
throw new Error(`scene ${name} cannot be swapped: its styles moved`);
}
- return { oldParts, newParts, oldHost, newHost };
+ return {
+ name,
+ oldParts,
+ homes: oldParts.map((el) => el.parentNode),
+ newParts,
+ oldHost,
+ newHost,
+ };
});
+ // Each parent on a scene host's way up to the film root, once, with its children in order. The runtime marks
+ // what it inserts beside media, such as grading canvases, as ignored.
+ const sceneLayout = () => {
+ const film = resolveRootCompositionElement();
+ const parents = new Set<Element>();
+ for (const el of document.querySelectorAll(`[${SCENE_PART_ATTR}]`)) {
+ if (el.tagName === "STYLE" || el.tagName === "SCRIPT") continue;
+ let node = el.parentElement;
+ for (; node; node = node === film ? null : node.parentElement) {
+ parents.add(node);
+ }
+ }
+ return [...parents].flatMap((parent) => [
+ parent,
+ ...Array.from(parent.children).filter((child) => !child.hasAttribute("data-hf-ignore")),
+ null,
+ ]);
+ };
+ const layout = sceneLayout();
// Fetched before the first write, so a stalled or failed request leaves the page as it was.
const captionOverrides = swaps.some(({ newHost }) => newHost.querySelector(".caption-group"))
? await fetchCaptionOverrides()
: [];
if (state.tornDown) throw new Error("the preview was torn down during the swap");
+ if (signal?.aborted) throw new Error("the swap was cancelled");
if (generation !== sceneSwapGeneration) {
throw new Error("the preview changed while this swap waited");
}
+ // A data handler or a revert callback can replace or move a scene's parts; the swap would then lose the scene.
+ const refuseReplacedScenes = () => {
+ const moved = ({ oldParts, homes }: (typeof swaps)[number]) =>
+ oldParts.some((el, i) => !el.isConnected || el.parentNode !== homes[i]);
+ const now = sceneLayout();
+ const relaidOut = now.length !== layout.length || now.some((node, i) => node !== layout[i]);
+ if (relaidOut || swaps.some(moved)) {
+ throw new Error("a scene changed while this swap waited");
+ }
+ };
+ refuseReplacedScenes();
+ // Read at each use: a data handler or an animation's callback may replace the registry mid-swap.
+ const timelines = () =>
+ (window.__timelines ??= {}) as Record<string, RuntimeTimelineLike | undefined>;
+ const sceneAnimations = () => (window.__hfSceneAnimations ??= {});
+ const refuseAnyOutsideTweens = () => {
+ for (const { name, oldHost } of swaps)
+ refuseOutsideTweens(name, oldHost, timelines(), sceneAnimations());
+ };
+ // Checked after the wait, which a tween could start in, and before anything changes.
+ refuseAnyOutsideTweens();
sceneSwapGeneration += 1;
- const timelines = (window.__timelines ??= {}) as Record<
- string,
- RuntimeTimelineLike | undefined
- >;
const root = state.capturedTimeline as
| (RuntimeTimelineLike & { remove?: (child: unknown) => unknown })
| null;
// Overrides re-dim every word they touch, so only the swapped scenes' captions get them.
const captionHosts: Element[] = [];
const swappedHosts: Element[] = [];
- for (const { oldParts, newParts, oldHost, newHost } of swaps) {
- for (const el of [oldHost, ...oldHost.querySelectorAll("[data-composition-id]")]) {
- const id = el.getAttribute("data-composition-id");
- const previous = id ? timelines[id] : undefined;
- if (!id || !previous) continue;
- const old = previous as { revert?: () => void; kill?: () => void };
- if (old.revert) old.revert();
- else previous.totalTime?.(0, true);
- root?.remove?.(previous);
- // revert() has already killed it; a second kill() fires onInterrupt again.
- if (!old.revert) old.kill?.();
- delete timelines[id];
+ const oldIds = swaps.flatMap(({ oldHost }) => compositionIdsIn(oldHost));
+ const stopped = new Set<unknown>();
+ const stopOldAnimations = () => {
+ const before = stopped.size;
+ for (const id of oldIds) {
+ // Newest first: each revert restores what the animation before it wrote.
+ for (const previous of [
+ ...(sceneAnimations()[id] ?? []).slice().reverse(),
+ timelines()[id],
+ ]) {
+ if (!previous || stopped.has(previous)) continue;
+ stopped.add(previous);
+ const old = previous as SceneAnimation;
+ if (old.revert) old.revert();
+ else old.totalTime?.(0, true);
+ root?.remove?.(previous);
+ // revert() has already killed it; a second kill() fires onInterrupt again.
+ if (!old.revert) old.kill?.();
+ }
}
+ return stopped.size > before;
+ };
+ // A revert fires the animation's onInterrupt, which can register more; stop those too, until none appear.
+ let passes = 0;
+ while (stopOldAnimations()) {
+ if (++passes > 8) throw new Error("the old scene keeps starting animations as they stop");
+ }
+ refuseReplacedScenes();
+ refuseAnyOutsideTweens();
+ for (const id of oldIds) {
+ delete timelines()[id];
+ delete sceneAnimations()[id];
+ }
+ // Released before kept media is reset: a later stop puts back the mute and volume it saved under the old script.
+ webAudio.stopAll();
+ clock.detachAudioSource();
+ for (const { oldParts, newParts, oldHost, newHost } of swaps) {
// Each new style takes its own old one's place: same-named @keyframes resolve by order.
const newStyles = newParts.filter((el) => el.tagName === "STYLE");
oldParts
@@ -3347,10 +3543,15 @@ export function initSandboxRuntimeModular(): void {
.forEach((el, i) => el.replaceWith(document.importNode(newStyles[i]!, true)));
for (const el of oldParts) if (el !== oldHost) el.remove();
const host = document.importNode(newHost, true);
- keepUnchangedMedia(oldHost, host);
+ const scripts = (parts: Element[]) =>
+ parts.flatMap((el) => (el.tagName === "SCRIPT" ? el.outerHTML : [])).join("");
+ keepUnchangedMedia(oldHost, host, scripts(oldParts) === scripts(newParts));
oldHost.replaceWith(host);
swappedHosts.push(host);
if (host.querySelector(".caption-group")) captionHosts.push(host);
+ }
+ // Run once every host is replaced, so no new script binds to a scene still to be swapped.
+ for (const { newParts } of swaps) {
for (const el of newParts) {
if (el.tagName !== "SCRIPT") continue;
// An imported <script> never runs; a created one does.
@@ -3359,8 +3560,6 @@ export function initSandboxRuntimeModular(): void {
script.textContent = el.textContent;
document.body.appendChild(script);
}
- for (const el of host.querySelectorAll("video, audio"))
- if (!authoredMedia.has(el)) authoredMedia.set(el, authoredShape(el));
}
document
.querySelector(`meta[name="${SCENE_PARTS_META}"]`)
@@ -3373,7 +3572,7 @@ export function initSandboxRuntimeModular(): void {
for (const host of captionHosts) {
for (const el of [host, ...host.querySelectorAll("[data-composition-id]")]) {
const id = el.getAttribute("data-composition-id");
- if (id) timelines[id]?.totalTime?.(0, true);
+ if (id) window.__timelines?.[id]?.totalTime?.(0, true);
}
}
};
@@ -3395,8 +3594,9 @@ export function initSandboxRuntimeModular(): void {
runAdapters("discover", state.currentTime);
// The rebind above skips these when the root timeline object did not change.
applyPositionEdits(document);
- // Redraw the current frame as a seek does, forcing a render at an unchanged time.
- transport.seek(state.currentTime, { keepPlaying: true });
+ // Redraw the current frame as a seek does; a playing film cut to end at or before it stops there, as at its end.
+ const cutShort = clock.isPlaying() && duration > 0 && state.currentTime >= duration;
+ transport.seek(cutShort ? duration : state.currentTime, { keepPlaying: !cutShort });
syncTimedElementVisibility(state.currentTime);
postTimeline();
};
diff --git a/packages/core/src/runtime/positionEdits.ts b/packages/core/src/runtime/positionEdits.ts
index d2908a9091..12d2c8e4df 100644
--- a/packages/core/src/runtime/positionEdits.ts
+++ b/packages/core/src/runtime/positionEdits.ts
@@ -123,6 +123,11 @@ export const readCurrentTranslate = (el: StylableElement): string => {
*/
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
diff --git a/packages/core/src/runtime/types.ts b/packages/core/src/runtime/types.ts
index 2c2dabda8a..1ea0823d52 100644
--- a/packages/core/src/runtime/types.ts
+++ b/packages/core/src/runtime/types.ts
@@ -295,6 +295,16 @@ export type RuntimeTimelineChildLike = {
getChildren?: RuntimeTimelineLike["getChildren"];
};
+/** A timeline or tween a composition script started, as a scene swap stops it. */
+export type SceneAnimation = {
+ targets?: () => unknown[];
+ duration?: () => number;
+ getChildren?: (nested?: boolean, tweens?: boolean, timelines?: boolean) => SceneAnimation[];
+ revert?: () => void;
+ kill?: () => void;
+ totalTime?: (timeSeconds?: number, suppressEvents?: boolean) => unknown;
+};
+
export type RuntimeTimelineLike = {
play: () => void;
pause: () => void;
diff --git a/packages/core/src/runtime/window.d.ts b/packages/core/src/runtime/window.d.ts
index 38d353de40..bca2aecff2 100644
--- a/packages/core/src/runtime/window.d.ts
+++ b/packages/core/src/runtime/window.d.ts
@@ -1,4 +1,10 @@
-import type { RuntimeSeekOptions, RuntimeTimelineMessage, RuntimeTimelineLike } from "./types";
+import type {
+ RuntimeSeekOptions,
+ RuntimeTimelineChildLike,
+ RuntimeTimelineMessage,
+ RuntimeTimelineLike,
+ SceneAnimation,
+} from "./types";
import type { RuntimeColorGradingApi } from "./colorGrading";
import type { HyperframePickerApi } from "../inline-scripts/pickerApi";
import type { PlayerAPI } from "../core.types";
@@ -80,8 +86,10 @@ declare global {
__playerReady?: boolean;
__renderReady?: boolean;
__hfRuntimeTeardown?: (() => void) | null;
+ /** What each composition's scripts started on gsap's global timeline, by composition id. */
+ __hfSceneAnimations?: Record<string, SceneAnimation[]> | null;
/** Swap edited scenes from a rebuilt preview document; refuses before changing anything when it cannot. */
- __hfSwapScenes?: (html: string) => Promise<void>;
+ __hfSwapScenes?: (html: string, signal?: AbortSignal) => Promise<void>;
__HF_EXPORT_RENDER_SEEK_CONFIG?: {
mode?: string;
diagnostics?: boolean;
@@ -127,11 +135,19 @@ declare global {
__HF_PICKER_API?: HyperframePickerApi;
gsap?: {
timeline: (params?: { paused?: boolean }) => RuntimeTimelineLike;
+ set?: (target: Element, vars: Record<string, unknown>) => unknown;
parseEase?: (
ease: string | ((progress: number) => number),
...args: unknown[]
) => ((progress: number) => number) | null;
registerPlugin?: (plugin: unknown) => void;
+ globalTimeline?: {
+ getChildren?: (
+ nested?: boolean,
+ tweens?: boolean,
+ timelines?: boolean,
+ ) => RuntimeTimelineChildLike[];
+ };
ticker?: {
tick: () => void;
};