@atolljs/islands 0.1.12 → 0.1.14

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.12",
+  "version": "0.1.14",
   "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.12"
+    "@atolljs/core": "^0.1.14"
   },
   "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

@@ -181,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;
 }
 
 /**
@@ -1369,9 +1377,11 @@ export async function mountIsland(opts: MountIslandOptions): Promise<IslandHandl
         cbTable.clear();
         slotNodes.clear();
         dispatchQueue.length = 0;
-        // keepAlive clients stay resident — the instance is unmounted but
-        // the thread idles so the next mount is a warm start.
-        if (remaining <= 0 && !isKeepAliveClient(client) && (clientMounts.get(client) ?? 0) === 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))

package/src/worker/subIsland.ts

@@ -650,10 +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);
-      // keepAlive clients release the instance but keep the thread warm;
-      // worker-owned and last-mount clients terminate outright.
-      if (!isKeepAliveClient(client) && (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(() => {});
     },
   };