React, islands

@atolljs/react-island, a worker-hosted React (or imperative proxy-DOM) tree mounted as an ordinary element in a React shell. The worker's render loop produces serialized DOM ops; the main thread just replays them.

Live demo, React in the worker

Four islands, React rendered inside the workers: a counter, a second counter instance, a notes composer, and a 1,000,000-record incident benchmark, the two counters share ONE client (both mounts live in a single worker, counter@N keys, one OS thread), notes gets its own client on the same script, and the incidents benchmark carries a third worker through its lazy contract module. The shell is just a thin <Island/> host: worker emits land in onEvent → React state → the status line.

The incident benchmark is the real-world case for offloading a heavy component. One million incidents exist as lazily generated logical rows: the component is a fixed-height virtualized scroller that renders only the ~22 visible rows plus overscan, no matter where you scroll. Each scroll event crosses the island protocol as a structured payload (the driver stamps scrollTop), React re-computes the window worker-side, and the commit rides back as an op batch: the stats line reports the worker-side re-render time, and a rendered emit updates the shell's status line. The main thread never touches more than a handful of DOM nodes; a million rows of state, generation, and diffing all stay off it.

If the frame is blank, the examples aren't up: run npm run dev:all (dev servers) or npm run serve:all (built apps) from the repository root.

The proxy API

ExportSignatureWhat it does
lazyIslandlazyIsland(loader: () => Promise<{ default: A } | { app, worker? } | A>): FC<IslandAppProps<A> & IslandShellProps>React.lazy mirrored: the returned component suspends on the dynamic import (a real bundler split point), then mounts the resolved app with props inferred from its signature. Contract modules { app, worker } carry their own worker factory: that's how the incidents island gets a dedicated worker.
islandComponentislandComponent<P>('name') | islandComponent(StampedApp)The pure-contract proxy: the shell never imports the implementation; a registry key + a type-only props import is the whole contract.
Island<Island app={ref|name} client|worker props onEvent slots onReady/>The underlying building block: declarative mountIsland as a component. props dedups by serialized identity.
islandAppislandApp('name', app)Stamps an app (component or {imperative} def) with its registry name: a data property, so references survive minification.
defineReactPolyWorkerdefineReactPolyWorker({ apps }), react-island/workerRegistry worker, one script serving a whole apps map; islands mount by name and several may share one client/worker. Components wrap through reactIslandApp automatically.
defineReactMonoWorkerdefineReactMonoWorker(app), react-island/workerInstance worker, the 1:1 topology: one script, one app, mounted namelessly. Its bundle carries only that app's dependencies.
Slot / emit<Slot name> / emit(name, payload)Transclusion: worker markup hands a real element to the shell's slots map (canvases, Monaco, AG Grid). emit is the island→shell event channel.
Island / islandComponent / lazyIslandfrom react-island/workerThe same mount components, for use inside a worker island: the mount spawns or reuses a sub-worker. Same props, same meaning.

Mounting, the proxies make islands look local

The counters mount through plain <Island/> elements on a shared connectIslandWorker client; notes mounts through islandComponent('notes'), a registry key is the whole contract; incidents mounts through lazyIsland with a contract module, so its chunk code-splits and its worker is self-contained. <Suspense> covers the module load; the proxy's fallback prop covers the worker-mount window: mounting can't suspend because a suspended tree never commits and the container must be in the DOM first.

examples/react-dom-worker/src/shell.tsxfrontend
/**
 * The React islands demo — REACT RUNNING INSIDE WORKERS.
 *
 * Each island below mounts an app from `worker/react.worker.tsx`'s
 * registry: ordinary React components (useState/useLayoutEffect) rendered
 * by react-reconciler into serialized DOM ops. The worker bundle carries
 * React; this page is just a thin host that replays its ops.
 *
 * What changes versus main.ts (the seven-island demo):
 *   - The shell itself is React — each island is an <Island/> element, a
 *     islandComponent facade, or a lazyIsland contract module.
 *   - `client` (not `worker:`) is passed so the doorbell choice travels
 *     with the connection; the two counters deliberately share ONE client
 *     so their islands live in the same OS worker.
 *   - Mediation is plain React state: worker emits land in onEvent →
 *     setState → the status line.
 *
 * The ops console at the bottom mounts a SECOND PolyWorker definition
 * (worker/console.worker.tsx) three ways: compute inline on a shared
 * client, compute offloaded to a `workers: 1` compute worker, and nested
 * (render sub-worker for the cards, a `workers: 3` compute pool for them).
 *
 * The seven-island demo lives in index.html — this page is the small
 * framework-island edition matching vue/solid/svelte/angular-shell.html.
 */
import { useEffect, useRef, useState, Suspense } from 'react';
import type { ReactElement, ReactNode } from 'react';
import { createRoot } from 'react-dom/client';
import { Island, islandComponent, lazyIsland } from '@atolljs/react-island';
import { connectIslandWorker } from '@atolljs/islands';
import type { IslandHandle, Mode } from '@atolljs/islands';
import { initDevtools } from '@atolljs/devtools';

