@atolljs/core 0.1.7 → 0.1.8

package/README.md

@@ -68,7 +68,7 @@ export const counter = connectWorker<CounterWorker>({
   // Inline new Worker(new URL(..., import.meta.url)) — every bundler's
   // worker transform can see the entry point this way.
   worker: () => new Worker(new URL('./counter.worker.ts', import.meta.url), { type: 'module' }),
-  poolSize: 'auto',   // navigator.hardwareConcurrency, or pass a number
+  workers: 'auto',    // navigator.hardwareConcurrency; default 1 (one worker, no pool)
 });
 // counter.increment(1) → Promise<number>. The pool spawns on first call
 // (SSR-safe to import); counter.terminate() tears it down.

package/dist/contract/memoryDevtools.d.ts

@@ -0,0 +1,30 @@
+import type { Connector, SharedMemory } from './sharedMemory.js';
+export type WatchRule = {
+    text: string;
+    test: (value: unknown) => boolean;
+};
+interface WatchState {
+    rule: WatchRule;
+    /** Per contract: last version checked and last value preview ('change'). */
+    seen: WeakMap<SharedMemory<any>, {
+        version: number;
+        preview: string;
+    }>;
+    stop: () => void;
+    hits: number;
+}
+/** path → watch. Read by the write path — keep `.size` the only hot check. */
+export declare const memoryWatches: Map<string, WatchState>;
+/** Bounded preview of a field's current value — lists/typed arrays read only a head. */
+export declare const fieldPreview: (connector: Connector<any>) => string;
+/**
+ * Parse a watch rule: 'change' | '> n' | '< n' | '>= n' | '<= n' | '== v' |
+ * '!= v'. `v` is JSON when it parses ('"down"', 'true', '3'), else a bare
+ * string. Numeric comparisons only match number/bigint fields.
+ */
+export declare const parseWatchRule: (raw: string) => WatchRule;
+/** Write-path hook — only called when `memoryWatches.size > 0`. */
+export declare const checkWatchOnWrite: (memory: SharedMemory<any>, path: string, version: number) => void;
+/** Register the `memory.*` commands once; `contracts` lists every defined contract. */
+export declare const ensureMemoryCommands: (contracts: () => readonly SharedMemory<any>[]) => void;
+export {};

package/dist/contract/sharedMemory.d.ts

@@ -81,6 +81,8 @@ export interface Connector<T> {
         view: Int32Array;
         index: number;
     };
+    /** Internal: the field's contract path — devtools node labels. */
+    readonly _path?: string;
 }
 export type ScalarKind = 'i8' | 'u8' | 'i16' | 'u16' | 'i32' | 'u32' | 'f32' | 'f64' | 'i64' | 'u64';
 /** A fixed-layout member spec: a scalar kind, `{ string: n }` for an inline UTF-8 field of n bytes, or `{ bool: true }` for a flag byte. */
@@ -318,8 +320,8 @@ export declare class SharedMemory<S extends SharedSpec = SharedSpec> {
         byteLength: number;
     }[];
     /**
-     * Fires when the contract is bound on this thread — immediately if already
-     * bound. Returns an unsubscribe function.
+     * Fires when the contract is bound on this thread — on every bind, and
+     * immediately if already bound. Returns an unsubscribe function.
      */
     onBound(cb: () => void): () => void;
     /** Typed lookup for flat (ungrouped) field keys. */

package/dist/contract/types.d.ts

@@ -52,6 +52,17 @@ export interface WorkerPoolConfig<S extends SharedSpec = SharedSpec, T extends T
      * skipped and workers receive a plain `{ type: 'INIT' }` handshake.
      */
     sharedMemory?: SharedMemory<S> & Prettify<SharedAccess<S>>;
