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.sortover 100,000 JS objects followed byJSON.stringify(rows)and an IndexedDBput(), 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.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
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 Simulator
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:
- 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.
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
// 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.

Top comments (0)