fix(frontend): stop WebKit storage and engine failures from hanging the app

Follow-up to #7314. That PR fixed the IndexedDB blob rejection itself; this
one fixes the ways the same failures surfaced as a permanent spinner, and adds
the cross-browser CI signal that would have caught them on the pull request
instead of six weeks later in a nightly run.

Storage no longer hangs:
- Blocked IndexedDB opens and deletes now time out with an actionable error
  instead of never settling, and the app sets `onversionchange` so an open tab
  yields its connection rather than blocking every other tab forever.
- The in-flight open promise is registered before the first await, so
  concurrent boot-time callers share one connection. Only the first request
  receives `blocked`; the others were getting no events at all.
- Transactions settle on abort. Read-modify-write moves to a single
  `updateRecord` helper that owns its transaction, guards it once, and resolves
  on commit - the previous two-promises-over-one-transaction shape left the
  write with no abort handler, which could hang output persistence silently.
- The blob-value refusal is remembered from any write, not just the initial
  add: WebKit reports it per-operation, so an engine that accepted the add can
  still refuse the rewrite.

WebKit engine gaps:
- ReadableStream async iteration, which pdf.js uses for all text extraction.
  Without it Compare, read-aloud and the text editor were dead on Safari.
- requestIdleCallback, installed once at the entry point instead of guarded at
  each call site.
- convertToBlob silently returns PNG for a format it can't encode, so canvas
  output now probes what the engine really produced and picks the best lossy
  format it honours.

CI:
- A small @engine-capability suite runs on Chromium, Firefox and WebKit on
  every pull request. It asserts the primitives actually work (a counted
  comparison, a raster thumbnail, a byte round-trip through a reload) rather
  than that the UI rendered, which is how two total WebKit outages passed.
- The cross-browser projects now share the stubbed project's viewport so a
  layout difference can't read as an engine outage.

Author: EthanHealy01

.github/workflows/e2e-stubbed.yml

@@ -3,6 +3,9 @@ name: Playwright E2E (stubbed)
 # Reusable workflow called from build.yml. Backend-free Playwright suite —
 # fast, no Spring Boot required. Runs against the `stubbed` project which
 # mocks API responses in the browser.
+#
+# Chromium-only for speed, except the `@engine-capability` specs, which run on
+# all three engines here - nightly-only let two WebKit outages sit on main.
 on:
   workflow_call:
 
@@ -27,13 +30,29 @@ jobs:
           cache-dependency-path: frontend/package-lock.json
       - name: Install Task
         uses: go-task/setup-task@01a4adf9db2d14c1de7a560f09170b6e0df736aa # v2.1.0
-      - name: Install Playwright (chromium only)
-        run: task e2e:install -- chromium
+      - name: Install Playwright (chromium, firefox, webkit)
+        run: task e2e:install -- chromium firefox webkit
       - name: Build frontend (production bundle for vite preview)
         env:
           VITE_BUILD_FOR_PREVIEW: "1"
         run: task frontend:build
+      - name: Run engine-capability smoke tests (chromium, firefox, webkit)
+        # First, so "this engine can't read a PDF" lands at the top of the log.
+        # Own JSON path: the Chromium run below would overwrite it.
+        env:
+          PLAYWRIGHT_JSON_OUTPUT_FILE: ${{ github.workspace }}/frontend/playwright-report/capability-results.json
+        run: task e2e:capabilities
+      - name: Upload engine-capability Playwright report
+        # Uploaded here because the Chromium run below writes the same directory.
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: playwright-report-capabilities-${{ github.run_id }}
+          path: frontend/playwright-report/
+          retention-days: 7
       - name: Run stubbed E2E tests (chromium)
+        # Runs even if the smoke tests failed, so a PR gets both signals at once.
+        if: ${{ !cancelled() }}
         env:
           PLAYWRIGHT_JSON_OUTPUT_FILE: ${{ github.workspace }}/frontend/playwright-report/results.json
         run: task e2e:stubbed -- --workers=3
@@ -43,9 +62,10 @@ jobs:
         # ::warning:: annotations + a job summary; never fails the job.
         if: always()
         working-directory: frontend
-        run: npx tsx editor/scripts/report-flaky-tests.mts "$PLAYWRIGHT_JSON_OUTPUT_FILE"
-        env:
-          PLAYWRIGHT_JSON_OUTPUT_FILE: ${{ github.workspace }}/frontend/playwright-report/results.json
+        run: >-
+          npx tsx editor/scripts/report-flaky-tests.mts
+          "${{ github.workspace }}/frontend/playwright-report/results.json"
+          "${{ github.workspace }}/frontend/playwright-report/capability-results.json"
       - name: Upload Playwright report
         if: always()
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1

