@hyperframes/studio 0.7.92 → 0.7.93

package/src/player/components/useTimelineRowVirtualization.ts

@@ -20,9 +20,9 @@ interface UseTimelineRowVirtualizationInput {
   viewport: TimelineScrollViewportSnapshot;
   rowGeometry: TimelineRowGeometry;
   sessionEpoch: number;
-  elements: TimelineElement[];
+  elements: readonly TimelineElement[];
   selectedElementId: string | null;
-  revealElementId: string | null;
+  focusedRowKey?: number;
   draggedRowKey?: number;
   resizingElementIds?: readonly string[];
   clipContextMenuRowKey?: number;
@@ -31,19 +31,12 @@ interface UseTimelineRowVirtualizationInput {
   syncScrollViewport: (element: HTMLDivElement, isScrolling?: boolean) => void;
 }
 
-interface TimelineDomFocusPin {
-  readonly rowKey?: number;
-  readonly elementId?: string;
-}
-
-function getTimelineDomFocusPin(target: EventTarget | null): TimelineDomFocusPin | undefined {
+function getFocusedTimelineRowKey(target: EventTarget | null): number | undefined {
   if (!(target instanceof Element)) return undefined;
   const value = target.closest<HTMLElement>("[data-timeline-row-key]")?.dataset.timelineRowKey;
-  const parsedRowKey = value === undefined ? undefined : Number(value);
-  const rowKey =
-    parsedRowKey !== undefined && Number.isFinite(parsedRowKey) ? parsedRowKey : undefined;
-  const elementId = target.closest<HTMLElement>("[data-el-id]")?.dataset.elId;
-  return rowKey === undefined && elementId === undefined ? undefined : { rowKey, elementId };
+  if (value === undefined) return undefined;
+  const rowKey = Number(value);
+  return Number.isFinite(rowKey) ? rowKey : undefined;
 }
 
 export function useTimelineRowVirtualization({
@@ -53,7 +46,7 @@ export function useTimelineRowVirtualization({
   sessionEpoch,
   elements,
   selectedElementId,
-  revealElementId,
+  focusedRowKey,
   draggedRowKey,
   resizingElementIds,
   clipContextMenuRowKey,
@@ -62,21 +55,17 @@ export function useTimelineRowVirtualization({
   syncScrollViewport,
 }: UseTimelineRowVirtualizationInput) {
   const enabled = STUDIO_TIMELINE_ROW_VIRTUALIZATION_ENABLED;
-  const [domFocusPin, setDomFocusPin] = useState<TimelineDomFocusPin>();
+  const [domFocusedRowKey, setDomFocusedRowKey] = useState<number>();
   const onTimelineFocus = useCallback((event: ReactFocusEvent<HTMLDivElement>) => {
-    setDomFocusPin(getTimelineDomFocusPin(event.target));
+    setDomFocusedRowKey(getFocusedTimelineRowKey(event.target));
   }, []);
   const onTimelineBlur = useCallback((event: ReactFocusEvent<HTMLDivElement>) => {
-    setDomFocusPin(getTimelineDomFocusPin(event.relatedTarget));
+    setDomFocusedRowKey(getFocusedTimelineRowKey(event.relatedTarget));
   }, []);
-  const focusIdentity = useMemo(
+  const selectedIdentity = useMemo(
     () => resolveTimelineFocusIdentity(elements, selectedElementId),
     [elements, selectedElementId],
   );
-  const revealIdentity = useMemo(
-    () => resolveTimelineFocusIdentity(elements, revealElementId),
-    [elements, revealElementId],
-  );
   const resizingRowKeys = useMemo(
     () =>
       resizingElementIds
@@ -89,16 +78,18 @@ export function useTimelineRowVirtualization({
       [
         draggedRowKey,
         ...resizingRowKeys,
-        revealIdentity?.rowKey,
+        selectedIdentity?.rowKey,
+        focusedRowKey,
         clipContextMenuRowKey,
         keyframeContextMenuRowKey,
       ].filter((rowKey): rowKey is number => rowKey !== undefined),
     [
       clipContextMenuRowKey,
       draggedRowKey,
+      focusedRowKey,
       keyframeContextMenuRowKey,
       resizingRowKeys,
-      revealIdentity,
+      selectedIdentity,
     ],
   );
   const virtualRows = useTimelineVirtualRows({
@@ -108,7 +99,7 @@ export function useTimelineRowVirtualization({
     rowGeometry,
     sessionEpoch,
     pinnedRowKeys,
-    focusedRowKey: domFocusPin?.rowKey ?? focusIdentity?.rowKey,
+    focusedRowKey: domFocusedRowKey ?? focusedRowKey,
   });
 
   const previousLayoutRef = useRef(rowGeometry);
@@ -141,7 +132,6 @@ export function useTimelineRowVirtualization({
   return {
     enabled,
     virtualRows,
-    focusedElementId: domFocusPin?.elementId,
     timelineFocusProps: { onFocus: onTimelineFocus, onBlur: onTimelineBlur },
   };
 }

package/src/player/store/liveTime.ts

@@ -0,0 +1,11 @@
+// ponytail: Playback RAF updates the playhead/time display without per-frame React renders.
+type TimeListener = (time: number) => void;
+const timeListeners = new Set<TimeListener>();
+
+export const liveTime = {
+  notify: (time: number) => timeListeners.forEach((listener) => listener(time)),
+  subscribe: (listener: TimeListener) => {
+    timeListeners.add(listener);
+    return () => timeListeners.delete(listener);
+  },
+};

package/src/player/store/playerStore.test.ts

@@ -492,29 +492,36 @@ describe("usePlayerStore", () => {
     });
   });
 
-  describe("clipRevealRequest", () => {
-    it("starts null and carries the requested element id", () => {
-      expect(usePlayerStore.getState().clipRevealRequest).toBeNull();
-      usePlayerStore.getState().requestClipReveal("el-1");
-      expect(usePlayerStore.getState().clipRevealRequest?.elementId).toBe("el-1");
-    });
-
-    it("bumps the nonce on repeat requests for the same clip", () => {
-      usePlayerStore.getState().requestClipReveal("el-1");
-      const first = usePlayerStore.getState().clipRevealRequest;
-      usePlayerStore.getState().requestClipReveal("el-1");
-      const second = usePlayerStore.getState().clipRevealRequest;
-      expect(second?.nonce).not.toBe(first?.nonce);
-    });
-
-    it("clears via clearClipRevealRequest and on reset", () => {
-      usePlayerStore.getState().requestClipReveal("el-1");
-      usePlayerStore.getState().clearClipRevealRequest();
-      expect(usePlayerStore.getState().clipRevealRequest).toBeNull();
+  describe("timelineFocus", () => {
+    it("stamps project scope and carries the requested logical id", () => {
+      usePlayerStore.getState().beginTimelineSession("project-a");
+      usePlayerStore.getState().requestTimelineFocus("clip:el-1");
+      expect(usePlayerStore.getState().timelineFocus).toMatchObject({
+        id: "clip:el-1",
+        projectId: "project-a",
+        sessionEpoch: usePlayerStore.getState().timelineSessionEpoch,
+      });
+      const store = usePlayerStore.getState();
+      store.requestTimelineFocus("clip:el-1");
+      const first = usePlayerStore.getState().timelineFocus;
+      if (!first) throw new Error("expected timeline focus request");
+      store.clearTimelineFocus(first.nonce);
+      store.reset();
+      store.requestTimelineFocus("clip:el-1");
+      const second = usePlayerStore.getState().timelineFocus;
+      expect(second?.nonce).toBe(first.nonce + 1);
 
-      usePlayerStore.getState().requestClipReveal("el-2");
-      usePlayerStore.getState().reset();
-      expect(usePlayerStore.getState().clipRevealRequest).toBeNull();
+      store.beginTimelineSession("project-a");
+      store.requestTimelineFocus("clip:el-1");
+      const stale = usePlayerStore.getState().timelineFocus;
+      if (!stale) throw new Error("expected timeline focus request");
+      store.requestTimelineFocus("clip:el-2");
+      const replacement = usePlayerStore.getState().timelineFocus;
+      if (!replacement) throw new Error("expected replacement timeline focus request");
+      store.clearTimelineFocus(stale.nonce);
+      expect(usePlayerStore.getState().timelineFocus).toBe(replacement);
+      store.beginTimelineSession("project-b");
+      expect(usePlayerStore.getState().timelineFocus).toBeNull();
     });
   });
 

package/src/player/store/playerStore.ts

@@ -10,8 +10,10 @@ import {
 } from "../../utils/studioUiPreferences";
 import { clampTimelineZoomPercent, computePinnedZoomPercent } from "../components/timelineZoom";
 import { createKeyframeSlice, type KeyframeCacheEntry, type KeyframeSlice } from "./keyframeSlice";
+import { createTimelineFocusRequest, type TimelineFocusRequest } from "./timelineFocusState";
 
 export type { KeyframeCacheEntry } from "./keyframeSlice";
+export { liveTime } from "./liveTime";
 
 export interface TimelineElement {
   id: string;
@@ -220,15 +222,10 @@ interface PlayerState extends KeyframeSlice {
   requestSeek: (time: number) => void;
   clearSeekRequest: () => void;
 
-  /**
-   * Request the timeline to scroll a clip into view (e.g. clicking an
-   * already-added asset card in the sidebar). Consumed and cleared by
-   * useTimelineRevealClip. The nonce makes repeat requests for the same
-   * clip observable so a second click re-reveals after the user scrolls away.
-   */
-  clipRevealRequest: { elementId: string; nonce: number } | null;
-  requestClipReveal: (elementId: string) => void;
-  clearClipRevealRequest: () => void;
+  timelineFocus: TimelineFocusRequest | null;
+  timelineFocusNonce: number;
+  requestTimelineFocus: (id: string) => void;
+  clearTimelineFocus: (nonce: number) => void;
 
   lintFindingsByElement: Map<string, { count: number; messages: string[] }>;
   setLintFindingsByElement: (map: Map<string, { count: number; messages: string[] }>) => void;
@@ -279,19 +276,6 @@ interface BeatHistoryEntry {
   label: string;
 }
 
-// Lightweight pub-sub for current time during playback.
-// Bypasses React state so the RAF loop can update the playhead/time display
-// without triggering re-renders on every frame.
-type TimeListener = (time: number) => void;
-const _timeListeners = new Set<TimeListener>();
-export const liveTime = {
-  notify: (t: number) => _timeListeners.forEach((cb) => cb(t)),
-  subscribe: (cb: TimeListener) => {
-    _timeListeners.add(cb);
-    return () => _timeListeners.delete(cb);
-  },
-};
-
 export function createTimelineResetState() {
   return {
     isPlaying: false,
@@ -313,8 +297,8 @@ export function createTimelineResetState() {
     focusedEaseSegment: null,
     selectedElementIds: new Set<string>(),
     requestedSeekTime: null,
-    clipRevealRequest: null,
     lintFindingsByElement: new Map<string, { count: number; messages: string[] }>(),
+    timelineFocus: null,
     keyframeCache: new Map<string, KeyframeCacheEntry>(),
     gsapAnimations: new Map<string, GsapAnimation[]>(),
     beatAnalysis: null,
@@ -387,12 +371,23 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   requestSeek: (time) => set({ requestedSeekTime: time }),
   clearSeekRequest: () => set({ requestedSeekTime: null }),
 
-  clipRevealRequest: null,
-  requestClipReveal: (elementId) =>
-    set((s) => ({
-      clipRevealRequest: { elementId, nonce: (s.clipRevealRequest?.nonce ?? 0) + 1 },
-    })),
-  clearClipRevealRequest: () => set({ clipRevealRequest: null }),
+  timelineFocus: null,
+  timelineFocusNonce: 0,
+  requestTimelineFocus: (id) =>
+    set((s) => {
+      const nonce = s.timelineFocusNonce + 1;
+      return {
+        timelineFocusNonce: nonce,
+        timelineFocus: createTimelineFocusRequest(
+          id,
+          s.timelineProjectId,
+          s.timelineSessionEpoch,
+          nonce,
+        ),
+      };
+    }),
+  clearTimelineFocus: (nonce) =>
+    set((s) => (s.timelineFocus?.nonce === nonce ? { timelineFocus: null } : s)),
 
   lintFindingsByElement: new Map(),
   setLintFindingsByElement: (map) => set({ lintFindingsByElement: map }),

package/src/player/store/timelineFocusState.ts

@@ -0,0 +1,15 @@
+export interface TimelineFocusRequest {
+  id: string;
+  projectId: string | null;
+  sessionEpoch: number;
+  nonce: number;
+}
+
+export function createTimelineFocusRequest(
+  id: string,
+  projectId: string | null,
+  sessionEpoch: number,
+  nonce: number,
+): TimelineFocusRequest {
+  return { id, projectId, sessionEpoch, nonce };
+}

package/src/utils/domEditSaveQueue.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { createDomEditSaveQueue } from "./domEditSaveQueue";
-import { StudioSaveHttpError } from "./studioSaveDiagnostics";
+import { StudioFileConflictError, StudioSaveHttpError } from "./studioSaveDiagnostics";
 
 describe("dom edit save queue", () => {
   afterEach(() => {
@@ -115,6 +115,23 @@ describe("dom edit save queue", () => {
     queue.destroy();
   });
 
+  it("clears a stale drain failure after a successful save", async () => {
+    const failure = new Error("temporary failure");
+    const queue = createDomEditSaveQueue();
+
+    await expect(
+      queue.enqueue(async () => {
+        throw failure;
+      }),
+    ).rejects.toBe(failure);
+    await expect(queue.waitForIdle()).resolves.toEqual({ status: "failed", error: failure });
+
+    await queue.enqueue(async () => undefined);
+
+    await expect(queue.waitForIdle()).resolves.toEqual({ status: "clean" });
+    queue.destroy();
+  });
+
   it("pauses immediately on a file conflict instead of retrying stale work", async () => {
     const onOpen = vi.fn();
     const queue = createDomEditSaveQueue({ failureThreshold: 5, onOpen });
@@ -133,4 +150,23 @@ describe("dom edit save queue", () => {
     await expect(queue.enqueue(async () => {})).rejects.toThrow("Auto-save is paused");
     queue.destroy();
   });
+
+  it("returns the original conflict from a drain instead of erasing it", async () => {
+    const conflict = new StudioFileConflictError({
+      filePath: "index.html",
+      currentVersion: "external-v2",
+      currentContent: "external",
+      attemptedContent: "studio",
+    });
+    const queue = createDomEditSaveQueue();
+
+    await expect(
+      queue.enqueue(async () => {
+        throw conflict;
+      }),
+    ).rejects.toBe(conflict);
+
+    await expect(queue.waitForIdle()).resolves.toEqual({ status: "conflict", error: conflict });
+    queue.destroy();
+  });
 });

package/src/utils/domEditSaveQueue.ts

@@ -1,4 +1,9 @@
-import { getStudioSaveErrorMessage, getStudioSaveStatusCode } from "./studioSaveDiagnostics";
+import {
+  getStudioSaveErrorMessage,
+  getStudioSaveStatusCode,
+  StudioFileConflictError,
+  type StudioSaveDrainResult,
+} from "./studioSaveDiagnostics";
 
 interface DomEditSaveQueueOpenEvent {
   consecutiveFailures: number;
@@ -14,11 +19,13 @@ interface DomEditSaveQueueOptions {
 
 export interface DomEditSaveQueue {
   enqueue: <T>(save: () => Promise<T>) => Promise<T>;
-  waitForIdle: () => Promise<void>;
+  waitForIdle: () => Promise<DomEditSaveDrainResult>;
   reset: () => void;
   destroy: () => void;
 }
 
+export type DomEditSaveDrainResult = StudioSaveDrainResult;
+
 const DEFAULT_FAILURE_THRESHOLD = 5;
 
 export class DomEditSaveQueueOpenError extends Error {
@@ -34,11 +41,13 @@ export function createDomEditSaveQueue(options: DomEditSaveQueueOptions = {}): D
   let tail = Promise.resolve();
   let consecutiveFailures = 0;
   let breakerOpen = false;
+  let drainError: unknown = null;
 
   const reset = (notify = true) => {
     const wasOpen = breakerOpen;
     consecutiveFailures = 0;
     breakerOpen = false;
+    drainError = null;
     if (notify && wasOpen) options.onReset?.();
   };
 
@@ -55,9 +64,13 @@ export function createDomEditSaveQueue(options: DomEditSaveQueueOptions = {}): D
   const run = async <T>(save: () => Promise<T>): Promise<T> => {
     try {
       const result = await save();
-      if (!breakerOpen) consecutiveFailures = 0;
+      if (!breakerOpen) {
+        consecutiveFailures = 0;
+        drainError = null;
+      }
       return result;
     } catch (error) {
+      drainError = error;
       consecutiveFailures += 1;
       if (getStudioSaveStatusCode(error) === 409 || consecutiveFailures >= failureThreshold)
         open(error);
@@ -76,8 +89,13 @@ export function createDomEditSaveQueue(options: DomEditSaveQueueOptions = {}): D
       return queued;
     },
 
-    async waitForIdle() {
+    async waitForIdle(): Promise<DomEditSaveDrainResult> {
       await tail.catch(() => undefined);
+      if (drainError instanceof StudioFileConflictError) {
+        return { status: "conflict", error: drainError };
+      }
+      if (drainError != null) return { status: "failed", error: drainError };
+      return { status: "clean" };
     },
 
     reset,

package/src/utils/externalConflictStorage.test.ts

@@ -0,0 +1,95 @@
+import { IDBFactory } from "fake-indexeddb";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  createMemoryExternalConflictStorage,
+  deleteExternalConflictSnapshot,
+  loadExternalConflictSnapshot,
+  persistExternalConflictSnapshot,
+  type ExternalConflictSnapshot,
+} from "./externalConflictStorage";
+import { StudioFileConflictError } from "./studioSaveDiagnostics";
+
+describe("external conflict snapshots", () => {
+  beforeEach(() => {
+    vi.stubGlobal("indexedDB", new IDBFactory());
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it("durably records both complete file versions before resolution", async () => {
+    const storage = createMemoryExternalConflictStorage();
+    const snapshot: ExternalConflictSnapshot = {
+      kind: "conflict",
+      projectId: "project-a",
+      filePath: "index.html",
+      externalVersion: "v2",
+      externalContent: "external full file",
+      studioContent: "studio full file",
+      createdAt: 100,
+    };
+
+    await storage.set(snapshot);
+    expect(await storage.get("project-a", "index.html")).toEqual(snapshot);
+    await storage.delete("project-a", "index.html");
+    expect(await storage.get("project-a", "index.html")).toBeNull();
+  });
+
+  it("records a failed final Studio candidate for remount recovery", async () => {
+    const storage = createMemoryExternalConflictStorage();
+    const snapshot: ExternalConflictSnapshot = {
+      kind: "failed",
+      projectId: "project-a",
+      filePath: "index.html",
+      externalVersion: null,
+      externalContent: null,
+      studioContent: "recover me",
+      failureMessage: "network unavailable",
+      createdAt: 101,
+    };
+
+    await storage.set(snapshot);
+    expect(await storage.get("project-a", "index.html")).toEqual(snapshot);
+  });
+
+  it("persists, loads, and deletes a snapshot through the production IndexedDB adapter", async () => {
+    vi.spyOn(Date, "now").mockReturnValue(1234);
+    const conflict = new StudioFileConflictError({
+      filePath: "index.html",
+      currentVersion: "v2",
+      currentContent: "external full file",
+      attemptedContent: "studio full file",
+    });
+
+    await persistExternalConflictSnapshot("indexeddb-project", conflict);
+    await expect(loadExternalConflictSnapshot("indexeddb-project", "index.html")).resolves.toEqual({
+      kind: "conflict",
+      projectId: "indexeddb-project",
+      filePath: "index.html",
+      externalVersion: "v2",
+      externalContent: "external full file",
+      studioContent: "studio full file",
+      createdAt: 1234,
+    });
+    await deleteExternalConflictSnapshot("indexeddb-project", "index.html");
+    await expect(
+      loadExternalConflictSnapshot("indexeddb-project", "index.html"),
+    ).resolves.toBeNull();
+  });
+
+  it("rejects persistence when IndexedDB is unavailable", async () => {
+    vi.stubGlobal("indexedDB", undefined);
+    const conflict = new StudioFileConflictError({
+      filePath: "index.html",
+      currentVersion: "v2",
+      currentContent: "external",
+      attemptedContent: "studio",
+    });
+
+    await expect(persistExternalConflictSnapshot("project-a", conflict)).rejects.toThrow(
+      "IndexedDB is unavailable; conflict recovery snapshot was not saved",
+    );
+  });
+});

package/src/utils/externalConflictStorage.ts

@@ -0,0 +1,172 @@
+import type { StudioFileConflictError } from "./studioSaveDiagnostics";
+
+interface ExternalRecoverySnapshotBase {
+  projectId: string;
+  filePath: string;
+  externalVersion: string | null;
+  externalContent: string | null;
+  studioContent: string;
+  createdAt: number;
+}
+
+export type ExternalConflictSnapshot =
+  | (ExternalRecoverySnapshotBase & { kind: "conflict" })
+  | (ExternalRecoverySnapshotBase & { kind: "failed"; failureMessage: string });
+
+export interface ExternalConflictStorage {
+  get(projectId: string, filePath: string): Promise<ExternalConflictSnapshot | null>;
+  set(snapshot: ExternalConflictSnapshot): Promise<void>;
+  delete(projectId: string, filePath: string): Promise<void>;
+}
+
+const DB_NAME = "hyperframes-studio-external-conflicts";
+const DB_VERSION = 1;
+const STORE_NAME = "file-conflicts";
+
+function key(projectId: string, filePath: string): string {
+  return `${projectId}\0${filePath}`;
+}
+
+export function createMemoryExternalConflictStorage(): ExternalConflictStorage {
+  const snapshots = new Map<string, ExternalConflictSnapshot>();
+  return {
+    async get(projectId, filePath) {
+      const snapshot = snapshots.get(key(projectId, filePath));
+      return snapshot ? structuredClone(snapshot) : null;
+    },
+    async set(snapshot) {
+      snapshots.set(key(snapshot.projectId, snapshot.filePath), structuredClone(snapshot));
+    },
+    async delete(projectId, filePath) {
+      snapshots.delete(key(projectId, filePath));
+    },
+  };
+}
+
+function openDb(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    if (!globalThis.indexedDB) {
+      reject(new Error("IndexedDB is unavailable; conflict recovery snapshot was not saved"));
+      return;
+    }
+    const request = globalThis.indexedDB.open(DB_NAME, DB_VERSION);
+    request.onupgradeneeded = () => {
+      if (!request.result.objectStoreNames.contains(STORE_NAME)) {
+        request.result.createObjectStore(STORE_NAME);
+      }
+    };
+    request.onerror = () => reject(request.error ?? new Error("Failed to open conflict storage"));
+    request.onsuccess = () => resolve(request.result);
+  });
+}
+
+function withStore<T>(
+  mode: IDBTransactionMode,
+  callback: (store: IDBObjectStore) => IDBRequest<T>,
+): Promise<T> {
+  return openDb().then(
+    (db) =>
+      new Promise<T>((resolve, reject) => {
+        const transaction = db.transaction(STORE_NAME, mode);
+        const request = callback(transaction.objectStore(STORE_NAME));
+        let result!: T;
+        request.onerror = () => reject(request.error ?? new Error("Conflict storage failed"));
+        request.onsuccess = () => {
+          result = request.result;
+        };
+        transaction.oncomplete = () => {
+          db.close();
+          resolve(result);
+        };
+        transaction.onerror = () => {
+          db.close();
+          reject(transaction.error ?? new Error("Conflict storage transaction failed"));
+        };
+        transaction.onabort = () => {
+          db.close();
+          reject(transaction.error ?? new Error("Conflict storage transaction was aborted"));
+        };
+      }),
+  );
+}
+
+function createIndexedDbExternalConflictStorage(): ExternalConflictStorage {
+  return {
+    async get(projectId, filePath) {
+      return (
+        (await withStore<ExternalConflictSnapshot | undefined>("readonly", (store) =>
+          store.get(key(projectId, filePath)),
+        )) ?? null
+      );
+    },
+    async set(snapshot) {
+      await withStore<IDBValidKey>("readwrite", (store) =>
+        store.put(snapshot, key(snapshot.projectId, snapshot.filePath)),
+      );
+    },
+    async delete(projectId, filePath) {
+      await withStore<undefined>("readwrite", (store) => store.delete(key(projectId, filePath)));
+    },
+  };
+}
+
+const indexedDbStorage = createIndexedDbExternalConflictStorage();
+
+/**
+ * Persist a conflict before offering destructive recovery actions.
+ * Callers must await this promise: rejection means the Studio draft was not saved durably and
+ * must remain available in memory while the storage failure is surfaced to the user.
+ */
+export async function persistExternalConflictSnapshot(
+  projectId: string,
+  conflict: StudioFileConflictError,
+): Promise<void> {
+  await indexedDbStorage.set({
+    kind: "conflict",
+    projectId,
+    filePath: conflict.filePath,
+    externalVersion: conflict.currentVersion,
+    externalContent: conflict.currentContent,
+    studioContent: conflict.attemptedContent,
+    createdAt: Date.now(),
+  });
+}
+
+/**
+ * Persist the final Studio candidate after its file write fails.
+ * Callers must await this promise: rejection means the Studio draft was not saved durably and
+ * must remain available in memory while the storage failure is surfaced to the user.
+ */
+export async function persistExternalFailureSnapshot(
+  projectId: string,
+  filePath: string,
+  studioContent: string,
+  externalVersion: string | null,
+  externalContent: string | null,
+  error: unknown,
+): Promise<void> {
+  await indexedDbStorage.set({
+    kind: "failed",
+    projectId,
+    filePath,
+    externalVersion,
+    externalContent,
+    studioContent,
+    failureMessage: error instanceof Error ? error.message : String(error),
+    createdAt: Date.now(),
+  });
+}
+
+export async function loadExternalConflictSnapshot(
+  projectId: string,
+  filePath: string,
+): Promise<ExternalConflictSnapshot | null> {
+  return indexedDbStorage.get(projectId, filePath);
+}
+
+export async function deleteExternalConflictSnapshot(
+  projectId: string,
+  filePath: string,
+): Promise<void> {
+  await indexedDbStorage.delete(projectId, filePath);
+}