@atolljs/islands 0.1.0

package/src/worker/instance.ts

@@ -0,0 +1,317 @@
+/**
+ * Instance-scoped state shared by every renderer backend running inside a worker.
+ *
+ * - Per-instance op queues: each island/app owns a queue of {@link Op}s that the
+ *   main-thread driver replays as real DOM mutations.
+ * - A shared id counter for element/text instances, used by both the React
+ *   reconciler and the proxy DOM.
+ * - Handler registry for event listeners.
+ * - Doorbell contract used to bump the ops-version after a commit.
+ * - Pushed container-size geometry.
+ *
+ * This module is renderer-agnostic: it contains no react-reconciler imports.
+ * The React-specific host config lives in `hostConfig.ts`.
+ */
+
+import { renderMemory } from '../memory';
+import type { Op, WireProps } from '../ops';
+
+/* ── Host instances ─────────────────────────────────────────────────────── */
+
+export interface ElementInstance {
+  kind: 'element';
+  id: number;
+  type: string;
+  /** Which mounted app this node belongs to — routes its ops. */
+  instance: string;
+  /** Namespace URI for non-HTML elements (svg/mathml) — rides the `create`
+   *  op so the driver uses `createElementNS`. Tracked via host context. */
+  ns?: string;
+  /** Last serialized prop set — needed so hide/unhide can resend it. */
+  props: WireProps;
+  /** propName → stable handler id (keeps DOM listeners stable across updates). */
+  listenerSlots: Record<string, number>;
+}
+
+export interface TextInstance {
+  kind: 'text';
+  id: number;
+  text: string;
+  instance: string;
+}
+
+export type HostInstance = ElementInstance | TextInstance;
+
+/** The root container is a sentinel — op `parent: 0` means "the root".
+ *  definePolyWorker stamps `instance` on the container it hands
+ *  createContainer, so createInstance can bind every element to the instance
+ *  that rendered it — deterministic even when a commit runs outside a instance
+ *  task (passive-effect renders, scheduler flushes), where activeInstance is
+ *  ''. Instance-bound ops then always reach their island's queue. */
+export interface RootContainer {
+  id: 0;
+  instance?: string;
+}
+export const ROOT_CONTAINER = Object.freeze({ id: 0 }) as RootContainer;
+
+/* ── Per-instance op queues + instance/handler tables ──────────────────────── */
+
+/** instance (app name) → queued ops. Each island flushes only its own queue. */
+const opsByInstance = new Map<string, Op[]>();
+/** The instance a task is currently executing under — see setActiveInstance. */
+let activeInstance = '';
+/**
+ * instance id → host record. Exported so the proxy DOM (worker/proxyDom.ts)
+ * shares the SAME instance space as the reconciler: a proxy-created element
+ * can nest inside a React-rendered parent and vice versa, because ops are
+ * id-addressed and ids come from one counter.
+ */
+export const instances = new Map<number, HostInstance>();
+interface HandlerEntry {
+  fn: (payload: unknown) => void;
+  instance: string;
+  /** The element this handler was attached to — the event's currentTarget. */
+  instanceId?: number;
+}
+/** handler id → prop function + owning instance. Lives worker-side; never serialized. */
+const handlers = new Map<number, HandlerEntry>();
+let nextId = 1;
+let nextHandlerId = 1;
+
+/** Allocate an instance id — the shared counter React and the proxy DOM both draw from. */
+export const allocId = (): number => nextId++;
+
+/**
+ * Marks which instance the currently-running task belongs to; returns the
+ * previous value for restore. Structural ops don't need it — they route by
+ * their instance's instance — but instance-less ops (`clear`, `emit`) and
+ * handler dispatch do. Worker tasks run synchronously, so a single pointer
+ * is safe even when several mounts coexist in one module.
+ */
+let lastInstance = '';
+export const setActiveInstance = (instance: string): string => {
+  const prev = activeInstance;
+  activeInstance = instance;
+  if (instance !== '') lastInstance = instance;
+  return prev;
+};
+
+/** The instance the current task is running under — '' outside a instance task. */
+export const getActiveInstance = (): string => activeInstance;
+
+/**
+ * The most recent instance a task ran under — used by the instance dispatcher to
+ * route deferred library work (timers, promise continuations) to the right
+ * document when several mounts share one module (in-process tests).
+ */
+export const getLastActiveInstance = (): string => lastInstance;
+
+/**
+ * The most recent instance an op was pushed for — stamped in `pushOp`, so
+ * every proxy-DOM mutation records it. This is the last rung of the
+ * ambient-resolution chain (active → lastActive → lastTouched): a renderer
+ * whose scheduler flushes outside any task still lands on the instance whose
+ * tree it just mutated.
+ */
+let touchedInstance = '';
+export const getLastTouchedInstance = (): string => touchedInstance;
+
+/**
+ * Marks `instance` as the ambient instance for out-of-task readers (timers,
+ * continuations, shim consumers outside instance work). Called by
+ * installDomShim so its document becomes the ambient document.
+ */
+export const markInstanceActive = (instance: string): void => {
+  if (instance) lastInstance = instance;
+};
+
+/**
+ * Run `fn` while `instance` is the active instance — the imperative-code twin of
+ * the reconciler's syncCommit wrapper. Imperative DOM writes (`emit`, the
+ * proxy DOM's `emit` calls, `clear`) only route correctly while a instance
+ * task holds the active instance: mount, updateProps, and dispatch all wrap
+ * their work in this, and imperative apps should do the same for any
+ * worker-initiated work (timers, promise continuations).
+ */
+export const runInInstance = <T>(instance: string, fn: () => T): T => {
+  const prev = setActiveInstance(instance);
+  try {
+    return fn();
+  } finally {
+    setActiveInstance(prev);
+  }
+};
+
+/** Queue an op onto a instance's queue — instance-bound ops pass their
+ *  instance's instance, instance-less ops (`clear`, `emit`) the active one. */
+export const pushOp = (instance: string, op: Op): void => {
+  if (instance !== '') touchedInstance = instance;
+  let queue = opsByInstance.get(instance);
+  if (!queue) opsByInstance.set(instance, (queue = []));
+  queue.push(op);
+};
+
+/** The minimum surface `bumpOpsVersion` needs off the doorbell contract. */
+interface DoorbellContract {
+  readonly bound: boolean;
+  connector(path: string): { read(): unknown; write(v: unknown): void };
+}
+
+/**
+ * The contract `bumpOpsVersion` writes to — `renderMemory` by default, or
+ * whatever doorbell-shaped contract `definePolyWorker({ sharedMemory })`
+ * was handed. Overriding requires the SAME spec as the main-side
+ * `makeDoorbell()` (the pool sizes the buffer for it), so this is a rarely
+ * needed escape hatch, not a general field contract.
+ */
+let doorbell: DoorbellContract = renderMemory;
+
+/** Point the doorbell writes at a different doorbell-spec contract. */
+export const setDoorbellContract = (contract: DoorbellContract): void => {
+  doorbell = contract;
+};
+
+/**
+ * The doorbell write resetAfterCommit performs, exported so non-React op
+ * producers (the proxy DOM) can ring it too — a commit made outside any
+ * task still needs to wake the island's observe() loop. No-op while the
+ * contract is unbound (before the pool's INIT_MEMORY handshake).
+ */
+export const bumpOpsVersion = (): void => {
+  if (!doorbell.bound) return;
+  const bell = doorbell.connector('opsVersion');
+  bell.write(Number(bell.read() ?? 0) + 1);
+};
+
+/** Drain one instance's queued ops — called by the worker's task methods. */
+export const takeOps = (instance: string): Op[] => {
+  const queue = opsByInstance.get(instance);
+  if (!queue || queue.length === 0) return [];
+  opsByInstance.set(instance, []);
+  return queue;
+};
+
+export const getHandler = (id: number): HandlerEntry | undefined => handlers.get(id);
+
+/* ── Pushed container size (setSize channel) ────────────────────────────── */
+
+/**
+ * instance key → the island container's last measured {w,h}, pushed by the
+ * driver's `setSize` task. This is the ONLY geometry channel: the main
+ * thread can only measure the island's root box, so the proxy DOM serves
+ * this value to `doc.body`/`documentElement` and to elements explicitly
+ * marked `doc.markContainer(el)` — every other element keeps the honest 0.
+ * Module-level (not per-document) so it survives imperative rebuilds that
+ * swap in a fresh proxy document.
+ */
+const instanceSizes = new Map<string, { w: number; h: number }>();
+
+/** The instance's last pushed container size, or undefined if none arrived. */
+export const getInstanceSize = (instance: string): { w: number; h: number } | undefined =>
+  instanceSizes.get(instance);
+
+/** Store the container size a `setSize` task pushed. */
+export const setInstanceSize = (instance: string, w: number, h: number): void => {
+  instanceSizes.set(instance, { w, h });
+};
+
+/**
+ * Register a function in the handler table outside prop serialization —
+ * the proxy DOM's addEventListener uses this. The instance is stamped on the
+ * entry so a dispatched event routes its re-render ops to the right queue.
+ * `listen`/`unlisten` ops carry the returned id so the main thread can wire
+ * and later detach the matching DOM listener.
+ */
+export const registerHandler = (
+  fn: (payload: unknown) => void,
+  instance: string,
+  instanceId?: number,
+): number => {
+  const id = nextHandlerId++;
+  handlers.set(id, { fn, instance, instanceId });
+  return id;
+};
+
+export const unregisterHandler = (id: number): void => {
+  handlers.delete(id);
+};
+
+/**
+ * The island→shell channel. Apps call `emit(name, payload)` inside event
+ * handlers or commit-phase effects — it just queues an `emit` op, which the
+ * main-thread driver routes to the island's `onEvent` callback instead of
+ * the DOM. Call it while a task holds the instance (handlers, layout effects);
+ * a bare emit from a passive effect has no instance to route to in the
+ * many-mounts-per-module case and would be dropped.
+ */
+export const emit = (name: string, payload?: unknown): void => {
+  pushOp(activeInstance, { t: 'emit', name, payload });
+};
+
+/* ── Prop serialization ─────────────────────────────────────────────────── */
+
+/**
+ * Props must cross postMessage, so: `children` is skipped (structure comes
+ * from append/remove ops), `key`/`ref` are skipped, functions named `on*`
+ * become `{ __evt: id }`, everything else passes through structured clone.
+ * Each (instance, propName) pair reuses one handler-id slot, so the id the
+ * main thread sees never changes across re-renders — it can attach the DOM
+ * listener exactly once while the handler id keeps pointing at the latest
+ * closure.
+ */
+export function serializeProps(instance: ElementInstance, props: Record<string, unknown>): WireProps {
+  const out: WireProps = {};
+  for (const [name, value] of Object.entries(props)) {
+    if (value === undefined || value === null) continue;
+    if (name === 'children' || name === 'key' || name === 'ref' || name === 'dangerouslySetInnerHTML') {
+      continue;
+    }
+    if (typeof value === 'function') {
+      if (name.length > 2 && name.startsWith('on')) {
+        let slot = instance.listenerSlots[name];
+        if (slot === undefined) {
+          slot = nextHandlerId++;
+          instance.listenerSlots[name] = slot;
+        }
+        handlers.set(slot, {
+          fn: value as (payload: unknown) => void,
+          instance: instance.instance,
+          instanceId: instance.id,
+        });
+        out[name] = { __evt: slot };
+      }
+      // Non-event functions (render props, callbacks) can't cross the wire — dropped.
+      continue;
+    }
+    out[name] = value; // style objects, numbers, strings, booleans all clone fine
+  }
+  return out;
+}
+
+/* ── Small factories ────────────────────────────────────────────────────── */
+
+export function newElement(
+  type: string,
+  props: Record<string, unknown>,
+  ns: string | undefined,
+  instance: string,
+): ElementInstance {
+  const record: ElementInstance = {
+    kind: 'element',
+    id: allocId(),
+    type,
+    ns,
+    instance,
+    props: {},
+    listenerSlots: {},
+  };
+  record.props = serializeProps(record, props);
+  instances.set(record.id, record);
+  return record;
+}
+
+export function newText(text: string, instance: string): TextInstance {
+  const record: TextInstance = { kind: 'text', id: allocId(), text, instance };
+  instances.set(record.id, record);
+  return record;
+}

