Architecture Autopsies
Case #12Main-Thread Freeze7 min read

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

Production Symptom

Rich spreadsheet and graph app drops to 4 FPS during 100k-row sorts until state and OPFS move to a Worker.

The Incident & The False Culprit

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.

  1. T+00:00Enterprise customers opened 100,000-row production workbooks after the release.
  2. T+03:00Long Task observers recorded 620 ms main-thread stalls per column click, dropping scroll input and collapsing frame rates to 4 FPS.
  3. T+08:00Each 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.
  4. T+12:00V8 major garbage collection pauses hit 140 ms every time a user toggled a sort direction.
REJECTED PATCH

The Red Herring — Why the First Reflex Failed

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 Traversed

Step-by-step propagation across atomic concepts. Hover or click any step to inspect the underlying mechanism.

  1. 01Web APIs
    Dedicated Web Workers and Transferables

    Relocates the 100k-row store and sort engine out of the main-thread event loop.

  2. 02JS Runtime
    TypedArrays, ArrayBuffer, and Zero-Copy Transfers

    Transfers sorted row index buffers via ArrayBuffer transferables with zero structured-clone copy.

  3. 03Web APIs
    Origin Private File System (OPFS)

    Persists binary snapshots synchronously in the worker via FileSystemSyncAccessHandle.

  4. 04Web APIs
    WebAssembly Linear Memory & JS Boundary Crossing Cost

    Batches 100k-row numeric sorts inside Wasm linear memory to avoid per-row JS boundary crossings.

  5. 05Web APIs
    Actor-over-Worker Architecture (Off-Main-Thread UI)

    Decouples UI rendering from engine state via typed message-passing actor mailboxes.

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 Reproduction Lab

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

Interactive Simulator

100k-Row Engine: Main-Thread Sort vs Worker Actor + Wasm + OPFS

Compare blocking 100k-row sorts and JSON IndexedDB writes on the main thread against an off-main-thread Worker actor with zero-copy transfers and OPFS sync writes.

Lines of Code
Before
6
After
7
Reflows / Browser Cost
Before
4 FPS (600ms+ Long Task)
After
60 FPS (0ms Main-Thread Sort)
BeforeMain-Thread Sort + JSON Persistence
function onSortColumn(colIndex) {
  rows.sort((a, b) => a[colIndex] - b[colIndex]); // 420ms main-thread block
  const blob = JSON.stringify(rows);              // 180ms serialization
  idbStore.put(blob, 'sheet-v1');                 // Async IDB structured clone
  renderVisibleViewport(rows.slice(0, 60));
}
Lines: 6Reflows: 4 FPS (600ms+ Long Task)Dependencies: Main Thread 100%

Every sort triggers a >600 ms Long Task, starving rAF, dropping frame rate to 4 FPS, and allocating 90 MB of transient JSON strings.

After (Native)Worker Actor + Wasm Sort + OPFS Sync + Transfer
// Inside Dedicated Worker actor
function handleSort(colIndex, syncHandle) {
  wasmExports.sortColumnInPlace(colIndex); // 11ms in linear memory
  const view = new Uint32Array(wasmMemory.buffer, idxPtr, rowCount).slice();
  syncHandle.write(view, { at: 0 });       // Sync OPFS write off main thread
  self.postMessage({ type: 'SORTED', indices: view.buffer }, [view.buffer]);
}
Lines: 7Reflows: 60 FPS (0ms Main-Thread Sort)Dependencies: Worker + Wasm + OPFS

Main thread stays at 60 FPS; only a zero-copy ArrayBuffer of sorted row indices crosses the Worker boundary.

Layer-by-Layer Dissection

01 → 02

Worker Offloading Requires Zero-Copy Transfers

Relocating the data engine into Dedicated Web Workers and Transferables 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:

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), 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 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) 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.

Primary Sources

Last verified: 2026-11-16