@hyperframes/studio 0.8.79 → 0.8.81

package/src/hooks/liveLanes.ts

@@ -0,0 +1,147 @@
+import { useRef, useState } from "react";
+import { readTargetAttribute, type PatchTarget } from "./timelineEditingHelpers";
+
+/** Where a lane's value lives in source, so an undo can re-read it. */
+export interface LiveLaneSource {
+  path: string;
+  target: PatchTarget | null;
+  attr: string;
+}
+
+/** The files an undo or redo rewrote. */
+export interface LiveLaneRestore {
+  paths?: string[];
+  files?: Record<string, { restored: string }>;
+}
+
+/** Per-lane live-preview state: the value before a gesture, pending saves, the last verified value. */
+function createLiveLanes(project: () => string, composition: () => string) {
+  const before = new Map<string, string | null>();
+  const sources = new Map<string, LiveLaneSource>();
+  const pending = new Map<string, Set<number>>();
+  const verified = new Map<string, string | null>();
+  // Lanes whose before-value was read with no save pending, so it is what the file holds.
+  const clean = new Set<string>();
+  let saves = 0;
+  const take = (key: string): string | null | undefined => {
+    const claimed = before.has(key) ? (before.get(key) ?? null) : undefined;
+    before.delete(key);
+    clean.delete(key);
+    if (!pending.has(key)) sources.delete(key);
+    return claimed;
+  };
+  const overtaken = (key: string, save: number): boolean =>
+    [...(pending.get(key) ?? [])].some((newer) => newer > save);
+  const rebase = (key: string, value: string | null | undefined): void => {
+    if (value === undefined) {
+      clean.delete(key);
+      verified.delete(key);
+      return;
+    }
+    if (before.has(key)) before.set(key, value);
+    if (pending.has(key)) verified.set(key, value);
+    if (pending.has(key)) clean.delete(key);
+    else clean.add(key);
+  };
+  const scoped = (laneKey: string): string => `${project()}\n${composition()}\n${laneKey}`;
+  return {
+    preview(laneKey: string, readCurrent: () => string | null, source: LiveLaneSource): void {
+      const key = scoped(laneKey);
+      if (before.has(key)) return;
+      before.set(key, readCurrent());
+      sources.set(key, source);
+      if (!pending.has(key)) clean.add(key);
+    },
+    // A save. Its settle records what the file holds: `saved`, else the last value verified on
+    // this lane (a landed save, a read-back, or a clean before-value), never an unsaved one.
+    // Store and preview follow only while no newer save is pending and its composition is open,
+    // and the preview only while no drag is live.
+    claim(laneKey: string, apply: LiveLaneApply, source: LiveLaneSource): LiveLaneSave {
+      const key = scoped(laneKey);
+      const open = () => scoped(laneKey) === key;
+      const trusted = clean.has(key);
+      const claimed = take(key);
+      const mine = ++saves;
+      sources.set(key, source);
+      if (claimed !== undefined && trusted) verified.set(key, claimed);
+      pending.set(key, (pending.get(key) ?? new Set<number>()).add(mine));
+      const preview = (value: string | null) => {
+        if (open() && !before.has(key) && !overtaken(key, mine)) apply.preview(value);
+      };
+      return {
+        preview,
+        read(value) {
+          verified.set(key, value);
+        },
+        settle(saved) {
+          const inFlight = pending.get(key);
+          inFlight?.delete(mine);
+          if (saved !== undefined) verified.set(key, saved);
+          const value = verified.get(key);
+          // With no save left in flight the file can change under it (undo, an outside edit).
+          if (!inFlight?.size) {
+            pending.delete(key);
+            verified.delete(key);
+            if (!before.has(key)) sources.delete(key);
+          }
+          if (value === undefined || overtaken(key, mine) || !open()) return;
+          if (before.has(key)) {
+            before.set(key, value);
+            clean.add(key);
+          }
+          apply.store(value);
+          preview(value);
+        },
+      };
+    },
+    // A gesture refused before it saved: put its before-value back, which hands the lane
+    // back to any save still pending on it.
+    revert(laneKey: string, apply: LiveLaneApply): void {
+      const claimed = take(scoped(laneKey));
+      if (claimed === undefined) return;
+      apply.preview(claimed);
+      apply.store(claimed);
+    },
+    // An undo or redo rewrote files under the project's live gestures and pending saves, in any
+    // composition: each takes what the restored file holds, or stops trusting a value it cannot read.
+    restore({ paths = [], files }: LiveLaneRestore): void {
+      const inProject = `${project()}\n`;
+      for (const [key, source] of sources) {
+        if (key.startsWith(inProject) && paths.includes(source.path)) {
+          rebase(key, restoredValue(source, files));
+        }
+      }
+    },
+  };
+}
+
+function restoredValue({ path, target, attr }: LiveLaneSource, files: LiveLaneRestore["files"]) {
+  const html = files?.[path]?.restored;
+  return html === undefined || !target ? undefined : readTargetAttribute(html, target, attr);
+}
+
+/** A hook's live lanes, scoped to the project and composition open when each save starts. */
+export function useLiveLanes(
+  projectIdRef: { readonly current: string | null },
+  activeCompPath: string | null,
+) {
+  const compositionRef = useRef(activeCompPath);
+  compositionRef.current = activeCompPath;
+  const [lanes] = useState(() =>
+    createLiveLanes(
+      () => projectIdRef.current ?? "",
+      () => compositionRef.current ?? "",
+    ),
+  );
+  return lanes;
+}
+
+interface LiveLaneSave {
+  preview: (value: string | null) => void;
+  read: (value: string | null) => void;
+  settle: (saved?: string | null) => void;
+}
+interface LiveLaneApply {
+  preview: (value: string | null) => void;
+  store: (value: string | null) => void;
+}

