@atolljs/islands 0.1.12 → 0.1.13

package/dist/contract.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Island contracts — the framework-free seam between a micro-frontend's
+ * worker and any shell.
+ *
+ * The contract module is the one file BOTH sides import: it names the
+ * registry app, declares the props/events wire shape as `Schema`s (the
+ * vendored `z` from `@atolljs/core`, consumer-supplied zod, or any
+ * `{ parse }` validator), and can carry the worker factory so
+ * `lazyIsland(() => import('./x.contract.js'))` is a self-contained split
+ * point. No framework types cross it — a React shell mounting an Angular
+ * app needs only this file.
+ *
+ * ```ts
+ * // checkout.contract.ts — published by the MFE, imported by both threads
+ * import { z } from '@atolljs/core';
+ * import { defineIslandContract } from '@atolljs/islands';
+ *
+ * export const checkout = defineIslandContract({
+ *   app: 'checkout',
+ *   props: z.object({ label: z.string().optional() }),
+ *   events: { paid: z.object({ total: z.number() }) },
+ *   worker: () => new Worker(new URL('./checkout.worker.ts', import.meta.url), { type: 'module' }),
+ * });
+ * ```
+ *
+ * Enforcement is worker-side: mount/updateProps parse props AFTER
+ * `unmarshalCallbackProps` restores `callbackProp` callables (declare those
+ * members `z.callback<Fn>()`), and `emit` parses payloads for declared
+ * event names. Undeclared event names pass through — a contract describes
+ * the wire, it doesn't fence it (a newer worker emitting an event an older
+ * shell doesn't know is normal evolution; a mismatched payload on a KNOWN
+ * event is the violation).
+ */
+import type { Schema } from '@atolljs/core';
+/**
+ * A mountable app contract: the registry key, the prop/event wire schemas,
+ * and optionally the worker factory. `P`/`E` are the shell-facing types —
+ * they ride the contract as pure type information, so consumers of a
+ * framework-rendered island (an Angular component, a Vue SFC) get typed
+ * props and narrowed `onEvent` without ever importing that framework.
+ */
+export interface IslandContract<P = Record<string, unknown>, E extends Record<string, unknown> = Record<string, unknown>> {
+    readonly islandContract: true;
+    /** Registry key — the name `mountIsland({ app })` resolves to. */
+    readonly app: string;
+    /** Prop wire schema — enforced worker-side at mount and updateProps. */
+    readonly props?: Schema<P>;
+    /** Declared emit vocabulary — declared names' payloads parse at emit(). */
+    readonly events?: {
+        readonly [K in keyof E & string]: Schema<E[K]>;
+    };
+    /** The worker factory — optional; when present the contract object itself
+     *  is a lazy contract module (`{ app, worker }`). */
+    readonly worker?: (() => Worker) | URL;
+}
+export declare function defineIslandContract<P = Record<string, unknown>, E extends Record<string, unknown> = Record<string, unknown>>(contract: {
+    app: string;
+    props?: Schema<P>;
+    events?: {
+        [K in keyof E & string]: Schema<E[K]>;
+    };
+    worker?: (() => Worker) | URL;
+}): IslandContract<P, E>;
+/** Structural contract check — the brand, not the shape, so a hand-rolled
+ *  `{ app, props }` without `defineIslandContract` stays an app reference. */
+export declare const isIslandContract: (value: unknown) => value is IslandContract;
+/** The props a contract admits — `IslandContract<P>` → `P`. */
+export type IslandContractProps<C> = C extends IslandContract<infer P, infer _E> ? P : Record<string, unknown>;
+/** The event vocabulary a contract declares — name → payload map. */
+export type IslandContractEvents<C> = C extends IslandContract<infer _P, infer E> ? E : Record<string, unknown>;
+/**
+ * The `onEvent` signature a contract implies — `(name, payload)` with the
+ * payload narrowed per event name. Framework-free sibling of
+ * `@atolljs/angular-island`'s `IslandEventHandler<C>`.
+ */
+export type IslandContractEventHandler<C> = <K extends keyof IslandContractEvents<C> & string>(name: K, payload: IslandContractEvents<C>[K]) => void;
+/**
+ * `withContract(contract, app)` — attach a contract to a registry app
+ * (imperative def or any framework adapter's `RenderedIslandApp`). The
+ * stamp rides the app object like `islandAppName`; the worker reads it at
+ * mount/updateProps for prop validation and hands it to `emit` for
+ * declared-payload checks.
+ *
+ *   apps: {
+ *     checkout: withContract(checkout, angularIslandApp(CheckoutComponent)),
+ *   }
+ */
+export declare function withContract<C extends IslandContract, A>(contract: C, app: A): A;
+/** Read the contract a `withContract`-stamped app carries (undefined when
+ *  unstamped — most registry entries). */
+export declare const contractOf: (app: unknown) => IslandContract | undefined;
+/** The worker factory a contract-carrying `app` reference supplies —
+ *  mount seams fall back to it when no `worker`/`client` was passed, so
+ *  `<Island app={contract}/>` and `islandComponent(contract)` are fully
+ *  self-contained. */
+export declare const contractWorkerOf: (app: unknown) => (() => Worker) | URL | undefined;

