@atolljs/islands 0.1.11 → 0.1.13

package/dist/worker/instance.d.ts

@@ -0,0 +1,187 @@
+/**
+ * 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 type { IslandContract } from '../contract.js';
+import type { Op, WireProps } from '../ops.js';
+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 declare const ROOT_CONTAINER: RootContainer;
+/**
+ * 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 declare const instances: Map<number, HostInstance>;
+interface HandlerEntry {
+    fn: (payload: unknown) => void;
+    instance: string;
+    /** The element this handler was attached to — the event's currentTarget. */
+    instanceId?: number;
+}
+/** Move an instance record + its handler ids out of the live maps. */
+export declare const detachInstance: (id: number, handlerIds: number[]) => void;
+/** Restore an instance record + handler ids on re-append (idempotent). */
+export declare const attachInstance: (id: number, handlerIds: number[]) => void;
+/** instances.get that also resolves detached records — stale dispatches and
+ *  relatedTarget materialization may still reference them. */
+export declare const lookupInstance: (id: number) => HostInstance | undefined;
+export declare const setInstanceContract: (instance: string, contract: IslandContract | undefined) => void;
+/** Allocate an instance id — the shared counter React and the proxy DOM both draw from. */
+export declare const allocId: () => number;
+export declare const setActiveInstance: (instance: string) => string;
+/** The instance the current task is running under — '' outside a instance task. */
+export declare const getActiveInstance: () => string;
+/**
+ * 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 declare const getLastActiveInstance: () => string;
+export declare const getLastTouchedInstance: () => string;
+/**
+ * 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 declare const markInstanceActive: (instance: string) => void;
+/**
+ * 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 declare const runInInstance: <T>(instance: string, fn: () => T) => T;
+/** 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 declare const pushOp: (instance: string, op: Op) => void;
+/** The minimum surface `bumpOpsVersion` needs off the doorbell contract. */
+interface DoorbellContract {
+    readonly bound: boolean;
+    connector(path: string): {
+        read(): unknown;
+        write(v: unknown): void;
+    };
+}
+/** Point the doorbell writes at a different doorbell-spec contract. */
+export declare const setDoorbellContract: (contract: DoorbellContract) => void;
+/**
+ * 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 declare const bumpOpsVersion: () => void;
+/** Drain one instance's queued ops — called by the worker's task methods. */
+export declare const takeOps: (instance: string) => Op[];
+/**
+ * Structural memory snapshot of the proxy layer — how much shadow state the
+ * engine retains for live nodes, handlers, and ops still queued. Removed
+ * nodes leave `instances` for a bounded tombstone (event dispatch may still
+ * resolve recently-detached target ids), so liveNodes is attached-only.
+ */
+export declare const proxyInstanceStats: () => {
+    liveNodes: number;
+    handlers: number;
+    queuedOps: number;
+    queuedByInstance: Record<string, number>;
+};
+export declare const getHandler: (id: number) => HandlerEntry | undefined;
+/** The instance's last pushed container size, or undefined if none arrived. */
+export declare const getInstanceSize: (instance: string) => {
+    w: number;
+    h: number;
+} | undefined;
+/** Store the container size a `setSize` task pushed. */
+export declare const setInstanceSize: (instance: string, w: number, h: number) => void;
+/** The last pushed rect for one element id, or undefined if never measured. */
+export declare const getInstanceRect: (instance: string, id: number) => {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+} | undefined;
+/** Store one element's measured box from a `setRects` push. */
+export declare const setInstanceRect: (instance: string, rect: {
+    id: number;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}) => void;
+/** Drop every measured rect for the instance — the unmount path calls this
+ *  so stale geometry can't answer reads on a re-mounted instance's ids. */
+export declare const clearInstanceRects: (instance: string) => void;
+/**
+ * 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 declare const registerHandler: (fn: (payload: unknown) => void, instance: string, instanceId?: number) => number;
+export declare const unregisterHandler: (id: number) => void;
+/**
+ * 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 declare const emit: (name: string, payload?: unknown) => void;
+/**
+ * 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 declare function serializeProps(instance: ElementInstance, props: Record<string, unknown>): WireProps;
+export declare function newElement(type: string, props: Record<string, unknown>, ns: string | undefined, instance: string): ElementInstance;
+export declare function newText(text: string, instance: string): TextInstance;
+export {};

package/dist/worker/proxyDom.d.ts

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

package/dist/worker/subIsland.d.ts

@@ -0,0 +1,11 @@
+import { type IslandHandle, type MountIslandOptions } from '../island.js';
+/**
+ * The surface is ONE function: `mountIsland`. A proxy `el` makes the mount
+ * nested — these are the same options either way. `slots` receive the
+ * anchor's ProxyElement (worker-side content portals into it); slot names
+ * this mount doesn't list bubble up to the outer island's `slots`.
+ */
+export type MountSubIslandOptions = MountIslandOptions;
+/** One handle shape for both mount targets — `instance` reads `parent~app@N`. */
+export type SubIslandHandle = IslandHandle;
+export declare function mountSubIsland(opts: MountSubIslandOptions): Promise<SubIslandHandle>;

