@atolljs/core 0.1.7 → 0.1.8

package/src/contract/types.ts

@@ -57,6 +57,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/src/devtools.ts

@@ -26,8 +26,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 }
   | { type: 'worker:spawn'; poolId: string; slot: number }
@@ -41,6 +47,8 @@ export type DevtoolsEvent =
       taskId: string;
       slot: number;
       waitMs: number;
+      /** Estimated structured-clone size of the task args (`estimateCloneBytes`). */
+      argBytes?: number;
     }
   | {
       type: 'task:settle';
@@ -51,6 +59,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';
@@ -59,6 +69,16 @@ export type DevtoolsEvent =
       totalBytes: number;
     }
   | { 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;
@@ -70,7 +90,20 @@ export type DevtoolsEvent =
       framework?: string;
     }
   | { type: 'island:unmount'; instance: string }
-  | { type: 'island:event'; instance: string; name: string }
+  | {
+      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;
@@ -90,6 +123,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';
@@ -148,6 +183,56 @@ export type DevtoolsEvent =
        * Worker contexts are identified by their script URL.
        */
       contexts?: { bytes: number; 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 & {
@@ -170,11 +255,54 @@ const THREAD: DevtoolsThread =
     ? 'worker'
     : 'main';
 
+/** The composed sink `emitDevtools` calls: null when nothing listens. */
 let sink: DevtoolsSink | null = null;
+/** The transport slot `setDevtoolsSink` owns. */
+let primary: DevtoolsSink | null = null;
+/** Additive listeners (`addDevtoolsSink`): exporters riding alongside the transport. */
+const extraSinks = new Set<DevtoolsSink>();
 
-/** Install the event sink (devtools transports hook here); null disables. */
+const recompose = (): void => {
+  if (extraSinks.size === 0) {
+    sink = primary;
+    return;
+  }
+  const all = primary ? [primary, ...extraSinks] : [...extraSinks];
+  // Fan-out isolates listeners: one throwing sink can't starve the others.
+  sink =
+    all.length === 1
+      ? all[0]
+      : (event) => {
+          for (const s of all) {
+            try {
+              s(event);
+            } catch {
+              /* a broken listener must not break the app or its siblings */
+            }
+          }
+        };
+};
+
+/**
+ * Install the transport sink (devtools transports hook here); null removes
+ * it. Additive sinks (`addDevtoolsSink`) are unaffected.
+ */
 export const setDevtoolsSink = (custom: DevtoolsSink | null): void => {
-  sink = custom;
+  primary = custom;
+  recompose();
+};
+
+/**
+ * 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 const addDevtoolsSink = (listener: DevtoolsSink): (() => void) => {
+  extraSinks.add(listener);
+  recompose();
+  return () => {
+    if (extraSinks.delete(listener)) recompose();
+  };
 };
 
 /** Emit a structured event — one branch when no sink is installed. */
@@ -190,9 +318,109 @@ export const forwardDevtools = (event: EmittedDevtoolsEvent): void => {
   if (sink) sink(event);
 };
 
-/** 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 const devtoolsEnabled = (): boolean => sink !== null;
 
+/**
+ * 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 const previewValue = (value: unknown, max = 2048): string => {
+  const seen = new WeakSet<object>();
+  let out: string;
+  try {
+    out =
+      JSON.stringify(value, (_k, v: unknown) => {
+        if (typeof v === 'function') return '[fn]';
+        if (typeof v === 'bigint') return `${v}n`;
+        if (v instanceof ArrayBuffer) return `[ArrayBuffer ${v.byteLength}B]`;
+        if (ArrayBuffer.isView(v)) return `[${v.constructor.name} ${v.byteLength}B]`;
+        if (v instanceof Map) return { '[Map]': [...v.entries()].slice(0, 50) };
+        if (v instanceof Set) return { '[Set]': [...v].slice(0, 50) };
+        if (v && typeof v === 'object') {
+          if (seen.has(v)) return '[cycle]';
+          seen.add(v);
+        }
+        return v;
+      }) ?? String(value);
+  } catch {
+    out = String(value);
+  }
+  return out.length > max ? `${out.slice(0, max)}…` : out;
+};
+
+/**
+ * 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 const estimateCloneBytes = (value: unknown, budget = 5000): number => {
+  let nodes = 0;
+  const seen = new WeakSet<object>();
+  const walk = (v: unknown): number => {
+    if (++nodes > budget) return 0;
+    switch (typeof v) {
+      case 'string': return 4 + v.length * 2;
+      case 'number': return 8;
+      case 'boolean': return 4;
+      case 'bigint': return 16;
+      case 'undefined': return 1;
+      case 'object': {
+        if (v === null) return 1;
+        if (v instanceof ArrayBuffer) return v.byteLength;
+        if (ArrayBuffer.isView(v)) return v.byteLength;
+        if (typeof SharedArrayBuffer !== 'undefined' && v instanceof SharedArrayBuffer) return 8;
+        if (seen.has(v)) return 4;
+        seen.add(v);
+        let n = 8;
+        if (v instanceof Map) for (const [k, x] of v) n += walk(k) + walk(x);
+        else if (v instanceof Set) for (const x of v) n += walk(x);
+        else if (Array.isArray(v)) for (const x of v) n += walk(x);
+        else for (const k of Object.keys(v)) n += 4 + k.length * 2 + walk((v as Record<string, unknown>)[k]);
+        return n;
+      }
+      default: return 0;
+    }
+  };
+  return walk(value);
+};
+
+/* ── control: dashboard → app commands ───────────────────────────────────── */
+
+/**
+ * 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>;
+
+const commands = new Map<string, DevtoolsCommandHandler>();
+
+/**
+ * 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 const registerDevtoolsCommand = (name: string, handler: DevtoolsCommandHandler): (() => void) => {
+  commands.set(name, handler);
+  return () => {
+    if (commands.get(name) === handler) commands.delete(name);
+  };
+};
+
+/** Names of the registered commands — the dashboard enables controls from this. */
+export const listDevtoolsCommands = (): string[] => [...commands.keys()].sort();
+
+/** Run a registered command (transports call this for inbound `control` frames). */
+export const runDevtoolsCommand = async (name: string, args: Record<string, unknown> = {}): Promise<unknown> => {
+  if (name === 'devtools.commands') return listDevtoolsCommands();
+  const handler = commands.get(name);
+  if (!handler) throw new Error(`unknown devtools command '${name}'`);
+  return handler(args);
+};
+
 let workerForwarding = false;
 
 /**
@@ -486,5 +714,22 @@ export const installMemoryProbe = (scope: object, intervalMs = 2500): void => {
 };
 
 let seq = 0;
-/** Process-unique ids for pools — 'pool-1', 'pool-2', … */
-export const nextDevtoolsId = (prefix: string): string => `${prefix}-${++seq}`;
+const named = new Map<string, number>();
+/**
+ * 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 const nextDevtoolsId = (prefix: string, name?: string): string => {
+  const slug = name
+    ?.toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  if (!slug) return `${prefix}-${++seq}`;
+  const base = `${slug}-${prefix === 'pool' ? 'p' : prefix === 'worker' ? 'w' : prefix}`;
+  const n = (named.get(base) ?? 0) + 1;
+  named.set(base, n);
+  return n === 1 ? base : `${base}${n}`;
+};

package/src/index.ts

@@ -62,13 +62,18 @@ export {
   TaskTimeoutError,
   WorkerCrashedError,
 } from './pool/errors';
-export { connectWorker, workerClient } from './pool/workerClient';
+export { DedicatedWorker } from './pool/dedicatedWorker';
+export type { DedicatedWorkerConfig } from './pool/dedicatedWorker';
+export { connectWorker, resolveWorkerCount, workerClient } from './pool/workerClient';
 export type {
   ClientMethods,
   ConnectWorkerConfig,
   WorkerClient,
   WorkerMethods,
+  WorkerRunner,
 } from './pool/workerClient';
+export { connectSubWorker } from './pool/subWorkerClient';
+export type { ConnectSubWorkerConfig } from './pool/subWorkerClient';
 
 /* ── SharedWorker — one worker (and one buffer) across tabs/iframes ──────── */
 
@@ -115,13 +120,20 @@ export type { AsyncTask, TaskSnapshot } from './task';
 export { getLogLevel, log, scoped, setLogLevel, setLogSink } from './log';
 export type { LogEntry, LogLevel, LogSink } from './log';
 export {
+  addDevtoolsSink,
   devtoolsEnabled,
   emitDevtools,
+  estimateCloneBytes,
   installFetchProbe,
   installMemoryProbe,
+  listDevtoolsCommands,
+  previewValue,
+  registerDevtoolsCommand,
+  runDevtoolsCommand,
   setDevtoolsSink,
 } from './devtools';
 export type {
+  DevtoolsCommandHandler,
   DevtoolsEvent,
   DevtoolsSink,
   DevtoolsThread,

package/src/log.ts

@@ -7,6 +7,8 @@
  *   setLogLevel('debug'); // or 'trace', 'warn', 'off'
  */
 
+import { devtoolsEnabled, emitDevtools, previewValue } from './devtools';
+
 export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'off';
 
 const LEVELS: Record<LogLevel, number> = { trace: 0, debug: 1, info: 2, warn: 3, error: 4, off: 5 };
@@ -46,9 +48,29 @@ export const getLogLevel = (): LogLevel => minLevel;
 /** Replace the console sink (e.g. collect entries for a UI panel); null restores it. */
 export const setLogSink = (custom: LogSink | null): void => { sink = custom ?? consoleSink; };
 
+/** Set while a log entry is being mirrored, so a transport that logs can't recurse. */
+let teeing = false;
+
 export function log(level: Exclude<LogLevel, 'off'>, scope: string, message: string, data?: unknown): void {
   if (LEVELS[level] < LEVELS[minLevel]) return;
   sink({ level, scope, message, data, thread: THREAD, at: performance.now() });
+  // Mirror into the devtools stream alongside (never instead of) the log
+  // sink. Worker-side entries ride the same ATOLL_DEVTOOLS forwarding as
+  // every other worker event once the INIT handshake enables it.
+  if (!teeing && devtoolsEnabled()) {
+    teeing = true;
+    try {
+      emitDevtools({
+        type: 'log',
+        level,
+        scope,
+        message,
+        ...(data !== undefined ? { data: previewValue(data, 1024) } : {}),
+      });
+    } finally {
+      teeing = false;
+    }
+  }
 }
 
 /** A logger bound to a subsystem scope: `poolLog.info('spawned')`. */

package/src/observable.ts

@@ -1,5 +1,6 @@
 import type { Connector, PathConnector, SharedMemory, SharedSpec, SpecPath } from './contract/sharedMemory';
-import { watch, type SliceOptions } from './reactive';
+import { watchNodes, type SliceOptions } from './reactive';
+import { relabelNode } from './reactiveGraph';
 import { scoped } from './log';
 
 const obsLog = scoped('observe');
@@ -57,7 +58,10 @@ export function observe<S extends SharedSpec, K extends SpecPath<S>, Sel>(
   let pendingBind: (() => void) | null = null;
   let rebindUn: (() => void) | null = null;
   let watched: Connector<T> | null = null;
+  /** Devtools graph id of the watch's effect node — relabelled with the subscriber count. */
+  let effectNode: string | null = null;
   const subscribers = new Set<(value: Out | undefined) => void>();
+  const relabel = () => relabelNode(effectNode, `observe(${String(key)}) · ${subscribers.size} sub${subscribers.size === 1 ? '' : 's'}`);
 
   const activate = () => {
     if (unwatch || pendingBind) return;
@@ -67,12 +71,14 @@ export function observe<S extends SharedSpec, K extends SpecPath<S>, Sel>(
     } catch {
       // Not bound on this thread yet — activate when it is.
       pendingBind = memory.onBound(() => {
+        const un = pendingBind;
         pendingBind = null;
+        un?.();
         activate();
       });
       return;
     }
-    unwatch = watch(
+    const w = watchNodes(
       connector,
       selectFn as (value: T) => Sel,
       (value) => {
@@ -83,8 +89,12 @@ export function observe<S extends SharedSpec, K extends SpecPath<S>, Sel>(
           for (const cb of subscribers) cb(value);
         }
       },
-      options
+      options,
+      { sliced: select !== undefined, label: 'observe' }
     );
+    unwatch = w.stop;
+    effectNode = w.effect;
+    relabel();
     watched = connector;
     // bind() can REBIND this contract to a different buffer — in-process
     // harnesses run every worker's bindSharedMemories in one module graph,
@@ -111,6 +121,7 @@ export function observe<S extends SharedSpec, K extends SpecPath<S>, Sel>(
   const deactivate = () => {
     unwatch?.();
     unwatch = null;
+    effectNode = null;
     watched = null;
     pendingBind?.();
     pendingBind = null;
@@ -142,9 +153,11 @@ export function observe<S extends SharedSpec, K extends SpecPath<S>, Sel>(
     subscribe(onChange) {
       subscribers.add(onChange);
       activate();
+      relabel();
       return () => {
         subscribers.delete(onChange);
         if (subscribers.size === 0) deactivate();
+        else relabel();
       };
     },
   };