@hyperframes/studio 0.8.88 → 0.8.90

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.88",
+  "version": "0.8.90",
   "description": "",
   "repository": {
     "type": "git",
@@ -60,12 +60,12 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/parsers": "0.8.88",
-    "@hyperframes/core": "0.8.88",
-    "@hyperframes/player": "0.8.88",
-    "@hyperframes/studio-server": "0.8.88",
-    "@hyperframes/sdk": "0.8.88",
-    "@hyperframes/shader-transitions": "0.8.88"
+    "@hyperframes/core": "0.8.90",
+    "@hyperframes/parsers": "0.8.90",
+    "@hyperframes/player": "0.8.90",
+    "@hyperframes/sdk": "0.8.90",
+    "@hyperframes/shader-transitions": "0.8.90",
+    "@hyperframes/studio-server": "0.8.90"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -81,7 +81,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.88"
+    "@hyperframes/producer": "0.8.90"
   },
   "peerDependencies": {
     "react": "19",

package/src/components/editor/DomEditOverlay.tsx

@@ -81,15 +81,18 @@ export interface DomEditOverlayProps {
     selection: DomEditSelection,
     next: { x: number; y: number },
     modifiers?: { altKey?: boolean },
-  ) => Promise<void> | void;
-  onGroupPathOffsetCommit: (updates: DomEditGroupPathOffsetCommit[]) => Promise<void> | void;
+  ) => Promise<unknown> | void;
+  onGroupPathOffsetCommit: (updates: DomEditGroupPathOffsetCommit[]) => Promise<unknown> | void;
   onBoxSizeCommit: (
     selection: DomEditSelection,
     next: { width: number; height: number },
     offset?: { x: number; y: number },
     restore?: () => void,
-  ) => Promise<void> | void;
-  onRotationCommit: (selection: DomEditSelection, next: { angle: number }) => Promise<void> | void;
+  ) => Promise<unknown> | void;
+  onRotationCommit: (
+    selection: DomEditSelection,
+    next: { angle: number },
+  ) => Promise<unknown> | void;
   onStyleCommit?: (property: string, value: string) => Promise<unknown> | void;
   recordingState?: GestureRecordingState;
   onToggleRecording?: () => void;

package/src/components/editor/domEditOverlayGestures.ts

@@ -247,10 +247,10 @@ export type UseDomEditOverlayGesturesOptions = {
       s: DomEditSelection,
       n: { x: number; y: number },
       m?: { altKey?: boolean },
-    ) => Promise<void> | void
+    ) => Promise<unknown> | void
   >;
   onGroupPathOffsetCommitRef: RefObject<
-    (updates: DomEditGroupPathOffsetCommit[]) => Promise<void> | void
+    (updates: DomEditGroupPathOffsetCommit[]) => Promise<unknown> | void
   >;
   onBoxSizeCommitRef: RefObject<
     (
@@ -258,10 +258,10 @@ export type UseDomEditOverlayGesturesOptions = {
       n: { width: number; height: number },
       offset?: { x: number; y: number },
       restore?: () => void,
-    ) => Promise<void> | void
+    ) => Promise<unknown> | void
   >;
   onRotationCommitRef: RefObject<
-    (s: DomEditSelection, n: { angle: number }) => Promise<void> | void
+    (s: DomEditSelection, n: { angle: number }) => Promise<unknown> | void
   >;
   onCanvasPointerMoveRef: RefObject<
     (

package/src/components/editor/useDomEditNudge.ts

@@ -60,10 +60,10 @@ export interface UseDomEditNudgeParams {
       s: DomEditSelection,
       n: { x: number; y: number },
       m?: { altKey?: boolean },
-    ) => Promise<void> | void
+    ) => Promise<unknown> | void
   >;
   onGroupPathOffsetCommitRef: RefObject<
-    (updates: DomEditGroupPathOffsetCommit[]) => Promise<void> | void
+    (updates: DomEditGroupPathOffsetCommit[]) => Promise<unknown> | void
   >;
 }
 