package/dist/devtoolsCommands.d.ts

@@ -0,0 +1,21 @@
+import type { IslandHandle } from './island.js';
+export interface DevtoolsIslandEntry {
+    handle: IslandHandle;
+    /** The real container element the island replays into. */
+    el: HTMLElement;
+    /** The props as the caller last gave them (pre-marshal: markers intact). */
+    props(): Record<string, unknown>;
+}
+/** Track a mounted island for the dashboard; returns the untrack function. */
+export declare const trackIslandForDevtools: (entry: DevtoolsIslandEntry) => (() => void);
+export interface IslandTreeNode {
+    /** Child-index path from the container: '0', '0.2', '0.2.s' (shadow root). */
+    id: string;
+    /** Lowercase tag, or '#text' / '#shadow-root'. */
+    tag: string;
+    attrs: [string, string][];
+    text?: string;
+    children: IslandTreeNode[];
+    /** Children omitted once the node budget ran out. */
+    more?: number;
+}

package/dist/devtoolsPreview.d.ts

@@ -0,0 +1,8 @@
+/**
+ * JSON-safe deep copy of caller-given props: functions and `callbackProp`
+ * markers become '[fn]', bigints `'<n>n'`, binary data a size label,
+ * cycles '[cycle]'. The shape the dashboard can display and round-trip.
+ */
+export declare const jsonSafe: (value: unknown) => unknown;
+/** `island:props` payload: a bounded preview with callbacks as '[fn]'. */
+export declare const propsPreview: (props: Record<string, unknown>) => string;

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The main-thread surface of @atolljs/islands — React trees (or
+ * imperative proxy-DOM apps) rendered inside Web Workers, replayed onto
+ * real DOM here as a serialized op stream. There is no React on this side.
+ *
+ *   const island = await mountIsland({
+ *     client: connectIslandWorker({
+ *       worker: () => new Worker(new URL('./render.worker.ts', import.meta.url), { type: 'module' }),
+ *     }),
+ *     el: document.getElementById('island')!,
+ *     app: 'controls',
+ *   });
+ */
+export { connectIslandWorker, isKeepAliveClient, mountIsland } from './island.js';
+export type { ConnectIslandWorkerConfig, IslandClient, IslandHandle, IslandWorkerDefinition, IslandWorkerOptions, Mode, MountIslandOptions, } from './island.js';
+export { makeDoorbell } from './memory.js';
+export type { DoorbellSpec } from './memory.js';
+export { islandApp, islandAppNameOf } from './app.js';
+export type { IslandAppLike, IslandAppProps } from './app.js';
+export { defineIslandContract, isIslandContract, withContract, contractOf, contractWorkerOf, } from './contract.js';
+export type { IslandContract, IslandContractEventHandler, IslandContractEvents, IslandContractProps, } from './contract.js';
+export { callbackProp } from './callbackProps.js';
+export { isEventRef } from './ops.js';
+export type { EventPayload, EventRef, IslandWorkerMethods, MeasuredRect, Op, WireProps, } from './ops.js';

package/dist/index.js