.taskfiles/e2e.yml

@@ -15,6 +15,24 @@ tasks:
     cmds:
       - npx playwright test --project=stubbed {{.CLI_ARGS}}
 
+  capabilities:
+    desc: "Run the engine-capability smoke tests on Chromium, Firefox, and WebKit"
+    summary: |
+      Asserts the PDF engine primitives actually work on each engine - text
+      extraction, page rasterisation, and an IndexedDB byte round-trip - rather
+      than that the UI rendered. Small enough to run on every browser on every
+      pull request, which is the point.
+
+      Pass extra Playwright flags via -- :
+        task e2e:capabilities -- --headed
+    dir: frontend/editor
+    deps: [ ':frontend:prepare' ]
+    cmds:
+      - >-
+        npx playwright test
+        --project=stubbed --project=stubbed-firefox --project=stubbed-webkit
+        --grep @engine-capability {{.CLI_ARGS}}
+
   live:
     desc: "Run live E2E tests"
     summary: |

frontend/editor/playwright.config.ts

@@ -17,9 +17,12 @@ import { defineConfig, devices } from "@playwright/test";
  *
  * @see https://playwright.dev/docs/test-configuration
  */
+/** Shared by every stubbed project so a spec sees one layout on all engines. */
+const STUBBED_VIEWPORT = { width: 1920, height: 1080 };
+
 const chromiumViewport = {
   ...devices["Desktop Chrome"],
-  viewport: { width: 1920, height: 1080 },
+  viewport: STUBBED_VIEWPORT,
 };
 
 export default defineConfig({
@@ -93,16 +96,17 @@ export default defineConfig({
       },
     },
 
-    // Cross-browser coverage for the stubbed suite (opt-in locally)
+    // Cross-browser coverage for the stubbed suite. Same viewport as `stubbed`,
+    // or a layout difference here reads as an engine outage.
     {
       name: "stubbed-firefox",
       testDir: "./src/core/tests/stubbed",
-      use: { ...devices["Desktop Firefox"] },
+      use: { ...devices["Desktop Firefox"], viewport: STUBBED_VIEWPORT },
     },
     {
       name: "stubbed-webkit",
       testDir: "./src/core/tests/stubbed",
-      use: { ...devices["Desktop Safari"] },
+      use: { ...devices["Desktop Safari"], viewport: STUBBED_VIEWPORT },
     },
   ],
 

frontend/editor/src/core/components/shared/FileSelectorPicker.tsx

@@ -201,13 +201,27 @@ export function FileSelectorPicker({
     setSortDir(lsGet(LS_SORT_DIR, "desc", ["asc", "desc"]));
   }, [isOpen]);
 
-  // Load saved files when the saved tab is active and the picker is open
+  // Load saved files when the saved tab is active and the picker is open.
+  // Cancellable: storage reads can be slow or reject, and outlive the popover.
   useEffect(() => {
     if (activeTab !== "saved" || !isOpen) return;
+    let cancelled = false;
     setSavedLoading(true);
     loadRecentFiles()
-      .then(setSavedStubs)
-      .finally(() => setSavedLoading(false));
+      .then((stubs) => {
+        if (!cancelled) setSavedStubs(stubs);
+      })
+      .catch((error: unknown) => {
+        if (!cancelled) setSavedStubs([]);
+        console.warn("Failed to load saved files for the picker:", error);
+      })
+      .finally(() => {
+        if (!cancelled) setSavedLoading(false);
+      });
+    return () => {
+      cancelled = true;
+      setSavedLoading(false);
+    };
   }, [activeTab, isOpen, loadRecentFiles]);
 
   const workbenchIdSet = useMemo(
@@ -541,7 +555,9 @@ export function FileSelectorPicker({
           </div>
 
           <ScrollArea h={260} className={styles.list}>
-            {savedLoading ? (
+            {/* Workbench renders from memory, so a stuck storage read must not
+                spin it too. */}
+            {savedLoading && activeTab === "saved" ? (
               <div className={styles.emptyState}>
                 <Loader size="sm" />
               </div>

frontend/editor/src/core/components/shared/FileSidebar.tsx

@@ -306,32 +306,45 @@ const FileSidebar = forwardRef<HTMLDivElement, FileSidebarProps>(
     const storageEnabled = config?.storageEnabled === true && !isAnonymous;
 
     const refreshStubs = useCallback(async () => {
-      // Leaf files from IDB - same source as the file selection modal.
-      const stubs = await indexedDB.loadLeafMetadata();
-      const idbIds = new Set(stubs.map((s) => s.id as string));
-
-      // Also include workbench files not yet flushed to IDB.
-      const pendingStubs = state.files.ids
-        .map((id) => state.files.byId[id])
-        .filter(
-          (stub): stub is NonNullable<typeof stub> =>
-            !!stub && stub.isLeaf !== false && !idbIds.has(stub.id as string),
-        );
+      // `stubsLoaded` gates the spinner, so the `finally` below must set it on
+      // every path - callers never await this, so a rejection goes nowhere.
+      let stubs: StirlingFileStub[] = [];
+      try {
+        // Leaf files from IDB - same source as the file selection modal.
+        stubs = await indexedDB.loadLeafMetadata();
+      } catch (error) {
+        // Carry on with the in-memory workbench files: an unreadable library
+        // should cost the user their history, not the file they're working on.
+        console.error("Failed to read the file library from storage:", error);
+      }
 
-      const allStubs = [...stubs, ...pendingStubs];
-      // A version swap briefly lists both the old leaf (IDB) and its replacement (workbench); two stubs for one lineage collide on the row key and corrupt React reconciliation, so drop any stub another names as its parent.
-      const superseded = new Set(
-        allStubs.map((s) => s.parentFileId as string | undefined),
-      );
-      const currentStubs = allStubs.filter(
-        (s) => !superseded.has(s.id as string),
-      );
-      setAllFileStubs(
-        currentStubs.sort(
-          (a, b) => (b.lastModified ?? 0) - (a.lastModified ?? 0),
-        ),
-      );
-      setStubsLoaded(true);
+      try {
+        const idbIds = new Set(stubs.map((s) => s.id as string));
+
+        // Also include workbench files not yet flushed to IDB.
+        const pendingStubs = state.files.ids
+          .map((id) => state.files.byId[id])
+          .filter(
+            (stub): stub is NonNullable<typeof stub> =>
+              !!stub && stub.isLeaf !== false && !idbIds.has(stub.id as string),
+          );
+
+        const allStubs = [...stubs, ...pendingStubs];
+        // A version swap briefly lists both the old leaf (IDB) and its replacement (workbench); two stubs for one lineage collide on the row key and corrupt React reconciliation, so drop any stub another names as its parent.
+        const superseded = new Set(
+          allStubs.map((s) => s.parentFileId as string | undefined),
+        );
+        const currentStubs = allStubs.filter(
+          (s) => !superseded.has(s.id as string),
+        );
+        setAllFileStubs(
+          currentStubs.sort(
+            (a, b) => (b.lastModified ?? 0) - (a.lastModified ?? 0),
+          ),
+        );
+      } finally {
+        setStubsLoaded(true);
+      }
     }, [indexedDB, state.files.ids, state.files.byId]);
 
     // Refresh on mount, workbench changes, or external IndexedDB writes —

frontend/editor/src/core/services/fileStorage.blobFallback.test.ts

@@ -3,22 +3,17 @@ import "fake-indexeddb/auto";
 import { expectConsole } from "@app/tests/failOnConsole";
 
 /**
- * Regression test for the WebKit nightly breakage introduced with the
- * large-file OOM fix (#7175): `storeStirlingFile` began putting the `File`
- * itself into IndexedDB (persisted by reference, so multi-GB uploads never
- * materialize in JS memory). WebKit refuses blob values whenever it can't write
- * the blob's backing file and rejects the request with `UnknownError: Error
- * preparing Blob/File data to be stored in object store`, so on WebKit every
- * upload silently failed to persist: files vanished on navigation, Compare
- * slots never filled, and the classification backfill had no bytes to read.
+ * WebKit refuses blob values when it can't write the blob's backing file, so
+ * every upload silently failed to persist after #7175. Retried as a copy now.
  *
- * The service now retries such a rejection with an ArrayBuffer copy and stops
- * offering blobs for the rest of the session.
+ * fake-indexeddb never returns a Blob from a read, so round-trips can't be
+ * modelled here - `engine-capabilities.spec.ts` covers those on a real engine.
  */
 
 const nativeAdd = IDBObjectStore.prototype.add;
+const nativePut = IDBObjectStore.prototype.put;
 
-/** What each `add` attempt carried in `data` — the blob path or the copy path. */
+/** What each `add` attempt carried in `data`: blob path or copy path. */
 let attempts: Array<"blob" | "copy"> = [];
 
 /** An IDBRequest that fails asynchronously, the way WebKit rejects blob puts. */
@@ -32,10 +27,7 @@ class FailingRequest extends EventTarget {
   }
 }
 
-/**
- * Record every add attempt, optionally failing the blob-valued ones the way an
- * engine without blob storage does.
- */
+/** Record every add, optionally failing the blob-valued ones. */
 function instrumentAdd(options: { rejectBlobs: boolean }) {
   IDBObjectStore.prototype.add = function (
     this: IDBObjectStore,
@@ -58,11 +50,8 @@ function instrumentAdd(options: { rejectBlobs: boolean }) {
   } as typeof IDBObjectStore.prototype.add;
 }
 
-/**
- * A fresh service per test: whether the engine accepts blobs is remembered for
- * the process lifetime by design, so tests must not inherit that decision from
- * each other.
- */
+/** A fresh service per test: the blob decision is remembered by design, so
+ *  tests must not inherit it from each other. */
 async function freshFileStorage() {
   vi.resetModules();
   const [{ fileStorage }, { createStirlingFile, createNewStirlingFileStub }] =
@@ -90,6 +79,49 @@ beforeEach(() => {
 
 afterEach(() => {
   IDBObjectStore.prototype.add = nativeAdd;
+  IDBObjectStore.prototype.put = nativePut;
+});
+
+/** Abort the transaction the moment a write is issued over it. */
+function abortOnPut() {
+  IDBObjectStore.prototype.put = function (this: IDBObjectStore) {
+    const request = new FailingRequest(
+      new DOMException("transaction aborted", "AbortError"),
+    ) as unknown as IDBRequest<IDBValidKey>;
+    this.transaction.abort();
+    return request;
+  } as typeof IDBObjectStore.prototype.put;
+}
+
+describe("read-modify-write — a refused rewrite must not hang or vanish", () => {
+  /** The abort guard used to sit on the read promise, leaving the write with a
+   *  dead reject - and `.catch` can't rescue a promise that never settles. */
+  test("settles instead of hanging when the write transaction aborts", async () => {
+    expectConsole.error(/Failed to mark file as processed/);
+    const { fileStorage, store } = await freshFileStorage();
+    instrumentAdd({ rejectBlobs: false });
+    const id = await store("aborts.pdf");
+
+    abortOnPut();
+
+    // Before the fix this never settled and the test timed out.
+    await expect(fileStorage.markFileAsProcessed(id)).resolves.toBe(false);
+  });
+
+  /** The copy-and-retry recovery can't be exercised here: it needs a record that
+   *  reads back as a Blob, which fake-indexeddb never returns. */
+  test("a metadata rewrite still commits, and reports commit not put", async () => {
+    const { fileStorage, store } = await freshFileStorage();
+    instrumentAdd({ rejectBlobs: false });
+    const id = await store("rewrite.pdf");
+
+    await expect(fileStorage.markFileAsProcessed(id)).resolves.toBe(true);
+    // Missing record: `false`, not a throw and not a claim of success.
+    await expect(
+      fileStorage.markFileAsProcessed("nope" as never),
+    ).resolves.toBe(false);
+    expect((await fileStorage.getStirlingFile(id))?.name).toBe("rewrite.pdf");
+  });
 });
 
 describe("storeStirlingFile — blob-value fallback", () => {
@@ -113,8 +145,7 @@ describe("storeStirlingFile — blob-value fallback", () => {
     const id = await store("webkit.pdf");
 
     expect(attempts).toEqual(["blob", "copy"]);
-    // Readable back is what every downstream consumer depends on: rehydration
-    // after navigation, thumbnails, the classification backfill.
+    // Readable back is what rehydration, thumbnails and backfill depend on.
     expect((await fileStorage.getStirlingFile(id))?.name).toBe("webkit.pdf");
   });
 
@@ -127,8 +158,7 @@ describe("storeStirlingFile — blob-value fallback", () => {
     attempts = [];
     const id = await store("second.pdf");
 
-    // Straight to the copy path — no repeated blob probe, and only the single
-    // warning expected above.
+    // Straight to the copy path, and only the one warning expected above.
     expect(attempts).toEqual(["copy"]);
     expect((await fileStorage.getStirlingFile(id))?.name).toBe("second.pdf");
   });