package/src/components/editor/useInlineTextEditing.tsx

@@ -61,10 +61,8 @@ export function useInlineTextEditing(
   const elementUnderPress = (event: { clientX: number; clientY: number }) => {
     const iframe = actions?.previewIframeRef?.current;
     if (!iframe) return null;
-    // Studio suppresses pointer events inside the composition so the canvas
-    // overlay can own input, which means a plain elementFromPoint only ever
-    // finds wrappers. This helper lifts that for the length of the hit test,
-    // and is the same one the canvas uses to decide what was clicked.
+    // The same hit test the canvas uses to decide what was clicked; a plain
+    // elementFromPoint only finds wrappers, since Studio suppresses pointer events.
     return getPreviewTargetFromPointer(
       iframe,
       event.clientX,

package/src/hooks/useDomGeometryCommit.test.tsx

@@ -0,0 +1,226 @@
+// @vitest-environment happy-dom
+import { act, createElement, useRef } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  useDomGeometryCommit,
+  usePlayerStore,
+  type DomEditOverlayProps,
+  type UseDomGeometryCommitOptions,
+} from "../index";
+import { makeSelection } from "./domSelectionTestHarness";
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+
+const SOURCE = '<div id="card">Card</div><div id="other">Other</div>';
+
+/** A warm parse where only another element animates, and a GSAP writer answering `status`. */
+function stubServer(status = 200, parseStatus = 200) {
+  const mutations: unknown[] = [];
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = String(input instanceof Request ? input.url : input);
+      const json = (body: unknown, code = 200) =>
+        new Response(JSON.stringify(body), {
+          status: code,
+          headers: { "content-type": "application/json" },
+        });
+      if (url.includes("/api/projects/p1/gsap-animations/")) {
+        if (parseStatus !== 200) return json({ error: "down" }, parseStatus);
+        return json({
+          animations: [
+            {
+              id: "other-fade",
+              targetSelector: "#other",
+              method: "to",
+              position: 0,
+              duration: 1,
+              properties: { opacity: 1 },
+              propertyGroup: "opacity",
+            },
+          ],
+        });
+      }
+      if (url.includes("/api/projects/p1/gsap-mutations/")) {
+        mutations.push(JSON.parse(String(init?.body)));
+        if (status !== 200) return json({ error: "refused" }, status);
+        return json({ ok: true, changed: true, before: "BEFORE", after: "AFTER" });
+      }
+      throw new Error(`Unexpected fetch: ${url}`);
+    }),
+  );
+  return mutations;
+}
+
+function renderHost(options: Partial<UseDomGeometryCommitOptions> = {}) {
+  const iframe = document.createElement("iframe");
+  document.body.append(iframe);
+  const doc = iframe.contentDocument;
+  if (!doc) throw new Error("Expected iframe document");
+  doc.body.innerHTML = SOURCE;
+  const element = doc.getElementById("card") as HTMLElement;
+  const recordEdit = vi.fn(async () => {});
+  const writeProjectFile = vi.fn(async () => {});
+  const reloadPreview = vi.fn();
+  const api: { current: ReturnType<typeof useDomGeometryCommit> | null } = { current: null };
+  function Host() {
+    const iframeRef = useRef<HTMLIFrameElement | null>(iframe);
+    api.current = useDomGeometryCommit({
+      projectId: "p1",
+      iframeRef,
+      writeProjectFile,
+      recordEdit,
+      reloadPreview,
+      ...options,
+    });
+    return null;
+  }
+  const root = createRoot(document.createElement("div"));
+  act(() => root.render(createElement(Host)));
+  const hook = () => {
+    if (!api.current) throw new Error("Expected the hook to render");
+    return api.current;
+  };
+  return {
+    element,
+    recordEdit,
+    hook,
+    rerender: () => act(() => root.render(createElement(Host))),
+    unmount: () => act(() => root.unmount()),
+  };
+}
+
+beforeEach(() => {
+  usePlayerStore.setState({ previewBooted: true, timelineProjectId: "p1" });
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  document.body.innerHTML = "";
+});
+
+describe("useDomGeometryCommit, from the package entry", () => {
+  it("plugs into DomEditOverlay and saves a move as one GSAP write and one undo step", async () => {
+    const mutations = stubServer();
+    const { element, recordEdit, hook, unmount } = renderHost();
+    const overlayCommits: Pick<
+      DomEditOverlayProps,
+      "onPathOffsetCommit" | "onGroupPathOffsetCommit" | "onBoxSizeCommit" | "onRotationCommit"
+    > = {
+      onPathOffsetCommit: hook().commitPathOffset,
+      onGroupPathOffsetCommit: hook().commitGroupPathOffset,
+      onBoxSizeCommit: hook().commitBoxSize,
+      onRotationCommit: hook().commitRotation,
+    };
+
+    const outcome = await overlayCommits.onPathOffsetCommit(makeSelection("card", element), {
+      x: 40,
+      y: 20,
+    });
+
+    expect(outcome).toEqual({ ok: true });
+    expect(mutations).toEqual([
+      expect.objectContaining({ type: "add", targetSelector: "#card", method: "set" }),
+    ]);
+    expect(recordEdit).toHaveBeenCalledTimes(1);
+    expect(recordEdit).toHaveBeenCalledWith(
+      expect.objectContaining({ files: { "index.html": { before: "BEFORE", after: "AFTER" } } }),
+    );
+    unmount();
+  });
+
+  it("keeps the same commits across renders, so the overlay's handlers stay put", () => {
+    stubServer();
+    const { hook, rerender, unmount } = renderHost();
+    const first = hook();
+    rerender();
+    expect(hook().commitPathOffset).toBe(first.commitPathOffset);
+    expect(hook().commitRotation).toBe(first.commitRotation);
+    unmount();
+  });
+
+  it("rejects a move the server refuses, so the overlay undoes it", async () => {
+    stubServer(500);
+    const showToast = vi.fn();
+    const { element, recordEdit, hook, unmount } = renderHost({ showToast });
+
+    await expect(
+      hook().commitPathOffset(makeSelection("card", element), { x: 40, y: 20 }),
+    ).rejects.toThrow();
+    expect(recordEdit).not.toHaveBeenCalled();
+    expect(showToast).toHaveBeenCalledWith(expect.any(String), "error");
+    unmount();
+  });
+
+  it("undoes a resize whose animations cannot be read, and saves nothing", async () => {
+    const mutations = stubServer(200, 500);
+    const showToast = vi.fn();
+    const restore = vi.fn();
+    const { element, recordEdit, hook, unmount } = renderHost({ showToast });
+
+    await expect(
+      hook().commitBoxSize(
+        makeSelection("card", element),
+        { width: 300, height: 90 },
+        undefined,
+        restore,
+      ),
+    ).rejects.toThrow();
+    expect(restore).toHaveBeenCalledTimes(1);
+    expect(showToast).toHaveBeenCalledWith(expect.any(String), "error");
+    expect(mutations).toHaveLength(0);
+    expect(recordEdit).not.toHaveBeenCalled();
+    unmount();
+  });
+
+  it.each([
+    ["the player shows another project", { timelineProjectId: "another-project" }],
+    ["the preview has not booted", { previewBooted: false }],
+  ])("refuses at once when %s", async (_state, store) => {
+    const mutations = stubServer();
+    usePlayerStore.setState(store);
+    const restore = vi.fn();
+    const showToast = vi.fn();
+    const { element, hook, unmount } = renderHost({ showToast });
+
+    await expect(
+      hook().commitBoxSize(
+        makeSelection("card", element),
+        { width: 300, height: 90 },
+        undefined,
+        restore,
+      ),
+    ).rejects.toThrow("has not loaded yet");
+    expect(restore).toHaveBeenCalledTimes(1);
+    expect(showToast).toHaveBeenCalledWith(expect.stringContaining("not loaded"), "error");
+    expect(mutations).toHaveLength(0);
+    unmount();
+  });
+
+  it("waits for a move still being saved", async () => {
+    const mutations = stubServer();
+    const { element, recordEdit, hook, unmount } = renderHost();
+
+    const move = hook().commitPathOffset(makeSelection("card", element), { x: 40, y: 20 });
+    await hook().waitForPendingSaves();
+
+    expect(mutations).toHaveLength(1);
+    expect(recordEdit).toHaveBeenCalledTimes(1);
+    await move;
+    unmount();
+  });
+
+  it("rejects without a project and writes nothing", async () => {
+    const mutations = stubServer();
+    const { element, hook, unmount } = renderHost({ projectId: null });
+
+    await expect(
+      hook().commitRotation(makeSelection("card", element), { angle: 15 }),
+    ).rejects.toThrow("No project is open");
+    expect(mutations).toHaveLength(0);
+    unmount();
+  });
+});