/** The registry worker — one script serving all three React apps. */
const reactWorker = (): Worker =>
  new Worker(new URL('./worker/react.worker.tsx', import.meta.url), { type: 'module' });

// SharedArrayBuffer only exists in cross-origin-isolated contexts — on
// hosts without COOP/COEP (GitHub Pages where coi-sw.js didn't take, or a
// browser without `credentialless`) the doorbell can't bind, so every
// island runs its 50ms poll transport instead of push.
const isolated =
  typeof SharedArrayBuffer !== 'undefined' &&
  (typeof window.crossOriginIsolated === 'undefined' || window.crossOriginIsolated);
const initialMode: Mode = isolated ? 'push' : 'poll';

// Sink before any island mounts — workers only forward events when the
// flag reaches them at INIT. No-op without ?__atoll_devtools.
initDevtools({
  session: { name: 'islands-react-shell', framework: 'react' },
  overlay: { src: '__atoll/?mini=1' },
});

/**
 * Two clients = two OS workers running the same script. The counters share
 * one client (one worker, two 'counter@N' instances); notes gets its own —
 * and the incidents benchmark carries a third worker through its contract
 * module below.
 */
const counterClient = connectIslandWorker({ name: 'counters', worker: reactWorker, doorbell: isolated });
const notesClient = connectIslandWorker({ name: 'notes', worker: reactWorker, doorbell: isolated });

/**
 * The facades — mount worker apps this shell never imports. Notes goes
 * through an eager proxy component (the string is the registry key);
 * incidents is lazy: a dynamic import + contract module that carries its
 * OWN worker, so the 1M-row benchmark can't contend with anything else
 * and its chunk only loads when the island mounts.
 */
const NotesIsland = islandComponent<{ title?: string }>('notes');
const IncidentsIsland = lazyIsland(() => import('./incidents.island'));

/**
 * The ops console: a SECOND PolyWorker definition, spawned three ways
 * below. `opsInline` and `opsOffload` are each one render worker hosting
 * two instances: the first computes inline (and stalls), the second sends
 * the export to a compute worker. 'regions' passes `worker={consoleWorker}`
 * and nests a render sub-worker plus compute workers inside its worker.
 */
const consoleWorker = (): Worker =>
  new Worker(new URL('./worker/console.worker.tsx', import.meta.url), { type: 'module' });
const opsInline = connectIslandWorker({ name: 'ops-inline', worker: consoleWorker, doorbell: isolated });
const opsOffload = connectIslandWorker({ name: 'ops-offload', worker: consoleWorker, doorbell: isolated });

/** Main-thread heartbeat: proves the page never stalls, whatever the workers do. */
function MainHeartbeat(): ReactElement {
  const [beats, setBeats] = useState(0);
  const [worst, setWorst] = useState(0);
  const last = useRef(0);
  useEffect(() => {
    last.current = performance.now();
    const id = setInterval(() => {
      const now = performance.now();
      const late = Math.max(0, now - last.current - 250);
      last.current = now;
      setBeats((b) => b + 1);
      if (late > 50) setWorst((w) => Math.max(w, Math.round(late)));
    }, 250);
    return () => clearInterval(id);
  }, []);
  return (
    <div id="main-heartbeat" className="ops-main">
      <span className={`ops-dot ${beats % 2 ? 'on' : ''}`} /> main thread · ticks {beats} ·{' '}
      <span className={`ops-stall ${worst ? 'hit' : ''}`}>longest stall {worst}ms</span>
    </div>
  );
}

/* ── Shell ──────────────────────────────────────────────────────────────── */

const loading = (
  <div className="island-root" style={{ color: '#7d8a9c' }}>
    loading worker module…
  </div>
);

function IslandPanel(props: {
  title: string;
  badge?: string;
  children: ReactNode;
}): ReactElement {
  return (
    <section className="island">
      <div className="island-head">
        <span>{props.title}</span>
        <span className="badge">{props.badge ?? 'worker …'}</span>
      </div>
      {props.children}
    </section>
  );
}

