@hyperframes/studio 0.8.116 → 0.8.118

package/src/components/editor/usePanelHiddenToggle.ts

@@ -0,0 +1,44 @@
+import { HF_AUDIO_GROUP_TAG } from "@hyperframes/core/audio-groups";
+import { useDomEditActionsContextOptional } from "../../contexts/DomEditContext";
+import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
+import { hiddenToggleVerb } from "../../player/components/hiddenToggle";
+import type { DomEditSelection } from "./domEditingTypes";
+
+/** The panel header's hide toggle, or undefined when this selection has no writer for it. */
+export function usePanelHiddenToggle({
+  element,
+  hidden,
+  selectedElementId,
+  onToggleElementHidden,
+}: {
+  element: Pick<DomEditSelection, "id" | "tagName">;
+  hidden: boolean;
+  selectedElementId: string | null | undefined;
+  onToggleElementHidden?: (elementKey: string, hidden: boolean) => void | Promise<void>;
+}): (() => void) | undefined {
+  const { onSetAudioGroupAttributeQuiet } = useTimelineEditContextOptional();
+  const domEditActions = useDomEditActionsContextOptional();
+  // A bus has no timeline row, so it mutes through the group's own writer.
+  const audioGroupId = element.tagName.toLowerCase() === HF_AUDIO_GROUP_TAG ? element.id : null;
+  const write = audioGroupId
+    ? onSetAudioGroupAttributeQuiet &&
+      (() =>
+        onSetAudioGroupAttributeQuiet(
+          audioGroupId,
+          "data-hidden",
+          hidden ? null : "",
+          `${hiddenToggleVerb(true, hidden)} element`,
+        ))
+    : selectedElementId && onToggleElementHidden
+      ? () => onToggleElementHidden(selectedElementId, !hidden)
+      : undefined;
+  // The label reads the selection snapshot, so re-read whatever is selected once the write lands.
+  return (
+    write &&
+    (() =>
+      void Promise.resolve(write()).then(() => {
+        const selection = domEditActions?.domEditSelectionRef.current;
+        if (selection) void domEditActions?.refreshDomEditSelectionFromPreview(selection);
+      }))
+  );
+}

package/src/contexts/DomEditContext.tsx