package/src/worker/proxyDom.ts

@@ -0,0 +1,28 @@
+export {
+  ProxyNode,
+  ProxyText,
+  ProxyComment,
+  ProxyFragment,
+} from './dom/node';
+export type { ProxyEventHandler, WireListenerOpts } from './dom/node';
+export {
+  ProxyElement,
+} from './dom/element';
+export type { AdjacentPosition } from './dom/element';
+export type { ProxyClassList } from './dom/css';
+export {
+  createProxyDocument,
+  docForInstance,
+} from './dom/document';
+export type {
+  ProxyDocument,
+  InternalDocument,
+} from './dom/document';
+export {
+  installInstanceDispatcher,
+  installDomShim,
+} from './dom/window';
+export type {
+  WindowShim,
+  WindowFacadeBundle,
+} from './dom/window';

package/src/worker/reactInstance.ts

@@ -0,0 +1,74 @@
+/**
+ * The React-runtime half of the island worker — `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. `definePolyWorker` reaches this module only through
+ * `await import('./reactInstance')` when a mounted app resolves to a component
+ * function — first mount of a React instance pays one microtask's worth of
+ * module init, everything after is the same sync path.
+ */
+import { createElement, type ReactElement } from 'react';
+import Reconciler from 'react-reconciler';
+import { hostConfig } from './hostConfig';
+import { ROOT_CONTAINER } from './instance';
+
+/**
+ * A mounted React instance — carries its own reconciler + container and the
+ * `render`/`unmountTree` verbs, so the runtime module never needs the
+ * `react` import itself (element creation is the only place it was used).
+ */
+export interface ReactInstance {
+  /** The wire key — 'app' or 'app@instance'; op queues route by this. */
+  key: string;
+  /** The registry name — which component this instance renders. */
+  app: string;
+  /** Per-instance random id — the island's "worker pid" badge. */
+  pid: string;
+  imperative?: undefined;
+  rendered?: undefined;
+  reconciler: ReturnType<typeof Reconciler>;
+  container: unknown;
+  /** Mount/re-render the component into this instance's container. */
+  render(App: (props: Record<string, unknown>) => ReactElement, props: Record<string, unknown>): void;
+  /** Unmount the tree — emits the detach ops the driver replays. */
+  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(key: string, app: string, pid: 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: key } as typeof ROOT_CONTAINER,
+    0,
+    null,
+    false,
+    null,
+    '',
+    console.error, // onUncaughtError
+    console.error, // onCaughtError
+    console.error, // onRecoverableError
+    null, // onDefaultTransitionIndicator
+  );
+  return {
+    key,
+    app,
+    pid,
+    reconciler,
+    container,
+    render: (App, props) =>
+      reconciler.updateContainer(createElement(App, props), container, null, null),
+    unmountTree: () => reconciler.updateContainer(null, container, null, null),
+    flush: () => {
+      reconciler.flushPassiveEffects();
+      reconciler.flushSyncWork();
+    },
+  };
+}

package/src/worker/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} />;
+}