package/src/hooks/timelineAudioGroupVolume.ts

@@ -1,5 +1,9 @@
-import { useCallback, useRef } from "react";
-import { projectForTimelineSave, type TimelineEditOutcome } from "./timelineEditPermission";
+import { useCallback } from "react";
+import {
+  failedTimelineSave,
+  projectForTimelineSave,
+  type TimelineEditOutcome,
+} from "./timelineEditPermission";
 import { HF_AUDIO_FX_ATTR } from "@hyperframes/core/audio-fx";
 import { HF_AUDIO_AUTOMATION_ATTR } from "@hyperframes/core/audio-automation";
 import { usePlayerStore } from "../player";
@@ -8,8 +12,10 @@ import { invalidateGroupInfoCache } from "../player/lib/timelineGroupInfo";
 import {
   buildPatchTarget,
   persistElementAttribute,
+  readSavedAttribute,
   type RecordEditInput,
 } from "./timelineEditingHelpers";
+import { useLiveLanes, type LiveLaneRestore, type LiveLaneSource } from "./liveLanes";
 import type {
   MutableRef,
   UseTimelineElementVisibilityEditingInput,
@@ -146,6 +152,8 @@ interface SetAudioGroupAttributeInput {
   value: string | null;
   label: string;
   previewIframe: HTMLIFrameElement | null;
+  patchLive: (value: string | null) => void;
+  onFileRead: (value: string | null) => void;
   writeProjectFile: (path: string, content: string) => Promise<void>;
   recordEdit: (input: RecordEditInput) => Promise<void>;
   pendingTimelineEditPathRef: MutableRef<Set<string>>;
@@ -157,6 +165,28 @@ interface SetAudioGroupAttributeInput {
  * `createAudioGroupAndAssignMembers`'s save shape but for a single element
  * and attribute rather than a member-assignment sweep.
  */
+function groupSaveTarget(
+  previewIframe: HTMLIFrameElement | null,
+  groupId: string,
+  activeCompPath: string | null,
+) {
+  const groupEl = previewIframe?.contentDocument?.getElementById(groupId) ?? null;
+  return {
+    targetPath: resolveGroupSourceFile(groupEl) || activeCompPath || "index.html",
+    patchTarget: buildPatchTarget({ domId: groupId }),
+  };
+}
+
+function groupLiveSource(
+  previewIframe: HTMLIFrameElement | null,
+  groupId: string,
+  activeCompPath: string | null,
+  attr: string,
+): LiveLaneSource {
+  const { targetPath, patchTarget } = groupSaveTarget(previewIframe, groupId, activeCompPath);
+  return { path: targetPath, target: patchTarget, attr };
+}
+
 async function setAudioGroupAttribute({
   projectId,
   activeCompPath,
@@ -165,6 +195,8 @@ async function setAudioGroupAttribute({
   value,
   label,
   previewIframe,
+  patchLive,
+  onFileRead,
   writeProjectFile,
   recordEdit,
   pendingTimelineEditPathRef,
@@ -177,9 +209,7 @@ async function setAudioGroupAttribute({
   // means `readTagSnippetByTarget` finds nothing and every mute, fader move and
   // FX preset throws "Unable to patch element in index.html". Every sibling
   // timeline writer already routes `element.sourceFile || activeCompPath`.
-  const groupEl = previewIframe?.contentDocument?.getElementById(groupId) ?? null;
-  const targetPath = resolveGroupSourceFile(groupEl) || activeCompPath || "index.html";
-  const patchTarget = buildPatchTarget({ domId: groupId });
+  const { targetPath, patchTarget } = groupSaveTarget(previewIframe, groupId, activeCompPath);
   if (!patchTarget) return null;
 
   return persistElementAttribute({
@@ -192,7 +222,8 @@ async function setAudioGroupAttribute({
     writeProjectFile,
     recordEdit,
     pendingTimelineEditPathRef,
-    patchLive: (v) => patchLiveGroupAttribute(previewIframe, groupId, attr, v),
+    patchLive,
+    onFileRead,
   });
 }
 
@@ -221,42 +252,43 @@ export function useSetAudioGroupAttribute({
     label: string,
   ) => Promise<TimelineEditOutcome>;
   revertLive: (groupId: string, attr: string) => void;
+  restoreLive: (restore: LiveLaneRestore) => void;
 } {
-  const liveBeforeRef = useRef(new Map<string, string | null>());
+  const liveLanes = useLiveLanes(projectIdRef, activeCompPath);
   const setLive = useCallback(
     (groupId: string, attr: string, value: string | null) => {
       const key = audioGroupAttributeLiveKey(groupId, attr);
       const target = previewIframeRef.current?.contentDocument?.getElementById(groupId);
-      if (!liveBeforeRef.current.has(key)) {
-        liveBeforeRef.current.set(key, target?.getAttribute(attr) ?? null);
-      }
+      liveLanes.preview(
+        key,
+        () => target?.getAttribute(attr) ?? null,
+        groupLiveSource(previewIframeRef.current, groupId, activeCompPath, attr),
+      );
       patchLiveGroupAttribute(previewIframeRef.current, groupId, attr, value);
       // Live too, not just on commit: a fader drag is `setLive` per frame and
       // `setQuiet` once on release, so without this the strip's own readout
       // fights the drag.
       syncStoredGroupAttribute(groupId, attr, value);
     },
+    [liveLanes, previewIframeRef, activeCompPath],
+  );
+  const laneApply = useCallback(
+    (groupId: string, attr: string) => ({
+      preview: (value: string | null) =>
+        patchLiveGroupAttribute(previewIframeRef.current, groupId, attr, value),
+      store: (value: string | null) => syncStoredGroupAttribute(groupId, attr, value),
+    }),
     [previewIframeRef],
   );
+  const claimLive = useCallback(
+    (groupId: string, attr: string, source: LiveLaneSource) =>
+      liveLanes.claim(audioGroupAttributeLiveKey(groupId, attr), laneApply(groupId, attr), source),
+    [liveLanes, laneApply],
+  );
   const revertLive = useCallback(
-    (groupId: string, attr: string) => {
-      const key = audioGroupAttributeLiveKey(groupId, attr);
-      if (!liveBeforeRef.current.has(key)) return;
-      patchLiveGroupAttribute(
-        previewIframeRef.current,
-        groupId,
-        attr,
-        liveBeforeRef.current.get(key) ?? null,
-      );
-      syncStoredGroupAttribute(
-        groupId,
-        attr,
-        previewIframeRef.current?.contentDocument?.getElementById(groupId)?.getAttribute(attr) ??
-          null,
-      );
-      liveBeforeRef.current.delete(key);
-    },
-    [previewIframeRef],
+    (groupId: string, attr: string) =>
+      liveLanes.revert(audioGroupAttributeLiveKey(groupId, attr), laneApply(groupId, attr)),
+    [liveLanes, laneApply],
   );
   const setQuiet = useCallback(
     async (
@@ -265,8 +297,19 @@ export function useSetAudioGroupAttribute({
       value: string | null,
       label: string,
     ): Promise<TimelineEditOutcome> => {
-      const pid = projectForTimelineSave(isRecordingRef?.current, projectIdRef.current, showToast);
-      if (typeof pid !== "string") return pid;
+      const project = projectIdRef.current;
+      const pid = projectForTimelineSave(isRecordingRef?.current, project, showToast);
+      // Settles on what the file holds, so overlapping saves that fail cannot leave
+      // the preview or the store on a value that never landed.
+      const source = groupLiveSource(previewIframeRef.current, groupId, activeCompPath, attr);
+      const live = claimLive(groupId, attr, source);
+      const unsaved = async (outcome: TimelineEditOutcome): Promise<TimelineEditOutcome> => {
+        live.settle(
+          await readSavedAttribute(project, source.path, source.target, attr, writeProjectFile),
+        );
+        return outcome;
+      };
+      if (typeof pid !== "string") return unsaved(pid);
       try {
         const written = await setAudioGroupAttribute({
           projectId: pid,
@@ -276,33 +319,24 @@ export function useSetAudioGroupAttribute({
           value,
           label,
           previewIframe: previewIframeRef.current,
+          patchLive: live.preview,
+          onFileRead: live.read,
           writeProjectFile,
           recordEdit,
           pendingTimelineEditPathRef,
         });
-        liveBeforeRef.current.delete(audioGroupAttributeLiveKey(groupId, attr));
-        if (!written) return { status: "failed", reason: "This group has no id to save it by" };
-        syncStoredGroupAttribute(groupId, attr, value);
+        if (!written)
+          return unsaved(failedTimelineSave("This group has no id to save it by", showToast));
+        live.settle(value);
         return { status: "saved" };
       } catch (error) {
-        // `persistElementAttribute` leaves the live DOM at the previous value
-        // however it failed — it unwinds a failed save, and an unresolvable
-        // target now throws before patching at all. But `setLive` mirrored the
-        // in-progress value into the store on every drag frame — so without
-        // this the fader reads 0.4 while
-        // the preview and the file are both back at 1.0, and nothing re-parses
-        // to correct it (a live patch causing no parse is this mirror's whole
-        // premise). Re-mirror from the DOM, which is now authoritative again.
-        const live = previewIframeRef.current?.contentDocument?.getElementById(groupId);
-        syncStoredGroupAttribute(groupId, attr, live?.getAttribute(attr) ?? null);
         console.error("[Timeline] Failed to set group attribute", error);
         const message = error instanceof Error ? error.message : "Failed to update group";
-        showToast(message);
-        liveBeforeRef.current.delete(audioGroupAttributeLiveKey(groupId, attr));
-        return { status: "failed", reason: message };
+        return unsaved(failedTimelineSave(message, showToast));
       }
     },
     [
+      claimLive,
       activeCompPath,
       previewIframeRef,
       writeProjectFile,
@@ -313,5 +347,5 @@ export function useSetAudioGroupAttribute({
       projectIdRef,
     ],
   );
-  return { setLive, setQuiet, revertLive };
+  return { setLive, setQuiet, revertLive, restoreLive: liveLanes.restore };
 }

package/src/hooks/timelineEditPermission.ts

@@ -21,7 +21,15 @@ export function projectForTimelineSave(
     showToast("Cannot edit timeline while recording", "error");
     return { status: "refused", reason: "Cannot edit timeline while recording" };
   }
-  return projectId ?? { status: "failed", reason: "No project is open" };
+  return projectId ?? failedTimelineSave("No project is open", showToast);
+}
+
+export function failedTimelineSave(
+  reason: string,
+  showToast: (message: string, tone?: "error" | "info") => void,
+): TimelineEditOutcome {
+  showToast(reason);
+  return { status: "failed", reason };
 }
 
 function timelineEditRefusal(

package/src/hooks/timelineEditingHelpers.test.ts

@@ -3,6 +3,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   applyTimelineStackingReorder,
   buildTimelineMoveTimingPatch,
+  buildTimelineResizeTimingPatch,
   deleteSelectedKeyframes,
   extendRootDurationIfNeeded,
   patchIframeDomTiming,
@@ -230,6 +231,19 @@ describe("extendRootDurationIfNeeded", () => {
   });
 });
 
+describe("buildTimelineResizeTimingPatch", () => {
+  it("moves a source-only in-point by the caller's own start change", () => {
+    const source = `<div id="root"><video id="a" class="clip" data-start="5" data-duration="3" data-media-start="0.337"></video></div>`;
+    const element = el({ id: "a", tag: "video", domId: "a", start: 5, duration: 3 });
+    const patched = buildTimelineResizeTimingPatch(source, { id: "a" }, element, {
+      start: 3,
+      duration: 5,
+      playbackStart: undefined,
+    });
+    expect(patched).toContain('data-media-start="0"');
+  });
+});
+
 describe("persistTimelineBatchEdit", () => {
   const SOURCE = `<div id="root"><video id="a" class="clip" data-start="1" data-track-index="0"></video><video id="b" class="clip" data-start="2" data-track-index="1"></video></div>`;
 
@@ -452,6 +466,7 @@ describe("persistElementAttribute", () => {
         writeProjectFile,
         recordEdit: vi.fn(),
         pendingTimelineEditPathRef: { current: new Set() },
+        onFileRead: vi.fn(),
         patchLive,
       }),
     ).rejects.toThrow("Unable to patch element in index.html");
@@ -495,6 +510,7 @@ describe("persistElementAttribute — unwind value", () => {
         writeProjectFile,
         recordEdit: vi.fn(),
         pendingTimelineEditPathRef: { current: new Set() },
+        onFileRead: vi.fn(),
         // The live DOM is ALREADY at the new value when the commit runs — that
         // is what `setLive` does on every drag frame.
         patchLive: (v) => patched.push(v),

package/src/hooks/timelineEditingHelpers.ts

@@ -8,6 +8,7 @@ import {
 } from "../utils/sourcePatcher";
 import {
   formatTimelineAttributeNumber,
+  formatTimelineMediaOffset,
   type TimelineStackingReorderIntent,
 } from "../player/components/timelineEditing";
 import { getElementZIndex } from "../player/lib/layerOrdering";
@@ -15,7 +16,12 @@ import {
   furthestClipEndFromSource,
   getTimelineElementIdentity,
 } from "../player/lib/timelineElementHelpers";
-import { saveProjectFilesWithHistory, type RecordEditInput } from "../utils/studioFileHistory";
+import {
+  saveProjectFilesWithHistory,
+  writeProjectFilesWithHistoryInQueue,
+  type RecordEditInput,
+} from "../utils/studioFileHistory";
+import { serializeStudioFileMutations } from "../utils/studioFileMutationCoordinator";
 import type { TimelineZIndexReorderCommit } from "./useTimelineEditingTypes";
 import { setCompositionDurationToContent } from "../utils/timelineAssetDrop";
 import { readFileContent } from "./timelineTimingSync";
@@ -279,7 +285,7 @@ export function buildTimelineResizeTimingPatch(
     patched = applyPatchByTarget(patched, target, {
       type: "attribute",
       property: pbs.attrName,
-      value: formatTimelineAttributeNumber(pbs.value),
+      value: formatTimelineMediaOffset(pbs.value),
     });
   }
   // Content-driven duration from the PATCHED SOURCE (raw data-duration) —
@@ -396,7 +402,32 @@ export async function persistTimelineBatchEdit(
   });
 }
 
-export { applyPatchByTarget, formatTimelineAttributeNumber };
+/** What the file holds for `attr` once queued writes to it land; undefined when unreadable. */
+export async function readSavedAttribute(
+  projectId: string | null,
+  targetPath: string,
+  patchTarget: PatchTarget | null,
+  attr: string,
+  writeFile: (path: string, content: string, expectedContent?: string) => Promise<void>,
+): Promise<string | null | undefined> {
+  if (!projectId || !patchTarget) return undefined;
+  const html = await serializeStudioFileMutations(writeFile, [targetPath], () =>
+    readFileContent(projectId, targetPath),
+  ).catch(() => null);
+  return html === null ? undefined : readTargetAttribute(html, patchTarget, attr);
+}
+
+/** What `html` holds for `attr` on the target; undefined when the target is not in it. */
+export function readTargetAttribute(
+  html: string,
+  patchTarget: PatchTarget,
+  attr: string,
+): string | null | undefined {
+  if (readTagSnippetByTarget(html, patchTarget) === undefined) return undefined;
+  return readAttributeByTarget(html, patchTarget, attr) ?? null;
+}
+
+export { applyPatchByTarget, formatTimelineAttributeNumber, formatTimelineMediaOffset };
 
 export { patchDocumentRootDuration } from "./timelineEditingGsap";
 
@@ -412,6 +443,8 @@ export interface PersistElementAttributeInput {
   pendingTimelineEditPathRef: { current: Set<string> };
   /** Write the attribute directly on the live preview DOM node. */
   patchLive: (value: string | null) => void;
+  /** What the file held for the attribute, read inside the queue before this write. */
+  onFileRead: (value: string | null) => void;
 }
 
 /**
@@ -433,47 +466,40 @@ export async function persistElementAttribute({
   recordEdit,
   pendingTimelineEditPathRef,
   patchLive,
+  onFileRead,
 }: PersistElementAttributeInput): Promise<string[]> {
-  // Resolve the target BEFORE patching the live DOM. The optimistic patch used
-  // to run first, and only the save was wrapped in the unwind — so an
-  // unresolvable target threw with the live preview (and, through the callers'
-  // catch, the store mirrored off it) holding a value that never reached disk.
-  // The write then read as successful until a reload dropped it.
-  const before = await readFileContent(projectId, targetPath);
-  if (readTagSnippetByTarget(before, patchTarget) === undefined) {
-    throw new Error(`Unable to patch element in ${targetPath}`);
-  }
-  // The unwind value comes from the FILE, not from `readLive()`.
-  //
-  // Every live-write caller patches the DOM before committing — a fader drag is
-  // `setLive` per frame, hovering a preset auditions the whole chain — so by the
-  // time this runs the live DOM already holds the in-progress value. Reading it
-  // here made `previousValue === value`, so the unwind below was a no-op, and
-  // `setQuiet`'s catch (which deliberately re-mirrors the store from the live
-  // DOM) then mirrored that same never-saved value. The group audibly had the
-  // preset, the panel agreed, and a reload dropped it — the failure class the
-  // target check above was added to close, still open on the live-write path.
-  const previousValue = readAttributeByTarget(before, patchTarget, attr) ?? null;
-  patchLive(value);
+  // Joins the file's mutation queue before reading, so saves land in the order they start
+  // and each patches what the save before it wrote. Resolve the target before patching
+  // the live DOM, so an unresolvable target never leaves an unsaved preview.
+  return serializeStudioFileMutations(writeProjectFile, [targetPath], async () => {
+    const before = await readFileContent(projectId, targetPath);
+    if (readTagSnippetByTarget(before, patchTarget) === undefined) {
+      throw new Error(`Unable to patch element in ${targetPath}`);
+    }
+    // Unwind to the file's value: live writers already patched the DOM, so `readLive()`
+    // would equal `value` and a failed save would keep a never-saved preview.
+    const previousValue = readAttributeByTarget(before, patchTarget, attr) ?? null;
+    onFileRead(previousValue);
+    patchLive(value);
 
-  const operation: PatchOperation = { type: "attribute", property: attr, value };
-  const patched = applyPatchByTarget(before, patchTarget, operation);
+    const operation: PatchOperation = { type: "attribute", property: attr, value };
+    const patched = applyPatchByTarget(before, patchTarget, operation);
 
-  pendingTimelineEditPathRef.current.add(targetPath);
-  try {
-    const changedPaths = await saveProjectFilesWithHistory({
-      projectId,
-      label,
-      files: { [targetPath]: patched },
-      readFile: async (path) => (path === targetPath ? before : readFileContent(projectId, path)),
-      writeFile: writeProjectFile,
-      recordEdit,
-    });
-    return changedPaths;
-  } catch (error) {
-    // The optimistic live write already ran; unwind it on a save failure so
-    // the preview doesn't show a value that never reached disk.
-    patchLive(previousValue);
-    throw error;
-  }
+    pendingTimelineEditPathRef.current.add(targetPath);
+    try {
+      return await writeProjectFilesWithHistoryInQueue({
+        projectId,
+        label,
+        files: { [targetPath]: patched },
+        readFile: async (path) => (path === targetPath ? before : readFileContent(projectId, path)),
+        writeFile: writeProjectFile,
+        recordEdit,
+      });
+    } catch (error) {
+      // The optimistic live write already ran; unwind it on a save failure so
+      // the preview doesn't show a value that never reached disk.
+      patchLive(previousValue);
+      throw error;
+    }
+  });
 }