package/src/hooks/useDomGeometryCommit.ts

@@ -0,0 +1,147 @@
+import { useCallback, useMemo, useRef } from "react";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { DomEditSelection } from "../components/editor/domEditing";
+import type { DomEditGroupPathOffsetCommit } from "../components/editor/DomEditOverlay";
+import { isPreviewBooted } from "../player/store/playerStore";
+import type { DomEditCommitOutcome } from "./domEditCommitRunner";
+import type { UseDomStyleCommitOptions } from "./useDomStyleCommit";
+import { useGsapAnimationFetchFallback } from "./useGsapAnimationFetchFallback";
+import { useGsapAwareEditing } from "./useGsapAwareEditing";
+import { useGsapInteractionFailureTelemetry } from "./useGsapInteractionFailureTelemetry";
+import { useGsapScriptCommits } from "./useGsapScriptCommits";
+import { useGsapCacheVersion } from "./useGsapTweenCache";
+
+/**
+ * Studio's `Player` must show the project, with `beginTimelineSession(projectId)` run before it
+ * mounts; drain `waitForPendingSaves` before switching projects.
+ */
+export interface UseDomGeometryCommitOptions extends UseDomStyleCommitOptions {
+  /** Called when a save cannot patch the preview in place; defaults to reloading the iframe. */
+  reloadPreview?: () => void;
+}
+
+export interface DomGeometryCommits {
+  commitPathOffset: (
+    selection: DomEditSelection,
+    next: { x: number; y: number },
+    modifiers?: { altKey?: boolean },
+  ) => Promise<DomEditCommitOutcome>;
+  commitGroupPathOffset: (updates: DomEditGroupPathOffsetCommit[]) => Promise<DomEditCommitOutcome>;
+  commitBoxSize: (
+    selection: DomEditSelection,
+    next: { width: number; height: number },
+    offset?: { x: number; y: number },
+    restore?: () => void,
+  ) => Promise<DomEditCommitOutcome>;
+  commitRotation: (
+    selection: DomEditSelection,
+    next: { angle: number },
+  ) => Promise<DomEditCommitOutcome>;
+  waitForPendingSaves: () => Promise<void>;
+}
+
+const noop = () => {};
+const NO_SELECTED_ANIMATIONS: GsapAnimation[] = [];
+// ponytail: unreachable, the GSAP writer always exists so a resize never takes the DOM route.
+const noDomBoxSizeRoute = () => Promise.reject(new Error("Resize has no DOM route here"));
+
+/**
+ * Saves canvas moves, resizes and rotations through Studio's own GSAP-aware commits, for a host
+ * without the editor. A failed save rejects, so DomEditOverlay undoes the live gesture.
+ */
+export function useDomGeometryCommit({
+  projectId,
+  iframeRef,
+  writeProjectFile,
+  recordEdit,
+  activeCompPath = null,
+  showToast = noop,
+  reloadPreview,
+}: UseDomGeometryCommitOptions): DomGeometryCommits {
+  const projectIdRef = useRef(projectId);
+  projectIdRef.current = projectId;
+  const pending = useRef(new Set<Promise<void>>()).current;
+  const editHistory = useMemo(() => ({ recordEdit }), [recordEdit]);
+  const reload = useCallback(
+    () => (reloadPreview ? reloadPreview() : iframeRef.current?.contentWindow?.location.reload()),
+    [reloadPreview, iframeRef],
+  );
+  const { bump: bumpGsapCache } = useGsapCacheVersion();
+  const gsap = useGsapScriptCommits({
+    projectIdRef,
+    activeCompPath,
+    previewIframeRef: iframeRef,
+    editHistory,
+    reloadPreview: reload,
+    onCacheInvalidate: bumpGsapCache,
+    showToast,
+    writeProjectFile,
+  });
+  const makeFetchFallback = useGsapAnimationFetchFallback(projectId);
+  const trackGsapInteractionFailure = useGsapInteractionFailureTelemetry(activeCompPath, showToast);
+  const {
+    handleGsapAwarePathOffsetCommit,
+    handleGsapAwareGroupPathOffsetCommit,
+    handleGsapAwareBoxSizeCommit,
+    handleGsapAwareRotationCommit,
+  } = useGsapAwareEditing({
+    // The host owns selection, so every gesture reads its element's animations from the server.
+    domEditSelection: null,
+    selectedGsapAnimations: NO_SELECTED_ANIMATIONS,
+    gsapCommitMutation: gsap.commitMutation,
+    previewIframeRef: iframeRef,
+    showToast,
+    bumpGsapCache,
+    makeFetchFallback,
+    trackGsapInteractionFailure,
+    handleDomBoxSizeCommit: noDomBoxSizeRoute,
+    addGsapAnimation: gsap.addGsapAnimation,
+    convertToKeyframes: gsap.convertToKeyframes,
+    setArcPath: gsap.setArcPath,
+    updateArcSegment: gsap.updateArcSegment,
+  });
+  const saved = useCallback(
+    async (commit: () => Promise<void>, restore = noop): Promise<DomEditCommitOutcome> => {
+      const refusal = !projectIdRef.current
+        ? "No project is open"
+        : !isPreviewBooted(projectIdRef.current)
+          ? "The preview for this project has not loaded yet"
+          : null;
+      if (refusal) {
+        restore();
+        showToast(refusal, "error");
+        throw new Error(refusal);
+      }
+      const run = commit();
+      pending.add(run);
+      try {
+        await run;
+      } finally {
+        pending.delete(run);
+      }
+      return { ok: true };
+    },
+    [pending, showToast],
+  );
+  return useMemo(
+    () => ({
+      commitPathOffset: (selection, next, modifiers) =>
+        saved(() => handleGsapAwarePathOffsetCommit(selection, next, modifiers)),
+      commitGroupPathOffset: (updates) =>
+        saved(() => handleGsapAwareGroupPathOffsetCommit(updates)),
+      commitBoxSize: (selection, next, offset, restore) =>
+        saved(() => handleGsapAwareBoxSizeCommit(selection, next, offset, restore), restore),
+      commitRotation: (selection, next) =>
+        saved(() => handleGsapAwareRotationCommit(selection, next)),
+      waitForPendingSaves: () => Promise.allSettled([...pending]).then(noop),
+    }),
+    [
+      saved,
+      pending,
+      handleGsapAwarePathOffsetCommit,
+      handleGsapAwareGroupPathOffsetCommit,
+      handleGsapAwareBoxSizeCommit,
+      handleGsapAwareRotationCommit,
+    ],
+  );
+}

