@atolljs/react-island 0.1.0 → 0.1.2

package/README.md

@@ -1,13 +1,17 @@
 # @atolljs/react-island
 
-The React shell surface for `@atolljs/islands` — mount a
-worker-hosted React (or imperative proxy-DOM) tree as an ordinary element
-in a main-thread React app. The worker's render loop produces a serialized
-op stream; this package's components own the mount lifecycle and replay it
-onto a real `div`.
+The React shell surface for `@atolljs/islands` — mount a worker-hosted React
+(or imperative proxy-DOM) tree as an ordinary element in a main-thread React
+app. The worker's render loop produces a serialized op stream; this package's
+components own the mount lifecycle and replay it onto a real `div`.
+
+**[Atoll — package documentation](https://jwhenry3.github.io/atolljs/consumer/quickstart/)**
+
+## Install
 
 ```bash
-npm install @atolljs/core @atolljs/islands @atolljs/react-island react
+npm install @atolljs/core @atolljs/islands @atolljs/react-island react react-dom
+npm install react-reconciler   # worker islands only — the /worker entry's renderer
 ```
 
 ## `<Island/>`
@@ -37,50 +41,31 @@ app itself — stamp it once with `islandApp` and both sides share one handle:
 // worker/apps.tsx — the stamp is a data property, minification-proof
 export const ChartsApp = islandApp('charts', function ChartsApp(props: ChartsProps) { ... });
 export const mapApp = islandApp('map', { imperative: buildMap });
-// worker entry: apps: { charts: ChartsApp, map: mapApp }   (definePolyWorker
-// warns if a stamp and its registry key drift apart)
+// worker entry: apps: { charts: ChartsApp, map: mapApp }
 ```
 
-`IslandAppProps` infers `props` from the reference's signature — a React
-component's own props or an imperative def's props parameter — so
-`props={{missing: 1}}` fails to compile. Bare (unstamped) components fall
-back to `displayName`/function name for the wire key — dev convenience;
-bundlers mangle `fn.name`, which is what the stamp exists for.
-
-The rendered `div` is the island's container — `className`/`style`/`data-*`
-spread onto it. Mounting is async (worker spawn + first op batch in an
-effect, cancellation-safe); `props` changes call `updateProps`, deduped by
-serialized identity so equal props don't cost a round-trip. `onEvent`/
-`slots`/`onActivity` are read through refs — fresh closures never remount.
-`app` remounts on change; `worker`/`client` are mount-stable (use `key` to
-swap). Unmount destroys the island and terminates its worker. All the
-[islands island rules](../islands/README.md#island-rules) apply
-unchanged.
-
-`examples/react-dom-worker/react-shell.html` mounts all seven demo islands
-this way — worth a look for the mediation pattern (`onEvent → setState →
-<Island props>` replaces hand-wired `updateProps`).
+`IslandAppProps` infers `props` from the reference's signature, so
+`props={{missing: 1}}` fails to compile. The rendered `div` is the island's
+container — `className`/`style`/`data-*` spread onto it. Mounting is async and
+cancellation-safe; `props` changes call `updateProps` (deduped by serialized
+identity); unmount destroys the island and terminates its worker.
 
 ## Worker-loaded component proxies
 
-`islandComponent` and `lazyIsland` go one step further: they return a
-component that takes the **worker app's props inline** — the island looks
-and types like a local component. Every prop that isn't a shell concern
-(`worker`/`client`/`onEvent`/`onReady`/`onError`/`onActivity`/`slots`/
-`fallback`/`containerProps`) forwards as the island's props.
+`islandComponent` and `lazyIsland` return a component that takes the **worker
+app's props inline** — the island looks and types like a local component:
 
 ```tsx
 import { islandComponent, lazyIsland } from '@atolljs/react-island';
-import type { TableProps } from './worker/apps'; // type-only: erased, zero bundle cost
+import type { TableProps } from './worker/apps'; // type-only: zero bundle cost
 
-// The pure-contract proxy — the shell NEVER imports the implementation.
-// Registry key + props type IS the contract; the worker owns the code.
+// Pure-contract proxy — the shell NEVER imports the implementation.
 const TableIsland = islandComponent<TableProps>('data-table');
 <TableIsland worker={renderWorker} filter={filter} desc onEvent={…} />
 
-// The React.lazy mirror — suspends while the module loads, then mounts by
-// stamped component reference. The dynamic import is a real split point:
-// the worker component's deps only load when the island mounts.
+// React.lazy mirror — suspends on the module load (a real split point:
+// the worker component's deps only load when the island mounts), then
+// mounts by stamped reference.
 const ChartsIsland = lazyIsland(() =>
   import('./worker/apps').then((m) => ({ default: m.ChartsApp })),
 );
@@ -89,38 +74,46 @@ const ChartsIsland = lazyIsland(() =>
 </Suspense>
 ```
 
-One asymmetry vs `React.lazy`, by construction: the *loader* suspends but
-the *mount* can't — suspended trees never commit, and mounting needs the
-container div in the DOM. The mount window is covered by the `fallback`
-prop instead of Suspense. `lazyIsland` also fixes the bundle caveat from
-`<Island app={Comp}>`: a static import pulls the worker component's deps
-(recharts in the demo: +~500 kB) into the shell chunk eagerly; the lazy
-path splits them out, and `islandComponent` never imports them at all.
-
-`islandComponent` overloads: `islandComponent<P>('name')` for the
-type-contract form above, or `islandComponent(StampedApp)` to infer `P`
-from a stamped reference the shell already has.
+The mount window is covered by the `fallback` prop (suspended trees never
+commit, so mounting can't suspend). `islandComponent` also takes a stamped
+reference (`islandComponent(StampedApp)`) to infer `P` instead of a key +
+type parameter.
 
-## Worker topologies — registry, instance, shared client
+## Worker topologies
 
-Two worker entry points, mixable in one app:
+The worker side lives in `@atolljs/react-island/worker` — the entry that
+pulls `react` + `react-reconciler` into the worker bundle:
 
 ```ts
 // render.worker.ts — REGISTRY worker: one script, many named apps
-export const renderWorker = definePolyWorker({ apps: { charts: ChartsApp, table: TableApp } });
+import { defineReactPolyWorker } from '@atolljs/react-island/worker';
+export const renderWorker = defineReactPolyWorker({ apps: { charts: ChartsApp, table: TableApp } });
 
-// map.worker.ts — REALM worker: one script, ONE app (1:1)
-export const mapWorker = defineMonoWorker(mapApp);
+// map.worker.ts — MONO worker: one script, ONE app (1:1), mounted namelessly
+import { defineReactMonoWorker } from '@atolljs/react-island/worker';
+export const mapWorker = defineReactMonoWorker(mapApp);
 ```
 
-A instance worker's app resolves regardless of the requested registry name, so
-the shell mounts it **namelessly** — `<Island worker={mapWorker}/>` or
-`islandComponent<P>()` with no key — and its bundle carries only that app's
-dependencies. `lazyIsland` accepts the worker module itself as the contract:
-`lazyIsland(() => import('./worker/map.worker'))` resolves `{ app, worker }`
-so the island carries its own worker.
-
-For multi-island-per-worker, share a client: `client={connectIslandWorker({ worker })}`
-mounts each island's instance into the SAME worker (separate reconcilers, op
-queues, and pids — one OS thread). `destroy()` on one island unmounts just
-its instance; the worker dies with the last island to leave.
+For a mixed-framework registry, use `@atolljs/islands/worker`'s
+`definePolyWorker` and wrap each React app in `reactIslandApp(App)` —
+non-React registries never see this entry, so they ship zero React.
+`<Slot/>`, `emit`, and `runInInstance` re-export from `/worker` too, so an
+app's worker imports need no second specifier.
+
+A mono worker's app resolves regardless of the requested registry name — mount
+it with `<Island worker={mapWorker}/>` or `islandComponent<P>()` with no key.
+`lazyIsland` accepts the worker module itself as the contract:
+`lazyIsland(() => import('./worker/map.worker'))` resolves `{ app, worker }`.
+
+For multi-island-per-worker, share a client:
+`client={connectIslandWorker({ worker })}` mounts each island's instance into
+the SAME worker (separate reconcilers, op queues, and pids — one OS thread).
+
+## Documentation
+
+- [Atoll — package documentation](https://jwhenry3.github.io/atolljs/consumer/quickstart/)
+- [Worker islands for React](https://jwhenry3.github.io/atolljs/consumer/fw-react/worker-islands/)
+- [Worker islands](https://jwhenry3.github.io/atolljs/consumer/islands/) —
+  `mountIsland` options, `IslandHandle`, island rules
+- In-repo internals: [`docs/islands.md`](../../docs/islands.md),
+  [`docs/islands-worker.md`](../../docs/islands-worker.md)

package/package.json

@@ -1,25 +1,38 @@
 {
   "name": "@atolljs/react-island",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "React shell components for atoll-islands islands — <Island/>, islandComponent, lazyIsland",
+  "homepage": "https://jwhenry3.github.io/atolljs/consumer/quickstart/",
   "type": "module",
   "exports": {
-    ".": "./src/index.tsx"
+    ".": "./src/index.tsx",
+    "./worker": "./src/worker.ts"
   },
   "files": [
     "src"
   ],
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
   },
   "peerDependencies": {
-    "@atolljs/core": "0.1.0",
-    "@atolljs/islands": "0.1.0",
-    "react": "^19.3.0"
+    "@atolljs/core": "0.1.2",
+    "@atolljs/islands": "0.1.2",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "react-reconciler": "^0.34.0"
+  },
+  "peerDependenciesMeta": {
+    "react-reconciler": {
+      "optional": true
+    }
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/jwhenry3/atolljs",
     "directory": "packages/react-island"
+  },
+  "bugs": {
+    "url": "https://github.com/jwhenry3/atolljs/issues"
   }
 }

package/src/hostConfig.ts

@@ -0,0 +1,449 @@
+/**
+ * React-reconciler host adapter for the worker DOM backend.
+ *
+ * The generic instance state (op queues, instance ids, handler registry,
+ * doorbell, geometry) lives in `@atolljs/islands/worker`'s instance module.
+ * This file only wires the reconciler's create/append/update/remove/commit
+ * hooks to that backend.
+ *
+ * react-reconciler@0.34 reads ~150 fields off the config object. Most are
+ * stubs for features this renderer doesn't implement (hydration,
+ * persistence, resources, singletons, view transitions, test selectors,
+ * scope/hydratable APIs) — they exist so nothing throws when the reconciler
+ * destructures them; they are never invoked behind the `supports*` flags.
+ */
+
+import { createContext } from 'react';
+import {
+  bumpOpsVersion,
+  docForInstance,
+  getActiveInstance,
+  getLastActiveInstance,
+  instances,
+  newElement,
+  newText,
+  pushOp,
+  serializeProps,
+  unregisterHandler,
+  type ElementInstance,
+  type HostInstance,
+  type ProxyNode,
+  type RootContainer,
+  type TextInstance,
+} from '@atolljs/islands/worker';
+
+/* ── Event-priority plumbing ────────────────────────────────────────────── */
+/*
+ * React 19 expresses event priorities as lane numbers: 2 = discrete
+ * (click/keydown → SyncLane), 8 = continuous, 32 = default, 0 = none. The
+ * reconciler calls setCurrentUpdatePriority around its own flushes
+ * (flushSyncFromReconciler sets 2), so honoring the set/get pair and echoing
+ * the value back from resolveUpdatePriority is all that's needed.
+ */
+let currentUpdatePriority = 0;
+const DEFAULT_EVENT_PRIORITY = 32;
+
+/* ── React-19 transition context (must be real React objects) ───────────── */
+
+const NotPendingTransition = Object.freeze({ pending: false, data: null, method: null, action: null });
+const HostTransitionContext = createContext(NotPendingTransition);
+
+const noop = (): void => {};
+const NULL = (): null => null;
+const FALSE = (): boolean => false;
+const TRUE = (): boolean => true;
+
+/* ── Refs & portals ───────────────────────────────────────────────────────
+ *
+ * React refs must receive an object the COMPONENT treats as "the element" —
+ * for React DOM that's the real DOM node, for us the closest truthful thing
+ * is the proxy DOM's facade (it navigates the shadow tree, mutates via ops,
+ * and reports `nodeType === 1`). getPublicInstance therefore adopts the
+ * host instance into a per-instance proxy document, created lazily so React
+ * mounts only pay for it when something actually holds a ref.
+ *
+ * This is what makes react-dom's `createPortal(children, ref.current)` work
+ * here: isValidContainer() only checks nodeType, the portal fiber then feeds
+ * the facade back as `containerInfo`, and the container-level methods below
+ * unwrap `.instance` so portal children land inside the real target node —
+ * that is the entire recharts <Tooltip>/<Legend> path.
+ */
+const publicInstanceFor = (instance: HostInstance): ProxyNode | HostInstance =>
+  docForInstance(instance.instance).adopt(instance);
+
+/**
+ * Portal `containerInfo` is the public instance (a ProxyElement) the caller
+ * passed to createPortal; the ROOT_CONTAINER sentinel and raw instances keep
+ * their own `id`. Anything unrecognizable falls back to the island root.
+ */
+const containerParentId = (container: unknown): number => {
+  const inst = (container as { instance?: { id?: unknown } } | null)?.instance;
+  if (inst && typeof inst.id === 'number') return inst.id;
+  const id = (container as { id?: unknown } | null)?.id;
+  return typeof id === 'number' ? id : 0;
+};
+
+/**
+ * The instance a create should bind to — read off the root container for
+ * ordinary renders, off the portal container's wrapped instance for portal
+ * subtrees (a ProxyElement, whose `.instance` field doesn't exist but whose
+ * `.instance.instance` does), finally falling back to ambient instance state.
+ */
+const containerInstance = (container: unknown): string => {
+  // `.instance` is the instance KEY on a RootContainer/raw host record and
+  // the host RECORD on a ProxyElement (portal containers) — disambiguate
+  // by shape: a string IS the key; a record holds `.instance.instance`.
+  const inner = (container as { instance?: unknown } | null)?.instance;
+  if (typeof inner === 'string') return inner;
+  return (inner as { instance?: string } | undefined)?.instance ??
+    (getActiveInstance() !== '' ? getActiveInstance() : getLastActiveInstance());
+};
+
+/* Host context = DOM namespace tracking, same role it plays in React DOM:
+ * `getChildHostContext` flips the namespace when the element type requires
+ * it, and `createInstance` stamps the result on the instance so the `create`
+ * op can tell the driver to createElementNS. Recharts-style SVG trees need
+ * this — without it every <svg>/<path> would arrive as an HTMLUnknownElement. */
+interface HostContext {
+  ns?: string;
+}
+const SVG_NS = 'http://www.w3.org/2000/svg';
+const MATH_NS = 'http://www.w3.org/1998/Math/MathML';
+const HTML_CTX: HostContext = Object.freeze({});
+const SVG_CTX: HostContext = Object.freeze({ ns: SVG_NS });
+const MATH_CTX: HostContext = Object.freeze({ ns: MATH_NS });
+
+/** The namespace context a host element gives its children — and the
+ *  namespace the element itself belongs to (getChildNamespace semantics:
+ *  <svg> in HTML is SVG, foreignObject/desc/title flip back to HTML). */
+const childHostContextFor = (parent: HostContext, type: string): HostContext => {
+  if (type === 'svg') return SVG_CTX;
+  if (type === 'math') return MATH_CTX;
+  if (type === 'foreignObject' || type === 'desc' || type === 'title') return HTML_CTX;
+  return parent;
+};
+
+/* ── The host config ────────────────────────────────────────────────────── */
+
+export const hostConfig = {
+  // Identity / capabilities
+  rendererVersion: '0.34.0',
+  rendererPackageName: '@atolljs/react-island',
+  extraDevToolsConfig: null,
+  isPrimaryRenderer: true,
+  warnsIfNotActing: false,
+  supportsMutation: true,
+  supportsPersistence: false,
+  supportsHydration: false,
+  supportsResources: false,
+  supportsSingletons: false,
+  supportsMicrotasks: false,
+  supportsTestSelectors: false,
+
+  getPublicInstance: (instance: HostInstance): unknown => publicInstanceFor(instance),
+  // Host contexts must be non-null objects (the reconciler pushes them on a
+  // context stack and warns "Expected host context to exist" on null). This
+  // renderer carries no per-subtree context — echo a single frozen sentinel.
+  // Host contexts must be non-null objects (the reconciler warns on null).
+  // Ours carries only the element namespace: <svg>/<math> enter their
+  // namespaces; foreignObject/desc/title are HTML-integration points that
+  // flip children back to HTML; everything else inherits the parent's.
+  // For portals, this becomes the context the portal subtree renders under —
+  // derived from the container's own namespace so children of an SVG portal
+  // target (recharts zIndex <g> layers) stay in the SVG namespace.
+  getRootHostContext: (container: unknown): HostContext => {
+    const ns = (container as { instance?: { ns?: string } } | null)?.instance?.ns;
+    if (ns === SVG_NS) return SVG_CTX;
+    if (ns === MATH_NS) return MATH_CTX;
+    return HTML_CTX;
+  },
+  getChildHostContext: (parent: HostContext, type: string): HostContext =>
+    childHostContextFor(parent, type),
+  prepareForCommit: NULL,
+  // The doorbell: every commit bumps opsVersion once — the main thread's
+  // observe() wakes (Atomics.waitAsync) and flushes the op queue, so commits
+  // made outside task calls (effects, timers, async setState) arrive as a
+  // push instead of waiting on a poll. Task-returned ops bump too; the
+  // follow-up flush just finds an empty queue.
+  resetAfterCommit: bumpOpsVersion,
+
+  // Creation — emit ops
+  createInstance: (
+    type: string,
+    props: Record<string, unknown>,
+    rootContainer: unknown,
+    hostContext: unknown,
+    _internalHandle: unknown,
+  ): ElementInstance => {
+    // The element's own namespace = the child context its TYPE produces
+    // under the parent's context — the same computation React DOM runs
+    // (getChildNamespace): <svg> in HTML is itself SVG, <foreignObject> in
+    // SVG is itself HTML. Instance comes from the container (see RootContainer).
+    const ctx = childHostContextFor(hostContext as HostContext, type);
+    const instance = newElement(type, props, ctx.ns, containerInstance(rootContainer));
+    pushOp(instance.instance, {
+      t: 'create',
+      id: instance.id,
+      type,
+      props: instance.props,
+      ns: instance.ns,
+    });
+    return instance;
+  },
+  createTextInstance: (
+    text: string,
+    rootContainer: unknown,
+    _hostContext: unknown,
+    _internalHandle: unknown,
+  ): TextInstance => {
+    const instance = newText(text, containerInstance(rootContainer));
+    pushOp(instance.instance, { t: 'text', id: instance.id, text });
+    return instance;
+  },
+  finalizeInitialChildren: FALSE,
+  // Always false: string/number children become real text instances, so the
+  // tree arrives as linear ops and `utext` handles every text update. (The
+  // `true` path would expect commitUpdate to set textContent from
+  // props.children — which we deliberately never serialize.)
+  shouldSetTextContent: FALSE,
+
+  // Tree wiring — emit ops
+  appendInitialChild: (parent: HostInstance, child: HostInstance): void => {
+    pushOp(parent.instance, { t: 'append', parent: parent.id, child: child.id });
+  },
+  appendChild: (parent: HostInstance, child: HostInstance): void => {
+    pushOp(parent.instance, { t: 'append', parent: parent.id, child: child.id });
+  },
+  appendChildToContainer: (container: unknown, child: HostInstance): void => {
+    pushOp(child.instance, { t: 'append', parent: containerParentId(container), child: child.id });
+  },
+  insertBefore: (parent: HostInstance, child: HostInstance, before: HostInstance): void => {
+    pushOp(parent.instance, { t: 'append', parent: parent.id, child: child.id, before: before.id });
+  },
+  insertInContainerBefore: (container: unknown, child: HostInstance, before: HostInstance): void => {
+    pushOp(child.instance, {
+      t: 'append',
+      parent: containerParentId(container),
+      child: child.id,
+      before: before.id,
+    });
+  },
+  removeChild: (_parent: HostInstance, child: HostInstance): void => {
+    pushOp(child.instance, { t: 'remove', child: child.id });
+  },
+  removeChildFromContainer: (_container: unknown, child: HostInstance): void => {
+    pushOp(child.instance, { t: 'remove', child: child.id });
+  },
+  // No instance argument — routed by the task's active instance (only reached
+  // inside mount/remount's syncCommit).
+  clearContainer: (): void => {
+    pushOp(getActiveInstance(), { t: 'clear' });
+  },
+
+  // Updates — emit ops
+  commitUpdate: (
+    instance: ElementInstance,
+    _type: string,
+    _oldProps: Record<string, unknown>,
+    newProps: Record<string, unknown>,
+    _internalHandle: unknown,
+  ): void => {
+    // Serialize first so the op carries the latest props; re-serialization
+    // also re-registers event handlers against the current closure.
+    instance.props = serializeProps(instance, newProps);
+    pushOp(instance.instance, { t: 'update', id: instance.id, props: instance.props });
+  },
+  commitTextUpdate: (instance: TextInstance, _oldText: string, newText: string): void => {
+    instance.text = newText;
+    pushOp(instance.instance, { t: 'utext', id: instance.id, text: newText });
+  },
+  commitMount: noop,
+  // Unreachable while shouldSetTextContent is always false; still emit the
+  // spec'd op for completeness.
+  resetTextContent: (instance: ElementInstance): void => {
+    instance.props = {};
+    pushOp(instance.instance, { t: 'update', id: instance.id, props: {} });
+  },
+
+  // Suspense visibility — `hidden` is a global HTML attribute the main
+  // thread applies like any other prop.
+  hideInstance: (instance: ElementInstance): void => {
+    pushOp(instance.instance, { t: 'update', id: instance.id, props: { ...instance.props, hidden: true } });
+  },
+  unhideInstance: (instance: ElementInstance): void => {
+    pushOp(instance.instance, { t: 'update', id: instance.id, props: { ...instance.props } });
+  },
+  hideTextInstance: (instance: TextInstance): void => {
+    pushOp(instance.instance, { t: 'utext', id: instance.id, text: '' });
+  },
+  unhideTextInstance: (instance: TextInstance, text: string): void => {
+    pushOp(instance.instance, { t: 'utext', id: instance.id, text });
+  },
+
+  // GC hook — drop the record and its handler slots.
+  detachDeletedInstance: (instance: HostInstance): void => {
+    instances.delete(instance.id);
+    if (instance.kind === 'element') {
+      for (const hid of Object.values(instance.listenerSlots)) unregisterHandler(hid);
+    }
+  },
+
+  // Scheduler
+  scheduleTimeout: setTimeout,
+  cancelTimeout: clearTimeout,
+  noTimeout: -1,
+  // supportsMicrotasks is false, so the reconciler schedules root work via
+  // the `scheduler` package (MessageChannel in a worker). This export is
+  // still destructured — provide a real one for completeness.
+  scheduleMicrotask: (fn: () => void): void => queueMicrotask(fn),
+
+  // Event priorities (see note above — values are lane numbers).
+  setCurrentUpdatePriority: (p: number): void => {
+    currentUpdatePriority = p;
+  },
+  getCurrentUpdatePriority: (): number => currentUpdatePriority,
+  resolveUpdatePriority: (): number =>
+    currentUpdatePriority !== 0 ? currentUpdatePriority : DEFAULT_EVENT_PRIORITY,
+  resolveEventType: NULL,
+  resolveEventTimeStamp: (): number => -1.1,
+  trackSchedulerEvent: noop,
+  shouldAttemptEagerTransition: FALSE,
+
+  // Events/portals/scopes — no DOM event system exists worker-side.
+  getInstanceFromNode: NULL,
+  beforeActiveInstanceBlur: noop,
+  afterActiveInstanceBlur: noop,
+  preparePortalMount: noop,
+  prepareScopeUpdate: noop,
+  getInstanceFromScope: NULL,
+
+  // React 19 "suspend on commit" — never suspend.
+  requestPostPaintCallback: noop,
+  maySuspendCommit: FALSE,
+  maySuspendCommitOnUpdate: FALSE,
+  maySuspendCommitInSyncRender: FALSE,
+  preloadInstance: TRUE,
+  startSuspendingCommit: noop,
+  suspendInstance: noop,
+  suspendOnActiveViewTransition: noop,
+  waitForCommitToBeReady: NULL,
+  getSuspendedCommitReason: () => 0,
+
+  // Transitions / forms / console
+  NotPendingTransition,
+  HostTransitionContext,
+  resetFormInstance: noop,
+  bindToConsole: (methodName: string, args: unknown[]) =>
+    (console as unknown as Record<string, (...a: unknown[]) => void>)[methodName]?.bind(console, ...args) ??
+    noop,
+
+  // Persistence (supportsPersistence: false — destructured, never called)
+  createContainerChildSet: () => [],
+  appendChildToContainerChildSet: noop,
+  finalizeContainerChildren: noop,
+  replaceContainerChildren: noop,
+  cloneInstance: NULL,
+  cloneMutableInstance: (instance: HostInstance) => instance,
+  cloneMutableTextInstance: (instance: HostInstance) => instance,
+  cloneHiddenInstance: (instance: HostInstance) => instance,
+  cloneHiddenTextInstance: (instance: HostInstance) => instance,
+
+  // Fragment instances (only used for `<Fragment ref={…}>` — unimplemented)
+  createFragmentInstance: () => ({}),
+  updateFragmentInstanceFiber: noop,
+  commitNewChildToFragmentInstance: noop,
+  deleteChildFromFragmentInstance: noop,
+
+  // View transitions (React 19) — all stubs
+  createViewTransitionInstance: (name: string) => ({ name, autoName: null }),
+  applyViewTransitionName: noop,
+  restoreViewTransitionName: noop,
+  cancelViewTransitionName: noop,
+  cancelRootViewTransitionName: noop,
+  restoreRootViewTransitionName: noop,
+  cloneRootViewTransitionContainer: noop,
+  removeRootViewTransitionClone: noop,
+  measureInstance: NULL,
+  measureClonedInstance: NULL,
+  wasInstanceInViewport: FALSE,
+  hasInstanceChanged: FALSE,
+  hasInstanceAffectedParent: FALSE,
+  startViewTransition: NULL,
+  startGestureTransition: NULL,
+  stopViewTransition: noop,
+  addViewTransitionFinishedListener: noop,
+  getCurrentGestureOffset: () => 0,
+
+  // Hydration (supportsHydration: false — destructured, never called)
+  isSuspenseInstancePending: FALSE,
+  isSuspenseInstanceFallback: FALSE,
+  getSuspenseInstanceFallbackErrorDetails: () => ({}),
+  registerSuspenseInstanceRetry: noop,
+  getNextHydratableSibling: NULL,
+  getNextHydratableSiblingAfterSingleton: NULL,
+  getFirstHydratableChild: NULL,
+  getFirstHydratableChildWithinContainer: NULL,
+  getFirstHydratableChildWithinActivityInstance: NULL,
+  getFirstHydratableChildWithinSingleton: NULL,
+  getFirstHydratableChildWithinSuspenseInstance: NULL,
+  canHydrateInstance: NULL,
+  canHydrateTextInstance: NULL,
+  canHydrateActivityInstance: NULL,
+  canHydrateSuspenseInstance: NULL,
+  canHydrateFormStateMarker: NULL,
+  isFormStateMarkerMatching: FALSE,
+  hydrateInstance: noop,
+  hydrateTextInstance: noop,
+  hydrateActivityInstance: noop,
+  hydrateSuspenseInstance: noop,
+  getNextHydratableInstanceAfterActivityInstance: NULL,
+  getNextHydratableInstanceAfterSuspenseInstance: NULL,
+  commitHydratedInstance: noop,
+  commitHydratedContainer: noop,
+  commitHydratedSuspenseInstance: noop,
+  finalizeHydratedChildren: FALSE,
+  flushHydrationEvents: noop,
+  clearActivityBoundary: FALSE,
+  clearSuspenseBoundary: FALSE,
+  clearActivityBoundaryFromContainer: FALSE,
+  clearSuspenseBoundaryFromContainer: FALSE,
+  hideDehydratedBoundary: noop,
+  unhideDehydratedBoundary: noop,
+  shouldDeleteUnhydratedTailInstances: FALSE,
+  diffHydratedPropsForDevWarnings: NULL,
+  diffHydratedTextForDevWarnings: NULL,
+  describeHydratableInstanceForDevWarnings: NULL,
+  validateHydratableInstance: TRUE,
+  validateHydratableTextInstance: TRUE,
+
+  // Host resources (stylesheets/scripts — supportsResources: false)
+  isHostHoistableType: FALSE,
+  getHoistableRoot: NULL,
+  getResource: NULL,
+  acquireResource: noop,
+  releaseResource: noop,
+  hydrateHoistable: noop,
+  mountHoistable: noop,
+  unmountHoistable: noop,
+  createHoistableInstance: NULL,
+  prepareToCommitHoistables: noop,
+  mayResourceSuspendCommit: FALSE,
+  preloadResource: TRUE,
+  suspendResource: noop,
+
+  // Singletons (supportsSingletons: false)
+  resolveSingletonInstance: NULL,
+  acquireSingletonInstance: noop,
+  releaseSingletonInstance: noop,
+  isHostSingletonType: FALSE,
+  isSingletonScope: FALSE,
+
+  // Test selectors (supportsTestSelectors: false)
+  findFiberRoot: NULL,
+  getBoundingRect: NULL,
+  getTextContent: NULL,
+  isHiddenSubtree: FALSE,
+  matchAccessibilityRole: FALSE,
+  setFocusIfFocusable: FALSE,
+  setupIntersectionObserver: noop,
+};

package/src/index.tsx

@@ -82,8 +82,13 @@ export interface IslandProps<A = string>
    */
   worker?: (() => Worker) | URL;
   client?: IslandClient;
-  /** Extra pool options — concurrency, taskTimeout, respawn… (poolSize stays 1). */
-  workerOptions?: IslandWorkerOptions;
+  /**
+   * Extra pool options — concurrency, taskTimeout, respawn… (poolSize stays
+   * 1). `doorbell: false` builds the shorthand client message-only — no
+   * SharedArrayBuffer, no COOP/COEP requirement (same as `mode: 'poll'` on
+   * a direct `mountIsland` shorthand mount).
+   */
+  workerOptions?: IslandWorkerOptions & { doorbell?: boolean };
   /**
    * Initial flush mode — 'push' (default) drives op replay off the
    * shared-memory doorbell (needs cross-origin isolation); 'poll' drains on
@@ -272,7 +277,8 @@ export interface IslandShellProps {
   /** How to reach the worker — see IslandProps.worker/client. */
   worker?: (() => Worker) | URL;
   client?: IslandClient;
-  workerOptions?: IslandWorkerOptions;
+  /** See IslandProps.workerOptions — `doorbell` included. */
+  workerOptions?: IslandWorkerOptions & { doorbell?: boolean };
   /** Initial flush mode — see IslandProps.mode. */
   mode?: Mode;
   /** Island → shell channel: every `emit` op lands here. */
@@ -323,12 +329,14 @@ const splitProxyProps = (
 
 /* ── Shared proxy implementation ─────────────────────────────────────────── */
 
-type LazyModule<A> = A | { default: A } | { app: A; worker?: (() => Worker) | URL };
+type LazyModule<A> = A | { default: A } | { app: A | string; worker?: (() => Worker) | URL };
 
 /** Cached state for a lazy loader. One cache entry per loader function. */
 interface LazyState {
   promise: Promise<unknown>;
-  value?: IslandAppLike;
+  // Contract modules may carry a registry-key string instead of the app —
+  // `Island`'s `app` prop accepts `IslandAppRef` (name or reference).
+  value?: IslandAppLike | string;
   worker?: (() => Worker) | URL;
   error?: unknown;
 }
@@ -337,7 +345,7 @@ const lazyCache = new WeakMap<() => Promise<LazyModule<IslandAppLike>>, LazyStat
 
 /** Resolve a lazy module through Suspense; reused across re-renders. */
 function useLazyApp(loader: () => Promise<LazyModule<IslandAppLike>>): {
-  app?: IslandAppLike;
+  app?: IslandAppLike | string;
   worker?: (() => Worker) | URL;
 } {
   let state = lazyCache.get(loader);

package/src/react-reconciler.d.ts

@@ -0,0 +1,18 @@
+/**
+ * react-reconciler ships no TypeScript types. It is a CommonJS factory —
+ * `Reconciler(hostConfig)` returns the reconciler API (createContainer,
+ * updateContainer, flushSyncWork, flushSyncFromReconciler, flushPassiveEffects…).
+ * The host config surface is documented in hostConfig.ts.
+ */
+declare module 'react-reconciler' {
+  const createReconciler: (hostConfig: unknown) => {
+    createContainer: (...args: unknown[]) => unknown;
+    updateContainer: (...args: unknown[]) => unknown;
+    updateContainerSync: (...args: unknown[]) => unknown;
+    flushSyncWork: () => unknown;
+    flushSyncFromReconciler: <T>(fn: () => T) => T;
+    flushPassiveEffects: () => boolean;
+    [key: string]: unknown;
+  };
+  export default createReconciler;
+}

package/src/reactInstance.ts

@@ -0,0 +1,76 @@
+/**
+ * The React-runtime half of a React island — `react`, `react-reconciler`
+ * and the host config live HERE so a worker bundle whose registry holds only
+ * non-React apps (Vue/Svelte/Solid/Angular/imperative) never pulls the
+ * reconciler in. `@atolljs/react-island/worker` reaches this module through
+ * `reactIslandApp`'s mount, inside the RenderedIslandApp contract.
+ */
+import type { ReactElement } from 'react';
+import Reconciler from 'react-reconciler';
+import { hostConfig } from './hostConfig';
+import type { RootContainer } from '@atolljs/islands/worker';
+
+/**
+ * A mounted React tree — carries its own reconciler + container and the
+ * `render`/`unmountTree`/`flush` verbs the adapter maps onto the
+ * RenderedHandle contract. Identity (key/app/pid) lives on the core
+ * Instance — this object is only the renderer half.
+ */
+export interface ReactInstance {
+  reconciler: ReturnType<typeof Reconciler>;
+  container: unknown;
+  /**
+   * Commit synchronously around `fn`.
+   *
+   * In 0.34, `updateContainer`/setState only *schedule* work — the actual
+   * render+commit happens when the root scheduler task runs (a macrotask via
+   * the `scheduler` package). `flushSyncFromReconciler` pins the update
+   * priority to the discrete/sync lane for the duration of `fn` and
+   * `flushSyncWork` flushes pending sync work, so by the time it returns the
+   * mutation hooks have run and the instance's op queue is full.
+   */
+  sync(fn: () => void): void;
+  /** Schedule a mount/re-render of `el` — call inside `sync`. */
+  render(el: ReactElement): void;
+  /** Schedule the detach — emits the remove ops; call inside `sync`. */
+  unmountTree(): void;
+  /** Passive effects + pending sync work — the `flush` task's React branch. */
+  flush(): void;
+}
+
+/**
+ * Legacy root (tag 0) — no concurrent features. Container creation is
+ * per-instance, not module-level, so a second mount() can't collide with the
+ * first instance's tree.
+ */
+export function createReactInstance(instance: string): ReactInstance {
+  const reconciler = Reconciler(hostConfig);
+  const container = reconciler.createContainer(
+    // Instance-stamped root container — createInstance reads `.instance` off it,
+    // binding every element to this instance even in out-of-task commits.
+    { id: 0, instance } as RootContainer,
+    0,
+    null,
+    false,
+    null,
+    '',
+    console.error, // onUncaughtError
+    console.error, // onCaughtError
+    console.error, // onRecoverableError
+    null, // onDefaultTransitionIndicator
+  );
+  return {
+    reconciler,
+    container,
+    sync: (fn) => {
+      reconciler.flushSyncFromReconciler(fn);
+      reconciler.flushSyncWork();
+    },
+    render: (el) => reconciler.updateContainer(el, container, null, null),
+    unmountTree: () => reconciler.updateContainer(null, container, null, null),
+    flush: () => {
+      reconciler.flushPassiveEffects();
+      reconciler.flushSyncWork();
+    },
+  };
+}

package/src/slot.tsx

@@ -0,0 +1,18 @@
+/**
+ * A transclusion slot — renders a leaf element marked `data-atoll-slot`.
+ * The element's BOX belongs to this worker tree (layout/style ops apply as
+ * usual); its CONTENTS belong to the shell: when the create op lands on the
+ * main thread, the island's `slots[name]` callback gets the real element
+ * and can mount anything inside — a canvas, Monaco, a main-thread React
+ * root — all real DOM with real events and zero wire traffic.
+ *
+ * Must stay a LEAF in this tree: if worker-side children were appended here
+ * their ops would interleave with shell-owned content. There is also no
+ * measurement channel — the island knows the box it laid out, not the
+ * pixel size the shell put inside it.
+ */
+import type { ReactElement } from 'react';
+
+export function Slot({ name, style }: { name: string; style?: Record<string, unknown> }): ReactElement {
+  return <div data-atoll-slot={name} style={style} />;
+}

package/src/worker.ts

@@ -0,0 +1,139 @@
+/**
+ * `@atolljs/react-island/worker` — the worker-side half of React
+ * islands: `reactIslandApp(Component)` wraps a React component as a islands
+ * `RenderedIslandApp`, so it can sit in a `definePolyWorker` `apps`
+ * registry beside Vue/Svelte/Solid/Angular and imperative apps:
+ *
+ *   // render.worker.ts — React-only registry
+ *   import { defineReactPolyWorker } from '@atolljs/react-island/worker';
+ *   export const renderWorker = defineReactPolyWorker({
+ *     apps: { controls: ControlsApp, charts: ChartsApp },
+ *   });
+ *
+ *   // one-app worker
+ *   import { defineReactMonoWorker } from '@atolljs/react-island/worker';
+ *   export const worker = defineReactMonoWorker(ChartsApp);
+ *
+ *   // mixed-framework registry — compose the adapters directly
+ *   import { definePolyWorker } from '@atolljs/islands/worker';
+ *   import { reactIslandApp } from '@atolljs/react-island/worker';
+ *   export const renderWorker = definePolyWorker({ apps: {
+ *     charts: reactIslandApp(ChartsApp),
+ *     badge: vueIslandApp(VueBadge),
+ *   }});
+ *
+ * The reconciler + host config live in `reactInstance.ts`/`hostConfig.ts`:
+ * importing THIS module is what pulls `react` + `react-reconciler` into a
+ * worker bundle (once, shared across every React app in the registry).
+ * `@atolljs/islands/worker` itself stays framework-neutral — non-React
+ * registries never see this code.
+ */
+import { createElement, type ComponentType } from 'react';
+import type { SharedMemory, WorkerDefinition } from '@atolljs/core';
+import {
+  defineMonoWorker,
+  definePolyWorker,
+  islandApp,
+  islandAppNameOf,
+} from '@atolljs/islands/worker';
+import type {
+  DoorbellSpec,
+  ImperativeIslandApp,
+  IslandWorkerMethods,
+  RenderContext,
+  RenderedHandle,
+  RenderedIslandApp,
+} from '@atolljs/islands/worker';
+import { createReactInstance } from './reactInstance';
+
+// Worker entries shouldn't need a second package specifier for the
+// island→shell channel — `import { emit } from '@atolljs/react-island/worker'`.
+export { emit, runInInstance } from '@atolljs/islands/worker';
+export { Slot } from './slot';
+
+type AnyComponent = ComponentType<Record<string, unknown>>;
+
+/**
+ * Wrap a React component as a `RenderedIslandApp` — `mount` creates the
+ * instance's reconciler + container and renders the initial tree inside the
+ * sync lane; `update` re-renders with new props (the reconciler diffs, only
+ * changed ops emit); `sync` is the dispatch-time commit pin; `dispose`
+ * schedules the unmount; `flush` drains passive effects + pending sync work
+ * for the `flush` task.
+ *
+ * A stamped component (`islandApp('name', Comp)`) keeps its stamp through
+ * the wrap, so registry warn-checks and `defineMonoWorker` name resolution
+ * still see the shell-facing name.
+ */
+export function reactIslandApp(App: AnyComponent): RenderedIslandApp {
+  const app: RenderedIslandApp = {
+    mount({ instance, props }: RenderContext): RenderedHandle {
+      const react = createReactInstance(instance);
+      const render = (next: Record<string, unknown>): void =>
+        react.sync(() => react.render(createElement(App, next)));
+      render(props);
+      return {
+        update: render,
+        sync: (fn) => react.sync(fn),
+        dispose: () => react.sync(() => react.unmountTree()),
+        flush: () => react.flush(),
+      };
+    },
+  };
+  const stamp = islandAppNameOf(App);
+  if (stamp !== undefined) (app as { islandAppName?: string }).islandAppName = stamp;
+  return app;
+}
+
+/** Stamp + wrap in one step — `reactIsland('charts', ChartsApp)` yields the
+ *  registry value AND the name the shell mounts by. */
+export const reactIsland = (
+  name: string,
+  App: AnyComponent,
+): RenderedIslandApp & { readonly islandAppName: string } =>
+  islandApp(name, reactIslandApp(App));
+
+export interface ReactPolyWorkerRegistry {
+  /**
+   * Name → React component (or `{ imperative }` app) registry, mirroring
+   * `definePolyWorker({ apps })`. Components pass through `reactIslandApp`;
+   * imperative defs and already-wrapped apps (e.g. `reactIsland()` results)
+   * register as-is.
+   */
+  apps: Record<string, AnyComponent | ImperativeIslandApp | RenderedIslandApp>;
+  /** Doorbell contract override — forwarded to `definePolyWorker`. */
+  sharedMemory?: SharedMemory<DoorbellSpec>;
+}
+
+/**
+ * `definePolyWorker` for React apps — maps each component in the registry
+ * through `reactIslandApp` and delegates. One worker, many React islands;
+ * for a mixed-framework registry call `definePolyWorker` with the per-app
+ * adapters instead.
+ */
+export function defineReactPolyWorker(
+  registry: ReactPolyWorkerRegistry,
+  options?: { sharedMemory?: SharedMemory<DoorbellSpec> },
+): WorkerDefinition<DoorbellSpec, IslandWorkerMethods> {
+  const apps: Record<string, RenderedIslandApp | ImperativeIslandApp> = {};
+  for (const [key, app] of Object.entries(registry.apps)) {
+    apps[key] = typeof app === 'function' ? reactIslandApp(app) : app;
+  }
+  return definePolyWorker({
+    apps,
+    sharedMemory: registry.sharedMemory ?? options?.sharedMemory,
+  });
+}
+
+/**
+ * `defineMonoWorker` for React apps — one worker pinned to a single
+ * component (or `{ imperative }` app), the isolated-bundle host shape.
+ */
+export function defineReactMonoWorker(
+  app: AnyComponent | ImperativeIslandApp | RenderedIslandApp,
+  options?: { sharedMemory?: SharedMemory<DoorbellSpec> },
+): WorkerDefinition<DoorbellSpec, IslandWorkerMethods> {
+  return typeof app === 'function'
+    ? defineMonoWorker(reactIslandApp(app), options)
+    : defineMonoWorker(app, options);
+}