@@ -77,6 +77,7 @@ const SAVES_AN_EDIT = {
   handleUnroll: true,
   invalidateGsapCache: false,
   previewIframeRef: false,
+  domEditSelectionRef: false,
   commitMutation: true,
   applyMarqueeSelection: false,
   handleUpdateKeyframeEase: true,
@@ -329,6 +330,7 @@ export function DomEditProvider({
       handleUnroll,
       invalidateGsapCache,
       previewIframeRef,
+      domEditSelectionRef,
       commitMutation: stableCommitMutation,
       applyMarqueeSelection,
       handleUpdateKeyframeEase,
@@ -406,6 +408,7 @@ export function DomEditProvider({
       handleUnroll,
       invalidateGsapCache,
       previewIframeRef,
+      domEditSelectionRef,
       stableCommitMutation,
       applyMarqueeSelection,
       handleUpdateKeyframeEase,

package/src/hooks/gsapRuntimeKeyframes.ts

@@ -449,12 +449,12 @@ export const ROTATION_CHANNELS: string[] = [
 
 /** GSAP owns this element's position: a tween or hold writes it, or GSAP already renders its
  *  transform (a CSS translate would then apply twice). Everything else moves by plain CSS. */
-export function gsapWritesPosition(el: Element): boolean {
+function gsapWritesPosition(el: Element): boolean {
   return gsapRendersTransform(el) || gsapWritesChannels(el, MOVE_CHANNELS);
 }
 
 /** `gsapWritesPosition` for a rotate: everything else turns by its own CSS `rotate`. */
-export function gsapWritesRotation(el: Element): boolean {
+function gsapWritesRotation(el: Element): boolean {
   return gsapRendersTransform(el) || gsapWritesChannels(el, ROTATION_CHANNELS);
 }
 
@@ -474,10 +474,23 @@ const BOX_CHANNELS = [
 ];
 
 /** GSAP owns this element's box: its position, or any property the CSS box writer sets. Else a resize writes CSS. */
-export function gsapWritesBox(el: Element): boolean {
+function gsapWritesBox(el: Element): boolean {
   return gsapWritesPosition(el) || gsapWritesChannels(el, BOX_CHANNELS);
 }
 
+export type EditGesture = "move" | "resize" | "rotate";
+const GSAP_OWNS: Record<EditGesture, (el: Element) => boolean> = {
+  move: gsapWritesPosition,
+  resize: gsapWritesBox,
+  rotate: gsapWritesRotation,
+};
+
+/** The one GSAP-or-CSS route decision. Make it when an edit starts and carry it: mid-gesture
+ *  writes make GSAP render the element, so asking again at commit can flip the route. */
+export function editsPlainCss(el: Element, gesture: EditGesture): boolean {
+  return !GSAP_OWNS[gesture](el);
+}
+
 /** `hasNonHoldTweenForElement` for an element in hand, read from its own window's timelines. */
 export function elementHasNonHoldTween(el: Element, channels?: string[]): boolean {
   const win = el.ownerDocument.defaultView as {

package/src/hooks/gsapScriptCommitTypes.ts

@@ -44,7 +44,7 @@ export interface CommitMutationOptions {
    * error handling — a failed write still throws.
    */
   deferPreviewSync?: boolean;
-  /** Shares an in-place patch miss with the final render of one multi-write action. */
+  /** Carries a deferred write not yet on screen (no patch, or a missed one) to the final render. */
   previewFallbackLatch?: { pending: boolean };
   beforeReload?: () => void;
   /**

package/src/hooks/plainRotation.ts

@@ -27,7 +27,11 @@ export function savePlainRotation(
     ? buildClearRotationPatches(element)
     : [];
   if (patches.length) clearStudioRotation(element);
-  const drawn = applyCssRotation(element, next.angle, patches.length ? undefined : next.plain);
+  const drawn = applyCssRotation(
+    element,
+    next.angle,
+    patches.length ? undefined : (next.plain ?? undefined),
+  );
   patches.push(...drawn);
   const turn = drawn.at(-1)!;
   return commitPositionPatchToHtml(selection, patches, {

package/src/hooks/timelineTrackVisibility.ts

@@ -8,7 +8,8 @@ import {
   trackDisplaySuffix,
 } from "../player/components/timelineTrackDisplay";
 import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
-import { isAudioTimelineElement } from "../utils/timelineInspector";
+import { isAudioOnlyTrack } from "../utils/timelineInspector";
+import { hiddenToggleVerb } from "../player/components/hiddenToggle";
 import type { PatchOperation } from "../utils/sourcePatcher";
 import {
   findTimelineElementInIframe,
@@ -206,14 +207,8 @@ export async function toggleTimelineTrackHidden({
     displayNumber ?? trackDisplayNumber(timelineTrackOrder(timelineElements), track),
   );
   const trackElements = timelineElements.filter((element) => element.track === track);
-  const isAudioOnlyTrack = trackElements.length > 0 && trackElements.every(isAudioTimelineElement);
-  const label = isAudioOnlyTrack
-    ? hidden
-      ? `Mute track${suffix}`
-      : `Unmute track${suffix}`
-    : hidden
-      ? `Hide track${suffix}`
-      : `Show track${suffix}`;
+  const hiddenBefore = !hidden;
+  const label = `${hiddenToggleVerb(isAudioOnlyTrack(trackElements), hiddenBefore)} track${suffix}`;
   return setElementsHidden({
     projectId,
     activeCompPath,
@@ -240,19 +235,14 @@ export async function toggleTimelineElementHidden({
 }: ToggleTimelineElementHiddenInput): Promise<string[]> {
   const keys = new Set(typeof elementKey === "string" ? [elementKey] : elementKey);
   const elements = timelineElements.filter((item) => keys.has(item.key ?? item.id));
+  const hiddenBefore = !hidden;
+  const verb = hiddenToggleVerb(isAudioOnlyTrack(elements), hiddenBefore);
   return setElementsHidden({
     projectId,
     activeCompPath,
     elements,
     hidden,
-    label:
-      elements.length > 1
-        ? hidden
-          ? `Hide ${elements.length} elements`
-          : `Show ${elements.length} elements`
-        : hidden
-          ? "Hide element"
-          : "Show element",
+    label: elements.length > 1 ? `${verb} ${elements.length} elements` : `${verb} element`,
     previewIframe,
     writeProjectFile,
     recordEdit,

package/src/hooks/useDomEditPersist.test.tsx

@@ -0,0 +1,335 @@
+// @vitest-environment happy-dom
+import { act, createElement } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { DomEditSelection } from "../components/editor/domEditing";
+import type { PatchOperation } from "../utils/sourcePatcher";
+import type { CutoverResult } from "../utils/sdkCutover";
+import { studioManualEditSavesIn } from "../components/editor/manualEditsDom";
+import {
+  DomEditPersistPreparedWriteError,
+  DomEditPersistUnresolvableError,
+  DomEditPersistUnsafeValueError,
+} from "./domEditPersistFailure";
+import type { PersistDomEditOperations } from "./domEditCommitTypes";
+import { jsonResponse, requestUrl } from "./fetchStubTestUtils";
+import { useDomEditPersist, type UseDomEditPersistParams } from "./useDomEditPersist";
+
+const trackStudioEvent = vi.fn();
+const reseekPreviewRuntime = vi.fn();
+vi.mock("../utils/studioTelemetry", () => ({
+  trackStudioEvent: (...args: unknown[]) => trackStudioEvent(...args),
+}));
+vi.mock("./timelineTrackVisibility", () => ({
+  reseekPreviewRuntime: (...args: unknown[]) => reseekPreviewRuntime(...args),
+}));
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+const SOURCE = '<div data-hf-id="hf-card" style="color: red">Card</div>';
+const PATCHED = '<div data-hf-id="hf-card" style="color: blue">Card</div>';
+const OPERATIONS: PatchOperation[] = [{ type: "inline-style", property: "color", value: "blue" }];
+const selection = {
+  hfId: "hf-card",
+  selector: '[data-hf-id="hf-card"]',
+  selectorIndex: 0,
+  sourceFile: "index.html",
+} as DomEditSelection;
+
+function stubServer(patchResponse: Record<string, unknown>) {
+  const fetchMock = vi.fn(async (input: Parameters<typeof fetch>[0], _init?: RequestInit) => {
+    const url = requestUrl(input);
+    if (url.includes("/api/projects/p1/files/")) return jsonResponse({ content: SOURCE });
+    if (url.includes("/api/projects/p1/file-mutations/patch-element/")) {
+      return jsonResponse(patchResponse);
+    }
+    throw new Error(`Unexpected fetch: ${url}`);
+  });
+  vi.stubGlobal("fetch", fetchMock);
+  return fetchMock;
+}
+
+const CHANGED = { changed: true, content: PATCHED, path: "index.html", version: "v2" };
+const PREPARED = PATCHED.replace("Card", "Card!");
+const sdkResult = (result: CutoverResult) => vi.fn(async (): Promise<CutoverResult> => result);
+
+const patchPosts = (fetchMock: ReturnType<typeof stubServer>) =>
+  fetchMock.mock.calls.filter(([input]) => requestUrl(input).includes("/patch-element/"));
+
+let unmount: (() => void) | null = null;
+
+function renderPersist(over: Partial<UseDomEditPersistParams> = {}) {
+  const params: UseDomEditPersistParams = {
+    activeCompPath: "index.html",
+    previewIframeRef: { current: null },
+    showToast: vi.fn(),
+    queueDomEditSave: (save) => save(),
+    writeProjectFile: vi.fn(async () => {}),
+    editHistory: { recordEdit: vi.fn(async () => {}) },
+    projectIdRef: { current: "p1" },
+    reloadPreview: vi.fn(),
+    forceReloadSdkSession: vi.fn(),
+    ...over,
+  };
+  const captured: { persist: PersistDomEditOperations | null } = { persist: null };
+  function Probe() {
+    captured.persist = useDomEditPersist(params);
+    return null;
+  }
+  const root = createRoot(document.createElement("div"));
+  act(() => root.render(createElement(Probe)));
+  unmount = () => act(() => root.unmount());
+  if (!captured.persist) throw new Error("hook did not initialize");
+  return { persist: captured.persist, params };
+}
+
+describe("useDomEditPersist", () => {
+  beforeEach(() => {
+    trackStudioEvent.mockReset();
+    reseekPreviewRuntime.mockReset();
+  });
+  afterEach(() => {
+    unmount?.();
+    unmount = null;
+    vi.unstubAllGlobals();
+  });
+
+  it("patches the source, records the edit and reloads the preview", async () => {
+    const fetchMock = stubServer({
+      changed: true,
+      content: PATCHED,
+      path: "index.html",
+      version: "v2",
+    });
+    const { persist, params } = renderPersist();
+
+    const outcome = await persist(selection, OPERATIONS, { label: "Recolor" });
+
+    expect(outcome).toEqual({ sourceFile: "index.html", version: "v2", changed: true });
+    const [, init] = patchPosts(fetchMock)[0]!;
+    expect(JSON.parse(String(init?.body))).toEqual({
+      target: { hfId: "hf-card", selector: '[data-hf-id="hf-card"]', selectorIndex: 0 },
+      operations: OPERATIONS,
+    });
+    expect(params.editHistory.recordEdit).toHaveBeenCalledWith({
+      label: "Recolor",
+      coalesceKey: undefined,
+      coalesceMs: undefined,
+      files: { "index.html": { before: SOURCE, after: PATCHED } },
+    });
+    expect(params.forceReloadSdkSession).toHaveBeenCalledTimes(1);
+    expect(params.reloadPreview).toHaveBeenCalledTimes(1);
+    expect(reseekPreviewRuntime).not.toHaveBeenCalled();
+  });
+
+  it("with skipRefresh reseeks the preview instead of reloading it", async () => {
+    stubServer({ changed: true, content: PATCHED, path: "index.html", version: "v2" });
+    const { persist, params } = renderPersist();
+
+    await persist(selection, OPERATIONS, { skipRefresh: true });
+
+    expect(params.reloadPreview).not.toHaveBeenCalled();
+    expect(reseekPreviewRuntime).toHaveBeenCalledTimes(1);
+  });
+
+  it("an unchanged patch records nothing and reports changed: false", async () => {
+    stubServer({ changed: false, matched: true, path: "index.html", version: "v1" });
+    const { persist, params } = renderPersist();
+
+    const outcome = await persist(selection, OPERATIONS);
+
+    expect(outcome).toEqual({ sourceFile: "index.html", version: "v1", changed: false });
+    expect(params.editHistory.recordEdit).not.toHaveBeenCalled();
+    expect(params.reloadPreview).not.toHaveBeenCalled();
+  });
+
+  it("an unmatched target throws and is reported once per target", async () => {
+    stubServer({ changed: false, matched: false });
+    const { persist } = renderPersist();
+
+    await expect(persist(selection, OPERATIONS)).rejects.toBeInstanceOf(
+      DomEditPersistUnresolvableError,
+    );
+    await expect(persist(selection, OPERATIONS)).rejects.toBeInstanceOf(
+      DomEditPersistUnresolvableError,
+    );
+
+    expect(trackStudioEvent).toHaveBeenCalledTimes(1);
+    expect(trackStudioEvent).toHaveBeenCalledWith(
+      "save_skipped_unresolvable",
+      expect.objectContaining({ target_selector: '[data-hf-id="hf-card"]' }),
+    );
+  });
+
+  it("refuses a non-finite layout value before any request, with a toast", async () => {
+    const fetchMock = stubServer({ changed: true });
+    const { persist, params } = renderPersist();
+
+    await expect(
+      persist({ ...selection, selectorIndex: Number.NaN }, OPERATIONS),
+    ).rejects.toBeInstanceOf(DomEditPersistUnsafeValueError);
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(params.showToast).toHaveBeenCalledWith(
+      "Couldn't save edit because it contains invalid layout values",
+      "error",
+    );
+  });
+
+  it("a committed SDK cutover skips the server patch and the reload", async () => {
+    const fetchMock = stubServer({ changed: true });
+    const onTrySdkPersist = vi.fn(
+      async (): Promise<CutoverResult> => ({
+        status: "committed",
+        version: "sdk-3",
+        before: SOURCE,
+        after: PATCHED,
+      }),
+    );
+    const { persist, params } = renderPersist({ onTrySdkPersist });
+
+    const outcome = await persist(selection, OPERATIONS, { label: "Recolor" });
+
+    expect(outcome).toEqual({ sourceFile: "index.html", version: "sdk-3", changed: true });
+    expect(onTrySdkPersist).toHaveBeenCalledWith(selection, OPERATIONS, SOURCE, "index.html", {
+      label: "Recolor",
+      coalesceKey: undefined,
+      skipRefresh: undefined,
+    });
+    expect(patchPosts(fetchMock)).toHaveLength(0);
+    expect(params.reloadPreview).not.toHaveBeenCalled();
+    expect(params.forceReloadSdkSession).not.toHaveBeenCalled();
+  });
+
+  it("records the edit once, and reloads only after the record has settled", async () => {
+    stubServer(CHANGED);
+    let finishRecord = () => {};
+    const recordEdit = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          finishRecord = resolve;
+        }),
+    );
+    const { persist, params } = renderPersist({ editHistory: { recordEdit } });
+
+    const saving = persist(selection, OPERATIONS);
+    await vi.waitFor(() => expect(recordEdit).toHaveBeenCalledTimes(1));
+    expect(params.reloadPreview).not.toHaveBeenCalled();
+    finishRecord();
+    await saving;
+
+    expect(recordEdit).toHaveBeenCalledTimes(1);
+    expect(params.reloadPreview).toHaveBeenCalledTimes(1);
+  });
+
+  it("writes prepared content after the patch and records it as the saved file", async () => {
+    stubServer(CHANGED);
+    const { persist, params } = renderPersist();
+
+    const outcome = await persist(selection, OPERATIONS, { prepareContent: () => PREPARED });
+
+    expect(params.writeProjectFile).toHaveBeenCalledWith("index.html", PREPARED, PATCHED);
+    expect(params.editHistory.recordEdit).toHaveBeenCalledWith(
+      expect.objectContaining({ files: { "index.html": { before: SOURCE, after: PREPARED } } }),
+    );
+    expect(params.reloadPreview).toHaveBeenCalledTimes(1);
+    expect(outcome).toBeUndefined();
+  });
+
+  it("a failed prepared write keeps the patch, reloads, then rejects", async () => {
+    stubServer(CHANGED);
+    const { persist, params } = renderPersist({
+      writeProjectFile: vi.fn(async () => {
+        throw new Error("disk full");
+      }),
+    });
+
+    const saving = persist(selection, OPERATIONS, { prepareContent: () => PREPARED });
+
+    await expect(saving).rejects.toBeInstanceOf(DomEditPersistPreparedWriteError);
+    expect(params.editHistory.recordEdit).toHaveBeenCalledWith(
+      expect.objectContaining({ files: { "index.html": { before: SOURCE, after: PATCHED } } }),
+    );
+    expect(params.reloadPreview).toHaveBeenCalledTimes(1);
+    expect(params.showToast).toHaveBeenCalledWith(
+      "Saved, but couldn't finish updating index.html: disk full",
+      "error",
+    );
+  });
+
+  it("a declined SDK cutover falls back to the server patch", async () => {
+    const fetchMock = stubServer(CHANGED);
+    const onTrySdkPersist = sdkResult({ status: "declined", reason: "unsupported" });
+    const { persist, params } = renderPersist({ onTrySdkPersist });
+
+    await persist(selection, OPERATIONS);
+
+    expect(onTrySdkPersist).toHaveBeenCalledTimes(1);
+    expect(patchPosts(fetchMock)).toHaveLength(1);
+    expect(params.editHistory.recordEdit).toHaveBeenCalledTimes(1);
+  });
+
+  it("a failed SDK cutover rethrows without a server patch", async () => {
+    const fetchMock = stubServer(CHANGED);
+    const error = new Error("sdk broke");
+    const { persist } = renderPersist({ onTrySdkPersist: sdkResult({ status: "failed", error }) });
+
+    await expect(persist(selection, OPERATIONS)).rejects.toBe(error);
+    expect(patchPosts(fetchMock)).toHaveLength(0);
+  });
+
+  it("an imported font or prepared content skips the SDK and goes to the server", async () => {
+    const fetchMock = stubServer(CHANGED);
+    const onTrySdkPersist = sdkResult({ status: "declined", reason: "unused" });
+    const { persist } = renderPersist({ onTrySdkPersist });
+    const importedFont = { family: "Inter", path: "fonts/inter.woff2", url: "/fonts/inter.woff2" };
+
+    await persist(selection, OPERATIONS, { importedFont });
+    await persist(selection, OPERATIONS, { prepareContent: (html) => html });
+
+    expect(onTrySdkPersist).not.toHaveBeenCalled();
+    const [[, fontInit]] = patchPosts(fetchMock);
+    expect(JSON.parse(String(fontInit?.body)).fontFaceCss).toContain("Inter");
+    expect(patchPosts(fetchMock)).toHaveLength(2);
+  });
+
+  it("counts a save on the edited element's document until it settles", async () => {
+    stubServer(CHANGED);
+    const element = document.createElement("div");
+    const { persist } = renderPersist();
+    const before = studioManualEditSavesIn(document);
+
+    const saving = persist({ ...selection, element }, OPERATIONS);
+    expect(studioManualEditSavesIn(document)).toBe(before + 1);
+    await saving;
+
+    expect(studioManualEditSavesIn(document)).toBe(before + 2);
+  });
+
+  it("does nothing when shouldSave says no", async () => {
+    const fetchMock = stubServer({ changed: true });
+    const { persist } = renderPersist();
+
+    await expect(persist(selection, OPERATIONS, { shouldSave: () => false })).resolves.toBe(
+      undefined,
+    );
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("refuses to save once the active project has changed", async () => {
+    stubServer({ changed: true });
+    const projectIdRef = { current: "p1" as string | null };
+    const { persist, params } = renderPersist({
+      projectIdRef,
+      queueDomEditSave: async (save) => {
+        projectIdRef.current = "p2";
+        return save();
+      },
+    });
+
+    await expect(persist(selection, OPERATIONS)).rejects.toThrow(
+      "Active project changed before the edit could be saved",
+    );
+    expect(params.editHistory.recordEdit).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/useDomGeometryCommit.test.tsx

@@ -1,7 +1,7 @@
 // @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 { afterEach, beforeEach, describe, expect, expectTypeOf, it, vi } from "vitest";
 import {
   useDomGeometryCommit,
   usePlayerStore,
@@ -108,6 +108,10 @@ afterEach(() => {
 });
 
 describe("useDomGeometryCommit, from the package entry", () => {
+  it("takes the host's own preview reload, with no fallback", () => {
+    expectTypeOf<UseDomGeometryCommitOptions["reloadPreview"]>().toEqualTypeOf<() => void>();
+  });
+
   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();

package/src/hooks/useDomGeometryCommit.ts

@@ -26,8 +26,8 @@ import { useMountEffect } from "./useMountEffect";
  * 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;
+  /** Reloads the host's preview when a save cannot patch it in place. */
+  reloadPreview: () => void;
 }
 
 export interface DomGeometryCommits {
@@ -42,6 +42,7 @@ export interface DomGeometryCommits {
     next: { width: number; height: number },
     offset?: { x: number; y: number },
     restore?: () => void,
+    route?: { plainTranslate: boolean },
   ) => Promise<DomEditCommitOutcome>;
   commitRotation: (
     selection: DomEditSelection,
@@ -70,17 +71,13 @@ export function useDomGeometryCommit({
   projectIdRef.current = projectId;
   const pending = useRef(new Set<Promise<GeometryCommitResult | undefined>>()).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,
+    reloadPreview,
     onCacheInvalidate: bumpGsapCache,
     showToast,
     writeProjectFile,
@@ -174,8 +171,8 @@ export function useDomGeometryCommit({
         saved(() => handleGsapAwarePathOffsetCommit(selection, next, modifiers)),
       commitGroupPathOffset: (updates) =>
         saved(() => handleGsapAwareGroupPathOffsetCommit(updates)),
-      commitBoxSize: (selection, next, offset, restore) =>
-        saved(() => handleGsapAwareBoxSizeCommit(selection, next, offset, restore), restore),
+      commitBoxSize: (selection, next, offset, restore, route) =>
+        saved(() => handleGsapAwareBoxSizeCommit(selection, next, offset, restore, route), restore),
       commitRotation: (selection, next) =>
         saved(() => handleGsapAwareRotationCommit(selection, next)),
       waitForPendingSaves: () => Promise.allSettled([...pending]).then(noop),

package/src/hooks/useFreezeFrame.test.ts

@@ -1,6 +1,9 @@
+// @vitest-environment happy-dom
+import { act, createElement } from "react";
+import { createRoot } from "react-dom/client";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { TimelineElement } from "../player";
-import { requestFreezeFrame } from "./useFreezeFrame";
+import { requestFreezeFrame, useFreezeFrame } from "./useFreezeFrame";
 
 afterEach(() => vi.unstubAllGlobals());
 
@@ -29,14 +32,15 @@ function stubFetch(freezeResponse: { status: number; body: unknown }) {
 
 describe("requestFreezeFrame", () => {
   it("posts the clip target, file version and an authored-time playhead", async () => {
-    const calls = stubFetch({ status: 200, body: { before: "a", after: "b", version: "v2" } });
+    const frozen = { before: "a", after: "b", version: "v2", stillPath: "assets/freeze/t.png" };
+    const calls = stubFetch({ status: 200, body: frozen });
     const result = await requestFreezeFrame({
       projectId: "p",
       path: "scene.html",
       element,
       playhead: 7.5,
     });
-    expect(result).toEqual({ before: "a", after: "b", version: "v2" });
+    expect(result).toEqual(frozen);
     const post = calls[1];
     expect(post?.url).toContain("/file-mutations/freeze-frame");
     expect(post?.body).toMatchObject({
@@ -54,3 +58,35 @@ describe("requestFreezeFrame", () => {
     ).rejects.toThrow("Move the playhead inside a video clip to freeze");
   });
 });
+
+describe("useFreezeFrame", () => {
+  it("records the still it made with the edit, so Undo removes it", async () => {
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    stubFetch({
+      status: 200,
+      body: { before: "a", after: "b", version: "v2", stillPath: "assets/freeze/talk.png" },
+    });
+    const recordEdit = vi.fn(async () => {});
+    let freeze!: ReturnType<typeof useFreezeFrame>;
+    function Harness() {
+      freeze = useFreezeFrame({
+        projectId: "p",
+        activeCompPath: "index.html",
+        showToast: () => {},
+        writeProjectFile: async () => {},
+        recordEdit,
+        reloadPreview: () => {},
+      });
+      return null;
+    }
+    const root = createRoot(document.createElement("div"));
+    await act(async () => root.render(createElement(Harness)));
+    await act(() => freeze({ ...element, sourceFile: "index.html" }, 7.5));
+    expect(recordEdit).toHaveBeenCalledWith({
+      label: "Freeze frame",
+      files: { "index.html": { before: "a", after: "b" } },
+      created: ["assets/freeze/talk.png"],
+    });
+    act(() => root.unmount());
+  });
+});

package/src/hooks/useFreezeFrame.ts

@@ -14,6 +14,7 @@ interface FreezeFrameResponse {
   before: string;
   after: string;
   version: string;
+  stillPath: string;
 }
 
 function isFreezeFrameResponse(value: unknown): value is FreezeFrameResponse {
@@ -22,7 +23,8 @@ function isFreezeFrameResponse(value: unknown): value is FreezeFrameResponse {
   return (
     typeof body.before === "string" &&
     typeof body.after === "string" &&
-    typeof body.version === "string"
+    typeof body.version === "string" &&
+    typeof body.stillPath === "string"
   );
 }
 
@@ -109,6 +111,7 @@ export function useFreezeFrame(options: UseFreezeFrameOptions) {
         await opts.recordEdit({
           label: "Freeze frame",
           files: { [path]: { before: result.before, after: result.after } },
+          created: [result.stillPath],
         });
         opts.observeProjectFileVersion?.(path, result.version);
       });