Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix(studio): undo and redo show on the next frame instead of after the server answers (#4798)
Miguel Ángel6ba35c9e3b7d
diff --git a/packages/studio/src/App.tsx b/packages/studio/src/App.tsxindex a026d797f5..38d728b393 100644--- a/packages/studio/src/App.tsx+++ b/packages/studio/src/App.tsx@@ -155,6 +155,7 @@ export function StudioApp({ readOnlyPreview = false, readOnlyPreviewReason }: StpreviewPersistence,pendingTimelineEditPathRef,reloadPreview,+ onOutsideChange: editHistory.noteOutsideChange,});const invalidateGsapCacheRef = useRef<() => void>(() => {});const invalidateGsapCache = useCallback(() => invalidateGsapCacheRef.current(), []);@@ -254,6 +255,7 @@ export function StudioApp({ readOnlyPreview = false, readOnlyPreviewReason }: StwriteProjectFile: fileManager.writeProjectFile,showToast,syncHistoryPreviewAfterApply: previewPersistence.syncHistoryPreviewAfterApply,+ showHistoryRestoreNow: previewPersistence.showHistoryRestoreNow,waitForPendingDomEditSaves: previewPersistence.waitForPendingDomEditSaves,handleCopy,handlePaste,diff --git a/packages/studio/src/hooks/useAppHotkeys.ts b/packages/studio/src/hooks/useAppHotkeys.tsindex 47fa2260ef..3895a5b2f4 100644--- a/packages/studio/src/hooks/useAppHotkeys.ts+++ b/packages/studio/src/hooks/useAppHotkeys.ts@@ -86,6 +86,7 @@ interface UseAppHotkeysParams {writeProjectFile: (path: string, content: string) => Promise<void>;showToast: (message: string, tone?: "error" | "info") => void;syncHistoryPreviewAfterApply: UseEditHistoryActionsOptions["syncHistoryPreviewAfterApply"];+ showHistoryRestoreNow?: UseEditHistoryActionsOptions["showHistoryRestoreNow"];waitForPendingDomEditSaves: () => Promise<void>;handleCopy: () => boolean;handlePaste: () => Promise<void>;@@ -124,6 +125,7 @@ export function useAppHotkeys({writeProjectFile,showToast,syncHistoryPreviewAfterApply,+ showHistoryRestoreNow,waitForPendingDomEditSaves,handleCopy,handlePaste,@@ -150,6 +152,7 @@ export function useAppHotkeys({writeProjectFile,showToast,syncHistoryPreviewAfterApply,+ showHistoryRestoreNow,waitForPendingDomEditSaves,onAfterUndoRedo,activeCompPath,diff --git a/packages/studio/src/hooks/useEditHistoryActions.paint.test.tsx b/packages/studio/src/hooks/useEditHistoryActions.paint.test.tsxnew file mode 100644index 0000000000..de1fc622d6--- /dev/null+++ b/packages/studio/src/hooks/useEditHistoryActions.paint.test.tsx@@ -0,0 +1,166 @@+// @vitest-environment happy-dom+import { act, createElement } from "react";+import { createRoot } from "react-dom/client";+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { afterEach, beforeEach, expect, it, vi } from "vitest";+import {+ createStudioApi,+ openProjectHistory,+ type StudioApiAdapter,+} from "@hyperframes/studio-server";+import { useEditHistoryActions } from "./useEditHistoryActions";+import { usePersistentEditHistory } from "./usePersistentEditHistory";+import { usePreviewPersistence } from "./usePreviewPersistence";++const page = (left: string, top = "0px") =>+ `<!doctype html><html><head></head><body><div id="root" data-composition-id="main"><div id="box" style="position: absolute; left: ${left}"></div><div id="other" style="position: absolute; top: ${top}"></div></div></body></html>`;+const BEFORE = page("10px");+const AFTER = page("50px");+const OUTSIDE = page("50px", "99px");++const cleanup: Array<() => unknown> = [];+let scratch = "";+beforeEach(() => {+ scratch = mkdtempSync(join(tmpdir(), "hf-undo-paint-"));+});+afterEach(async () => {+ for (const step of cleanup.splice(0).reverse()) await step();+ rmSync(scratch, { recursive: true, force: true });+ vi.unstubAllGlobals();+});++/** Studio's undo wired as App.tsx wires it, over the real history engine, with a live preview document. */+async function studio() {+ vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);+ const dir = join(scratch, "project");+ mkdirSync(dir);+ const path = join(dir, "index.html");+ writeFileSync(path, BEFORE);+ const engine = await openProjectHistory({+ projectDir: dir,+ historyRoot: join(scratch, "history"),+ });+ cleanup.push(() => engine.close());+ const api = createStudioApi({+ listProjects: () => [],+ resolveProject: (id: string) => (id === "demo" ? { id, dir } : null),+ history: () => engine,+ } as unknown as StudioApiAdapter);+ vi.stubGlobal("fetch", (url: string, init?: RequestInit) =>+ api.request(url.replace(/^\/api/, ""), init),+ );+ const iframe = document.createElement("iframe");+ document.body.append(iframe);+ cleanup.push(() => iframe.remove());+ const reloads = vi.fn();+ const readFile = async (p: string) => readFileSync(join(dir, p), "utf8");+ let history!: ReturnType<typeof usePersistentEditHistory>;+ let persistence!: ReturnType<typeof usePreviewPersistence>;+ let actions!: ReturnType<typeof useEditHistoryActions>;+ function Harness() {+ history = usePersistentEditHistory({ projectId: "demo" });+ persistence = usePreviewPersistence({+ showToast: () => {},+ readOptionalProjectFile: async () => "",+ writeProjectFile: async () => {},+ recordEdit: async () => {},+ previewIframeRef: { current: iframe },+ activeCompPathRef: { current: "index.html" },+ reloadPreview: reloads,+ });+ actions = useEditHistoryActions({+ editHistory: history,+ readOptionalProjectFile: async () => "",+ readProjectFile: readFile,+ writeProjectFile: async (p, content) => writeFileSync(join(dir, p), content),+ showToast: () => {},+ syncHistoryPreviewAfterApply: persistence.syncHistoryPreviewAfterApply,+ showHistoryRestoreNow: persistence.showHistoryRestoreNow,+ waitForPendingDomEditSaves: persistence.waitForPendingDomEditSaves,+ });+ return null;+ }+ const root = createRoot(document.createElement("div"));+ await act(async () => root.render(createElement(Harness)));+ cleanup.push(() => act(() => root.unmount()));+ const box = () => iframe.contentDocument!.getElementById("box")!.style.left;+ const other = () => iframe.contentDocument!.getElementById("other")!.style.top;+ const show = (html: string) => {+ iframe.contentDocument!.documentElement.innerHTML = new DOMParser().parseFromString(+ html,+ "text/html",+ ).documentElement.innerHTML;+ };+ /** A move Studio saved: the live preview already shows it, then the file and the history claim land. */+ const edit = async () => {+ show(AFTER);+ writeFileSync(path, AFTER);+ await act(() =>+ history.recordEdit({+ label: "Move layer",+ files: { "index.html": { before: BEFORE, after: AFTER } },+ }),+ );+ await vi.waitFor(() => expect(history.undoLabel).toBe("Move layer"));+ };+ return {+ history: () => history,+ persistence: () => persistence,+ actions: () => actions,+ box,+ other,+ show,+ path,+ edit,+ file: () => readFileSync(path, "utf8"),+ reloads,+ };+}++it("undo and redo of a style edit paint in the key's own task, before the server answers", async () => {+ const s = await studio();+ await s.edit();++ const undone = s.actions().undo();+ expect(s.box()).toBe("10px");+ await act(() => undone);+ expect(s.file()).toBe(BEFORE);+ expect(s.box()).toBe("10px");++ await vi.waitFor(() => expect(s.history().redoLabel).toBeTruthy());+ const redone = s.actions().redo();+ expect(s.box()).toBe("50px");+ await act(() => redone);+ expect(s.file()).toBe(AFTER);+ expect(s.box()).toBe("50px");+ expect(s.reloads).not.toHaveBeenCalled();+});++it("an undo pressed while a save is still running waits for the server instead of guessing", async () => {+ const s = await studio();+ await s.edit();+ let finish!: () => void;+ const saving = new Promise<void>((resolve) => (finish = resolve));+ void s.persistence().queueDomEditSave(() => saving);++ const undone = s.actions().undo();+ expect(s.box()).toBe("50px");+ finish();+ await act(() => undone);+ expect(s.file()).toBe(BEFORE);+ expect(s.box()).toBe("10px");+});++it("an undo after an outside write ends with the preview showing the file the server restored", async () => {+ const s = await studio();+ await s.edit();+ writeFileSync(s.path, OUTSIDE);+ s.show(OUTSIDE);++ await act(() => s.actions().undo());+ expect(s.file()).toBe(AFTER);+ expect(s.other()).toBe("0px");+ expect(s.box()).toBe("50px");+});diff --git a/packages/studio/src/hooks/useEditHistoryActions.test.tsx b/packages/studio/src/hooks/useEditHistoryActions.test.tsxindex 93fd878ee0..402242c4b7 100644--- a/packages/studio/src/hooks/useEditHistoryActions.test.tsx+++ b/packages/studio/src/hooks/useEditHistoryActions.test.tsx@@ -11,24 +11,36 @@ import { useEditHistoryActions, type EditHistoryHandle } from "./useEditHistoryAlet root: Root | null = null;afterEach(() => act(() => root?.unmount()));-function mount(result: {- ok: boolean;- reason?: string;- message?: string;- label?: string;- paths?: string[];-}) {+type RestoreFiles = Record<string, { previous: string; restored: string }>;+type Prediction = { id: string; files: RestoreFiles };++function mount(+ result: {+ ok: boolean;+ reason?: string;+ message?: string;+ label?: string;+ paths?: string[];+ undoes?: string;+ files?: RestoreFiles;+ },+ predicted?: Prediction,+) {const editHistory = {undo: vi.fn<EditHistoryHandle["undo"]>(async () => result),redo: vi.fn<EditHistoryHandle["redo"]>(async () => result),+ predict: () => predicted ?? null,};+ const putBack = vi.fn();const deps = {editHistory,readOptionalProjectFile: vi.fn(async () => ""),readProjectFile: vi.fn(async () => ""),writeProjectFile: vi.fn(async () => undefined),showToast: vi.fn(),- syncHistoryPreviewAfterApply: vi.fn(async () => undefined),+ syncHistoryPreviewAfterApply: vi.fn(async (_restore: unknown) => undefined),+ putBack,+ showHistoryRestoreNow: vi.fn((_files: RestoreFiles) => putBack),waitForPendingDomEditSaves: vi.fn(async () => undefined),onAfterUndoRedo: vi.fn(),activeCompPath: "index.html",@@ -44,7 +56,53 @@ function mount(result: {return { deps, actions };}+const PREDICTED = { id: "e1", files: { "index.html": { previous: "B", restored: "A" } } };+const SERVER_FILES = { "index.html": { previous: "B", restored: "A2" } };+describe("useEditHistoryActions", () => {+ it("corrects a shown step from the server's restore, diffed from what the preview shows", async () => {+ const { deps, actions } = mount(+ { ok: true, label: "Undid: Move", paths: ["index.html"], undoes: "e1", files: SERVER_FILES },+ PREDICTED,+ );+ await act(() => actions.undo());+ expect(deps.showHistoryRestoreNow).toHaveBeenCalledWith(PREDICTED.files);+ expect(deps.putBack).not.toHaveBeenCalled();+ expect(deps.syncHistoryPreviewAfterApply).toHaveBeenCalledWith({+ paths: ["index.html"],+ files: { "index.html": { previous: "A", restored: "A2" } },+ });+ });++ it("puts a shown step back and applies the server's own restore when it stepped another entry", async () => {+ const { deps, actions } = mount(+ {+ ok: true,+ label: "Undid: Outside",+ paths: ["index.html"],+ undoes: "e0",+ files: SERVER_FILES,+ },+ PREDICTED,+ );+ await act(() => actions.undo());+ expect(deps.putBack).toHaveBeenCalledTimes(1);+ expect(deps.syncHistoryPreviewAfterApply).toHaveBeenCalledWith({+ paths: ["index.html"],+ files: SERVER_FILES,+ });+ });++ it("puts a shown step back when the server refuses it", async () => {+ const { deps, actions } = mount(+ { ok: false, reason: "failed", message: "disk full" },+ PREDICTED,+ );+ await act(() => actions.undo());+ expect(deps.putBack).toHaveBeenCalledTimes(1);+ expect(deps.syncHistoryPreviewAfterApply).not.toHaveBeenCalled();+ });+it("undo resyncs the preview and toasts the step as the history names it", async () => {const { deps, actions } = mount({ ok: true, label: "Undid: Move clip", paths: ["index.html"] });await act(() => actions.undo());@@ -80,7 +138,7 @@ describe("useEditHistoryActions", () => {expect(deps.syncHistoryPreviewAfterApply).not.toHaveBeenCalled();});- it("says why when the history could not take the step", async () => {+ it("says why when the history could not take the step, with nothing shown to take back", async () => {const { deps, actions } = mount({ ok: false, reason: "failed", message: "disk full" });await act(() => actions.undo());expect(deps.showToast).toHaveBeenCalledWith("Undo failed: disk full", "error");diff --git a/packages/studio/src/hooks/useEditHistoryActions.ts b/packages/studio/src/hooks/useEditHistoryActions.tsindex d54051f67c..d2a82c3609 100644--- a/packages/studio/src/hooks/useEditHistoryActions.ts+++ b/packages/studio/src/hooks/useEditHistoryActions.ts@@ -2,6 +2,7 @@import { useCallback, useMemo } from "react";import { STUDIO_MOTION_PATH } from "../components/editor/studioMotion";import { serializeStudioFileMutations } from "../utils/studioFileMutationCoordinator";+import type { RestoreFiles } from "../utils/gsapUndoRestore";interface HistoryResult {ok: boolean;@@ -9,8 +10,9 @@ interface HistoryResult {message?: string;label?: string;paths?: string[];+ undoes?: string;/** Per-file restored/previous content, used to soft-apply the preview. */- files?: Record<string, { previous: string; restored: string }>;+ files?: RestoreFiles;}interface HistoryFileCallbacks {readFile: (path: string) => Promise<string>;@@ -19,6 +21,7 @@ interface HistoryFileCallbacks {export interface EditHistoryHandle {undo: (cb: HistoryFileCallbacks) => Promise<HistoryResult>;redo: (cb: HistoryFileCallbacks) => Promise<HistoryResult>;+ predict?: (direction: "undo" | "redo") => { id: string; files: RestoreFiles } | null;state: {undo: ReadonlyArray<{ createdAt: number }>;redo: ReadonlyArray<{ createdAt: number }>;@@ -26,12 +29,13 @@ export interface EditHistoryHandle {}export interface UseEditHistoryActionsOptions {- editHistory: Pick<EditHistoryHandle, "undo" | "redo">;+ editHistory: Pick<EditHistoryHandle, "undo" | "redo" | "predict">;readOptionalProjectFile: (path: string) => Promise<string>;readProjectFile: (path: string) => Promise<string>;writeProjectFile: (path: string, content: string) => Promise<void>;showToast: (message: string, tone?: "error" | "info") => void;syncHistoryPreviewAfterApply: (restore: Pick<HistoryResult, "paths" | "files">) => Promise<void>;+ showHistoryRestoreNow?: (files: RestoreFiles) => (() => void) | null;waitForPendingDomEditSaves: () => Promise<void>;onAfterUndoRedo?: (restore: Pick<HistoryResult, "paths" | "files">) => void;/** Active composition path — decides whether undo/redo must resync the SDK session. */@@ -48,6 +52,7 @@ export function useEditHistoryActions({writeProjectFile,showToast,syncHistoryPreviewAfterApply,+ showHistoryRestoreNow,waitForPendingDomEditSaves,onAfterUndoRedo,activeCompPath,@@ -67,11 +72,22 @@ export function useEditHistoryActions({const apply = useCallback(async (direction: "undo" | "redo") => {const noun = direction === "undo" ? "Undo" : "Redo";- await waitForPendingDomEditSaves();- const result = await editHistory[direction]({- readFile: readHistoryFile,- serialize: serializeHistoryFiles,- });+ // Paint the step in the key's own task when this tab knows it; the server's answer then confirms or corrects.+ const predicted = editHistory.predict?.(direction) ?? null;+ const putBack = predicted ? (showHistoryRestoreNow?.(predicted.files) ?? null) : null;+ let result: HistoryResult = { ok: false, reason: "failed" };+ let serverSteppedShown = false;+ try {+ await waitForPendingDomEditSaves();+ result = await editHistory[direction]({+ readFile: readHistoryFile,+ serialize: serializeHistoryFiles,+ });+ serverSteppedShown =+ Boolean(putBack && result.ok && result.label) && result.undoes === predicted?.id;+ } finally {+ if (putBack && !serverSteppedShown) putBack();+ }if (!result.ok && result.reason === "content-mismatch") {showToast(`Can't ${direction}: ${result.paths?.join(", ")} changed since that edit.`,@@ -84,7 +100,8 @@ export function useEditHistoryActions({return;}if (result.ok && result.label) {- const restore = { paths: result.paths, files: result.files };+ const files = serverSteppedShown ? fromShown(result.files, predicted!.files) : result.files;+ const restore = { paths: result.paths, files };onAfterUndoRedo?.(restore);if (activeCompPath && result.paths?.includes(activeCompPath)) {forceReloadSdkSession?.();@@ -98,6 +115,7 @@ export function useEditHistoryActions({readHistoryFile,showToast,syncHistoryPreviewAfterApply,+ showHistoryRestoreNow,waitForPendingDomEditSaves,serializeHistoryFiles,onAfterUndoRedo,@@ -110,3 +128,13 @@ export function useEditHistoryActions({const redo = useCallback(() => apply("redo"), [apply]);return useMemo(() => ({ undo, redo }), [undo, redo]);}++function fromShown(files: RestoreFiles | undefined, shown: RestoreFiles) {+ if (!files) return files;+ return Object.fromEntries(+ Object.entries(files).map(([path, f]) => [+ path,+ { previous: shown[path]?.restored ?? f.previous, restored: f.restored },+ ]),+ );+}diff --git a/packages/studio/src/hooks/usePersistentEditHistory.test.ts b/packages/studio/src/hooks/usePersistentEditHistory.test.tsindex 61a59d7510..2dda96b983 100644--- a/packages/studio/src/hooks/usePersistentEditHistory.test.ts+++ b/packages/studio/src/hooks/usePersistentEditHistory.test.ts@@ -76,6 +76,7 @@ it("an edit Studio saved is undone and redone by the project's history, with theexpect(undone).toEqual({ok: true,label: "Undid: Moved Title",+ undoes: expect.any(String),paths: ["index.html"],files: { "index.html": { previous: "B", restored: "A" } },});@@ -241,3 +242,48 @@ it("a step that cannot reach the server says so", async () => {message: "Studio could not reach its server.",});});++it("predicts a step from what this tab wrote, and not while a claim or step may have moved the history", async () => {+ const { hook, save, readFile } = await studio();+ save("B");+ const claim = hook().recordEdit({+ label: "Moved Title",+ files: { "index.html": { before: "A", after: "B" } },+ });+ expect(hook().predict("undo")).toBeNull();+ await act(() => claim);+ const predicted = await vi.waitFor(() => {+ const next = hook().predict("undo");+ expect(next?.files).toEqual({ "index.html": { previous: "B", restored: "A" } });+ return next!;+ });++ hook().noteOutsideChange();+ expect(hook().predict("undo")).toBeNull();+ await vi.waitFor(() => expect(hook().predict("undo")?.id).toBe(predicted.id));++ const undone = hook().undo({ readFile });+ expect(hook().predict("undo")).toBeNull();+ expect((await act(() => undone)).undoes).toBe(predicted.id);+ await vi.waitFor(() =>+ expect(hook().predict("redo")?.files).toEqual({+ "index.html": { previous: "A", restored: "B" },+ }),+ );+});++it("an undo taken before the view caught up with the edit still reports the preview's before and after", async () => {+ const { hook, save, readFile } = await studio();+ save("B");+ const record = hook().recordEdit({+ label: "Moved Title",+ files: { "index.html": { before: "A", after: "B" } },+ });+ const undo = hook().undo;+ await act(() => record);+ const undone = await act(() => undo({ readFile }));+ expect(undone).toMatchObject({+ ok: true,+ files: { "index.html": { previous: "B", restored: "A" } },+ });+});diff --git a/packages/studio/src/hooks/usePersistentEditHistory.ts b/packages/studio/src/hooks/usePersistentEditHistory.tsindex 8dc61f68cb..8675b5c0bd 100644--- a/packages/studio/src/hooks/usePersistentEditHistory.ts+++ b/packages/studio/src/hooks/usePersistentEditHistory.ts@@ -1,6 +1,7 @@import { useCallback, useEffect, useMemo, useRef, useState } from "react";import type { HistoryListItem, HistoryResult } from "@hyperframes/studio-server";import { studioFileContentVersion, studioWriteHeaders } from "../utils/studioFileVersion";+import type { RestoreFiles } from "../utils/gsapUndoRestore";interface RecordEditInput {label: string;@@ -18,11 +19,6 @@ export interface UsePersistentEditHistoryOptions {projectId: string | null;}-interface ApplyRestoredFile {- previous: string;- restored: string;-}-interface ApplyResult {ok: boolean;/** content-mismatch: `paths` changed after the step's entry. failed: `message` says why. */@@ -30,7 +26,8 @@ interface ApplyResult {message?: string;label?: string;paths?: string[];- files?: Record<string, ApplyRestoredFile>;+ undoes?: string;+ files?: RestoreFiles;}interface NextStep {@@ -47,6 +44,69 @@ interface HistoryView {}const EMPTY: HistoryView = { entries: [], back: null, forward: null };+/** ponytail: the newest entries' content is kept; older ones step through the server only. */+const OWN_ENTRIES_KEPT = 100;++type OwnFiles = Record<string, { before: string; after: string }>;++function createOwnHistory() {+ const own = new Map<string, OwnFiles>();+ let next: Record<"undo" | "redo", NextStep | null> | null = null;+ let changes = 0;+ const remember = (id: string, files: OwnFiles) => {+ const known = own.get(id) ?? {};+ for (const [path, { before, after }] of Object.entries(files)) {+ known[path] = { before: known[path]?.before ?? before, after };+ }+ own.delete(id);+ own.set(id, known);+ if (own.size > OWN_ENTRIES_KEPT) own.delete(own.keys().next().value!);+ };+ return {+ remember,+ overtake: () => {+ changes += 1;+ next = null;+ return changes;+ },+ offered: (seen: number, view: HistoryView) => {+ if (seen === changes) next = { undo: view.back, redo: view.forward };+ },+ changes: () => changes,+ stepped: (entry: { id: string; undoes?: string }) => {+ const undone = entry.undoes ? own.get(entry.undoes) : undefined;+ if (!undone) return;+ const swapped = Object.entries(undone).map(([path, f]) => [+ path,+ { before: f.after, after: f.before },+ ]);+ remember(entry.id, Object.fromEntries(swapped));+ },+ afterOf: (id: string | undefined): Record<string, string> =>+ Object.fromEntries(Object.entries((id && own.get(id)) || {}).map(([p, f]) => [p, f.after])),+ predict: (direction: "undo" | "redo"): { id: string; files: RestoreFiles } | null => {+ const step = next?.[direction];+ const files = step ? own.get(step.id) : undefined;+ const paths = files ? Object.keys(files) : [];+ if (+ !files ||+ paths.length !== step!.paths.length ||+ !paths.every((p) => step!.paths.includes(p))+ )+ return null;+ const restore = paths.map((path) => [+ path,+ { previous: files[path]!.after, restored: files[path]!.before },+ ]);+ return { id: step!.id, files: Object.fromEntries(restore) };+ },+ clear: () => {+ own.clear();+ next = null;+ changes += 1;+ },+ };+}const DEFAULT_COALESCE_MS = 300;function historyUrl(projectId: string, path = ""): string {@@ -71,12 +131,13 @@ async function post(return { ok: false, status: response.status, error: reply?.error ?? `HTTP ${response.status}` };}-/** Whether a drag's claim is held open; a failed one is logged (its write lands as an outside change; 404: none). */-function claimHeld(reply: Awaited<ReturnType<typeof post>>, label: string): boolean {- if (reply.ok) return Boolean((reply.body as { claimed: { id: string } | null } | null)?.claimed);+/** The entry id a claim took, or null; a failed one is logged (its write lands as an outside change; 404: none). */+function claimHeld(reply: Awaited<ReturnType<typeof post>>, label: string): string | null {+ if (reply.ok)+ return (reply.body as { claimed: { id: string } | null } | null)?.claimed?.id ?? null;if (reply.status !== 404)console.error(`"${label}" was not recorded as your edit: ${reply.error}`);- return false;+ return null;}async function overwroteVersions(files: RecordEditInput["files"]): Promise<Record<string, string>> {@@ -106,7 +167,7 @@ async function restoredFiles(paths: readonly string[],previous: Record<string, string> | null,readFile: (path: string) => Promise<string>,-): Promise<Record<string, ApplyRestoredFile> | undefined> {+): Promise<RestoreFiles | undefined> {if (!previous || paths.some((path) => !(path in previous))) return undefined;const restored = await readAll(paths, readFile);if (!restored) return undefined;@@ -128,36 +189,43 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistoryconst heldClaimRef = useRef<{ paths: string[]; at: number } | null>(null);const projectIdRef = useRef(projectId);projectIdRef.current = projectId;+ const [own] = useState(createOwnHistory);const refresh = useCallback(async () => {if (!projectId) return;+ const seen = own.changes();const response = await fetch(historyUrl(projectId)).catch(() => null);const next = response?.ok ? ((await response.json()) as HistoryView) : EMPTY;- if (projectIdRef.current === projectId) setView(next);- }, [projectId]);+ if (projectIdRef.current !== projectId) return;+ setView(next);+ own.offered(seen, next);+ }, [projectId, own]);useEffect(() => {setView(EMPTY);setLoaded(false);heldClaimRef.current = null;+ own.clear();void refresh().finally(() => setLoaded(true));- }, [refresh]);+ }, [refresh, own]);const recordEdit = useCallback(async ({ label, coalesceKey, coalesceMs, files }: RecordEditInput) => {if (!projectId) return;const paths = Object.keys(files);+ own.overtake();const reply = await post(historyUrl(projectId, "/claim"), {label,paths,overwrote: await overwroteVersions(files),...(coalesceKey && { coalesceKey, idleMs: coalesceMs ?? DEFAULT_COALESCE_MS }),});- heldClaimRef.current =- claimHeld(reply, label) && coalesceKey ? { paths, at: Date.now() } : null;+ const claimed = claimHeld(reply, label);+ if (claimed) own.remember(claimed, files);+ heldClaimRef.current = claimed && coalesceKey ? { paths, at: Date.now() } : null;void refresh();},- [projectId, refresh],+ [projectId, refresh, own],);const step = useCallback(@@ -165,6 +233,7 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistoryif (!projectId) return { ok: false, reason: "empty" };const next = direction === "undo" ? view.back : view.forward;const paths = [...new Set([...(next?.paths ?? []), ...(heldClaimRef.current?.paths ?? [])])];+ own.overtake();const run = async (): Promise<ApplyResult> => {const previous = await readAll(paths, callbacks.readFile);const posted = await post(@@ -183,19 +252,30 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistoryreturn { ok: false, reason: "content-mismatch", paths: files };}if (!reply.entry) return { ok: false, reason: "empty" };+ own.stepped(reply.entry);const changed = reply.entry.files.map((file) => file.path);return {ok: true,label: reply.entry.label,+ undoes: reply.entry.undoes,paths: changed,- files: await restoredFiles(changed, previous, callbacks.readFile),+ files: await restoredFiles(+ changed,+ { ...own.afterOf(reply.entry.undoes), ...previous },+ callbacks.readFile,+ ),};};return callbacks.serialize ? callbacks.serialize(paths, run) : run();},- [projectId, view, refresh],+ [projectId, view, refresh, own],);+ const noteOutsideChange = useCallback(() => {+ own.overtake();+ void refresh();+ }, [own, refresh]);+const undo = useCallback((callbacks: ApplyCallbacks) => step("undo", callbacks), [step]);const redo = useCallback((callbacks: ApplyCallbacks) => step("redo", callbacks), [step]);@@ -220,5 +300,7 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistoryrecordEdit,undo,redo,+ predict: own.predict,+ noteOutsideChange,};}diff --git a/packages/studio/src/hooks/usePreviewPersistence.ts b/packages/studio/src/hooks/usePreviewPersistence.tsindex cf32cc505f..913614a31b 100644--- a/packages/studio/src/hooks/usePreviewPersistence.ts+++ b/packages/studio/src/hooks/usePreviewPersistence.ts@@ -8,17 +8,22 @@ import { STUDIO_MOTION_PATH } from "../components/editor/studioMotion";import { createDomEditSaveQueue, type DomEditSaveDrainResult } from "../utils/domEditSaveQueue";import {flushStudioPendingEdits,+ hasStudioPendingEdits,type StudioPendingEditsDrainResult,} from "../utils/studioPendingEdits";import { trackStudioEvent } from "../utils/studioTelemetry";-import { applyUndoRestoreToPreview, type UndoRestoreFile } from "../utils/gsapUndoRestore";+import {+ applyUndoRestoreToPreview,+ showRestoreInPlace,+ type RestoreFiles,+} from "../utils/gsapUndoRestore";import { usePlayerStore } from "../player";import { syncStoredAutomationFromPreview } from "../player/lib/automationStoreSync";/** The restore payload the undo/redo preview-sync consumes (from the history store). */interface HistoryPreviewRestore {paths?: string[];- files?: Record<string, UndoRestoreFile>;+ files?: RestoreFiles;}// ── Types ──@@ -217,6 +222,23 @@ export function usePreviewPersistence({[previewIframeRef, activeCompPathRef, reloadPreview],);+ // A restore the server has not confirmed yet: in place now, or not at all. A GSAP script re-run is not+ // synchronous, and a pending save would land under it.+ const showHistoryRestoreNow = useCallback(+ (files: RestoreFiles): (() => void) | null => {+ if (!domEditSaveQueueRef.current?.isIdle() || hasStudioPendingEdits()) return null;+ const iframe = previewIframeRef.current;+ const now = () => usePlayerStore.getState().currentTime;+ const putBack = showRestoreInPlace(iframe, activeCompPathRef.current, files, now());+ if (!putBack) return null;+ return () => {+ if (putBack(now())) syncStoredAutomationFromPreview(iframe?.contentDocument ?? null);+ else void syncHistoryPreviewAfterApply({ paths: Object.keys(files) });+ };+ },+ [previewIframeRef, activeCompPathRef, syncHistoryPreviewAfterApply],+ );+// ── Migrate legacy studio-motion.json ──// Projects that used the old JSON-file approach may still have a populated// `.hyperframes/studio-motion.json`. The studio no longer reads from it, but@@ -239,5 +261,6 @@ export function usePreviewPersistence({applyCurrentStudioManualEditsToPreview,applyStudioManualEditsToPreview,syncHistoryPreviewAfterApply,+ showHistoryRestoreNow,};}diff --git a/packages/studio/src/hooks/useStudioExternalFileChanges.ts b/packages/studio/src/hooks/useStudioExternalFileChanges.tsindex 5e42cc9602..208915a941 100644--- a/packages/studio/src/hooks/useStudioExternalFileChanges.ts+++ b/packages/studio/src/hooks/useStudioExternalFileChanges.ts@@ -36,6 +36,7 @@ interface UseStudioExternalFileChangesOptions {previewPersistence: PreviewPersistence;pendingTimelineEditPathRef: MutableRefObject<Set<string>>;reloadPreview: () => void;+ onOutsideChange?: () => void;}/** Connects the app's save queues, recovery storage, and reload surfaces to one owner. */@@ -47,14 +48,17 @@ export function useStudioExternalFileChanges({previewPersistence,pendingTimelineEditPathRef,reloadPreview,+ onOutsideChange,}: UseStudioExternalFileChangesOptions) {const { flushPendingSourceSave, discardPendingSourceSave } = fileManager;const { drainPendingDomEditSaves, resetDomEditSaveQueueBreaker } = previewPersistence;const bumpThumbnailRevisions = usePlayerStore((state) => state.bumpThumbnailRevisions);const onAcceptedPersistedFileChange = useCallback(- (_path: string, affectedCompositions: readonly string[] | null) =>- bumpThumbnailRevisions(affectedCompositions),- [bumpThumbnailRevisions],+ (_path: string, affectedCompositions: readonly string[] | null) => {+ onOutsideChange?.();+ bumpThumbnailRevisions(affectedCompositions);+ },+ [bumpThumbnailRevisions, onOutsideChange],);const drainPendingChanges = useCallback(async () => {const source = await flushPendingSourceSave();diff --git a/packages/studio/src/utils/domEditSaveQueue.ts b/packages/studio/src/utils/domEditSaveQueue.tsindex eb9ad868c7..f1d8035449 100644--- a/packages/studio/src/utils/domEditSaveQueue.ts+++ b/packages/studio/src/utils/domEditSaveQueue.ts@@ -20,6 +20,7 @@ interface DomEditSaveQueueOptions {export interface DomEditSaveQueue {enqueue: <T>(save: () => Promise<T>) => Promise<T>;waitForIdle: () => Promise<DomEditSaveDrainResult>;+ isIdle: () => boolean;reset: () => void;destroy: () => void;}@@ -39,6 +40,7 @@ export function createDomEditSaveQueue(options: DomEditSaveQueueOptions = {}): Dconst failureThreshold = options.failureThreshold ?? DEFAULT_FAILURE_THRESHOLD;let tail = Promise.resolve();+ let queuedCount = 0;let consecutiveFailures = 0;let breakerOpen = false;let drainError: unknown = null;@@ -81,6 +83,7 @@ export function createDomEditSaveQueue(options: DomEditSaveQueueOptions = {}): Dreturn {enqueue(save) {if (breakerOpen) return Promise.reject(new DomEditSaveQueueOpenError());+ queuedCount += 1;const queued = tail.catch(() => undefined).then(() => {@@ -88,8 +91,8 @@ export function createDomEditSaveQueue(options: DomEditSaveQueueOptions = {}): Dreturn run(save);});tail = queued.then(- () => undefined,- () => undefined,+ () => void (queuedCount -= 1),+ () => void (queuedCount -= 1),);return queued;},@@ -103,6 +106,8 @@ export function createDomEditSaveQueue(options: DomEditSaveQueueOptions = {}): Dreturn { status: "clean" };},+ isIdle: () => queuedCount === 0,+reset,destroy() {diff --git a/packages/studio/src/utils/gsapSoftReload.ts b/packages/studio/src/utils/gsapSoftReload.tsindex a9094a0224..6e1006d78b 100644--- a/packages/studio/src/utils/gsapSoftReload.ts+++ b/packages/studio/src/utils/gsapSoftReload.ts@@ -91,7 +91,7 @@ function isGsapScript(text: string): boolean {);}-export function findGsapScriptElements(doc: Document): HTMLScriptElement[] {+export function findGsapScriptElements(doc: ParentNode): HTMLScriptElement[] {const results: HTMLScriptElement[] = [];const scripts = doc.querySelectorAll<HTMLScriptElement>("script:not([src])");for (const script of scripts) {diff --git a/packages/studio/src/utils/gsapUndoRestore.test.ts b/packages/studio/src/utils/gsapUndoRestore.test.tsindex 387fbac227..83b93aed8e 100644--- a/packages/studio/src/utils/gsapUndoRestore.test.ts+++ b/packages/studio/src/utils/gsapUndoRestore.test.ts@@ -366,6 +366,52 @@ describe("applyUndoRestoreToPreview", () => {expect(meta.content).toBe(content);});+ const SUB = "compositions/sub.html";+ const sub = (style: string, rootAttrs = "") =>+ `<template id="sub-template"><div data-hf-id="hf-root" id="sub" data-composition-id="sub"${rootAttrs}><div ${style} data-hf-id="hf-t" id="target"></div></div></template>`;+ const host = (style: string) =>+ `<div data-composition-file="${SUB}" data-hf-id="hf-host"><div data-hf-inner-root="true" data-hf-authored-id="sub" data-hf-id="hf-root"><div data-hf-id="hf-t" id="target" ${style}></div></div></div>`;++ it("restores a sub-composition file in place, on every host that inlines it", () => {+ const { iframe, doc } = buildLiveIframe(+ host(`style="clip-path: inset(0px 40px 0px 0px);"`) ++ host(`style="clip-path: inset(0px 40px 0px 0px);"`),+ );+ const reloadPreview = vi.fn();+ const files = {+ [SUB]: { previous: sub(`style="clip-path: inset(0px 40px 0px 0px)"`), restored: sub("") },+ };+ expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("soft");+ expect(reloadPreview).not.toHaveBeenCalled();+ const targets = [...doc.querySelectorAll('[data-hf-id="hf-t"]')];+ expect(targets.map((el) => el.getAttribute("style"))).toEqual([null, null]);+ });++ it("full-reloads a sub-composition restore that changes the file's own root", () => {+ const { iframe } = buildLiveIframe(host(""));+ const reloadPreview = vi.fn();+ const files = { [SUB]: { previous: sub("", ' data-width="10"'), restored: sub("") } };+ expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("full");+ expect(reloadPreview).toHaveBeenCalledTimes(1);+ });++ it("full-reloads a sub-composition restore whose file has a GSAP script", () => {+ const { iframe, doc } = buildLiveIframe(host(`style="clip-path: inset(0px 40px 0px 0px);"`));+ const reloadPreview = vi.fn();+ const script = `<script>gsap.timeline().to("#target", { x: 10 });</script>`;+ const scripted = (style: string) =>+ sub(style).replace("</div></template>", `${script}</div></template>`);+ const files = {+ [SUB]: {+ previous: scripted(`style="clip-path: inset(0px 40px 0px 0px)"`),+ restored: scripted(""),+ },+ };+ expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("full");+ expect(reloadPreview).toHaveBeenCalledTimes(1);+ expect(doc.querySelector('[data-hf-id="hf-t"]')?.getAttribute("style")).toContain("clip-path");+ });+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();diff --git a/packages/studio/src/utils/gsapUndoRestore.ts b/packages/studio/src/utils/gsapUndoRestore.tsindex 78174abd80..e8fa92ad2f 100644--- a/packages/studio/src/utils/gsapUndoRestore.ts+++ b/packages/studio/src/utils/gsapUndoRestore.ts@@ -8,6 +8,7 @@ import {extractGsapScriptText,findGsapScriptElements,} from "./gsapSoftReload";+import { isCompositionTemplate } from "@hyperframes/parsers/hf-ids";import { findAuthoredElement, parseSavedSource } from "./authoredSource";import { STUDIO_EDIT_ATTRS } from "../components/editor/manualEditsSeekReapply";import { markScenesStale } from "../player/sceneSwap";@@ -22,6 +23,7 @@ export interface UndoRestoreFile {previous: string;restored: string;}+export type RestoreFiles = Record<string, UndoRestoreFile>;/*** Identity for the soft diff: `data-hf-id` when present, else `id`. Nearly@@ -40,9 +42,9 @@ function elementIdentityKey(el: Element): string | null {const IDENTITY_SELECTOR = "[id], [data-hf-id]";-function identityElementMap(doc: Document): Map<string, Element> | null {+function identityElementMap(root: ParentNode): Map<string, Element> | null {const map = new Map<string, Element>();- for (const el of doc.querySelectorAll(IDENTITY_SELECTOR)) {+ for (const el of root.querySelectorAll(IDENTITY_SELECTOR)) {const key = elementIdentityKey(el);if (!key) continue;// Ambiguous identity must full-reload; silently overwriting would restore@@ -53,14 +55,26 @@ function identityElementMap(doc: Document): Map<string, Element> | null {return map;}+// A sub-composition file wraps its markup in a template; the preview inlines that markup into its host.+function parseRestoreSource(html: string): Document {+ const doc = new DOMParser().parseFromString(html, "text/html");+ for (const template of Array.from(doc.querySelectorAll("template")).filter(+ isCompositionTemplate,+ )) {+ template.replaceWith(template.content);+ }+ return doc;+}+// Strip identified elements to their bare identity attributes and blank GSAP// scripts, in place: docs that differ only in identified-element attributes/// inline-style/script text normalize equal; any residual difference is beyond// soft-reload's reach → caller full-reloads. Both identity attributes are// KEPT, so a change to `id`/`data-hf-id` themselves stays a residual// (structural) difference.-function normalizeSoftResidual(doc: Document): void {- for (const el of doc.querySelectorAll(IDENTITY_SELECTOR)) {+function normalizeSoftResidual(root: Element): void {+ const self = root.matches(IDENTITY_SELECTOR) ? [root] : [];+ for (const el of [...self, ...root.querySelectorAll(IDENTITY_SELECTOR)]) {const id = el.getAttribute("id");const hfId = el.getAttribute("data-hf-id");for (const name of [...el.getAttributeNames()]) {@@ -69,7 +83,7 @@ function normalizeSoftResidual(doc: Document): void {if (id) el.setAttribute("id", id);if (hfId) el.setAttribute("data-hf-id", hfId);}- for (const script of findGsapScriptElements(doc)) script.textContent = "";+ for (const script of findGsapScriptElements(root)) script.textContent = "";}/** Same attribute set with identical values (order-insensitive). */@@ -100,14 +114,11 @@ export function diffSoftReloadableRestore(previous: string,restored: string,): { changedElementKeys: string[] } | null {- let prevDoc: Document;- let nextDoc: Document;- try {- prevDoc = new DOMParser().parseFromString(previous, "text/html");- nextDoc = new DOMParser().parseFromString(restored, "text/html");- } catch {- return null;- }+ const keys = diffRestoreDocs(parseRestoreSource(previous), parseRestoreSource(restored));+ return keys && { changedElementKeys: keys };+}++function diffRestoreDocs(prevDoc: Document, nextDoc: Document): string[] | null {const prevByKey = identityElementMap(prevDoc);const nextByKey = identityElementMap(nextDoc);if (!prevByKey || !nextByKey) return null;@@ -121,10 +132,12 @@ export function diffSoftReloadableRestore(if (!attributesEqual(prevEl, nextEl)) changedElementKeys.push(key);}// Confirm nothing OUTSIDE identified-element attributes and GSAP scripts changed.- normalizeSoftResidual(prevDoc);- normalizeSoftResidual(nextDoc);- if (prevDoc.documentElement.outerHTML !== nextDoc.documentElement.outerHTML) return null;- return { changedElementKeys };+ const [prevRest, nextRest] = [prevDoc, nextDoc].map((doc) => {+ const root = doc.documentElement.cloneNode(true) as Element;+ normalizeSoftResidual(root);+ return root.outerHTML;+ });+ return prevRest === nextRest ? changedElementKeys : null;}/** Copy every attribute from `source` onto the live `target`, dropping extras. */@@ -148,14 +161,10 @@ function syncStaleEditMarks(doc: Document, restored: string): void {}}-function readGsapScriptTexts(html: string): string[] {- const doc = new DOMParser().parseFromString(html, "text/html");- return findGsapScriptElements(doc).map((script) => script.textContent ?? "");-}--function hasAmbiguousGsapScriptChange(previous: string, restored: string): boolean {- const previousScripts = readGsapScriptTexts(previous);- const restoredScripts = readGsapScriptTexts(restored);+function hasAmbiguousGsapScriptChange(+ previousScripts: string[],+ restoredScripts: string[],+): boolean {if (previousScripts.length <= 1 && restoredScripts.length <= 1) return false;return (previousScripts.length !== restoredScripts.length ||@@ -163,11 +172,124 @@ function hasAmbiguousGsapScriptChange(previous: string, restored: string): boole);}+type RestoreTarget = { live: Element; restored: Element };+type RestorePlan = { targets: RestoreTarget[]; scripted: boolean };++/** Whether either side has a GSAP script, or null when its scripts rule out an in-place restore. */+function restoreScripted(prevDoc: Document, nextDoc: Document, isActive: boolean): boolean | null {+ const [before, after] = [prevDoc, nextDoc].map((doc) =>+ findGsapScriptElements(doc).map((script) => script.textContent ?? ""),+ );+ const scripted = before!.length > 0 || after!.length > 0;+ // Only the active document's GSAP script can be re-run in place.+ if (scripted && !isActive) return null;+ return hasAmbiguousGsapScriptChange(before!, after!) ? null : scripted;+}++// The active document is the whole preview; a sub-composition lives in each host that inlines it.+function liveScopes(doc: Document, path: string, isActive: boolean): ParentNode[] {+ if (isActive) return [doc];+ return Array.from(doc.querySelectorAll(`[data-composition-file="${CSS.escape(path)}"]`));+}++function scopeTargets(+ scope: ParentNode,+ keys: string[],+ restoredByKey: Map<string, Element>,+): RestoreTarget[] | null {+ const liveByKey = identityElementMap(scope);+ if (!liveByKey) return null;+ const targets: RestoreTarget[] = [];+ for (const key of keys) {+ const live = liveByKey.get(key);+ const restored = restoredByKey.get(key);+ // The preview rewrites a sub-composition's own root, so its attributes are not the file's.+ if (!live || !restored || live.hasAttribute("data-hf-inner-root")) return null;+ targets.push({ live, restored });+ }+ return targets;+}++function fileTargets(+ doc: Document,+ path: string,+ isActive: boolean,+ file: UndoRestoreFile,+): RestorePlan | null {+ const prevDoc = parseRestoreSource(file.previous);+ const nextDoc = parseRestoreSource(file.restored);+ const scripted = restoreScripted(prevDoc, nextDoc, isActive);+ if (scripted === null) return null;+ const keys = diffRestoreDocs(prevDoc, nextDoc);+ const restoredByKey = identityElementMap(nextDoc);+ if (!keys || !restoredByKey) return null;+ const found = liveScopes(doc, path, isActive).map((scope) =>+ scopeTargets(scope, keys, restoredByKey),+ );+ if (!found.length || found.includes(null)) return null;+ return { targets: (found as RestoreTarget[][]).flat(), scripted };+}++/** Every live element a restore changes with its restored markup, or null when it needs a reload. */+function planRestoreTargets(+ doc: Document,+ activeDocPath: string,+ files: RestoreFiles,+): RestorePlan | null {+ const plan: RestorePlan = { targets: [], scripted: false };+ for (const [path, file] of Object.entries(files)) {+ const found = fileTargets(doc, path, path === activeDocPath, file);+ if (!found) return null;+ plan.targets.push(...found.targets);+ plan.scripted ||= found.scripted;+ }+ return plan;+}++// Rebind-only finalization (no script run); plain seek + manual reapply when the runtime has no rebind hook.+function finalizeInPlace(+ iframe: HTMLIFrameElement,+ win: PreviewWindow,+ currentTime: number,+): boolean {+ if (applySoftReloadFinalization(iframe, currentTime)) return true;+ try {+ win.__player?.seek?.(currentTime);+ win.__hfStudioManualEditsApply?.();+ return true;+ } catch {+ return false;+ }+}++/** Shows a restore without a GSAP script in place, or nothing; returns what puts the shown elements back. */+export function showRestoreInPlace(+ iframe: HTMLIFrameElement | null,+ activeCompPath: string | null,+ files: RestoreFiles,+ currentTime: number,+): ((currentTime: number) => boolean) | null {+ const doc = iframe?.contentDocument;+ const win = iframe?.contentWindow as PreviewWindow | null;+ const plan = doc && win ? planRestoreTargets(doc, activeCompPath ?? "index.html", files) : null;+ if (!iframe || !win || !plan || plan.scripted) return null;+ const before = plan.targets.map(({ live }) => [live, live.cloneNode(false) as Element] as const);+ for (const { live, restored } of plan.targets) syncElementAttributes(live, restored);+ const putBack = (time: number) => {+ if (iframe.contentDocument !== doc) return false;+ for (const [live, attributes] of before) syncElementAttributes(live, attributes);+ return finalizeInPlace(iframe, win, time);+ };+ if (finalizeInPlace(iframe, win, currentTime)) return putBack;+ putBack(currentTime);+ return null;+}+/*** Soft-apply an undo/redo restore to the live preview WITHOUT a full iframe- * remount (which blanks the frame black and re-flashes the WebGL context). Only- * the active composition — the document living in the root iframe — is eligible;- * a sub-comp or multi-file restore falls back to `reloadPreview`.+ * remount (which blanks the frame black and re-flashes the WebGL context). Eligible+ * files are the active composition and any sub-composition the preview inlines;+ * a file the preview does not show falls back to `reloadPreview`.** The restore is soft-applied when its only differences are identified-element* (id / data-hf-id) attributes / inline-style and/or the GSAP script (see@@ -184,10 +306,7 @@ function hasAmbiguousGsapScriptChange(previous: string, restored: string): boole* lane move, timing shift, style tweak) → NO script execution — the* blink-free finalization only (seek + __hfForceTimelineRebind + manual* reapply, exactly the rebindPreviewTiming path), so timing-attribute- * reverts refresh their visibility windows. Re-running an unchanged- * script here used to be the biggest undo blink source: it tore down- * and rebuilt live timelines (and full-reloaded whenever the script- * couldn't be scoped) for restores that never touched it.+ * reverts refresh their visibility windows.** Returns "soft" when applied in place, "full" when it escalated to reloadPreview* (ineligible restore, missing target, or a permanent soft-reload failure).@@ -196,7 +315,7 @@ function hasAmbiguousGsapScriptChange(previous: string, restored: string): booleexport function applyUndoRestoreToPreview(iframe: HTMLIFrameElement | null,activeCompPath: string | null,- files: Record<string, UndoRestoreFile> | undefined,+ files: RestoreFiles | undefined,currentTime: number,reload: () => void,): "soft" | "full" {@@ -210,62 +329,26 @@ export function applyUndoRestoreToPreview(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) {+ const doc = iframe?.contentDocument;+ const win = iframe?.contentWindow as PreviewWindow | null;+ const plan = doc && files && win ? planRestoreTargets(doc, activeDocPath, files) : null;+ if (!iframe || !doc || !files || !win || !plan) {reloadPreview();return "full";}- const doc = iframe.contentDocument;- const win = iframe.contentWindow as PreviewWindow | null;- if (!doc || !win) {- reloadPreview();- return "full";- }- const { previous, restored } = files[activeDocPath]!;- const diff = diffSoftReloadableRestore(previous, restored);- if (!diff) {- reloadPreview();- return "full";- }- // A serialized snapshot cannot identify which of several GSAP scripts owns a- // rewrite. Keep attribute-only restores soft when every script byte is equal,- // but fail closed before touching the live DOM when an ambiguous script changed.- if (hasAmbiguousGsapScriptChange(previous, restored)) {- reloadPreview();- return "full";- }-- // Resolve every changed pair BEFORE touching the live DOM. A missing target- // makes the soft restore incomplete, so escalate without leaving a partially- // restored preview behind.- const liveByKey = identityElementMap(doc);- const restoredByKey = identityElementMap(new DOMParser().parseFromString(restored, "text/html"));- if (!liveByKey || !restoredByKey) {- reloadPreview();- return "full";- }- const changedTargets: Array<{ live: Element; restored: Element }> = [];- for (const key of diff.changedElementKeys) {- const liveEl = liveByKey.get(key);- const restoredEl = restoredByKey.get(key);- if (!liveEl || !restoredEl) {- reloadPreview();- return "full";- }- changedTargets.push({ live: liveEl, restored: restoredEl });- }// Sync each changed element's attributes onto the live DOM from the restored// markup, so the runtime's seek-reapply reads the reverted values.- for (const target of changedTargets) syncElementAttributes(target.live, target.restored);+ for (const target of plan.targets) syncElementAttributes(target.live, target.restored);- const restoredScript = extractGsapScriptText(restored);- const previousScript = extractGsapScriptText(previous);+ const active = files[activeDocPath];+ const restoredScript = active ? extractGsapScriptText(active.restored) : null;+ const previousScript = active ? extractGsapScriptText(active.previous) : null;if (restoredScript && restoredScript !== previousScript) {- syncStaleEditMarks(doc, restored);+ syncStaleEditMarks(doc, active.restored);const result = applySoftReload(iframe, restoredScript, {onAsyncFailure: reloadPreview,currentTimeOverride: currentTime,- authoredHtml: restored,+ authoredHtml: active.restored,});if (result === "cannot-soft-reload") {reloadPreview();@@ -274,16 +357,8 @@ export function applyUndoRestoreToPreview(return "soft";}// Script unchanged or absent — the live timelines are still valid; only the- // synced attributes need to take effect. Rebind-only finalization (zero- // script execution); plain seek + manual reapply as a degraded fallback when- // the runtime rebind hook is unavailable.- if (applySoftReloadFinalization(iframe, currentTime)) return "soft";- try {- win.__player?.seek?.(currentTime);- win.__hfStudioManualEditsApply?.();- } catch {- reloadPreview();- return "full";- }- return "soft";+ // synced attributes need to take effect.+ if (finalizeInPlace(iframe, win, currentTime)) return "soft";+ reloadPreview();+ return "full";}diff --git a/packages/studio/src/utils/studioPendingEdits.ts b/packages/studio/src/utils/studioPendingEdits.tsindex 876ce7e432..ea3940f589 100644--- a/packages/studio/src/utils/studioPendingEdits.ts+++ b/packages/studio/src/utils/studioPendingEdits.ts@@ -27,6 +27,18 @@ function inspectDrainFailures(results: PromiseSettledResult<unknown>[]): {return { firstFailure };}+function focusedField(): HTMLElement | null {+ const active = document.activeElement;+ return active instanceof HTMLElement &&+ active.matches('input, textarea, select, [contenteditable="true"], [role="textbox"]')+ ? active+ : null;+}++export function hasStudioPendingEdits(): boolean {+ return pendingEditPromises.size > 0 || focusedField() !== null;+}+export function trackStudioPendingEdit(result: Promise<unknown> | unknown,): Promise<unknown> | undefined {@@ -41,11 +53,8 @@ export function trackStudioPendingEdit(}export async function flushStudioPendingEdits(): Promise<StudioPendingEditsDrainResult> {- const active = document.activeElement;- if (- active instanceof HTMLElement &&- active.matches('input, textarea, select, [contenteditable="true"], [role="textbox"]')- ) {+ const active = focusedField();+ if (active) {active.blur();// ponytail: Preserve synchronous/microtask blur commits, then cross one task boundary// so React effects triggered by the blur can register their flush listener.