Islands — the proxy document

Inside the worker there is no DOM — there is a ProxyDocument: a faithful facade that records every mutation as an op in a queue. Task calls return the flushed batch; the main thread's only job is replaying ops against real nodes. No shared memory is involved — ops ride postMessage.

The pipeline

worker app → ProxyDocument → per-instance op queue → task batch → postMessage → driver replay → real DOM

Every island owns an independent op stream keyed by its app@N instance — separate queue, document, and node map — so several islands can share one worker without cross-talk. The task surface each worker exposes is fixed: mount, updateProps, dispatch, setSize, flush, unmount — each returns the op batch it produced.

The op vocabulary

Twelve ops cover the entire protocol — everything a reconciler or hand-rolled DOM code can express:

DOM coverage

The facade implements what frameworks and libraries actually touch: createElement(NS)/createTextNode/createComment, insertBefore/appendChild/removeChild (fragments splice in), setAttribute(NS), reflected properties (value, checked, src…), classList/style/dataset, textContent, innerHTML, cloneNode, template.content, shadow-tree reads (children, querySelector, getElementsBy*), and addEventListener with { once, passive, capture } crossing the wire.

• Instance-aware globals — document/window/Element resolve to the active instance, so libraries work without an explicit shim.
• installDomShim(doc) puts the proxy doc on globalThis.document plus a window facade for libraries that read globals at module scope — install it before a dynamic import('lib').
• Worker-initiated work re-enters explicitly — timers and promise continuations have no active instance: runInInstance(instance, fn) + bumpOpsVersion() to flush.

Geometry — the one honest box

The only measurement channel is the island container itself: the driver observes el with a ResizeObserver and calls setSize(instance, w, h) at mount and on resizes (throttled ~100ms). Geometry reads on doc.body, documentElement, and elements marked doc.markContainer(el) return that box; everything else returns an honest 0. doc.onResize(cb) re-fires on each push — the callbacks' ops ride back in setSize's return batch.

Events

Handlers receive a spec-shaped EventPayload — pointer coords, modifiers, wheel deltas (+deltaMode), key, which, pointerType, target form state, and scrollTop. A synthesized target gives delegated handlers a proxy-DOM node toclosest()/dataset against. preventDefault/stopPropagation exist as no-ops so library code doesn't crash — they cannot cancel anything: the real event already dispatched on the main thread.

Benchmarks — where the time goes

Measured, not estimated: the same 200-row tree mounted through every adapter, then a prop-driven update and a click→state-commit. Each cell splits the JS cost three ways — app (framework render/diff + adapter glue), engine (proxy-DOM bookkeeping: op recording, prop serialization, instance allocation, queue drain), and replay (main thread applying ops to real DOM).

app / rendererproxy enginemain-thread replay

• The engine is cheap relative to the renderer — framework mounts spend ~10–35% of worker time in proxy bookkeeping; the rest is the framework's own render/diff.
• Imperative is the ceiling case — with no framework, the app IS proxy calls, so the engine dominates its worker time; that row is the proxy document's own cost profile.
• Replay scales with op count, not tree size — a diffed framework update emits ~200 ops; the imperative rebuild emits ~2,600 and pays for it on the main thread.
• Clicks are ~all worker — dispatch runs the handler in the island; typically one op crosses back.

Memory & wire inflation

The proxy layer keeps its own state per island — this is what it retains after the three scenarios, plus how much op traffic each renderer generated:

• One instance record per rendered node — the shadow map keeps id → record for everything the island has mounted, so a 200-row tree costs ~1,000+ proxy records on top of the real DOM nodes.
• Records survive removal — the instance map is never pruned (event dispatch may still resolve a detached target id), so long-lived churning islands accumulate; a full remount is the reclaim.
• ~45–50 bytes per op on the wire — a 200-row mount is a ~100–160 KB structuredClone batch. Big state should live in shared memory, not in props — the serialization boundary is postMessage.
• One happy-dom run on one machine — treat the ratios, not the decimals, as the data. In-process transport is ~free; real workers add marshalling to the worker side. Regenerate with npm run stats:islands.

Limits

• Only the island container is measured — arbitrary-element geometry and SVG metrics (getBBox…) return 0.
• getContext('2d'/'webgl') is out of scope — canvas libraries belong on OffscreenCanvas, a different transport.
• Async callbacks that mutate or emit outside a task need runInInstance.

Byte-side numbers — what each thread loads — are on Bundle size & load; mounting mechanics on Quickstart.