# Autopsy #12: Moving the Entire App Engine Off the Main Thread

- **Canonical URL:** https://frontend.rocks/autopsies/zero-main-thread-ui-worker/
- **Case:** #12
- **Failure Mode:** Main-Thread Freeze
- **Production Symptom:** Rich spreadsheet and graph app drops to 4 FPS during 100k-row sorts until state and OPFS move to a Worker.
- **Last Verified:** 2026-11-16

## Causal Chain
1. [Dedicated Web Workers and Transferables](https://frontend.rocks/concepts/dedicated-web-workers.md): Relocates the 100k-row store and sort engine out of the main-thread event loop.
2. [TypedArrays, ArrayBuffer, and Zero-Copy Transfers](https://frontend.rocks/concepts/typed-arrays-zero-copy.md): Transfers sorted row index buffers via ArrayBuffer transferables with zero structured-clone copy.
3. [Origin Private File System (OPFS)](https://frontend.rocks/concepts/opfs-origin-private-fs.md): Persists binary snapshots synchronously in the worker via FileSystemSyncAccessHandle.
4. [WebAssembly Linear Memory & JS Boundary Crossing Cost](https://frontend.rocks/concepts/wasm-js-boundary-overhead.md): Batches 100k-row numeric sorts inside Wasm linear memory to avoid per-row JS boundary crossings.
5. [Actor-over-Worker Architecture (Off-Main-Thread UI)](https://frontend.rocks/concepts/actor-over-worker-architecture.md): Decouples UI rendering from engine state via typed message-passing actor mailboxes.

## Primary Sources
- https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers
- https://developer.mozilla.org/en-US/docs/Web/API/FileSystemSyncAccessHandle
- https://webassembly.org/docs/high-level-goals/

---
## Incident Report

A client-side table PR enabled multi-column sorting and automatic snapshot persistence for a collaborative spreadsheet and dependency-graph editor. On 200-row fixtures in CI, sorts finished in 2 ms.

- **T+00:00**: Enterprise customers opened 100,000-row production workbooks after the release.
- **T+03:00**: Long Task observers recorded 620 ms main-thread stalls per column click, dropping scroll input and collapsing frame rates to 4 FPS.
- **T+08:00**: Each sort ran `Array.prototype.sort` over 100,000 JS objects followed by `JSON.stringify(rows)` and an IndexedDB `put()`, allocating 90 MB of transient strings.
- **T+12:00**: V8 major garbage collection pauses hit 140 ms every time a user toggled a sort direction.

## The Red Herring

In `#perf-ui`, the first patch wrapped the sort loop in `requestIdleCallback` and chunked rows into 5,000-item slices. Local synthetic benchmarks showed shorter individual task bars.

In production, it failed across three dimensions:

- **Shared heap contention remained**: Chunked JS objects still lived on the main-thread V8 isolate, triggering GC pauses during `requestAnimationFrame`.
- **Persistence still blocked**: `JSON.stringify` and IndexedDB structured cloning executed on the same event loop and contended with input tasks.
- **Inconsistent intermediate state**: Yielding mid-sort exposed half-sorted row arrays to concurrent graph-layout reads.

## Causal Chain

Five execution boundaries fail when heavy data processing shares the UI thread:

- **Main-thread compute**: 100k-row sorts and GC pauses starve Blink's 16.6 ms frame budget.
- **Structured-clone copy tax**: Posting plain JS object arrays across `postMessage` stalls both threads.
- **Async JSON storage**: `JSON.stringify` and IndexedDB transactions contend with UI mutations.
- **Wasm boundary thrashing & coupled state**: Per-row JS-to-Wasm calls and shared mutable stores block clean actor isolation.

## Failure Simulator

Compare the main-thread 4 FPS sort and JSON persistence path against the Worker Actor + Wasm linear memory + OPFS `createSyncAccessHandle()` architecture below.

## Layer Dissection

### 01 → 02: Worker Offloading Requires Zero-Copy Transfers

Relocating the data engine into [Dedicated Web Workers and Transferables](/concepts/dedicated-web-workers) removes the 420 ms sort from the main-thread event loop. However, posting a 100,000-element JS object array back to the UI thread still blocks both threads during a 180 ms `structuredClone` pass:

- **Structured clone**: Copies every object property across thread heaps, stalling both isolates.
- **Zero-copy transfer**: Transfers ownership of a 400 KB `Uint32Array` buffer via [TypedArrays, ArrayBuffer, and Zero-Copy Transfers](/concepts/typed-arrays-zero-copy) in under 0.1 ms.

### 02 → 03: Zero-Copy Buffers Eliminate JSON Serialization via OPFS

With row data stored in compact binary `TypedArray` columns inside the worker, `JSON.stringify` and IndexedDB become unnecessary. Using [Origin Private File System (OPFS)](/concepts/opfs-origin-private-fs), the worker opens a `FileSystemSyncAccessHandle` via `handle.createSyncAccessHandle()`:

- **Main-thread JSON**: Serializes 90 MB of strings and blocks the event loop.
- **Worker `syncHandle.write()`**: Flushes the binary snapshot synchronously inside the worker thread.

### 03 → 04: Binary Columns Feed Batched Wasm Sorts

Sorting 100,000 elements by invoking a Wasm comparator from JS on every comparison pays [WebAssembly Linear Memory & JS Boundary Crossing Cost](/concepts/wasm-js-boundary-overhead) roughly 1.7 million times per sort:

- **Per-row JS comparator**: Crosses the JS-to-Wasm trampoline $O(n \log n)$ times, negating native speed.
- **Batched linear sort**: Writes column values into Wasm linear memory once and invokes `sortColumnInPlace(colIndex)` in 11 ms.

### 04 → 05: Wasm Engine Wraps in an Actor-Over-Worker Mailbox

To decouple React rendering from raw Wasm pointers, [Actor-over-Worker Architecture (Off-Main-Thread UI)](/concepts/actor-over-worker-architecture) models the worker as an isolated actor with a typed command mailbox (`SORT_COLUMN`, `PATCH_CELL`).

The main thread receives only viewport slices and transferred index buffers, holding 60 FPS during dataset mutations.

## Architectural Fix & Invariants

```ts
// engine.worker.ts: Actor mailbox + Wasm linear sort + OPFS sync snapshot + zero-copy transfer
const root = await navigator.storage.getDirectory();
const file = await root.getFileHandle('sheet.bin', { create: true });
const syncHandle = await file.createSyncAccessHandle();

self.onmessage = ({ data }: MessageEvent<{ type: 'SORT'; col: number; count: number }>) => {
  if (data.type !== 'SORT') return;
  wasm.exports.sortColumnInPlace(data.col);
  const indices = new Uint32Array(wasm.memory.buffer, IDX_OFFSET, data.count).slice();
  syncHandle.write(new Uint8Array(wasm.memory.buffer, DATA_OFFSET, DATA_BYTES), { at: 0 });
  syncHandle.flush();
  self.postMessage({ type: 'VIEWPORT_READY', indices: indices.buffer }, [indices.buffer]);
};
```

**Architectural Invariants**

- **Main thread renders only**: Zero dataset sorting, graph layout math, or persistence serialization executes on the UI thread.
- **Zero-copy buffer handoff**: Worker-to-UI state updates transfer `ArrayBuffer` ownership via `postMessage(msg, [buffer])` instead of cloning JS object graphs.
- **Coarse-grained Wasm calls**: Data lives in Wasm linear memory; JS invokes one exported function per user command.
- **Worker-only synchronous OPFS**: `FileSystemSyncAccessHandle` writes binary snapshots synchronously inside the worker, eliminating `JSON.stringify` and IndexedDB bottlenecks.

**Golden Rule:** Keep the UI thread for pixels and input; move state, Wasm compute, and synchronous OPFS persistence into a worker actor and transfer only typed buffers.