package/package.json

@@ -1,16 +1,26 @@
 {
   "name": "@atolljs/islands",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Atoll islands — MonoWorker/PolyWorker hosts rendering framework islands (React/Vue/Svelte/Solid/Angular) over a proxy-DOM op protocol",
   "homepage": "https://jwhenry3.github.io/atolljs/consumer/quickstart/",
   "type": "module",
   "exports": {
-    ".": "./src/index.ts",
-    "./worker": "./src/worker/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./worker": {
+      "types": "./dist/worker/index.d.ts",
+      "default": "./dist/worker/index.js"
+    }
   },
   "files": [
-    "src"
+    "src",
+    "dist"
   ],
+  "scripts": {
+    "build": "node ../../scripts/build-lib.mjs"
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
@@ -19,7 +29,7 @@
     "htmlparser2": "^12.0.0"
   },
   "peerDependencies": {
-    "@atolljs/core": "0.1.11"
+    "@atolljs/core": "0.1.13"
   },
   "repository": {
     "type": "git",

package/src/index.ts

@@ -11,7 +11,7 @@
  *     app: 'controls',
  *   });
  */
-export { connectIslandWorker, mountIsland } from './island';
+export { connectIslandWorker, isKeepAliveClient, mountIsland } from './island';
 export type {
   ConnectIslandWorkerConfig,
   IslandClient,

package/src/island.ts

@@ -83,20 +83,40 @@ export interface ConnectIslandWorkerConfig extends IslandWorkerOptions {
    * polling and the page needs no special headers.
    */
   doorbell?: boolean;
+  /**
+   * Default false — when true, the last island to destroy on this client
+   * leaves the worker ALIVE but idle: the instance still unmounts (dispose
+   * hooks run, timers clear, ops stop, driver state releases) but the
+   * thread, its module graph, and any worker-side caches stay resident, so
+   * the next `mount` on this client is a warm start. Nothing runs while
+   * idle — the instance is gone; only the process survives.
+   */
+  keepAlive?: boolean;
 }
 
+/* Clients opted out of idle-termination by `keepAlive` — a WeakSet so the
+ * flag never pins a client that would otherwise collect. */
+const keepAliveClients = new WeakSet<object>();
+
+/** True when this client stays resident after its last island destroys. */
+export const isKeepAliveClient = (client: object): boolean => keepAliveClients.has(client);
+
 /** One island client: one dedicated worker, one doorbell buffer. */
 export const connectIslandWorker = <W extends IslandWorkerDefinition = IslandWorkerDefinition>({
   worker,
   doorbell,
+  keepAlive,
   ...options
-}: ConnectIslandWorkerConfig): WorkerClient<W, DoorbellSpec> =>
-  connectWorker<W, DoorbellSpec>({
+}: ConnectIslandWorkerConfig): WorkerClient<W, DoorbellSpec> => {
+  const client = connectWorker<W, DoorbellSpec>({
     ...options,
     sharedMemory: doorbell === false ? undefined : makeDoorbell(),
     worker,
     workers: 1,
   });
+  if (keepAlive) keepAliveClients.add(client);
+  return client;
+};
 
 interface MountIslandBaseOptions {
   /**
@@ -161,6 +181,14 @@ interface MountIslandBaseOptions {
    * hard failures (module error, crash) already reject immediately.
    */
   mountTimeout?: number;
+  /**
+   * This mount's `destroy()` never terminates the client: the instance
+   * unmounts (dispose hooks, `clear` op replay) but the thread stays
+   * resident and idle for a warm remount. The mount-level version of
+   * `connectIslandWorker({ keepAlive: true })` — either flag marks the
+   * client warm for this island's teardown.
+   */
+  keepAlive?: boolean;
 }
 
 /**
@@ -716,6 +744,10 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
    * edges stay ordered after the moves they coalesce past. */
   const COALESCE_EVENTS = new Set(['mousemove', 'pointermove', 'touchmove', 'drag', 'dragover']);
   const MAX_IN_FLIGHT_DISPATCH = 4;
+  /* How long destroy() waits for the worker's unmount batch before force-
+   * tearing down. Generous enough for a busy worker draining real tasks;
+   * short enough that a wedged worker is visibly gone soon. */
+  const UNMOUNT_GRACE_MS = 1500;
   const dispatchQueue: Array<{ handlerId: number; key: string | null; payload: EventPayload }> = [];
   let inFlightDispatches = 0;
 
@@ -1322,32 +1354,41 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
       measuredIds.clear();
       const remaining = (clientMounts.get(client) ?? 1) - 1;
       clientMounts.set(client, remaining);
-      if (remaining > 0) {
-        // The worker still serves sibling mounts — hand this one back, but
-        // replay the teardown batch anyway: the `clear` op unmounts slot
-        // anchors inside our tree, firing slots[name](null) so slot render
-        // roots come down. Dropping it would leave a slot-hosted sibling
-        // mounted on this client and pin the worker alive.
-        void islandCall('unmount', client.unmount(instance))
-          .then((ops) => applyOps(ops, 'unmount'))
-          .catch(() => {});
-      } else {
-        // Last island — still run the instance's teardown first so the app's
-        // dispose hook cancels deferred work (library timers, animation
-        // loops) and the proxy doc unwinds. In a real worker terminate may
-        // kill the thread before unmount lands — equally fine, process
-        // death is teardown — but in-process workers need this or the
-        // instance zombies on and its pending callbacks mutate foreign docs.
-        void islandCall('unmount', client.unmount(instance))
-          .then((ops) => applyOps(ops, 'unmount'))
-          .catch(() => {})
-          .finally(() => {
-            // A remount may have registered while teardown was in flight
-            // (app/client input swap does destroy → mount back-to-back) —
-            // terminate only when the client is still truly idle.
-            if ((clientMounts.get(client) ?? 0) === 0) client.terminate();
-          });
-      }
+      /* One bounded teardown for both cases. The worker's unmount batch is
+       * still awaited so the app's dispose hook cancels deferred work and
+       * the `clear` op can fire slots[name](null) for slot anchors — but
+       * the wait is capped by UNMOUNT_GRACE_MS. A wedged worker (a task
+       * that never settles) must not pin the worker, this island's driver
+       * state, or the pending-call closures forever. finish() releases the
+       * maps eagerly so ops arriving late replay against empty maps (all
+       * lookups miss → no-ops), and on the last mount it terminates the
+       * worker unconditionally — as long as no remount registered while
+       * teardown was in flight (app/client swap does destroy → mount
+       * back-to-back; terminate only when the client is truly idle). */
+      let finished = false;
+      const finish = () => {
+        if (finished) return;
+        finished = true;
+        nodes.clear();
+        detached.clear();
+        detachedIds.clear();
+        prevProps.clear();
+        nodeListeners.clear();
+        cbTable.clear();
+        slotNodes.clear();
+        dispatchQueue.length = 0;
+        // keepAlive (client-level flag or this mount's override) keeps the
+        // thread resident — the instance is unmounted but the worker idles
+        // so the next mount is a warm start.
+        const warm = opts.keepAlive === true || isKeepAliveClient(client);
+        if (remaining <= 0 && !warm && (clientMounts.get(client) ?? 0) === 0)
+          client.terminate();
+      };
+      void islandCall('unmount', client.unmount(instance))
+        .then((ops) => applyOps(ops, 'unmount'))
+        .catch(() => {})
+        .finally(finish);
+      setTimeout(finish, UNMOUNT_GRACE_MS);
     },
   };
   // Dashboard commands (`island.*`) — registered only while devtools is on.

package/src/worker/subIsland.ts

@@ -37,6 +37,7 @@ import {
   assertCloneableProps,
   connectIslandWorker,
   cssStyleValue,
+  isKeepAliveClient,
   registerSubIslandMounter,
   type ConnectIslandWorkerConfig,
   type IslandClient,
@@ -649,7 +650,11 @@ export async function mountSubIsland(opts: MountSubIslandOptions): Promise<SubIs
       if (pollTimer !== null) clearInterval(pollTimer);
       const remaining = (clientMounts.get(client) ?? 1) - 1;
       clientMounts.set(client, remaining);
-      if (givenClient === undefined || remaining <= 0) client.terminate();
+      // keepAlive (client-level or this mount's override) releases the
+      // instance but keeps the thread warm; worker-owned and last-mount
+      // clients terminate outright.
+      const warm = opts.keepAlive === true || isKeepAliveClient(client);
+      if (!warm && (givenClient === undefined || remaining <= 0)) client.terminate();
       else void islandCall('unmount', client.unmount(instance)).catch(() => {});
     },
   };