Autopsy #12: Moving the Entire App Engine Off the Main Thread
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.
- T+00:00Enterprise customers opened 100,000-row production workbooks after the release.
- T+03:00Long Task observers recorded 620 ms main-thread stalls per column click, dropping scroll input and collapsing frame rates to 4 FPS.
- 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.
- T+12:00V8 major garbage collection pauses hit 140 ms every time a user toggled a sort direction.
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.stringifyand 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.
- 01Web APIsDedicated Web Workers and Transferables
Relocates the 100k-row store and sort engine out of the main-thread event loop.
- 02JS RuntimeTypedArrays, ArrayBuffer, and Zero-Copy Transfers
Transfers sorted row index buffers via ArrayBuffer transferables with zero structured-clone copy.
- 03Web APIsOrigin Private File System (OPFS)
Persists binary snapshots synchronously in the worker via FileSystemSyncAccessHandle.
- 04Web APIsWebAssembly Linear Memory & JS Boundary Crossing Cost
Batches 100k-row numeric sorts inside Wasm linear memory to avoid per-row JS boundary crossings.
- 05Web APIsActor-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
postMessagestalls both threads. - Async JSON storage:
JSON.stringifyand 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.
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.
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));
}Every sort triggers a >600 ms Long Task, starving rAF, dropping frame rate to 4 FPS, and allocating 90 MB of transient JSON strings.
// 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]);
}Main thread stays at 60 FPS; only a zero-copy ArrayBuffer of sorted row indices crosses the Worker boundary.
Layer-by-Layer Dissection
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:
- Structured clone: Copies every object property across thread heaps, stalling both isolates.
- Zero-copy transfer: Transfers ownership of a 400 KB
Uint32Arraybuffer via TypedArrays, ArrayBuffer, and Zero-Copy Transfers in under 0.1 ms.
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.
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.
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
// 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
ArrayBufferownership viapostMessage(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:
FileSystemSyncAccessHandlewrites binary snapshots synchronously inside the worker, eliminatingJSON.stringifyand 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