The Proxy DOM

Problem. A worker can't touch document, and serializing rendered HTML per commit re-sends the whole subtree — losing element identity, focus, scroll position, and event targets.

Fix. Give the worker a proxy document and stream diffs: DOM mutations become ops (createElement, setAttribute, …) replayed incrementally on the main thread, scoped per app@N island instance.

The objection writes itself: a worker can't touch the DOM. True — and it's exactly why most off-main-thread rendering experiments end at a <canvas> or a proof-of-concept nobody ships.

Atoll's answer is a proxy document: inside the worker, a JS object implements just enough document for a real framework renderer to target — createElement, appendChild, setAttribute, text nodes, listeners — and every mutation lands on an op queue instead of a DOM.

The pipeline

worker render → proxy DOM mutations → op queue → flush (postMessage)
                                              ↓
main thread: driver replays op batches onto real DOM in `el`

Events flow the other way — the driver forwards real DOM events into the island's instance, and emit() sends app-defined messages to the shell's onEvent. Instance keys (app@N) scope every queue and every document, so islands sharing a worker are fully isolated.

Why ops, not HTML

The obvious alternative — ship rendered markup per commit — re-sends the whole subtree and destroys node identity: focus lost, scroll state gone, event targets orphaned. Ops are the diffs a framework's commit phase already computes. A two-character text change is a two-field message. That's the granularity worth paying a thread boundary for.

The split that decides whether this is fast:

• Worker side: framework render + op serialization. Million-row table re-renders: ~2–3 ms.
• Main-thread side: op replay + real DOM writes. A virtualized table holds ~22 live DOM rows regardless of logical size — replay cost tracks what's visible, not what's stored.

One rule keeps the stream coherent: worker-initiated DOM work outside a task re-enters through runInInstance(instance, fn) and bumpOpsVersion(). Ambient document/window lookup inside a worker is a heuristic, not a contract — worth knowing before you reach for it.

And the doorbell: with shared memory, an Atomics poke wakes the main thread the moment ops queue. Drop it — or run somewhere without SAB headers — and islands flush over ordinary postMessage. Same ops, same DOM, one fewer capability required. That's the kind of degradation a production system should have: silent and graceful, not a blank page.

Source: the islands engine guide and the worker-side contract.