@hyperframes/studio 0.7.90 → 0.7.93

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);
+}

package/src/utils/studioFileVersion.test.ts

@@ -1,5 +1,11 @@
 import { describe, expect, it } from "vitest";
-import { studioExpectedFileVersion, studioFileContentVersion } from "./studioFileVersion";
+import {
+  consumeStudioWriteToken,
+  markStudioWriteToken,
+  resetStudioWriteTokens,
+  studioExpectedFileVersion,
+  studioFileContentVersion,
+} from "./studioFileVersion";
 
 describe("studioFileContentVersion", () => {
   it("matches the strong SHA-256 ETag format used by studio-server", async () => {
@@ -34,3 +40,24 @@ describe("studioFileContentVersion", () => {
     expect(await studioExpectedFileVersion(versions, "untracked.html")).toBeUndefined();
   });
 });
+
+describe("studio write-token echo identity", () => {
+  it("suppresses exactly one matching API write receipt without hiding path-only external writes", () => {
+    resetStudioWriteTokens();
+    markStudioWriteToken("studio-write-1");
+
+    expect(consumeStudioWriteToken("studio-write-1")).toBe(true);
+    expect(consumeStudioWriteToken("studio-write-1")).toBe(false);
+    expect(consumeStudioWriteToken(null)).toBe(false);
+  });
+
+  it("keeps a token through a slow write and expires abandoned identity state", () => {
+    resetStudioWriteTokens();
+    markStudioWriteToken("slow-studio-write", 1_000);
+
+    expect(consumeStudioWriteToken("slow-studio-write", 61_000)).toBe(true);
+
+    markStudioWriteToken("abandoned-studio-write", 1_000);
+    expect(consumeStudioWriteToken("abandoned-studio-write", 301_000)).toBe(false);
+  });
+});

package/src/utils/studioFileVersion.ts

@@ -1,3 +1,33 @@
+// A token is marked before the request starts, so its lifetime must cover slow writes,
+// retries, and the subsequent file-change echo without retaining abandoned tokens forever.
+const WRITE_TOKEN_TTL_MS = 5 * 60_000;
+const studioWriteTokens = new Map<string, number>();
+
+function pruneStudioWriteTokens(now: number): void {
+  for (const [token, createdAt] of studioWriteTokens) {
+    if (now - createdAt >= WRITE_TOKEN_TTL_MS) studioWriteTokens.delete(token);
+  }
+}
+
+/** Marked by the Studio file writer introduced in external-change stack PR #2990. */
+export function markStudioWriteToken(token: string, now: number = Date.now()): void {
+  pruneStudioWriteTokens(now);
+  studioWriteTokens.set(token, now);
+}
+
+/** Consumed by the external-change coordinator introduced in stack PR #2991. */
+export function consumeStudioWriteToken(token: string | null, now: number = Date.now()): boolean {
+  pruneStudioWriteTokens(now);
+  if (!token || !studioWriteTokens.has(token)) return false;
+  studioWriteTokens.delete(token);
+  return true;
+}
+
+/** Resets module-level echo identity between PR #2991 coordinator tests. */
+export function resetStudioWriteTokens(): void {
+  studioWriteTokens.clear();
+}
+
 /** Browser-safe SHA-256 version matching studio-server's strong ETag format. */
 export async function studioFileContentVersion(content: string): Promise<string> {
   const bytes = new TextEncoder().encode(content);

package/src/utils/studioPendingEdits.test.ts

@@ -5,6 +5,7 @@ import {
   flushStudioPendingEdits,
   trackStudioPendingEdit,
 } from "./studioPendingEdits";
+import { StudioFileConflictError } from "./studioSaveDiagnostics";
 
 describe("studio pending edit flush", () => {
   it("waits for mounted panels to persist pending local edits", async () => {
@@ -12,13 +13,119 @@ describe("studio pending edit flush", () => {
     const remove = addStudioPendingEditFlushListener(persist);
 
     try {
-      await flushStudioPendingEdits();
+      await expect(flushStudioPendingEdits()).resolves.toEqual({ status: "clean" });
       expect(persist).toHaveBeenCalledTimes(1);
     } finally {
       remove();
     }
   });
 
+  it("commits the focused debounced field before draining pending work", async () => {
+    const input = document.createElement("textarea");
+    document.body.append(input);
+    const persist = vi.fn(async () => undefined);
+    input.addEventListener("blur", () => {
+      trackStudioPendingEdit(persist());
+    });
+    input.focus();
+
+    await expect(flushStudioPendingEdits()).resolves.toEqual({ status: "clean" });
+
+    expect(document.activeElement).not.toBe(input);
+    expect(persist).toHaveBeenCalledOnce();
+    input.remove();
+  });
+
+  it("waits for a post-blur effect to register its pending edit listener", async () => {
+    const input = document.createElement("textarea");
+    document.body.append(input);
+    const persist = vi.fn(async () => undefined);
+    let removeListener: (() => void) | undefined;
+    let registrationDone: Promise<void> | undefined;
+    input.addEventListener("blur", () => {
+      registrationDone = new Promise<void>((resolve) => {
+        setTimeout(() => {
+          removeListener = addStudioPendingEditFlushListener(persist);
+          resolve();
+        }, 0);
+      });
+    });
+    input.focus();
+
+    try {
+      await expect(flushStudioPendingEdits()).resolves.toEqual({ status: "clean" });
+
+      expect(persist).toHaveBeenCalledOnce();
+    } finally {
+      await registrationDone;
+      removeListener?.();
+      input.remove();
+    }
+  });
+
+  it("preserves a pending edit failure instead of reporting a clean drain", async () => {
+    const failure = new Error("field save failed");
+    const remove = addStudioPendingEditFlushListener(async () => {
+      throw failure;
+    });
+
+    try {
+      await expect(flushStudioPendingEdits()).resolves.toEqual({
+        status: "failed",
+        error: failure,
+      });
+    } finally {
+      remove();
+    }
+  });
+
+  it("keeps the full typed conflict payload for the external-change decision", async () => {
+    const conflict = new StudioFileConflictError({
+      filePath: "index.html",
+      currentVersion: "v2",
+      currentContent: "external",
+      attemptedContent: "studio",
+    });
+    const remove = addStudioPendingEditFlushListener(async () => {
+      throw conflict;
+    });
+
+    try {
+      await expect(flushStudioPendingEdits()).resolves.toEqual({
+        status: "conflict",
+        error: conflict,
+      });
+    } finally {
+      remove();
+    }
+  });
+
+  it("prioritizes a conflict when pending edits fail with mixed errors", async () => {
+    const failure = new Error("field save failed");
+    const conflict = new StudioFileConflictError({
+      filePath: "index.html",
+      currentVersion: "v2",
+      currentContent: "external",
+      attemptedContent: "studio",
+    });
+    const removeFailure = addStudioPendingEditFlushListener(async () => {
+      throw failure;
+    });
+    const removeConflict = addStudioPendingEditFlushListener(async () => {
+      throw conflict;
+    });
+
+    try {
+      await expect(flushStudioPendingEdits()).resolves.toEqual({
+        status: "conflict",
+        error: conflict,
+      });
+    } finally {
+      removeFailure();
+      removeConflict();
+    }
+  });
+
   it("waits for edits already started by unmounted panels", async () => {
     const steps: string[] = [];
     let resolvePersist!: () => void;

package/src/utils/studioPendingEdits.ts

@@ -1,11 +1,32 @@
+import { StudioFileConflictError, type StudioSaveDrainResult } from "./studioSaveDiagnostics";
+
 const STUDIO_FLUSH_PENDING_EDITS_EVENT = "hf-studio-flush-pending-edits";
 
 interface StudioFlushPendingEditsDetail {
   promises: Array<Promise<unknown>>;
 }
 
+export type StudioPendingEditsDrainResult = StudioSaveDrainResult;
+
 const pendingEditPromises = new Set<Promise<unknown>>();
 
+function waitForPostBlurEffects(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+function inspectDrainFailures(results: PromiseSettledResult<unknown>[]): {
+  conflict?: StudioFileConflictError;
+  firstFailure?: PromiseRejectedResult;
+} {
+  let firstFailure: PromiseRejectedResult | undefined;
+  for (const result of results) {
+    if (result.status !== "rejected") continue;
+    if (result.reason instanceof StudioFileConflictError) return { conflict: result.reason };
+    firstFailure ??= result;
+  }
+  return { firstFailure };
+}
+
 export function trackStudioPendingEdit(
   result: Promise<unknown> | unknown,
 ): Promise<unknown> | undefined {
@@ -19,16 +40,32 @@ export function trackStudioPendingEdit(
   return promise;
 }
 
-export async function flushStudioPendingEdits(): Promise<void> {
+export async function flushStudioPendingEdits(): Promise<StudioPendingEditsDrainResult> {
+  const active = document.activeElement;
+  if (
+    active instanceof HTMLElement &&
+    active.matches('input, textarea, select, [contenteditable="true"], [role="textbox"]')
+  ) {
+    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.
+    await Promise.resolve();
+    await waitForPostBlurEffects();
+  }
   const detail: StudioFlushPendingEditsDetail = { promises: [] };
   window.dispatchEvent(
     new CustomEvent<StudioFlushPendingEditsDetail>(STUDIO_FLUSH_PENDING_EDITS_EVENT, { detail }),
   );
+  let firstFailure: PromiseRejectedResult | undefined;
   while (detail.promises.length > 0 || pendingEditPromises.size > 0) {
     const promises = [...detail.promises, ...pendingEditPromises];
     detail.promises = [];
-    await Promise.allSettled(promises);
+    const results = await Promise.allSettled(promises);
+    const batchFailures = inspectDrainFailures(results);
+    if (batchFailures.conflict) return { status: "conflict", error: batchFailures.conflict };
+    firstFailure ??= batchFailures.firstFailure;
   }
+  return firstFailure ? { status: "failed", error: firstFailure.reason } : { status: "clean" };
 }
 
 export function addStudioPendingEditFlushListener(

package/src/utils/studioSaveDiagnostics.ts

@@ -56,6 +56,11 @@ export class StudioFileConflictError extends StudioSaveHttpError {
   }
 }
 
+export type StudioSaveDrainResult<Failure = unknown> =
+  | { status: "clean" }
+  | { status: "conflict"; error: StudioFileConflictError }
+  | { status: "failed"; error: Failure };
+
 function readNumericProperty(value: object, key: string): number | undefined {
   const record = value as Record<string, unknown>;
   const property = record[key];