@atolljs/core 0.1.6 → 0.1.8

package/src/reactive.ts

@@ -1,6 +1,7 @@
 import { createEffect, createMemo, createRenderEffect, createRoot, createSignal } from 'solid-js';
 import { Connector } from './contract/sharedMemory';
 import { scoped } from './log';
+import { disposeNodes, graphNode, graphSource } from './reactiveGraph';
 
 const reactiveLog = scoped('reactive');
 
@@ -45,11 +46,39 @@ export interface ReactiveConnector<T> {
  * write — local or remote, both bump it. waitAsync when available, 50ms poll
  * otherwise. No solid-js involved: this is the whole remote-write mechanism.
  */
-const watchVersion = <T>(connector: Connector<T>, onBump: () => void): (() => void) => {
+interface VersionWatch {
+  stop: () => void;
+  /** Devtools graph id of the bridge node (null while devtools is off). */
+  node: string | null;
+}
+
+const watchVersionNode = <T>(connector: Connector<T>, onBump: () => void): VersionWatch => {
   const version = connector._version;
   if (!version) {
     throw new Error('This connector does not support remote observation.');
   }
+  const waits = typeof Atomics.waitAsync === 'function';
+  const node = graphNode('bridge', `${waits ? 'waitAsync' : 'poll'} ${connector._path ?? `@${connector.byteOffset}`}`, [
+    graphSource(connector._path),
+  ]);
+  const stop = watchVersionRaw(connector, version, onBump);
+  return {
+    node,
+    stop: () => {
+      stop();
+      disposeNodes(node);
+    },
+  };
+};
+
+const watchVersion = <T>(connector: Connector<T>, onBump: () => void): (() => void) =>
+  watchVersionNode(connector, onBump).stop;
+
+const watchVersionRaw = <T>(
+  connector: Connector<T>,
+  version: { view: Int32Array; index: number },
+  onBump: () => void,
+): (() => void) => {
   let stopped = false;
   let last = Atomics.load(version.view, version.index);
 
@@ -167,6 +196,39 @@ export function watch<T, S = T>(
 ): () => void {
   const select = onChange ? (selOrCb as (value: T) => S) : ((v: T) => v as unknown as S);
   const cb = (onChange ?? selOrCb) as (slice: S, previous: S | undefined) => void;
+  return watchNodes(connector, select, cb, options, { sliced: onChange !== undefined, label: 'watch' }).stop;
+}
+
+/** Graph labelling for {@link watchNodes} — `observe()` names its effect. */
+export interface WatchMeta {
+  /** A real selector was given (draws a derived node), not the identity. */
+  sliced: boolean;
+  /** Effect node label prefix: 'watch', 'observe'. */
+  label: string;
+}
+
+/**
+ * `watch()` plus its devtools graph wiring: bridge → [derived slice] →
+ * effect. Internal: `observe()` uses it to own the effect node's label.
+ */
+export function watchNodes<T, S>(
+  connector: Connector<T>,
+  select: (value: T) => S,
+  cb: (slice: S, previous: S | undefined) => void,
+  options: SliceOptions<S> | undefined,
+  meta: WatchMeta,
+): { stop: () => void; effect: string | null } {
+  const path = connector._path ?? `@${connector.byteOffset}`;
+  // Nodes are created around the version watch below; ids are null while
+  // devtools is off, and every graph call no-ops on null.
+  let bridge: string | null = null;
+  let derived: string | null = null;
+  let effect: string | null = null;
+  const graph = (): void => {
+    derived = meta.sliced ? graphNode('derived', `select(${path})`, [bridge]) : null;
+    effect = graphNode('effect', `${meta.label}(${path})`, [derived ?? bridge]);
+  };
+  const ungraph = (): void => disposeNodes(effect, derived);
 
   // SSR solid build (node/worker conditions): effects never re-run, so the
   // signal pipeline below would silently never emit. Same semantics, driven
@@ -184,20 +246,29 @@ export function watch<T, S = T>(
       cb(s, old);
     };
     emit();
-    const stop = watchVersion(connector, emit);
+    const remote = watchVersionNode(connector, emit);
+    bridge = remote.node;
+    graph();
     reactiveLog.debug(`watching connector at offset ${connector.byteOffset} (direct)`);
-    return () => {
-      reactiveLog.debug(`watch stopped (offset ${connector.byteOffset})`);
-      stop();
+    return {
+      effect,
+      stop: () => {
+        reactiveLog.debug(`watch stopped (offset ${connector.byteOffset})`);
+        remote.stop();
+        ungraph();
+      },
     };
   }
 
-  const sig = reactive(connector);
-  const stopRemote = sig.observeRemote();
+  // reactive(connector) + observeRemote(), inlined to keep the bridge id.
+  const [value, setValue] = createSignal<T>(connector.read(), { equals: false });
+  const remote = watchVersionNode(connector, () => setValue(() => connector.read()));
+  bridge = remote.node;
+  graph();
   const dispose = createRoot((d) => {
     const slice = createMemo(
       () => {
-        const v = sig.get() as T | null | undefined;
+        const v = value() as T | null | undefined;
         return v == null ? undefined : select(v);
       },
       undefined,
@@ -218,9 +289,13 @@ export function watch<T, S = T>(
     return d;
   });
   reactiveLog.debug(`watching connector at offset ${connector.byteOffset}`);
-  return () => {
-    reactiveLog.debug(`watch stopped (offset ${connector.byteOffset})`);
-    stopRemote();
-    dispose();
+  return {
+    effect,
+    stop: () => {
+      reactiveLog.debug(`watch stopped (offset ${connector.byteOffset})`);
+      remote.stop();
+      dispose();
+      ungraph();
+    },
   };
 }

package/src/reactiveGraph.ts

@@ -0,0 +1,91 @@
+/**
+ * `reactive:node` emission for the dashboard's reactivity graph. The SDK's
+ * reactivity is shallow, and the node kinds map onto it directly:
+ *
+ * - **source**: a shared-memory field, id `mem:<path>`, owner 'shared'.
+ *   The same id on every thread, so a worker-side writer and a main-thread
+ *   watcher meet at one node. Two contracts with the same field path
+ *   share the node (ids carry no contract identity across threads).
+ * - **bridge**: a version-counter watcher (`Atomics.waitAsync`, or the
+ *   50ms poll fallback): the only thing that crosses threads.
+ * - **derived**: a `watch`/`observe` selector slice.
+ * - **effect**: a `watch` callback, or an `observe` observable's
+ *   subscriber fan-out (label carries the subscriber count).
+ *
+ * Non-source ids are per-thread counters ('b3', 'e7'); the dashboard
+ * qualifies them by the event's thread/worker stamp. Everything here is
+ * a no-op returning null while devtools is off.
+ */
+import { devtoolsEnabled, emitDevtools, registerDevtoolsCommand } from './devtools';
+
+export type ReactiveKind = 'source' | 'derived' | 'effect' | 'bridge';
+
+interface NodeInfo {
+  id: string;
+  kind: ReactiveKind;
+  label?: string;
+  deps?: string[];
+  owner?: string;
+}
+
+const OWNER =
+  typeof WorkerGlobalScope !== 'undefined' && self instanceof WorkerGlobalScope ? 'worker' : 'main';
+
+let seq = 0;
+const live = new Map<string, NodeInfo>();
+let commandRegistered = false;
+
+const emit = (node: NodeInfo, disposed?: boolean): void => {
+  emitDevtools({ type: 'reactive:node', ...node, ...(disposed ? { disposed: true } : {}) });
+};
+
+const ensureCommand = (): void => {
+  if (commandRegistered) return;
+  commandRegistered = true;
+  // Snapshot for dashboards that joined after the creation events scrolled
+  // out of the replay tail. This thread's nodes only (commands run on the
+  // main thread; worker nodes arrive through the event stream).
+  registerDevtoolsCommand('reactive.nodes', () => [...live.values()]);
+};
+
+/** The source node for a shared-memory field — emitted once per thread. */
+export const graphSource = (path: string | undefined): string | null => {
+  if (!devtoolsEnabled() || path === undefined) return null;
+  ensureCommand();
+  const id = `mem:${path}`;
+  if (!live.has(id)) {
+    const node: NodeInfo = { id, kind: 'source', label: path, owner: 'shared' };
+    live.set(id, node);
+    emit(node);
+  }
+  return id;
+};
+
+/** Create a node; returns its id, or null while devtools is off. */
+export const graphNode = (kind: ReactiveKind, label: string, deps: (string | null)[]): string | null => {
+  if (!devtoolsEnabled()) return null;
+  ensureCommand();
+  const id = `${kind[0]}${++seq}`;
+  const node: NodeInfo = { id, kind, label, deps: deps.filter((d): d is string => d !== null), owner: OWNER };
+  live.set(id, node);
+  emit(node);
+  return id;
+};
+
+/** Re-emit a node with a new label (same id — the dashboard replaces it). */
+export const relabelNode = (id: string | null, label: string): void => {
+  const node = id === null ? undefined : live.get(id);
+  if (!node || node.label === label || !devtoolsEnabled()) return;
+  node.label = label;
+  emit(node);
+};
+
+/** Mark nodes disposed (null ids are skipped). */
+export const disposeNodes = (...ids: (string | null)[]): void => {
+  for (const id of ids) {
+    const node = id === null ? undefined : live.get(id);
+    if (!node) continue;
+    live.delete(id!);
+    if (devtoolsEnabled()) emit(node, true);
+  }
+};

package/src/testing/inProcessWorker.ts

@@ -72,9 +72,10 @@ export class InProcessWorker {
       return;
     }
     if (data.type === 'INIT_MEMORY') {
-      this.ready ??= this.boot().then(() =>
-        bindSharedMemories((data.memory as WebAssembly.Memory).buffer as unknown as SharedArrayBuffer),
-      );
+      const buffer = (data.memory as WebAssembly.Memory | undefined)?.buffer ?? data.buffer;
+      this.ready ??= this.boot().then(() => {
+        if (buffer) bindSharedMemories(buffer as SharedArrayBuffer);
+      });
       try {
         await this.ready;
       } catch (err) {

package/src/userTiming.ts

@@ -0,0 +1,71 @@
+/**
+ * User Timing bridge: `performance.measure` entries for atoll work, so the
+ * browser's own Performance panel shows tasks next to the app's frames.
+ * Callers gate on `devtoolsEnabled()`; this module never checks it itself.
+ *
+ * `detail.devtools` is Chrome's extensibility payload: entries land on a
+ * custom track inside an 'atoll' track group. Other engines ignore the
+ * detail and record a plain measure.
+ */
+
+/** Chrome's extensibility palette names. */
+export type TimingColor = 'primary' | 'primary-light' | 'secondary' | 'tertiary' | 'error' | 'warning';
+
+export interface TimingTrack {
+  /** Track label inside the 'atoll' group, e.g. a pool id. */
+  track: string;
+  color?: TimingColor;
+  properties?: [string, string | number][];
+  tooltipText?: string;
+}
+
+type MeasureFn = (name: string, options: { start: number; end: number; detail?: unknown }) => unknown;
+
+/**
+ * Record `[start, end]` (performance.now() ms on this thread) as `name`.
+ * The entry is cleared from the timeline buffer right away: the Performance
+ * panel captures it at measure time, and per-task measures would otherwise
+ * grow the buffer without bound (and trip Node's buffer-size warning).
+ */
+export const measureAtoll = (name: string, start: number, end: number, t: TimingTrack): void => {
+  const perf = globalThis.performance as
+    | (Performance & { measure?: MeasureFn; clearMeasures?: (name?: string) => void })
+    | undefined;
+  if (typeof perf?.measure !== 'function') return;
+  try {
+    perf.measure(name, {
+      start,
+      end: Math.max(end, start),
+      detail: {
+        devtools: {
+          dataType: 'track-entry',
+          track: t.track,
+          trackGroup: 'atoll',
+          color: t.color ?? 'primary',
+          properties: t.properties,
+          tooltipText: t.tooltipText,
+        },
+      },
+    });
+    perf.clearMeasures?.(name);
+  } catch {
+    /* engines without the options-object measure signature */
+  }
+};
+
+/** Main-thread span of one call, dispatch → settle, on the runner's track. */
+export const measureTaskCall = (
+  runnerId: string,
+  taskId: string,
+  callId: number,
+  slot: number,
+  start: number,
+  end: number,
+  ok: boolean,
+): void =>
+  measureAtoll(`atoll task ${taskId}`, start, end, {
+    track: runnerId,
+    color: ok ? 'primary' : 'error',
+    properties: [['runner', runnerId], ['slot', slot], ['call', callId], ['outcome', ok ? 'ok' : 'error']],
+    tooltipText: `${taskId} on ${runnerId}#${slot}: ${(end - start).toFixed(1)}ms`,
+  });

package/src/worker/workerBootstrap.ts

@@ -1,9 +1,22 @@
 import { TaskRegistry } from './registry';
 import { bindSharedMemories, getDefinedSharedMemoryCount } from '../contract/sharedMemory';
+import { devtoolsEnabled, enableWorkerDevtoolsForwarding } from '../devtools';
 import { fmtBytes, scoped } from '../log';
+import { measureAtoll } from '../userTiming';
 
 const workerLog = scoped('worker');
 
+/** Worker-side span of one task execution, on this worker thread's 'tasks' track. */
+const measureRun = (taskId: string, messageId: number, t0: number, ok: boolean): void => {
+  const t1 = performance.now();
+  measureAtoll(`atoll run ${taskId}`, t0, t1, {
+    track: 'tasks',
+    color: ok ? 'secondary' : 'error',
+    properties: [['message', messageId], ['outcome', ok ? 'ok' : 'error']],
+    tooltipText: `${taskId}: ${(t1 - t0).toFixed(1)}ms in worker`,
+  });
+};
+
 let memoryInitialized = false;
 let wired = false;
 
@@ -30,6 +43,7 @@ export function installWorkerListener(): void {
 
     if (data.type === 'INIT') {
       memoryInitialized = true;
+      if (data.devtools) enableWorkerDevtoolsForwarding();
       if (getDefinedSharedMemoryCount() > 0) {
         workerLog.warn(
           'pool sent INIT without memory, but shared-memory contracts are defined — field access will throw until bound',
@@ -40,10 +54,20 @@ export function installWorkerListener(): void {
     }
 
     if (data.type === 'INIT_MEMORY') {
-      const memory = data.memory as WebAssembly.Memory;
-      bindSharedMemories(memory.buffer as unknown as SharedArrayBuffer);
+      // `memory` is the pool-allocated WebAssembly.Memory; `buffer` is an
+      // existing SharedArrayBuffer the caller ships directly (sub-worker
+      // shell, second pool sharing a buffer).
+      const buffer =
+        (data.memory as WebAssembly.Memory | undefined)?.buffer ??
+        (data.buffer as SharedArrayBuffer | undefined);
+      if (!buffer) {
+        workerLog.warn('INIT_MEMORY arrived without a buffer — contracts stay unbound');
+        return;
+      }
+      bindSharedMemories(buffer as unknown as SharedArrayBuffer);
       memoryInitialized = true;
-      workerLog.info(`shared memory initialized (${fmtBytes(memory.buffer.byteLength)})`);
+      if (data.devtools) enableWorkerDevtoolsForwarding();
+      workerLog.info(`shared memory initialized (${fmtBytes(buffer.byteLength)})`);
       return;
     }
 
@@ -59,9 +83,11 @@ export function installWorkerListener(): void {
       const t0 = performance.now();
       try {
         const result = await TaskRegistry.execute(taskId, ...(args || []));
+        if (devtoolsEnabled()) measureRun(taskId, messageId, t0, true);
         workerLog.debug(`task ${taskId} → ${(performance.now() - t0).toFixed(1)}ms`);
         self.postMessage({ messageId, success: true, result });
       } catch (err: any) {
+        if (devtoolsEnabled()) measureRun(taskId, messageId, t0, false);
         workerLog.warn(`task ${taskId} failed: ${err.message || String(err)}`);
         self.postMessage({ messageId, success: false, error: err.message || String(err) });
       }