package/src/hooks/useGsapAwareEditing.ts

@@ -298,10 +298,15 @@ export function useGsapAwareEditing({
       offset?: { x: number; y: number },
       restore: () => void = () => undefined,
     ) => {
-      const ownedAnimations = getGsapAnimationsForSelection(selection);
-      const targetAnimations = Array.isArray(ownedAnimations)
-        ? ownedAnimations
-        : await ownedAnimations;
+      let targetAnimations: GsapAnimation[];
+      try {
+        const ownedAnimations = getGsapAnimationsForSelection(selection);
+        targetAnimations = Array.isArray(ownedAnimations) ? ownedAnimations : await ownedAnimations;
+      } catch (error) {
+        restore();
+        trackGsapInteractionFailure(error, selection, "resize", "Resize animated layer");
+        throw error;
+      }
       const scaleRoute = targetAnimations.some((anim) => anim.propertyGroup === "scale");
       const selector = selectorFromSelection(selection);
       const hasLivePositionTween = selector

package/src/index.ts

@@ -167,7 +167,7 @@ export type { AudioMeterStripProps } from "./components/nle/AudioMeterStrip";
 export { useClipboard } from "./hooks/useClipboard";
 export type { UseClipboardOptions } from "./hooks/useClipboard";
 
-// DOM editing for a host outside EditorShell; useDomStyleCommit saves styles without the session.
+// DOM editing for a host outside EditorShell; the Commit hooks save without useDomEditSession.
 export { useDomEditSession } from "./hooks/useDomEditSession";
 export type { UseDomEditSessionParams } from "./hooks/useDomEditSession";
 export { usePreviewPersistence } from "./hooks/usePreviewPersistence";
@@ -181,6 +181,8 @@ export { useDomStyleCommit } from "./hooks/useDomStyleCommit";
 export type { UseDomStyleCommitOptions } from "./hooks/useDomStyleCommit";
 export type { DomEditCommitDeclineReason, DomEditCommitOutcome } from "./hooks/domEditCommitRunner";
 export { resolveDomEditSelection } from "./components/editor/domEditingLayers";
+export { useDomGeometryCommit } from "./hooks/useDomGeometryCommit";
+export type { DomGeometryCommits, UseDomGeometryCommitOptions } from "./hooks/useDomGeometryCommit";
 export { DomEditOverlay } from "./components/editor/DomEditOverlay";
 export type {
   DomEditGroupPathOffsetCommit,

package/src/player/sceneSwap.ts

@@ -17,6 +17,27 @@ export function onPreviewContentReplaced(
   };
 }
 
+export function markScenesStale(iframe: HTMLIFrameElement | null, files: readonly string[]): void {
+  const doc = iframe?.contentDocument;
+  const meta = doc?.querySelector<HTMLMetaElement>('meta[name="hf-scene-parts"]');
+  if (!doc || !meta) return;
+  let parts: { shared: string; scenes: Record<string, string> };
+  try {
+    parts = JSON.parse(meta.content);
+  } catch {
+    return;
+  }
+  for (const file of files) {
+    const hosts = doc.querySelectorAll(`[data-composition-file="${CSS.escape(file)}"]`);
+    if (hosts.length === 0 && file.endsWith(".html")) parts.shared = "";
+    for (const host of hosts) {
+      const scene = host.closest("[data-hf-scene]")?.getAttribute("data-hf-scene");
+      if (scene && scene in parts.scenes) parts.scenes[scene] = "";
+    }
+  }
+  meta.content = JSON.stringify(parts);
+}
+
 /** Null when the preview cannot swap; rejects when superseded, cancelled or a full reload is needed. */
 export function sceneSwapFor(
   iframe: HTMLIFrameElement,

package/src/utils/gsapUndoRestore.test.ts

@@ -259,6 +259,64 @@ describe("applyUndoRestoreToPreview", () => {
     expect(reloadPreview).toHaveBeenCalledTimes(1);
   });
 
+  it("blanks a restored scene's live hash before reloading, so the scene swap takes it", () => {
+    const { iframe, doc } = buildLiveIframe(
+      `<div data-hf-scene="scene0" data-composition-file="scenes/intro.html"><h1>Rep0</h1></div>` +
+        `<div data-hf-scene="scene1" data-composition-file="scenes/outro.html"></div>`,
+    );
+    const meta = doc.createElement("meta");
+    meta.name = "hf-scene-parts";
+    meta.content = JSON.stringify({ shared: "s", scenes: { scene0: "h0", scene1: "h1" } });
+    doc.head.append(meta);
+    let partsAtReload: unknown;
+    const reloadPreview = vi.fn(() => (partsAtReload = JSON.parse(meta.content)));
+    const files = {
+      "scenes/intro.html": { previous: "<h1>Rep0</h1>", restored: "<h1>Alpha</h1>" },
+    };
+    expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("full");
+    expect(partsAtReload).toEqual({ shared: "s", scenes: { scene0: "", scene1: "h1" } });
+
+    const withRoot = {
+      ...files,
+      [ROOT]: { previous: wrap("<p>b</p>"), restored: wrap("<p>a</p>") },
+    };
+    applyUndoRestoreToPreview(iframe, ROOT, withRoot, 3, reloadPreview);
+    // A restored page outside every scene forces the full reload, never a partial swap.
+    expect(partsAtReload).toEqual({ shared: "", scenes: { scene0: "", scene1: "h1" } });
+  });
+
+  it("leaves the scene hashes alone on a soft restore, so the next edit can still swap", () => {
+    const { iframe, doc } = buildLiveIframe(`<div id="a" style="color: red">t</div>`);
+    const meta = doc.createElement("meta");
+    meta.name = "hf-scene-parts";
+    meta.content = JSON.stringify({ shared: "s", scenes: { scene0: "h0" } });
+    doc.head.append(meta);
+    const files = {
+      [ROOT]: {
+        previous: wrap(`<div id="a" style="color: red">t</div>`),
+        restored: wrap(`<div id="a" style="color: blue">t</div>`),
+      },
+    };
+    expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, vi.fn())).toBe("soft");
+    expect(JSON.parse(meta.content)).toEqual({ shared: "s", scenes: { scene0: "h0" } });
+  });
+
+  it.each([
+    ["a restored stylesheet leaves the shared hash", "styles.css", '{"shared":"s","scenes":{}}'],
+    ["an unreadable manifest still reloads", "scenes/intro.html", "not json"],
+  ])("%s", (_name, path, content) => {
+    const { iframe, doc } = buildLiveIframe(`<div id="a">t</div>`);
+    const meta = doc.createElement("meta");
+    meta.name = "hf-scene-parts";
+    meta.content = content;
+    doc.head.append(meta);
+    const reloadPreview = vi.fn();
+    const files = { [path]: { previous: "a", restored: "b" } };
+    expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("full");
+    expect(reloadPreview).toHaveBeenCalledTimes(1);
+    expect(meta.content).toBe(content);
+  });
+
   it("full-reloads when the restore touches a sub-comp, not the active comp", () => {
     const { iframe } = buildLiveIframe(`<div id="a">t</div>`);
     const reloadPreview = vi.fn();

package/src/utils/gsapUndoRestore.ts

@@ -8,6 +8,7 @@ import {
   extractGsapScriptText,
   findGsapScriptElements,
 } from "./gsapSoftReload";
+import { markScenesStale } from "../player/sceneSwap";
 
 type PreviewWindow = Window & {
   __player?: { seek?: (t: number) => void };
@@ -184,7 +185,7 @@ export function applyUndoRestoreToPreview(
   activeCompPath: string | null,
   files: Record<string, UndoRestoreFile> | undefined,
   currentTime: number,
-  reloadPreview: () => void,
+  reload: () => void,
 ): "soft" | "full" {
   // The master view carries a NULL activeCompPath but the root iframe shows
   // index.html — the codebase-wide convention (`activeCompPath || "index.html"`).
@@ -192,6 +193,10 @@ export function applyUndoRestoreToPreview(
   // full-reloaded: the original "undo always blinks".
   const activeDocPath = activeCompPath ?? "index.html";
   const paths = files ? Object.keys(files) : [];
+  const reloadPreview = () => {
+    markScenesStale(iframe, paths);
+    reload();
+  };
   // Soft path only covers the single active-comp document in the root iframe.
   if (!iframe || !files || paths.length !== 1 || paths[0] !== activeDocPath) {
     reloadPreview();