@@ -0,0 +1,30 @@
+import {
+  callbackProp,
+  connectIslandWorker,
+  contractOf,
+  contractWorkerOf,
+  defineIslandContract,
+  isEventRef,
+  isIslandContract,
+  isKeepAliveClient,
+  islandApp,
+  islandAppNameOf,
+  makeDoorbell,
+  mountIsland,
+  withContract
+} from "./chunk-TX4FAHRB.js";
+export {
+  callbackProp,
+  connectIslandWorker,
+  contractOf,
+  contractWorkerOf,
+  defineIslandContract,
+  isEventRef,
+  isIslandContract,
+  isKeepAliveClient,
+  islandApp,
+  islandAppNameOf,
+  makeDoorbell,
+  mountIsland,
+  withContract
+};

package/dist/island.d.ts

@@ -0,0 +1,175 @@
+import type { ConnectWorkerConfig, SharedSpec, WorkerClient, WorkerDefinition } from '@atolljs/core';
+import { type DoorbellSpec } from './memory.js';
+import { type IslandWorkerMethods, type Op } from './ops.js';
+import type { ProxyElement } from './worker/dom/element.js';
+export type Mode = 'push' | 'poll';
+/** The worker definition every `definePolyWorker` call produces. */
+export type IslandWorkerDefinition = WorkerDefinition<DoorbellSpec, IslandWorkerMethods>;
+/** One island client: one dedicated worker, one doorbell buffer. */
+export type IslandClient = WorkerClient<IslandWorkerDefinition, DoorbellSpec>;
+/**
+ * An island client is ONE worker holding its islands' trees (one per mount
+ * on it), so pooling is disabled by construction — the type omits
+ * `workers`/`poolSize`/`worker`/`sharedMemory` (all island-internal) and the
+ * literal below pins `workers: 1` after the spread, so a pool can't sneak
+ * through a cast either. `worker` is supplied per call — the package can't
+ * know where the consumer's worker entry lives — everything else
+ * (taskTimeout, respawn, lazy…) still passes through. The pool-only
+ * `concurrency`/`maxQueue` are accepted but have no effect.
+ */
+export type IslandWorkerOptions = Omit<ConnectWorkerConfig<SharedSpec>, 'sharedMemory' | 'worker' | 'workers' | 'poolSize'>;
+export interface ConnectIslandWorkerConfig extends IslandWorkerOptions {
+    /**
+     * Bundler-detectable factory `() => new Worker(new URL('./x.worker.ts',
+     * import.meta.url), { type: 'module' })`, or a URL. The worker script must
+     * call `definePolyWorker({ apps })` from '@atolljs/islands/worker'.
+     */
+    worker: (() => Worker) | URL;
+    /**
+     * Default true — the client carries a SharedArrayBuffer doorbell for
+     * push-mode flush (requires COOP/COEP cross-origin isolation). Pass
+     * `false` for a message-only client: `setMode('push')` falls back to
+     * 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;
+}
+/** True when this client stays resident after its last island destroys. */
+export declare const isKeepAliveClient: (client: object) => boolean;
+/** One island client: one dedicated worker, one doorbell buffer. */
+export declare const connectIslandWorker: <W extends IslandWorkerDefinition = IslandWorkerDefinition>({ worker, doorbell, keepAlive, ...options }: ConnectIslandWorkerConfig) => WorkerClient<W, DoorbellSpec>;
+interface MountIslandBaseOptions {
+    /**
+     * Container element the island's ops are applied into — a real element on
+     * the shell side, or a `ProxyElement` inside a worker-rendered island
+     * (nested mount: the sub-island's ops replay into the parent instance's
+     * shadow tree and tunnel upward through its op stream). Required.
+     */
+    el: HTMLElement | ProxyElement;
+    /**
+     * Registry app name — a key of the `apps` map passed to
+     * `definePolyWorker`. Optional against a instance worker
+     * (`defineMonoWorker`), which resolves its single app regardless.
+     */
+    app?: string;
+    props?: Record<string, unknown>;
+    /** Island → shell channel: receives every `emit` op the app produces. */
+    onEvent?: (name: string, payload: unknown) => void;
+    /**
+     * Transclusion slots — worker markup renders `<div data-atoll-slot="name">`
+     * as a LEAF; when its create op lands, the real element is handed to
+     * `slots[name](el)` so the shell can mount main-thread content inside it
+     * (a widget, a canvas, even a main-thread React root — real DOM, real
+     * events, zero wire). Called again with `null` when the worker removes or
+     * renames the element, so the shell can tear down. The element itself
+     * stays worker-owned — its box/layout props apply normally.
+     *
+     * Nested mounts (a ProxyElement `el`) receive the anchor's ProxyElement
+     * instead, and only claim names present in this object (`name in slots`);
+     * unclaimed slot names bubble up to the outer island's `slots`.
+     */
+    slots?: Record<string, (el: HTMLElement | null) => void>;
+    /** Fired after each applied op batch — the shell uses it for stats. */
+    onActivity?: () => void;
+    /**
+     * Perf hook — fired after each op batch is replayed with the batch and the
+     * main-thread replay time in ms (performance.now). Pair with client call
+     * timing to split worker-vs-main cost for a sub-application.
+     */
+    onOps?: (ops: readonly Op[], elapsedMs: number) => void;
+    /**
+     * Initial flush mode — 'push' (default) subscribes the shared-memory
+     * doorbell once the mount handshake lands; 'poll' drains committed ops on
+     * a 50ms interval. With the `worker` shorthand, 'poll' also builds the
+     * client without a doorbell — no SharedArrayBuffer, so no COOP/COEP
+     * cross-origin isolation requirement. Switch later with `handle.setMode`.
+     */
+    mode?: Mode;
+    /**
+     * Optional renderer/framework tag — pure observability metadata forwarded
+     * to devtools on `island:mount` ('react', 'vue', 'svelte', …). When
+     * omitted (and devtools is on), the driver asks the worker: package
+     * adapters report their renderer, imperative apps report none and the
+     * map draws them as plain workers. An explicit tag always wins.
+     */
+    framework?: string;
+    /**
+     * Milliseconds the mount handshake (mount + whoami) may take before the
+     * returned promise rejects — default 15_000, `0` disables. A worker entry
+     * that loads but never answers (no definePolyWorker/defineMonoWorker
+     * call, an import that hangs) otherwise leaves mount pending forever;
+     * 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;
+}
+/**
+ * The mount needs one worker-side endpoint: either a `client` a
+ * `connectIslandWorker` call produced (shareable — several islands can
+ * mount into one worker), or a `worker` entry factory/URL this call builds
+ * its own client from (the common one-island-per-worker form — the client
+ * is island-internal and dies with `destroy()`).
+ */
+export type MountIslandOptions = MountIslandBaseOptions & ({
+    client: IslandClient;
+    worker?: undefined;
+} | (IslandWorkerOptions & {
+    worker: (() => Worker) | URL;
+    client?: undefined;
+}));
+export interface IslandHandle {
+    readonly app: string;
+    /** The worker-side instance's random id — proof each island is a distinct worker. */
+    readonly pid: string;
+    /**
+     * The wire instance key — `app@N` for a top-level island, `parent~app@N`
+     * when mounted into a proxy element inside a worker island.
+     */
+    readonly instance: string;
+    readonly mode: Mode;
+    opsApplied: number;
+    flushCalls: number;
+    /** Re-render the island's root with new serializable props. */
+    updateProps(props: Record<string, unknown>): Promise<void>;
+    /**
+     * Switch how async commits are noticed. The mode given at mount ('push'
+     * by default) is started automatically once the handshake lands — call
+     * this only to switch modes afterwards. Rebinds of the doorbell contract
+     * (in-process harnesses bind every contract on each pool spawn) re-watch
+     * transparently.
+     */
+    setMode(mode: Mode): void;
+    /** Manual flush — drains ops committed outside task calls. */
+    flush(): Promise<void>;
+    /**
+     * Stop transport timers/subscriptions and release the instance. When this
+     * island owns the client the worker terminates; when the client is shared
+     * (several islands mounted into it) the instance unmounts and the worker
+     * lives on for its siblings — it dies with the last island to leave.
+     */
+    destroy(): void;
+}
+export declare const assertCloneableProps: (props: Record<string, unknown>, context: string) => void;
+/** Coerce a wire style value to a CSS string — px-suffixes bare numbers
+ *  on non-unitless keys (custom properties pass verbatim). Exported for the
+ *  worker-side nested driver (worker/subIsland.ts), which applies the same
+ *  unit semantics when replaying style values into proxy elements. */
+export declare const cssStyleValue: (key: string, value: unknown) => string;
+export declare const registerSubIslandMounter: (fn: (opts: MountIslandOptions) => Promise<IslandHandle>) => void;
+export declare function mountIsland(opts: MountIslandOptions): Promise<IslandHandle>;
+export {};

package/dist/memory.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The doorbell layout. One counter the worker bumps after every commit —
+ * the main thread observe()s it (Atomics.waitAsync underneath) and flushes
+ * the op queue on each tick. Ops themselves still ride postMessage; shared
+ * memory only replaces the flush() poll with a push.
+ */
+declare const doorbellSpec: {
+    opsVersion: import("@atolljs/core").FieldDescriptor<number>;
+};
+/** The spec `renderMemory`/`makeDoorbell` share — pinned to the doorbell layout. */
+export type DoorbellSpec = typeof doorbellSpec;
+/**
+ * The worker-side contract. A worker script has ONE module-level instance —
+ * the pool's INIT_MEMORY handshake binds it to that worker's own buffer, so
+ * every island's worker gets an independent doorbell for free.
+ */
+export declare const renderMemory: import("@atolljs/core").SharedMemory<{
+    opsVersion: import("@atolljs/core").FieldDescriptor<number>;
+}> & {
+    opsVersion: import("@atolljs/core").Connector<number>;
+};
+/**
+ * The main-thread side needs one contract INSTANCE per island: a contract
+ * object can only be bound to one buffer at a time (bind() rewires its
+ * connectors), and each island client creates its own pool with its own
+ * SharedArrayBuffer. Same spec, separate instance → separate buffer → a
+ * doorbell that only rings for that island's worker.
+ */
+export declare const makeDoorbell: () => import("@atolljs/core").SharedMemory<{
+    opsVersion: import("@atolljs/core").FieldDescriptor<number>;
+}> & {
+    opsVersion: import("@atolljs/core").Connector<number>;
+};
+export {};

package/dist/metrics.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Internal bookkeeping for measuring the island engine's own cost, separate
+ * from application/render work. Disabled by default — the flag check is one
+ * predictable branch per chokepoint, so production mounts pay nothing.
+ *
+ * The one subtlety is re-entrancy: a proxy-DOM method like `el.appendChild`
+ * calls `pushOp`, which is itself instrumented. Timing every frame would
+ * double-count, so `enter`/`exit` share a depth counter — only the
+ * outermost instrumented frame accumulates. The residual
+ * (`workerMs − recordMs`) is then application/adapter time.
+ *
+ * The bench spec additionally calls {@link instrumentPrototype} on the
+ * worker-side dom/* classes so imperative-app shadow-tree maintenance is
+ * captured too; framework adapters reach the same sinks directly.
+ */
+export declare const proxyMetrics: {
+    enabled: boolean;
+    /** Frames currently inside instrumented proxy code (re-entrancy guard). */
+    depth: number;
+    /** ms inside outermost instrumented frames since reset(). */
+    recordMs: number;
+    /** Ops pushed since reset() — a count, free to keep. */
+    opsPushed: number;
+    reset(): void;
+};
+/**
+ * Enter an instrumented frame — returns a start timestamp for the outermost
+ * frame, or -1 when nested (in which case exit records nothing).
+ */
+export declare const enterProxyFrame: () => number;
+/** Pair with {@link enterProxyFrame} — accumulates only for t0 >= 0. */
+export declare const exitProxyFrame: (t0: number) => void;
+/**
+ * Wrap every method/getter/setter on a class prototype with timing. Live
+ * for the rest of the process — intended for benchmark instrumentation,
+ * not production.
+ */
+export declare function instrumentPrototype(proto: object): void;