+    /**
+     * Hand an existing SharedArrayBuffer to every spawned worker instead of
+     * allocating a fresh `WebAssembly.Memory` — the worker-shell case: a worker
+     * already bound to a contract spawns sub-workers on the SAME buffer
+     * (`sharedBuffer: contract.buffer`), or a second pool shares the first
+     * pool's `pool.sharedBuffer`. A thunk is resolved once, when the pool
+     * constructs. With `sharedMemory` the contract binds locally to this
+     * buffer; without it the buffer still ships via INIT_MEMORY and the
+     * workers bind their own defined contracts.
+     */
+    sharedBuffer?: SharedArrayBuffer | (() => SharedArrayBuffer | undefined);
     /**
      * Persistence adapter for `sharedMemory` — invoked with the contract right
      * after the pool binds it, and its `stop()` runs on `terminate()`.

package/dist/devtools.d.ts

@@ -16,8 +16,14 @@ export type DevtoolsEvent = {
     /** Config `name`, when supplied — a display label, not the id. */
     label?: string;
     poolSize: number;
+    /** Per-worker in-flight cap; 0 for a dedicated worker (no queue, uncapped). */
     concurrency: number;
     memoryBytes?: number;
+    /**
+     * True for a single dedicated worker (`connectWorker({ workers: 1 })`,
+     * island clients): no pool, no queue. Same event vocabulary otherwise.
+     */
+    dedicated?: boolean;
 } | {
     type: 'pool:terminate';
     poolId: string;
@@ -46,6 +52,8 @@ export type DevtoolsEvent = {
     taskId: string;
     slot: number;
     waitMs: number;
+    /** Estimated structured-clone size of the task args (`estimateCloneBytes`). */
+    argBytes?: number;
 } | {
     type: 'task:settle';
     poolId: string;
@@ -55,6 +63,8 @@ export type DevtoolsEvent = {
     /** dispatch→reply; absent for calls that never ran. */
     runMs?: number;
     error?: string;
+    /** Estimated structured-clone size of the result (`estimateCloneBytes`). */
+    resultBytes?: number;
 } | {
     type: 'memory:bind';
     /** Version-counter index → field path, for pairing memory:write. */
@@ -64,6 +74,15 @@ export type DevtoolsEvent = {
     type: 'memory:write';
     path: string;
     version: number;
+} | {
+    /** A dashboard-set watchpoint matched on write (`memory.watch` command). */
+    type: 'memory:watch-hit';
+    path: string;
+    version: number;
+    /** Preview of the written value (`previewValue`). */
+    value: string;
+    /** The watch rule as set, e.g. '> 100', 'change', '== "down"'. */
+    rule: string;
 } | {
     type: 'island:mount';
     instance: string;
@@ -80,6 +99,14 @@ export type DevtoolsEvent = {
     type: 'island:event';
     instance: string;
     name: string;
+    /** Preview of the emitted payload (`previewValue`). */
+    payload?: string;
+} | {
+    /** The props an island currently holds: sent on mount and every updateProps. */
+    type: 'island:props';
+    instance: string;
+    /** Preview of the props object (`previewValue`); callbacks show as '[fn]'. */
+    props: string;
 } | {
     type: 'island:task';
     instance: string;
@@ -98,6 +125,8 @@ export type DevtoolsEvent = {
     count: number;
     /** Main-thread replay time; worker-side render time rides call timings. */
     replayMs?: number;
+    /** Estimated structured-clone size of the op batch (`estimateCloneBytes`). */
+    bytes?: number;
 } | {
     type: 'net:fetch';
     /** Per-context sequence — correlates the net:fetch-detail follow-up. */
@@ -164,6 +193,56 @@ export type DevtoolsEvent = {
         scope?: string;
         url?: string;
     }[];
+} | {
+    /**
+     * A main-thread frame that blocked rendering: Long Animation Frame
+     * entries where supported, `longtask` entries as the fallback.
+     */
+    type: 'runtime:longframe';
+    /** Frame (or long task) duration. */
+    ms: number;
+    /** Time past the 50ms budget that blocked input/render. */
+    blockingMs: number;
+    /** LoAF script attribution, longest first (capped). */
+    scripts?: {
+        src?: string;
+        fn?: string;
+        ms: number;
+    }[];
+    /**
+     * Page was hidden: frame duration is throttling, not work, so only
+     * frames with substantial script time are reported. Excluded from
+     * foreground jank metrics.
+     */
+    hidden?: boolean;
+} | {
+    /** Main-thread frame rate, sampled once a second via rAF while devtools is on. */
+    type: 'runtime:frames';
+    fps: number;
+    /** Frames over ~2× the display interval in that second. */
+    dropped: number;
+} | {
+    /** A `src/log.ts` entry, mirrored into the stream (worker logs forward too). */
+    type: 'log';
+    level: 'trace' | 'debug' | 'info' | 'warn' | 'error';
+    scope: string;
+    message: string;
+    /** Preview of the structured data (`previewValue`). */
+    data?: string;
+} | {
+    /**
+     * Cross-thread reactivity edge/node update for the dependency graph.
+     * `id` names a reactive source or subscriber; `deps` are the ids it reads.
+     */
+    type: 'reactive:node';
+    id: string;
+    kind: 'source' | 'derived' | 'effect' | 'bridge';
+    label?: string;
+    deps?: string[];
+    /** Thread-qualified owner, e.g. a pool id or island instance. */
+    owner?: string;
+    /** Set when the node is disposed. */
+    disposed?: boolean;
 };
 export type EmittedDevtoolsEvent = DevtoolsEvent & {
     /** performance.now() on the emitting thread. */
@@ -181,8 +260,17 @@ export type EmittedDevtoolsEvent = DevtoolsEvent & {
     };
 };
 export type DevtoolsSink = (event: EmittedDevtoolsEvent) => void;
-/** Install the event sink (devtools transports hook here); null disables. */
+/**
+ * Install the transport sink (devtools transports hook here); null removes
+ * it. Additive sinks (`addDevtoolsSink`) are unaffected.
+ */
 export declare const setDevtoolsSink: (custom: DevtoolsSink | null) => void;
+/**
+ * Add a listener alongside the transport sink (exporters like OTLP);
+ * returns its remover. Any installed listener turns `devtoolsEnabled()` on,
+ * so pools spawned afterwards enable worker forwarding the same way.
+ */
+export declare const addDevtoolsSink: (listener: DevtoolsSink) => (() => void);
 /** Emit a structured event — one branch when no sink is installed. */
 export declare const emitDevtools: (event: DevtoolsEvent) => void;
 /**
@@ -190,8 +278,37 @@ export declare const emitDevtools: (event: DevtoolsEvent) => void;
  * arrived over postMessage without re-stamping their timing/thread.
  */
 export declare const forwardDevtools: (event: EmittedDevtoolsEvent) => void;
-/** True when a devtools sink is installed on this thread. */
+/** True when a devtools sink (transport or additive listener) is installed on this thread. */
 export declare const devtoolsEnabled: () => boolean;
+/**
+ * Compact, bounded preview of any value for event payloads: JSON-ish,
+ * functions as '[fn]', typed arrays/buffers described by size, cycles cut,
+ * capped at `max` chars. Call only behind `devtoolsEnabled()`.
+ */
+export declare const previewValue: (value: unknown, max?: number) => string;
+/**
+ * Rough structured-clone size in bytes: strings 2B/char, numbers 8B,
+ * typed arrays/buffers by byteLength, plus small per-key overhead. A cost
+ * signal for the dashboard ("is this message big?"), not an exact count.
+ * Walks at most `budget` nodes. Call only behind `devtoolsEnabled()`.
+ */
+export declare const estimateCloneBytes: (value: unknown, budget?: number) => number;
+/**
+ * A command the dashboard can invoke on this app (`control` frames on the
+ * devtools transport). Args and result must be structured-cloneable and
+ * JSON-safe (the WebSocket path stringifies them).
+ */
+export type DevtoolsCommandHandler = (args: Record<string, unknown>) => unknown | Promise<unknown>;
+/**
+ * Register a dashboard-invocable command; returns an unregister function.
+ * Names are dotted by area: 'island.tree', 'worker.kill', 'memory.read'.
+ * A later registration under the same name replaces the earlier one.
+ */
+export declare const registerDevtoolsCommand: (name: string, handler: DevtoolsCommandHandler) => (() => void);
+/** Names of the registered commands — the dashboard enables controls from this. */
+export declare const listDevtoolsCommands: () => string[];
+/** Run a registered command (transports call this for inbound `control` frames). */
+export declare const runDevtoolsCommand: (name: string, args?: Record<string, unknown>) => Promise<unknown>;
 /**
  * Worker side: route emitted events to the main thread over the task
  * channel (`ATOLL_DEVTOOLS` messages — the pool re-emits them into its
@@ -219,5 +336,11 @@ export declare const installFetchProbe: (scope: {
  * inside worker_threads too). No-ops with none of the three.
  */
 export declare const installMemoryProbe: (scope: object, intervalMs?: number) => void;
-/** Process-unique ids for pools — 'pool-1', 'pool-2', … */
-export declare const nextDevtoolsId: (prefix: string) => string;
+/**
+ * Process-unique ids for runners. Unnamed: 'pool-1', 'worker-2', … Named:
+ * the slugged name plus a kind suffix, '-p' for a pool and '-w' for a
+ * dedicated worker ('regions-p', 'ops-inline-w'); a repeated name gets a
+ * counter ('regions-w', 'regions-w2'). Slugs never contain '#', '~' or
+ * '|', which the dashboard uses to qualify forwarded ids.
+ */
+export declare const nextDevtoolsId: (prefix: string, name?: string) => string;

package/dist/index.d.ts

@@ -11,8 +11,12 @@ export { MemoryManager } from './pool/memory.js';
 export { WorkerPool } from './pool/workerPool.js';
 export type { PoolStats, RunOptions } from './pool/workerPool.js';
 export { PoolQueueFullError, TaskAbortedError, TaskTimeoutError, WorkerCrashedError, } from './pool/errors.js';
-export { connectWorker, workerClient } from './pool/workerClient.js';
-export type { ClientMethods, ConnectWorkerConfig, WorkerClient, WorkerMethods, } from './pool/workerClient.js';
+export { DedicatedWorker } from './pool/dedicatedWorker.js';
+export type { DedicatedWorkerConfig } from './pool/dedicatedWorker.js';
+export { connectWorker, resolveWorkerCount, workerClient } from './pool/workerClient.js';
+export type { ClientMethods, ConnectWorkerConfig, WorkerClient, WorkerMethods, WorkerRunner, } from './pool/workerClient.js';
+export { connectSubWorker } from './pool/subWorkerClient.js';
+export type { ConnectSubWorkerConfig } from './pool/subWorkerClient.js';
 export { connectSharedWorker } from './shared/sharedWorkerClient.js';
 export type { SharedWorkerClient } from './shared/sharedWorkerClient.js';
 export { sharedWorkerHost } from './shared/sharedWorkerHost.js';
@@ -29,5 +33,5 @@ export { defineTask, isAsyncTask, toTask } from './task.js';
 export type { AsyncTask, TaskSnapshot } from './task.js';
 export { getLogLevel, log, scoped, setLogLevel, setLogSink } from './log.js';
 export type { LogEntry, LogLevel, LogSink } from './log.js';
-export { devtoolsEnabled, emitDevtools, installFetchProbe, installMemoryProbe, setDevtoolsSink, } from './devtools.js';
-export type { DevtoolsEvent, DevtoolsSink, DevtoolsThread, EmittedDevtoolsEvent, TaskSettleOutcome, } from './devtools.js';
+export { addDevtoolsSink, devtoolsEnabled, emitDevtools, estimateCloneBytes, installFetchProbe, installMemoryProbe, listDevtoolsCommands, previewValue, registerDevtoolsCommand, runDevtoolsCommand, setDevtoolsSink, } from './devtools.js';
+export type { DevtoolsCommandHandler, DevtoolsEvent, DevtoolsSink, DevtoolsThread, EmittedDevtoolsEvent, TaskSettleOutcome, } from './devtools.js';

package/dist/index.js

@@ -1,20 +1,22 @@
 import { msgpackrCodec as e } from "./index2.js";
 import { SchemaError as t, z as n } from "./index3.js";
 import { listSchema as r } from "./index4.js";
-import { devtoolsEnabled as i, emitDevtools as a, installFetchProbe as o, installMemoryProbe as s, setDevtoolsSink as c } from "./index5.js";
-import { getLogLevel as l, log as u, scoped as d, setLogLevel as f, setLogSink as p } from "./index6.js";
-import { bindSharedMemories as m, defineSharedMemory as h, field as g, getDefinedSharedMemoryCount as _, jsonCodec as v, registerConnectorFactory as y } from "./index7.js";
-import { reef as b } from "./index8.js";
-import { MemoryManager as x } from "./index9.js";
-import { PoolQueueFullError as S, TaskAbortedError as C, TaskTimeoutError as w, WorkerCrashedError as T } from "./index10.js";
-import { WorkerPool as E } from "./index11.js";
-import { connectWorker as D, workerClient as O } from "./index12.js";
-import { connectSharedWorker as k } from "./index13.js";
-import { TaskRegistry as A } from "./index14.js";
-import { sharedWorkerHost as j } from "./index15.js";
-import { createClient as M, defineService as N, implementService as P, rpc as F, serviceMethod as I } from "./index16.js";
-import { RESERVED_CLIENT_KEYS as L, defineWorker as R } from "./index18.js";
-import { reactive as z, shallowEqual as B, watch as V } from "./index19.js";
-import { observe as H } from "./index20.js";
-import { defineTask as U, isAsyncTask as W, toTask as G } from "./index21.js";
-export { x as MemoryManager, S as PoolQueueFullError, L as RESERVED_CLIENT_KEYS, t as SchemaError, C as TaskAbortedError, A as TaskRegistry, w as TaskTimeoutError, T as WorkerCrashedError, E as WorkerPool, m as bindSharedMemories, k as connectSharedWorker, D as connectWorker, M as createClient, N as defineService, h as defineSharedMemory, U as defineTask, R as defineWorker, i as devtoolsEnabled, a as emitDevtools, g as field, _ as getDefinedSharedMemoryCount, l as getLogLevel, P as implementService, o as installFetchProbe, s as installMemoryProbe, W as isAsyncTask, v as jsonCodec, r as listSchema, u as log, e as msgpackrCodec, H as observe, z as reactive, b as reef, y as registerConnectorFactory, F as rpc, d as scoped, I as serviceMethod, c as setDevtoolsSink, f as setLogLevel, p as setLogSink, B as shallowEqual, j as sharedWorkerHost, G as toTask, V as watch, O as workerClient, n as z };
+import { addDevtoolsSink as i, devtoolsEnabled as a, emitDevtools as o, estimateCloneBytes as s, installFetchProbe as c, installMemoryProbe as l, listDevtoolsCommands as u, previewValue as d, registerDevtoolsCommand as f, runDevtoolsCommand as p, setDevtoolsSink as m } from "./index5.js";
+import { getLogLevel as h, log as g, scoped as _, setLogLevel as v, setLogSink as y } from "./index7.js";
+import { bindSharedMemories as b, defineSharedMemory as x, field as S, getDefinedSharedMemoryCount as C, jsonCodec as w, registerConnectorFactory as T } from "./index8.js";
+import { reef as E } from "./index9.js";
+import { MemoryManager as D } from "./index10.js";
+import { PoolQueueFullError as O, TaskAbortedError as k, TaskTimeoutError as A, WorkerCrashedError as j } from "./index11.js";
+import { WorkerPool as M } from "./index15.js";
+import { DedicatedWorker as N } from "./index16.js";
+import { connectWorker as P, resolveWorkerCount as F, workerClient as I } from "./index17.js";
+import { connectSubWorker as L } from "./index18.js";
+import { connectSharedWorker as R } from "./index19.js";
+import { TaskRegistry as z } from "./index20.js";
+import { sharedWorkerHost as B } from "./index21.js";
+import { createClient as V, defineService as H, implementService as U, rpc as W, serviceMethod as G } from "./index22.js";
+import { RESERVED_CLIENT_KEYS as K, defineWorker as q } from "./index24.js";
+import { reactive as J, shallowEqual as Y, watch as X } from "./index26.js";
+import { observe as Z } from "./index27.js";
+import { defineTask as Q, isAsyncTask as $, toTask as ee } from "./index28.js";
+export { N as DedicatedWorker, D as MemoryManager, O as PoolQueueFullError, K as RESERVED_CLIENT_KEYS, t as SchemaError, k as TaskAbortedError, z as TaskRegistry, A as TaskTimeoutError, j as WorkerCrashedError, M as WorkerPool, i as addDevtoolsSink, b as bindSharedMemories, R as connectSharedWorker, L as connectSubWorker, P as connectWorker, V as createClient, H as defineService, x as defineSharedMemory, Q as defineTask, q as defineWorker, a as devtoolsEnabled, o as emitDevtools, s as estimateCloneBytes, S as field, C as getDefinedSharedMemoryCount, h as getLogLevel, U as implementService, c as installFetchProbe, l as installMemoryProbe, $ as isAsyncTask, w as jsonCodec, u as listDevtoolsCommands, r as listSchema, g as log, e as msgpackrCodec, Z as observe, d as previewValue, J as reactive, E as reef, T as registerConnectorFactory, f as registerDevtoolsCommand, F as resolveWorkerCount, W as rpc, p as runDevtoolsCommand, _ as scoped, G as serviceMethod, m as setDevtoolsSink, v as setLogLevel, y as setLogSink, Y as shallowEqual, B as sharedWorkerHost, ee as toTask, X as watch, I as workerClient, n as z };

package/dist/index10.js

@@ -1,20 +1,35 @@
-//#region src/pool/errors.ts
-var e = class extends Error {
-	constructor(e = "WorkerPool task queue is full") {
-		super(e), this.name = "PoolQueueFullError";
+//#region src/pool/memory.ts
+var e = class {
+	memory;
+	maxPages;
+	constructor(e = {}) {
+		let t = e.initialPages ?? 16;
+		this.maxPages = e.maximumPages ?? 16384, this.memory = new WebAssembly.Memory({
+			initial: t,
+			maximum: this.maxPages,
+			shared: !0
+		});
 	}
-}, t = class extends Error {
-	constructor(e = "task aborted") {
-		super(e), this.name = "AbortError";
+	ensureCapacity(e) {
+		let t = this.memory.buffer.byteLength;
+		if (t >= e) return;
+		let n = e - t, r = Math.ceil(n / 65536);
+		if (this.memory.buffer.byteLength / 65536 + r > this.maxPages) throw Error(`Cannot grow memory: exceeds maximum page limit of ${this.maxPages}`);
+		this.memory.grow(r);
 	}
-}, n = class extends Error {
-	constructor(e = "task timed out") {
-		super(e), this.name = "TaskTimeoutError";
+	getView(e, t = 0, n) {
+		let r = this.memory.buffer;
+		switch (e) {
+			case "Int32": return new Int32Array(r, t, n);
+			case "Float64": return new Float64Array(r, t, n);
+			case "BigInt64": return new BigInt64Array(r, t, n);
+			case "Uint8": return new Uint8Array(r, t, n);
+			default: throw Error(`Unsupported view type: ${e}`);
+		}
 	}
-}, r = class extends Error {
-	constructor(e = "worker crashed") {
-		super(e), this.name = "WorkerCrashedError";
+	getBuffer() {
+		return this.memory.buffer;
 	}
 };
 //#endregion
-export { e as PoolQueueFullError, t as TaskAbortedError, n as TaskTimeoutError, r as WorkerCrashedError };
+export { e as MemoryManager };