export function Shell(): ReactElement {
  // Mediation state — worker emits land here; the status line renders it.
  const [status, setStatus] = useState('mounting islands…');
  const [mode, setModeState] = useState<Mode>(initialMode);
  const [pids, setPids] = useState<Record<string, string>>({});
  const [statsTick, setStatsTick] = useState(0);

  /** Every mounted island's handle — setMode + the aggregate stats read them. */
  const handles = useRef(new Map<string, IslandHandle>());
  const modeRef = useRef(mode);
  modeRef.current = mode;

  const ready = (key: string) => (h: IslandHandle): void => {
    handles.current.set(key, h);
    h.setMode(modeRef.current); // applies the user's pick to late-mounting islands
    setPids((p) => ({ ...p, [key]: `worker ${h.pid}` }));
    setStatsTick((t) => t + 1);
  };
  const bump = (): void => setStatsTick((t) => t + 1);

  const setMode = (next: Mode): void => {
    setModeState(next);
    for (const h of handles.current.values()) h.setMode(next);
    bump();
  };

  const flushes = [...handles.current.values()].reduce((a, i) => a + i.flushCalls, 0);
  const ops = [...handles.current.values()].reduce((a, i) => a + i.opsApplied, 0);
  void statsTick; // re-render trigger for the aggregate read

  const counterOpts = (label: string, key: string) => ({
    client: counterClient,
    app: 'counter',
    props: { label },
    mode: initialMode,
    onReady: ready(key),
    onActivity: bump,
    framework: 'react',
    onEvent: (name: string, payload: unknown) => {
      const p = payload as { count?: number; label?: string };
      if (name === 'incremented')
        setStatus(`${p.label} counter → ${p.count} (React state stayed in the worker)`);
    },
  });

  return (
    <>
      <h1>React islands — React in the worker</h1>
      <p style={{ font: '12px monospace', color: '#9aa4b2', marginTop: -8 }}>
        registry worker + shared client — the worker bundle carries React, the shell is a thin{' '}
        <code>{'<Island/>'}</code> + <code>islandComponent</code>/<code>lazyIsland</code> host.{' '}
        <a href="./index.html" style={{ color: '#7fb6ff' }}>framework-free shell →</a>
      </p>

      <div id="transport-bar">
        <span>transport:</span>
        <label
          id="transport-toggle"
          title={isolated ? 'push via SharedArrayBuffer doorbell — off falls back to 50ms polling' : 'needs cross-origin isolation (no SharedArrayBuffer)'}
        >
          <input
            id="push-toggle"
            type="checkbox"
            checked={mode === 'push'}
            disabled={!isolated}
            onChange={() => setMode(mode === 'push' ? 'poll' : 'push')}
          />
          push (SAB doorbell)
        </label>
        <span id="transport-stats">
          sync: {mode} · flush calls: {flushes} · ops applied: {ops}
        </span>
      </div>
      <div id="status-line">{status}</div>

      <IslandPanel title="app: counter (react-reconciler — this worker has no DOM)" badge={pids.counter}>
        <Island {...counterOpts('alpha', 'counter')} className="island-root" />
      </IslandPanel>

      <IslandPanel
        title="app: counter — second instance (SAME worker as the first, one client)"
        badge={pids.counter2}
      >
        <Island {...counterOpts('beta', 'counter2')} className="island-root" />
      </IslandPanel>

      <IslandPanel
        title="app: nestedhost — an island INSIDE an island (worker → sub-worker)"
        badge={pids.nestedhost}
      >
        <Island
          client={counterClient}
          app="nestedhost"
          framework="react"
          props={{ label: 'inner counter' }}
          mode={initialMode}
          onReady={ready('nestedhost')}
          onActivity={bump}
          onEvent={(name, payload) => {
            const p = payload as { count?: number; label?: string };
            if (name === 'nestedIncremented')
              setStatus(
                `nested island → ${p.count} — emitted in the SUB-worker, relayed through the parent island`,
              );
          }}
          className="island-root"
        />
      </IslandPanel>

      <IslandPanel
        title="app: notes — islandComponent facade (attrs ARE the props)"
        badge={pids.notes}
      >
        <NotesIsland
          client={notesClient}
          framework="react"
          title="react island"
          onReady={ready('notes')}
          onActivity={bump}
          onEvent={(name, payload) => {
            const p = payload as { text?: string; total?: number };
            if (name === 'noteAdded')
              setStatus(`notes island emitted noteAdded → "${p.text}" (${p.total} total)`);
          }}
          containerProps={{ className: 'island-root' }}
        />
      </IslandPanel>

      <IslandPanel
        title="app: incidents — lazyIsland + contract module (own worker, 1M rows)"
        badge={pids.incidents}
      >
        <Suspense fallback={loading}>
          <IncidentsIsland
            // The contract supplies the worker; workerOptions carries the
            // doorbell choice through to the shorthand client it builds.
            workerOptions={{ doorbell: isolated }}
            framework="react"
            mode={initialMode}
            onReady={ready('incidents')}
            onActivity={bump}
            onEvent={(name, payload) => {
              const p = payload as { start?: number; end?: number; ms?: number };
              if (name === 'rendered')
                setStatus(
                  `incidents island rendered rows ${p.start?.toLocaleString()}–${p.end?.toLocaleString()} in ${p.ms?.toFixed(1)}ms (of 1,000,000)`,
                );
            }}
            containerProps={{ className: 'island-root' }}
          />
        </Suspense>
      </IslandPanel>

      <h2 id="ops-console">Ops console: render workers render, compute workers compute</h2>
      <p className="ops-intro">
        Every panel below mounts an app from the SAME definition,{' '}
        <code>worker/console.worker.tsx</code>. Island clients are always one worker (a rendered
        tree can't be split), so heavy work goes to a separate compute worker, and{' '}
        <code>workers</code> says how many: <code>1</code> to get it off the render thread,{' '}
        <code>N</code> when independent jobs should overlap. Press an export and watch which pulse
        freezes.
      </p>
      <MainHeartbeat />

      <h3 className="ops-row-title">A. anti-pattern: export computed INLINE on the render worker it shares with the pulse</h3>
      <div className="ops-row">
        <IslandPanel title="app: pulse (opsInline)" badge={pids.pulseInline}>
          <Island
            client={opsInline}
            framework="react"
            app="pulse"
            props={{ label: 'inline' }}
            mode={initialMode}
            onReady={ready('pulseInline')}
            onActivity={bump}
            className="island-root"
          />
        </IslandPanel>
        <IslandPanel title="app: export (opsInline)" badge={pids.exportInline}>
          <Island
            client={opsInline}
            framework="react"
            app="export"
            props={{ label: 'inline' }}
            mode={initialMode}
            onReady={ready('exportInline')}
            onActivity={bump}
            onEvent={(name, payload) => {
              const p = payload as { ms?: number; rows?: number };
              if (name === 'exported')
                setStatus(
                  `inline export: ${p.rows?.toLocaleString()} rows in ${p.ms}ms; the pulse on the same render worker was frozen the whole time`,
                );
            }}
            className="island-root"
          />
        </IslandPanel>
      </div>

      <h3 className="ops-row-title">B. fix: same two instances in ONE render worker, export offloaded (workers: 1)</h3>
      <div className="ops-row">
        <IslandPanel title="app: pulse (opsOffload)" badge={pids.pulseOffload}>
          <Island
            client={opsOffload}
            framework="react"
            app="pulse"
            props={{ label: 'offload' }}
            mode={initialMode}
            onReady={ready('pulseOffload')}
            onActivity={bump}
            className="island-root"
          />
        </IslandPanel>
        <IslandPanel title="app: export (opsOffload → compute.worker ×1)" badge={pids.exportOffload}>
          <Island
            client={opsOffload}
            framework="react"
            app="export"
            props={{ label: 'offload', offload: true }}
            mode={initialMode}
            onReady={ready('exportOffload')}
            onActivity={bump}
            onEvent={(name, payload) => {
              const p = payload as { ms?: number; rows?: number };
              if (name === 'exported')
                setStatus(
                  `offloaded export: ${p.rows?.toLocaleString()} rows in ${p.ms}ms on a dedicated compute worker; the pulse kept ticking`,
                );
            }}
            className="island-root"
          />
        </IslandPanel>
      </div>

      <h3 className="ops-row-title">C. nested: one render sub-worker for the cards, a compute pool for their work</h3>
      <IslandPanel
        title="app: regions (own worker → region.worker ×1, compute.worker pool ×3 + ×1)"
        badge={pids.regions}
      >
        <Island
          worker={consoleWorker}
          framework="react"
          workerOptions={{ doorbell: isolated }}
          app="regions"
          mode={initialMode}
          onReady={ready('regions')}
          onActivity={bump}
          onEvent={(name, payload) => {
            const p = payload as { regions?: string[]; wallMs?: number; workMs?: number; ms?: number; rows?: number };
            if (name === 'regionRecomputed')
              setStatus(
                p.regions?.length === 1
                  ? `${p.regions[0]} recomputed in ${p.wallMs}ms on the compute pool; every card kept ticking`
                  : `${p.regions?.length} regions recomputed in ${p.wallMs}ms wall (${p.workMs}ms of work) on a 3-worker pool`,
              );
            if (name === 'forecasted')
              setStatus(
                `forecast scored ${p.rows?.toLocaleString()} rows in ${p.ms}ms on a dedicated compute worker; cards kept ticking`,
              );
          }}
          className="island-root"
        />
      </IslandPanel>
    </>
  );
}

// Guarded so the module is import-safe in tests (they render <Shell/> directly).
const rootEl = document.getElementById('root');
if (rootEl) createRoot(rootEl).render(<Shell />);

The worker side: React running in the worker

The worker bundle carries React itself : defineReactPolyWorker serves the whole apps map from one script, and a real react-reconciler drives the proxy DOM with state staying worker-side. Components are unremarkable React: hooks, controlled inputs, emit(name, payload) for the island → shell channel. The only rules: no DOM access, serializable props, and handlers receive the plain EventPayload wire object instead of a SyntheticEvent : handler() in the file adapts it to JSX's event prop types. See the Islands page for modes, slots, and lifecycle.

examples/react-dom-worker/src/worker/react.worker.tsxfrontend
/**
 * React island worker — a registry worker serving React apps through
 * `reactIslandApp` (react-reconciler bound to the instance's op stream).
 * Its bundle carries React but no Vue/Solid/Svelte/Angular — the point of
 * the demo: islands are framework-agnostic over one op protocol, and this
 * worker's apps are the same counter/notes/incidents set the other
 * framework shells mount.
 *
 * Unlike the other frameworks' async schedulers, React's commit runs inside
 * the dispatch's sync lane — `useLayoutEffect` fires while the task still
 * holds the instance, so `emit` from a commit-phase effect needs no
 * `runInInstance` re-entry (see TableApp's `rowsChanged` in apps.tsx).
 */
import { useLayoutEffect, useRef, useState } from 'react';
import { defineReactPolyWorker, emit, SubIsland } from '@atolljs/react-island/worker';
import { islandApp, type EventPayload } from '@atolljs/islands/worker';

/**
 * Worker-side event handlers receive the plain wire payload — { type, value,
 * checked, key, scrollTop } — not a SyntheticEvent. `handler()` adapts them
 * to the DOM event prop types JSX expects; the cast is the whole story.
 */
const handler = <E,>(fn: (e: EventPayload) => void): ((e: E) => void) =>
  fn as unknown as (e: E) => void;

/**
 * 'counter' — the canonical framework island: a `label` wire prop, a
 * `useState` count, and an 'incremented' emit for the shell's status line.
 */
const CounterApp = islandApp('counter', function CounterApp({
  label = 'count',
}: {
  label?: string;
}) {
  const [count, setCount] = useState(0);
  return (
    <div className="react-counter">
      <span className="vanilla-heading">
        {label}: {count}
      </span>
      <button
        className="mw-btn"
        onClick={handler(() => {
          const n = count + 1;
          setCount(n);
          emit('incremented', { count: n, label });
        })}
      >
        increment
      </button>
    </div>
  );
});

/**
 * 'notes' — the notes composer: a controlled input, a `useState` list, and
 * a 'noteAdded' emit per add. `value` is a wire prop — the driver writes it
 * back onto the real input, so clearing the draft clears the field.
 */
const NotesApp = islandApp('notes', function NotesApp({
  title = 'react island',
}: {
  title?: string;
}) {
  const [draft, setDraft] = useState('');
  const [notes, setNotes] = useState<string[]>([]);
  const add = (): void => {
    const text = draft.trim();
    if (text === '') return;
    setNotes([...notes, text]);
    setDraft('');
    emit('noteAdded', { text, total: notes.length + 1 });
  };
  return (
    <div className="react-notes">
      <h3 className="vanilla-heading">{title}</h3>
      <div className="atoll-map-places">
        <input
          placeholder="write a note…"
          value={draft}
          // _enrichEvent stamps the wire payload's `value` onto the target.
          onInput={handler((e) => setDraft(e.value ?? ''))}
          onKeyDown={handler((e) => {
            if (e.key === 'Enter') add();
          })}
        />
        <button className="atoll-map-place-btn" onClick={handler(add)}>
          add
        </button>
      </div>
      <ul className="vanilla-log">
        {notes.map((n, i) => (
          <li key={i} className="vanilla-log-line">
            {n}
          </li>
        ))}
      </ul>
      <div className="vanilla-readout">{notes.length} note(s) — state lives in the worker</div>
    </div>
  );
});

/**
 * 'incidents' — the heavy-component benchmark: 1,000,000 incident records
 * in the worker, rendered through a virtualized scroller. The main thread
 * only ever sees ~22 rows of ops no matter how deep the user scrolls.
 *
 * Rows are lazily generated (deterministic pseudo-data — nothing is
 * materialized until it's visible). Each scroll event is a dispatch
 * round-trip — the driver stamps `scrollTop` onto the payload — the worker
 * re-renders the window and reports the re-render time back via 'rendered'.
 */
const REGIONS = ['us-east', 'us-west', 'eu-central', 'ap-south', 'sa-east'];
const SEVS = ['P1', 'P2', 'P3', 'P4'];
const ROW_H = 24;
const OV = 4;
const VISIBLE = Math.ceil(320 / ROW_H) + OV * 2;
const incident = (i: number) => ({
  id: i,
  site: `site-${(i * 7919) % 1409}`,
  region: REGIONS[i % REGIONS.length],
  sev: (i * 31) % 100,
  dur: `${((i * 104729) % 977) % 60}m`,
});
const sevClass = (s: number): string =>
  `inc-sev sev-p${s > 75 ? 1 : s > 40 ? 2 : s > 15 ? 3 : 4}`;
const sevLabel = (s: number): string => SEVS[s > 75 ? 0 : s > 40 ? 1 : s > 15 ? 2 : 3];

const IncidentsApp = islandApp('incidents', function IncidentsApp({
  count = 1_000_000,
}: {
  count?: number;
}) {
  const [start, setStart] = useState(0);
  const [lastMs, setLastMs] = useState(0);
  const t0 = useRef(performance.now());
  const prevKey = useRef('');

  const first = Math.min(start, Math.max(0, count - VISIBLE));
  const rows = Array.from({ length: Math.min(VISIBLE, count - first) }, (_, k) =>
    incident(first + k),
  );
  const end = first + rows.length - 1;

  // Commit-phase report: the delta from the scroll handler is the whole
  // worker-side re-render cost. React commits inside the dispatch's sync
  // lane, so emit here is still in instance scope — no runInInstance
  // re-entry needed. The window-key guard stops lastMs's own write from
  // looping back into another report.
  useLayoutEffect(() => {
    const key = `${first}:${end}`;
    if (key === prevKey.current) return;
    prevKey.current = key;
    const ms = performance.now() - t0.current;
    setLastMs(ms);
    emit('rendered', { start: first, end, ms });
  });

  return (
    <div className="incidents">
      <div className="inc-stats">
        {count.toLocaleString()} incidents · rows {first.toLocaleString()}–
        {end.toLocaleString()} · worker re-render {lastMs.toFixed(1)}ms
      </div>
      <div
        className="inc-viewport"
        onScroll={handler((e) => {
          t0.current = performance.now();
          // The driver stamps the scroller's scrollTop onto the wire
          // payload — the proxy element's geometry getters are stubs.
          setStart(Math.max(0, Math.floor((e.scrollTop ?? 0) / ROW_H) - OV));
        })}
      >
        <div className="inc-spacer" style={{ height: count * ROW_H }}>
          {rows.map((r) => (
            <div key={r.id} className="inc-row" style={{ top: r.id * ROW_H }}>
              <span className="inc-id">#{r.id}</span>
              <span className="inc-site">{r.site}</span>
              <span className="inc-region">{r.region}</span>
              <span className={sevClass(r.sev)}>
                {sevLabel(r.sev)} · {r.sev}
              </span>
              <span className="inc-dur">{r.dur}</span>
            </div>
          ))}
        </div>
      </div>
    </div>
  );
});

/**
 * 'nestedhost' — an island that hosts an island INSIDE itself. This
 * component renders in `react.worker` (already a worker); <SubIsland/>
 * spawns `nested.worker` as a sub-worker of this one and replays its ops
 * into this instance's shadow tree — so the inner counter's DOM lands
 * inside the outer island, three tiers deep (page → worker → worker).
 *
 * The `new Worker(new URL(...))` literal lives HERE (inside the worker
 * bundle) — bundler detection applies recursively: vite's worker pipeline
 * rewrites it to a nested `?worker_file` request.
 */
const nestedWorker = (): Worker =>
  new Worker(new URL('./nested.worker.tsx', import.meta.url), { type: 'module' });

const NestedHostApp = islandApp('nestedhost', function NestedHostApp({
  label = 'inner',
}: {
  label?: string;
}) {
  const [report, setReport] = useState('inner island not clicked yet');
  return (
    <div className="react-nested">
      <h3 className="vanilla-heading">
        outer island <em style={{ color: '#6e7f94' }}>(this worker)</em>
      </h3>
      <SubIsland
        worker={nestedWorker}
        app="nested"
        props={{ label }}
        onEvent={(name, payload) => {
          const p = payload as { count?: number; label?: string };
          // The inner island's emit surfaces HERE as a plain worker-side
          // call — re-emit so the shell's status line sees it too.
          if (name === 'incremented') {
            setReport(`inner island → ${p.count}`);
            emit('nestedIncremented', { count: p.count, label: p.label });
          }
        }}
      />
      <div className="vanilla-readout">{report} — relayed two hops to the shell</div>
    </div>
  );
});

export const reactWorker = defineReactPolyWorker({
  apps: { counter: CounterApp, notes: NotesApp, incidents: IncidentsApp, nestedhost: NestedHostApp },
});

The incidents island's contract module is the whole lazy story: a shell-safe module that names the registry key AND carries the worker factory: the shell-side lazyIsland resolves both, so the benchmark's worker is a bundler-detectable split point.

examples/react-dom-worker/src/incidents.island.tsfrontend
/**
 * Island contract for the `lazyIsland` facade — resolves `{ app, worker }`
 * so the island carries its own worker factory and the call site needs no
 * `worker` prop at all. The dynamic `import('./incidents.island')` in
 * shell.tsx is the bundler's split point: this module (and anything it
 * pulls) only loads when the island mounts.
 *
 * `app` is the registry key as a STRING — importing the component itself
 * would drag worker-side code into the shell bundle; the name is the
 * whole contract.
 */
export const app = 'incidents';
export const worker = (): Worker =>
  new Worker(new URL('./worker/react.worker.tsx', import.meta.url), { type: 'module' });

Islands inside islands: the same API, one level down

A worker-rendered app mounts islands with the components the shell uses. @atolljs/react-island/worker re-exports Island, islandComponent, lazyIsland and connectIslandWorker; inside a worker the container is a proxy element, so the mount is routed to a sub-worker whose DOM tunnels up through the parent island's own op stream. You don't pick a different API for nesting, only a mount shape:

  • worker={factory} spawns a sub-worker for that mount (from the parent worker, so the new Worker literal lives in the parent worker's bundle).
  • client={connectIslandWorker({ worker })}, built inside the parent worker, adds one instance per mount to a single sub-worker: shared runtime, shared thread.
  • onEvent runs in the parent island's scope, so emit relays to the shell; slots portal worker-side content into the sub-island, and names you don't list bubble up to the shell's slots.

The demo's ops console shows why the shape matters. One PolyWorker (below) is mounted three ways: pulse + export on a shared client, where an export freezes the pulse; the same two apps with worker each, where it doesn't; and regions, whose worker nests region.worker.tsx both ways: three region cards on one shared sub-client and a forecast model on its own sub-worker. See Quickstart for the definition/worker/instance model.

examples/react-dom-worker/src/worker/console.worker.tsxfrontend
/**
 * Ops console worker: a second PolyWorker definition on the React shell,
 * built to show that a definition is a menu of apps, not a thread, and
 * that render workers and compute workers are different jobs. The shell
 * spawns it in three shapes (see shell.tsx):
 *
 *   - Row A: 'pulse' + 'export' on ONE shared client, export computed
 *     INLINE. The synchronous aggregation freezes the pulse beside it:
 *     the anti-pattern, kept so the stall is visible.
 *   - Row B: the same two apps on another shared client, export offloaded
 *     to a compute worker (`workers: 1`). Still one render worker, and
 *     the pulse never stalls.
 *   - Row C: 'regions' on its own worker. It renders region.worker.tsx
 *     sub-islands on ONE shared sub-client and runs their work on compute
 *     workers: a 3-worker pool for recomputes, one worker for the model.
 *
 * Every worker spawned from this definition shares the bundle (React, the
 * opsKit helpers) but evaluates its own copy: shared deps, isolated state.
 */
import { useEffect, useState } from 'react';
import { connectSubWorker } from '@atolljs/core';
import {
  connectIslandWorker,
  defineReactPolyWorker,
  emit,
  Island,
} from '@atolljs/react-island/worker';
import { getActiveInstance, islandApp } from '@atolljs/islands/worker';
import { aggregate, handler, isolated, reenter, useHeartbeat, type AggregateResult } from './opsKit';
import type { ComputeWorker } from './compute.worker';

/**
 * The compute entry. The `new Worker(new URL(...))` literal stays inline
 * in this factory so vite detects it inside the worker bundle too.
 */
const computeEntry = (): Worker =>
  new Worker(new URL('./compute.worker.ts', import.meta.url), { type: 'module' });

/** Row B's export lane: one compute worker, no pool. Lazy: spawns on the first offloaded export. */
const exportLane = connectSubWorker<ComputeWorker>({ name: 'export-lane', worker: computeEntry, workers: 1 });

/** 'pulse' — live telemetry: a heartbeat that reports its worst stall. */
const PulseApp = islandApp('pulse', function PulseApp({
  label = 'telemetry',
}: {
  label?: string;
}) {
  const { beats, worstStall, reset } = useHeartbeat();
  return (
    <div className="ops-card ops-pulse">
      <div className="ops-card-title">{label} pulse</div>
      <div className="ops-beat">
        <span className={`ops-dot ${beats % 2 ? 'on' : ''}`} /> live · ticks {beats}
      </div>
      <div className={`ops-stall ${worstStall ? 'hit' : ''}`}>longest stall {worstStall}ms</div>
      <button className="mw-btn" onClick={handler(reset)}>
        reset
      </button>
    </div>
  );
});

const summary = (r: AggregateResult) =>
  `${r.rows.toLocaleString()} rows · ${r.p1.toLocaleString()} P1 · ${Math.round(r.ms)}ms`;

/**
 * 'export' — a CPU-heavy report export (~1.2s). `offload: false` runs it
 * on this render worker's thread; `offload: true` sends it to the compute
 * lane and re-enters the instance when the reply lands.
 */
const ExportApp = islandApp('export', function ExportApp({
  label = 'report',
  budgetMs = 1200,
  offload = false,
}: {
  label?: string;
  budgetMs?: number;
  offload?: boolean;
}) {
  const [last, setLast] = useState('no export yet');
  const [busy, setBusy] = useState(false);
  const [instance] = useState(() => getActiveInstance()!);
  const done = (r: AggregateResult) => {
    setLast(summary(r));
    emit('exported', { label, ms: Math.round(r.ms), rows: r.rows, offloaded: offload });
  };
  return (
    <div className="ops-card ops-export">
      <div className="ops-card-title">{label} export</div>
      <div className="ops-result">{busy ? 'exporting on the compute worker…' : last}</div>
      <button
        className="mw-btn"
        disabled={busy}
        onClick={handler(() => {
          if (!offload) return done(aggregate(budgetMs));
          setBusy(true);
          exportLane.ops.exportReport(budgetMs).then(
            (r) => reenter(instance, () => { setBusy(false); done(r); }),
            (e: unknown) => reenter(instance, () => { setBusy(false); setLast(`export failed: ${String(e)}`); }),
          );
        })}
      >
        export report
      </button>
    </div>
  );
});

/** The nested render definition, same inline-literal rule as computeEntry. */
const regionEntry = (): Worker =>
  new Worker(new URL('./region.worker.tsx', import.meta.url), { type: 'module' });

const subMode = isolated ? 'push' : 'poll';
const SLA_MS = 900;
const MODEL_MS = 1500;
const POOL_SIZE = 3;

interface CardState {
  sla?: string;
  busy?: boolean;
}

/**
 * 'regions' — a regional workspace. Rendering and compute are split:
 *   - every region card AND the forecast panel mount on ONE shared
 *     sub-client (one region.worker, one React runtime);
 *   - recomputes run on a `workers: 3` compute pool (independent, so they
 *     overlap); the model runs on a `workers: 1` compute worker.
 * Cards emit a request, the host runs it, results come back as props.
 */
const RegionsApp = islandApp('regions', function RegionsApp({
  regions = ['us-east', 'eu-central', 'ap-south'],
}: {
  regions?: string[];
}) {
  const [cards] = useState(() => connectIslandWorker({ name: 'region-cards', worker: regionEntry, doorbell: isolated }));
  const [slaPool] = useState(() => connectSubWorker<ComputeWorker>({ name: 'sla', worker: computeEntry, workers: POOL_SIZE }));
  const [modelLane] = useState(() => connectSubWorker<ComputeWorker>({ name: 'model-lane', worker: computeEntry, workers: 1 }));
  const [instance] = useState(() => getActiveInstance()!);
  const [slas, setSlas] = useState<Record<string, CardState>>({});
  const [forecast, setForecast] = useState<{ result?: string; busy: boolean }>({ busy: false });
  const [report, setReport] = useState('no region recomputed yet');

  useEffect(
    () => () => {
      slaPool.terminate();
      modelLane.terminate();
    },
    [slaPool, modelLane],
  );

  const recompute = (list: string[]) => {
    const t0 = performance.now();
    setSlas((s) => ({ ...s, ...Object.fromEntries(list.map((r) => [r, { ...s[r], busy: true }])) }));
    Promise.all(
      list.map((region) =>
        slaPool.ops.sla(region, SLA_MS).then((r) => {
          reenter(instance, () =>
            setSlas((s) => ({
              ...s,
              [region]: { sla: `P1 ${r.p1.toLocaleString()} · mean ${r.meanDur.toFixed(1)}m`, busy: false },
            })),
          );
          return r;
        }),
      ),
    ).then(
      (results) => {
        const wallMs = Math.round(performance.now() - t0);
        const workMs = results.reduce((a, r) => a + Math.round(r.ms), 0);
        reenter(instance, () => {
          setReport(
            list.length === 1
              ? `${list[0]} recomputed in ${wallMs}ms on the compute pool`
              : `${list.length} regions in ${wallMs}ms wall, ${workMs}ms of work, across ${POOL_SIZE} pool workers`,
          );
          emit('regionRecomputed', { regions: list, wallMs, workMs });
        });
      },
      (e: unknown) =>
        reenter(instance, () => {
          setSlas((s) => ({ ...s, ...Object.fromEntries(list.map((r) => [r, { ...s[r], busy: false }])) }));
          setReport(`recompute failed: ${String(e)}`);
        }),
    );
  };

  const runModel = () => {
    setForecast((f) => ({ ...f, busy: true }));
    modelLane.ops.forecast(MODEL_MS).then(
      (r) =>
        reenter(instance, () => {
          setForecast({ busy: false, result: `scored ${r.rows.toLocaleString()} rows in ${Math.round(r.ms)}ms` });
          emit('forecasted', { ms: Math.round(r.ms), rows: r.rows });
        }),
      (e: unknown) => reenter(instance, () => setForecast({ busy: false, result: `model failed: ${String(e)}` })),
    );
  };

  return (
    <div className="ops-regions">
      <div className="ops-sub-head">
        render: {regions.length} region cards + the forecast panel, ONE shared sub-worker (region.worker)
      </div>
      <div className="ops-grid">
        {regions.map((region) => (
          <Island
            key={region}
            client={cards}
            app="region"
            props={{ region, ...slas[region] }}
            mode={subMode}
            framework="react"
            className="ops-sub"
            onEvent={(name) => {
              if (name === 'recompute') recompute([region]);
            }}
          />
        ))}
        <Island
          client={cards}
          app="forecast"
          props={forecast}
          mode={subMode}
          framework="react"
          className="ops-sub"
          onEvent={(name) => {
            if (name === 'runModel') runModel();
          }}
        />
      </div>
      <div className="ops-sub-head">
        compute: recomputes on a {POOL_SIZE}-worker pool (<code>workers: {POOL_SIZE}</code>), the model on one
        worker (<code>workers: 1</code>), compute.worker, no React
      </div>
      <button className="mw-btn ops-all" onClick={handler(() => recompute(regions))}>
        recompute all ({regions.length} in parallel)
      </button>
      <div className="vanilla-readout">{report}</div>
    </div>
  );
});

export const consoleWorker = defineReactPolyWorker({
  apps: { pulse: PulseApp, export: ExportApp, regions: RegionsApp },
});

Notes

  • Mediation is unidirectional: an island's emit lands in onEvent, the shell sets state, and it flows back in as props. No hand-wired updateProps calls.
  • Two fallback phases: <Suspense> for the module load, the proxy's fallback prop for the worker mount.
  • React commits in the dispatch's sync lane: unlike the other frameworks' async schedulers, useLayoutEffect fires while the task still holds the instance, so commit-phase emitneeds no runInInstance re-entry. That's how the incidents benchmark reports its re-render time from a layout effect.
  • Fixed-dimension libs (recharts) get width/height as props: there's no ResizeObserver channel into the worker; measurement reads on the proxy DOM return zero.
  • Structural walls stay walls: closed libraries that need real DOM (Google Maps JS) are housed via transclusion slots or iframe elements: the worker owns the box, the shell owns the contents.