omkit 0.8.16 → 0.8.18

package/README.md

@@ -132,6 +132,8 @@ Resolution happens **inside** the run, so a prompt and its answer land on the ru
 
 An action can `attach` a value — a port, a client, a page — that downstream actions receive by awaiting `activity.ref`. Not a file descriptor scraped from a log: a typed runtime handoff, so steps chain without globals or string-parsing. The first `attach` wins; later ones are ignored. Unlike `.result`, `.ref` **rejects** on failure or cancellation — a consumer waiting on a capability that never arrives fails instead of hanging — and an action that publishes nothing still resolves its `.ref` with `undefined` on success, so awaiting it never wedges.
 
+The handle `.ref` resolves is a thin, shallow wrapper over the attached value: every reader gets the same one, methods run bound to the real object (private fields work), and each public method call another action makes on it is recorded in the run — who called, from which line, how long it took — so the report can show it. Return values are not wrapped, and recording stops after 500 calls per handle.
+
 ```ts
 const server = action("server")
   .ref<number>() // this action publishes a port
@@ -189,7 +191,7 @@ Every action's output, events, asserts, snapshots, and lifecycle land on **one t
 - `raw.jsonl` — every entry, machine-readable.
 - `main.log` + one `.log` per action — the human-readable timelines.
 - `events.log` / `asserts.log` / `snapshots.log` / `artifacts.log` — cross-cutting rollups.
-- `report.html` — the whole run as one self-contained page: a timeline of every action with its events, a flow graph of the tree, per-action details, logs, assertions, the run's snapshots and images, each action's source (the `<>` button next to a block), and an Errors tab that collects failures, failed assertions and error output, and can highlight the actions they came from in every graph. Everything is inlined (data, base64 images, d3), so it opens straight from disk and survives being zipped or attached.
+- `report.html` — the whole run as one self-contained page: a timeline of every action with its events, a flow graph of the tree, per-action details, logs, assertions, the run's snapshots and images, each action's source (the `<>` button next to a block), an Errors tab that collects failures, failed assertions and error output, and can highlight the actions they came from in every graph, and the links between actions: who waited on whose event (`once`), who cancelled whom, and the calls made on another action's `.ref`. Everything is inlined (data, base64 images, d3), so it opens straight from disk and survives being zipped or attached.
 
 `ctx` also gives each action `assert(cond, msg)` (tallies into the run's verdict), `snapshot(name, value)` (captures JSON state to the run folder), and `artifact(name, file, opts?)` (labels a file the action wrote — name, optional description, MIME inferred from the extension — and returns its absolute path) — so a run is an inspectable artifact, not just an exit code. Write the files you label under `ctx.artifactsFolder`, the run's own output folder.
 

package/dist/core/ActionRun.d.ts

@@ -72,6 +72,8 @@ export declare class ActionRun<Result = unknown, Events extends object = object,
     private attached;
     private observed;
     private refObserved;
+    /** The traced handle every `.ref` reader shares (see {@link traceHandle}); made on first read. */
+    private tracedRef;
     private cancelLogged;
     private armedExec;
     private armedArgs;
@@ -123,4 +125,6 @@ export declare class ActionRun<Result = unknown, Events extends object = object,
      */
     private lifecycle;
     private log;
+    /** A cross-node interaction, on this (the targeted) node's log; `source` is the link's op. */
+    private link;
 }

package/dist/core/ActionRun.js

@@ -2,6 +2,9 @@ import { defer } from "../foundation/Deferred.js";
 import { events } from "../foundation/events.js";
 import { CancelledError } from "../foundation/CancelledError.js";
 import { renderValue } from "../foundation/format.js";
+import { callerSite } from "../foundation/callsite.js";
+import { currentNode } from "./context.js";
+import { traceHandle, REF_CALL_CAP } from "./refTrace.js";
 import { createProc } from "../system/proc.js";
 import { FolderCache } from "../system/fs/FolderCache.js";
 /**
@@ -45,6 +48,8 @@ export class ActionRun {
     attached = false;
     observed = false;
     refObserved = false;
+    /** The traced handle every `.ref` reader shares (see {@link traceHandle}); made on first read. */
+    tracedRef;
     cancelLogged = false;
     // The armed body + args, set at launch and run once by `commit()` on a microtask — the
     // window during which `withCache` may still wrap the body. `committed` closes that window.
@@ -108,7 +113,23 @@ export class ActionRun {
     /** The attached handle; rejects on failure/cancel. */
     get ref() {
         this.refObserved = true;
-        return this.handle.promise;
+        // One traced handle for every reader — identity holds across reads, and each method call
+        // another node makes on it is recorded here as a `ref` link.
+        if (!this.tracedRef) {
+            this.tracedRef = this.handle.promise.then((h) => traceHandle(h, {
+                call: (c) => this.link(`${c.key}() ← ${c.from} · ${c.ms}ms${c.outcome === "failed" ? " · failed" : ""}`, {
+                    op: "ref",
+                    from: c.from,
+                    ...(c.site ? { site: c.site } : {}),
+                    key: c.key,
+                    ms: c.ms,
+                    outcome: c.outcome,
+                }),
+                capped: () => this.log("info", "ref", `ref calls past ${REF_CALL_CAP} are not recorded`),
+            }));
+            void this.tracedRef.catch(() => { });
+        }
+        return this.tracedRef;
     }
     on(key, handler) {
         // A late `on("error")` (e.g. attached after an `await`, once the body has already
@@ -119,9 +140,29 @@ export class ActionRun {
         this.emitter.listen(key, handler);
     }
     once(key) {
+        // Who waits, from where — recorded on this node as a `once` link when the wait ends.
+        const from = currentNode.getStore();
+        const site = callerSite();
+        const t0 = Date.now();
+        const note = (outcome) => {
+            if (!from || from.id === this.id)
+                return;
+            const ms = Date.now() - t0;
+            this.link(`${String(key)} ← ${from.id} · ${outcome} after ${ms}ms`, {
+                op: "once",
+                from: from.id,
+                ...(site ? { site } : {}),
+                key: String(key),
+                ms,
+                outcome,
+            });
+        };
         // `done` is the outcome itself — identical to `.result` (resolve the value, reject on failure).
-        if (key === "done")
-            return this.result;
+        if (key === "done") {
+            const outcome = this.result;
+            outcome.then(() => note("fired"), () => note("failed"));
+            return outcome;
+        }
         // Awaiting an event observes the activity: resolve the payload when it fires, but if the
         // activity settles first, resolve `undefined` on success and **reject** on failure/cancel —
         // so an event gate surfaces a failure instead of hanging (or, for `error`, hand back the error).
@@ -130,16 +171,21 @@ export class ActionRun {
             let done = false;
             const win = () => (done ? false : (done = true));
             this.emitter.listenOnce(key, (p) => {
-                if (win())
-                    resolve(p);
+                if (!win())
+                    return;
+                note("fired");
+                resolve(p);
             });
             this.settled.promise.then(() => {
-                if (win())
-                    resolve(undefined);
+                if (!win())
+                    return;
+                note("ended");
+                resolve(undefined);
             }, (error) => {
                 if (!win())
                     return;
                 // Awaiting the `error` event hands back the error; any other gate rejects on failure.
+                note(key === "error" ? "fired" : "failed");
                 if (key === "error")
                     resolve(error);
                 else
@@ -165,6 +211,16 @@ export class ActionRun {
         return this;
     }
     cancel() {
+        // A cancel from another node is a link: who stopped this one, and from where.
+        const from = currentNode.getStore();
+        if (from && from.id !== this.id && this.parentId !== null && this.status === "running") {
+            const site = callerSite();
+            this.link(`by ${from.id}${site ? ` @ ${site}` : ""}`, {
+                op: "cancel",
+                from: from.id,
+                ...(site ? { site } : {}),
+            });
+        }
         this.noteCancelled(); // a direct cancel of this activity
         this.controller.abort();
     }
@@ -335,6 +391,17 @@ export class ActionRun {
     log(level, source, message) {
         this.store.append({ nodeId: this.id, path: this.path, level, source, message });
     }
+    /** A cross-node interaction, on this (the targeted) node's log; `source` is the link's op. */
+    link(message, link) {
+        this.store.append({
+            nodeId: this.id,
+            path: this.path,
+            level: "link",
+            source: link.op,
+            message,
+            link,
+        });
+    }
 }
 const messageOf = (error) => error instanceof Error ? (error.stack ?? error.message) : String(error);
 const firstLine = (message) => message.split("\n", 1)[0] ?? message;

package/dist/core/refTrace.d.ts

@@ -0,0 +1,22 @@
+/** Calls recorded per handle; past this the trace goes quiet, so a polling loop can't flood the log. */
+export declare const REF_CALL_CAP = 500;
+/** One method call on a traced handle, as {@link traceHandle} reports it. */
+export interface RefCall {
+    /** The calling node's id. */
+    readonly from: string;
+    readonly site: string | undefined;
+    readonly key: string;
+    readonly ms: number;
+    readonly outcome: "ok" | "failed";
+}
+/**
+ * Wrap an attached handle so each public method call on it is reported — who called (the
+ * ambient node), from where, how long it took, and whether it threw. Shallow by design: what
+ * a method returns is handed back untraced. Methods run bound to the real object, so private
+ * fields keep working; symbol, `_`-prefixed and {@link QUIET} members pass through unrecorded.
+ * A primitive or nullish handle is returned as is.
+ */
+export declare const traceHandle: <H>(handle: H, report: {
+    call: (call: RefCall) => void;
+    capped: () => void;
+}) => H;

package/dist/core/refTrace.js

@@ -0,0 +1,71 @@
+import { callerSite } from "../foundation/callsite.js";
+import { currentNode } from "./context.js";
+/** Calls recorded per handle; past this the trace goes quiet, so a polling loop can't flood the log. */
+export const REF_CALL_CAP = 500;
+/** Members never recorded: promise/serialization/inspection plumbing, not the caller's intent. */
+const QUIET = new Set([
+    "then",
+    "catch",
+    "finally",
+    "toJSON",
+    "toString",
+    "valueOf",
+    "inspect",
+    "constructor",
+]);
+/**
+ * Wrap an attached handle so each public method call on it is reported — who called (the
+ * ambient node), from where, how long it took, and whether it threw. Shallow by design: what
+ * a method returns is handed back untraced. Methods run bound to the real object, so private
+ * fields keep working; symbol, `_`-prefixed and {@link QUIET} members pass through unrecorded.
+ * A primitive or nullish handle is returned as is.
+ */
+export const traceHandle = (handle, report) => {
+    if (handle === null || (typeof handle !== "object" && typeof handle !== "function"))
+        return handle;
+    const cache = new Map();
+    let count = 0;
+    return new Proxy(handle, {
+        get(target, prop) {
+            const value = Reflect.get(target, prop, target);
+            if (typeof value !== "function")
+                return value;
+            // a non-configurable, read-only property must come back as itself (a Proxy invariant)
+            const own = Reflect.getOwnPropertyDescriptor(target, prop);
+            if (own && !own.configurable && !own.writable)
+                return value;
+            const hit = cache.get(prop);
+            if (hit && hit.orig === value)
+                return hit.fn;
+            const name = String(prop);
+            const quiet = typeof prop === "symbol" || name.startsWith("_") || QUIET.has(name);
+            const method = value;
+            const fn = (...args) => {
+                const from = currentNode.getStore()?.id;
+                if (quiet || !from || count >= REF_CALL_CAP)
+                    return method.apply(target, args);
+                if (++count === REF_CALL_CAP)
+                    report.capped();
+                const site = callerSite();
+                const t0 = Date.now();
+                const done = (outcome) => report.call({ from, site, key: name, ms: Date.now() - t0, outcome });
+                let out;
+                try {
+                    out = method.apply(target, args);
+                }
+                catch (error) {
+                    done("failed");
+                    throw error;
+                }
+                if (out !== null && typeof out?.then === "function") {
+                    out.then(() => done("ok"), () => done("failed"));
+                }
+                else
+                    done("ok");
+                return out;
+            };
+            cache.set(prop, { orig: value, fn });
+            return fn;
+        },
+    });
+};

package/dist/foundation/LogEntry.d.ts

@@ -13,11 +13,31 @@ export interface LogEntry {
     readonly nodeId: string;
     /** The owning node's execution path (`main/chromePage_9f3c`). */
     readonly path: string;
-    /** `info` | `error` | `event` | `assert` | `snapshot` | `artifact` | `tag` | `child` | `run`. */
+    /** `info` | `error` | `event` | `assert` | `snapshot` | `artifact` | `tag` | `child` | `run` | `link`. */
     readonly level: string;
     /** Finer origin within the node (proc name, `event`, `run`, …). */
     readonly source: string;
     readonly message: string;
+    /** Set on `level: "link"` entries — the other side of a cross-node interaction. */
+    readonly link?: LogLink;
+}
+/**
+ * A cross-node interaction, recorded on the node it targets: another node waited on one of
+ * its events (`once`), cancelled it (`cancel`), or called a method on its attached handle
+ * (`ref`). The entry's `ts` is when the interaction ended, so a timed one spans `ts - ms … ts`.
+ */
+export interface LogLink {
+    readonly op: "once" | "cancel" | "ref";
+    /** The calling node's id. */
+    readonly from: string;
+    /** `file:line` of the call, when the stack had one. */
+    readonly site?: string;
+    /** The awaited event key (`once`) or the called method (`ref`). */
+    readonly key?: string;
+    /** How long the wait or call lasted (`once`, `ref`). */
+    readonly ms?: number;
+    /** How it ended — `fired` | `ended` | `failed` for a once, `ok` | `failed` for a ref call. */
+    readonly outcome?: string;
 }
 /** What an appender supplies; the store stamps `sequence` and `ts`. */
 export type LogInput = Omit<LogEntry, "sequence" | "ts">;

package/dist/output/writers/report/report.css

@@ -147,10 +147,11 @@ button { font: inherit; color: inherit; }
 .row .label .tcall { font-size: 11.5px; }
 .row .label .sep, .row .l2 .sep { color: var(--text-3); }
 .row .l2 { font-size: 11px; color: var(--text-2); font-variant-numeric: tabular-nums; }
-.row .l2 .st { display: inline-flex; align-items: center; gap: 4px; flex: none; }
+.row .l2 .meta { display: inline-flex; align-items: center; gap: 6px; flex: none; margin-left: auto; padding-right: 4px; }
+.row .l2 .st { display: inline-flex; align-items: center; gap: 4px; }
 .row .l2 .dot { width: 7px; height: 7px; }
 .row .l2 .du { flex: none; }
-.row .l2 .chips { flex: 0 1 auto; flex-wrap: nowrap; overflow: hidden; margin-left: 2px; }
+.row .l2 .chips { flex: 0 1 auto; flex-wrap: nowrap; overflow: hidden; }
 .row .l2 .chip { flex: 0 1 auto; min-width: 24px; font-size: 10px; line-height: 14px; }
 .row .l2 .chip.more { flex: none; }
 .row .twist { width: 16px; height: 16px; flex: none; display: grid; place-items: center; color: var(--text-3); border: 0; background: none; padding: 0; cursor: pointer; }
@@ -163,7 +164,8 @@ button { font: inherit; color: inherit; }
 
 .chart { position: relative; min-width: 0; }
 .chart svg { display: block; overflow: hidden; }
-.chart .bar-label { font-size: 12px; fill: var(--bar-text); font-weight: 500; cursor: pointer; }
+/* the row's hit target already spans the label — letting it through keeps the marks under it hoverable */
+.chart .bar-label { font-size: 12px; fill: var(--bar-text); font-weight: 500; pointer-events: none; }
 .chart .hit { fill: transparent; cursor: pointer; }
 .chart .hit:hover + .bar { filter: brightness(1.15); }
 .chart .bar-label.outside { fill: var(--text); }
@@ -189,7 +191,7 @@ button { font: inherit; color: inherit; }
 .flow-seq.parallel { stroke-dasharray: 1 4; stroke-linecap: round; stroke-width: 2; opacity: 0.8; }
 .flow-arrowhead { fill: var(--text-3); }
 .flow-par { fill: var(--text-3); font-size: 10px; font-style: italic; }
-.flow-shot-t { fill: var(--text-3); font-size: 10.5px; pointer-events: none; }
+.flow-shot-t { fill: var(--text-3); font-size: 10.5px; pointer-events: none; stroke: var(--panel); stroke-width: 4px; paint-order: stroke; }
 .flow-card text.sub { fill: var(--text-3); font-size: 11px; }
 .flow-card .tchip text { fill: var(--text); font-size: 10.5px; }
 .flow-card .tchip.more text { fill: var(--text-3); }
@@ -223,12 +225,12 @@ button { font: inherit; color: inherit; }
 .acc-b > .params { margin-bottom: 8px; }
 .acc-b .section-title:first-child { margin-top: 0; }
 .acc-file { display: flex; align-items: center; gap: 6px; margin-bottom: 6px; color: var(--text-2); }
-.shots { display: grid; gap: 6px; }
-.shot { display: grid; grid-template-columns: 64px minmax(0, 1fr) auto; align-items: center; gap: 10px; padding: 4px; border: 1px solid transparent; border-radius: 8px; cursor: pointer; }
-.shot:hover { border-color: var(--accent); background: var(--accent-soft); }
-.shot .thumb { width: 64px; }
-.shot .nm { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
-.shot .t { color: var(--text-3); font-size: 11px; font-variant-numeric: tabular-nums; }
+.dshots { display: grid; gap: 6px; }
+.dshot { display: grid; grid-template-columns: 64px minmax(0, 1fr) auto; align-items: center; gap: 10px; padding: 4px; border: 1px solid transparent; border-radius: 8px; cursor: pointer; }
+.dshot:hover { border-color: var(--accent); background: var(--accent-soft); }
+.dshot .thumb { width: 64px; }
+.dshot .nm { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.dshot .t { color: var(--text-3); font-size: 11px; font-variant-numeric: tabular-nums; }
 .kv { display: grid; grid-template-columns: 92px minmax(0, 1fr); gap: 6px 10px; margin: 2px 0 12px; }
 .kv .k { color: var(--text-2); }
 .kv .v { min-width: 0; overflow-wrap: anywhere; font-variant-numeric: tabular-nums; }
@@ -471,6 +473,13 @@ a.icon-btn { text-decoration: none; }
 #app.hl-on .flow-card.err-path rect.box { stroke: var(--fail); stroke-width: 1.2; stroke-dasharray: 4 3; }
 #app.hl-on .tree .row.err { background: rgba(239, 68, 68, 0.1); }
 .chart g.r, .flow-card, .tree .row { transition: opacity 0.15s; }
+/* cross-node links: hollow points on the caller's row, chips in the flow */
+.chart circle.mark.link { stroke-width: 2; }
+.xwire { stroke-width: 1.2; stroke-dasharray: 3 3; opacity: 0.55; pointer-events: none; }
+.xwire.hot { stroke-width: 2; opacity: 1; }
+.fwire { fill: none; stroke-width: 1.2; stroke-dasharray: 3 3; opacity: 0.5; pointer-events: none; }
+.fwire.hot { stroke-width: 2; opacity: 1; }
+.flow-shots .shot rect[stroke] { stroke-width: 1.5; }
 
 @media (max-width: 1100px) {
   .bottom { grid-template-columns: minmax(0, 1fr); }

package/dist/output/writers/report/report.js

@@ -63,6 +63,7 @@
     cancel: { color: "--cancel", icon: "stop", label: "Cancelled" },
     lifecycle: { color: "--c1", icon: "play", label: "Lifecycle" },
     run: { color: "--text-3", icon: "root", label: "Run" },
+    link: { color: "--text-3", icon: "flow", label: "Link" },
   };
 
   // ── formatting ───────────────────────────────────────────
@@ -156,7 +157,7 @@
       items.push(item);
       if (item.node) {
         item.node.entries.push(item);
-        if (kind !== "info" && kind !== "lifecycle") item.node.marks.push(item);
+        if (kind !== "info" && kind !== "lifecycle" && kind !== "link") item.node.marks.push(item);
       } else runEntries.push(item);
     }
 
@@ -186,6 +187,21 @@
       }
     }
 
+    // cross-node interactions, recorded on their target: who waited on, cancelled, or called into whom
+    const links = [];
+    for (const it of items) {
+      const l = it.kind === "link" && it.node && it.e.link;
+      const from = l && byId.get(l.from);
+      if (!from) continue;
+      links.push({ item: it, op: l.op, from, to: it.node, t: it.t, t0: it.t - (l.ms || 0), key: l.key || "", ms: l.ms, outcome: l.outcome || "", site: l.site || "" });
+    }
+    // …drawn as a point on the row of the action that made it: what it did, when it did it
+    for (const l of links) {
+      l.label = linkLabel(l);
+      l.from.marks.push({ idx: l.item.idx, e: l.item.e, kind: "link", t: l.t, label: l.label, node: l.from, link: l });
+    }
+    for (const l of links) l.from.marks.sort((a, b) => a.t - b.t);
+
     const asserts = items.filter((i) => i.kind === "pass" || i.kind === "fail");
     const errors = collectErrors(items, nodes, run, tEnd - t0);
     const errorsBy = new Map();
@@ -209,6 +225,7 @@
       byId,
       root: nodes[0],
       items,
+      links,
       runEntries,
       gallery,
       asserts,
@@ -266,10 +283,17 @@
     out.forEach((e, i) => (e.idx = i));
     return out;
   }
+  /** A link's short label, as its point or chip shows it. */
+  function linkLabel(l) {
+    if (l.op === "once") return `waited ${l.key}`;
+    if (l.op === "cancel") return `cancel ${displayName(l.to)}`;
+    return `${displayName(l.to)}.${l.key}()`;
+  }
   function firstLine(s) {
     return String(s).split("\n")[0];
   }
   function kindOf(e) {
+    if (e.level === "link") return "link";
     if (e.level === "assert") return e.message.startsWith("⊭") ? "fail" : "pass";
     if (e.level === "snapshot") return "snapshot";
     if (e.level === "artifact") return "artifact";
@@ -476,7 +500,7 @@
             <span class="l1"><span class="label">${labelHtml(n)}</span>${
               model.errorsBy.get(n) ? `<span class="errbadge" title="${model.errorsBy.get(n)} error${model.errorsBy.get(n) > 1 ? "s" : ""}">${model.errorsBy.get(n)}</span>` : ""
             }</span>
-            <span class="l2"><span class="st"><span class="dot ${n.status}"></span>${esc(n.status)}</span><span class="sep">·</span><span class="du">${fmtDur(n.duration)}</span>${tags}</span>
+            <span class="l2">${tags}<span class="meta"><span class="st"><span class="dot ${n.status}"></span>${esc(n.status)}</span><span class="sep">·</span><span class="du">${fmtDur(n.duration)}</span></span></span>
           </span>
         </div>
       </div>`;
@@ -503,6 +527,7 @@
         .on("mouseleave", () => moveCursor(null));
       chartSvg.append("g").attr("class", "grid");
       chartSvg.append("g").attr("class", "links");
+      chartSvg.append("g").attr("class", "xwires");
       chartSvg.append("g").attr("class", "rows");
       chartSvg.append("line").attr("class", "pin").attr("stroke", css("--accent")).attr("stroke-width", 1.5).attr("y1", 0).attr("y2", H);
       chartSvg.append("line").attr("class", "cursor").attr("y1", 0).attr("y2", H).attr("visibility", "hidden");
@@ -619,11 +644,73 @@
       g.select("g.marks").each(function (n) {
         drawMarks(d3.select(this), n, x);
       });
+      rowIndex = index;
+      drawWires(x);
 
       chartSvg.select("line.pin").attr("x1", state.pin != null ? x(state.pin) : -10).attr("x2", state.pin != null ? x(state.pin) : -10);
       if (app.classList.contains("hl-on") || state.errHl) applyHl();
     }
 
+    function linkColor(l) {
+      return l.op === "cancel" ? css("--cancel") : colorOf(l.to);
+    }
+    /** A link in words: who did what to whom, how it ended, and the line that did it. */
+    function linkTip(l, count) {
+      const from = esc(displayName(l.from));
+      const to = esc(displayName(l.to));
+      const title = l.op === "once" ? `once · ${esc(l.key)}` : l.op === "cancel" ? "cancel" : `ref · ${esc(l.key)}()`;
+      const what =
+        l.op === "once"
+          ? `<b>${from}</b> waited for <b>${esc(l.key)}</b> on <b>${to}</b>`
+          : l.op === "cancel"
+            ? `<b>${from}</b> cancelled <b>${to}</b>`
+            : `<b>${from}</b> called <b>${esc(l.key)}()</b> on <b>${to}</b>'s ref`;
+      const meta = [
+        count > 1 ? `×${count}` : "",
+        l.outcome ? esc(l.outcome) : "",
+        l.ms != null ? (l.op === "once" ? `after ${fmtDur(l.ms)}` : fmtDur(l.ms)) : "",
+        fmtRel(l.t),
+      ].filter(Boolean);
+      const line = (/:(\d+)$/.exec(l.site) || [])[1];
+      return `<div class="tt">${title}</div><div class="summary">${what}</div>
+        <div class="tmeta">${meta.join('<span class="sep">·</span>')}</div>
+        ${l.site ? `<div class="mono small" style="margin-top:6px">${esc(relOf(l.site))}${line ? ":" + line : ""}</div>` : ""}`;
+    }
+
+    let rowIndex = new Map();
+    /** The visible row standing in for `n`: its own, or its nearest expanded ancestor's. */
+    function rowOf(n) {
+      for (let p = n; p; p = p.parent) if (rowIndex.has(p.id)) return rowIndex.get(p.id);
+      return -1;
+    }
+    /**
+     * A link's wire: straight down (or up) the timeline at the moment it happened, from the
+     * caller's point to the target's row — both ends share the instant, so the line reads as
+     * "this, then, to that". Waits and cancels always have one; a ref call's shows on hover only,
+     * since a chatty handle would otherwise hatch the chart.
+     */
+    function wireOf(l, x) {
+      const a = rowOf(l.from);
+      const b = rowOf(l.to);
+      if (a < 0 || b < 0 || a === b) return null;
+      const cy = BAR_Y + BAR_H / 2;
+      return { l, x: x(l.t), y1: a * ROW_H + cy, y2: b * ROW_H + cy };
+    }
+    function drawWires(x, extra) {
+      const shown = model.links.filter((l) => l.op !== "ref" || l === extra);
+      chartSvg
+        .select(".xwires")
+        .selectAll("line")
+        .data(shown.map((l) => wireOf(l, x)).filter(Boolean))
+        .join("line")
+        .attr("class", (w) => `xwire ${w.l.op}${w.l === extra ? " hot" : ""}`)
+        .attr("x1", (w) => w.x)
+        .attr("x2", (w) => w.x)
+        .attr("y1", (w) => w.y1)
+        .attr("y2", (w) => w.y2)
+        .attr("stroke", (w) => linkColor(w.l));
+    }
+
     function drawMarks(g, n, x) {
       const cy = BAR_Y + BAR_H / 2;
       // cluster marks closer than 4px so a chatty node draws a readable line of dots
@@ -641,18 +728,27 @@
       g.selectAll("circle.mark")
         .data(marks)
         .join("circle")
-        .attr("class", "mark")
+        .attr("class", (d) => `mark ${worst(d)}`)
         .attr("cx", (d) => d.px)
         .attr("cy", cy)
         .attr("r", (d) => (d.more.length ? 6 : 5))
         .attr("fill", (d) => css(MARK[worst(d)].color))
+        // a link is a ring in its target's colour — set as styles, over the `.mark` stroke rule
+        .style("fill", (d) => (worst(d) === "link" ? "var(--panel)" : null))
+        .style("stroke", (d) => (worst(d) === "link" ? linkColor(d.m.link) : null))
         .on("click", (ev, d) => {
           ev.stopPropagation();
           openItem(d.m);
         })
-        .on("mouseenter", (ev, d) => showTip(ev, markTip(d)))
+        .on("mouseenter", (ev, d) => {
+          showTip(ev, markTip(d), d.m.kind === "link");
+          if (d.m.kind === "link") drawWires(xz(), d.m.link);
+        })
         .on("mousemove", (ev) => moveTip(ev))
-        .on("mouseleave", hideTip);
+        .on("mouseleave", (ev, d) => {
+          hideTip();
+          if (d.m.kind === "link") drawWires(xz());
+        });
       // labels under the bar, skipped where they would collide
       const labels = [];
       let edge = -Infinity;
@@ -739,6 +835,18 @@
         .attr("stroke", color ? alpha(color, 0.45) : css("--line"));
       return { g, w };
     }
+    /** A link chip's text: what kind of interaction, at a glance. */
+    function linkGlyph(x2) {
+      if (x2.l.op === "once") return "wait";
+      if (x2.l.op === "cancel") return "stop";
+      return x2.n > 1 ? `()×${x2.n}` : "()";
+    }
+    /** "3 snapshots", "2 links", or "4 items" for a mix. */
+    function chipCount(shots) {
+      const links = shots.filter((x2) => x2.type === "link").length;
+      if (!links) return `${shots.length} snapshots`;
+      return links === shots.length ? `${links} links` : `${shots.length} items`;
+    }
     function renderFlow() {
       d3.select(el.flow).selectAll("svg").remove();
       const svg = d3.select(el.flow).append("svg");
@@ -766,6 +874,16 @@
         if (!shotsBy.has(g.node)) shotsBy.set(g.node, []);
         shotsBy.get(g.node).push(g);
       }
+      // a node's links sit with its snapshots, in time order; a run of identical ref calls is one chip
+      for (const l of model.links) {
+        const list = shotsBy.get(l.from) || shotsBy.set(l.from, []).get(l.from);
+        const prev = list[list.length - 1];
+        if (l.op === "ref" && prev && prev.type === "link" && prev.l.op === "ref" && prev.l.to === l.to && prev.l.key === l.key) {
+          prev.n++;
+          continue;
+        }
+        list.push({ type: "link", l, n: 1, t: l.t, name: l.label });
+      }
       const byTime = (a, b) => (a.t ?? Infinity) - (b.t ?? Infinity);
       const pos = new Map();
       const lanes = [];
@@ -941,6 +1059,31 @@
 
       // snapshot chips — on lane arrows, and in strips under leaf cards
       const chipLayer = flowG.append("g").attr("class", "flow-shots");
+      // A link chip's wire, drawn under everything else: out of the chip to a gutter right of the
+      // column, along it, and into the target card's right edge — so it never runs behind the cards
+      // between. Waits and cancels always have one; a ref call's shows while hovered.
+      const wireLayer = flowG.insert("g", ":first-child").attr("class", "flow-wires");
+      const linkChips = [];
+      const drawFlowWires = (hot) => {
+        const wires = [];
+        for (const c of linkChips) {
+          const p = pos.get(c.x2.l.to.id);
+          if (!p || (c.x2.l.op === "ref" && c.x2 !== hot)) continue;
+          wires.push({ c, p });
+        }
+        wireLayer
+          .selectAll("path")
+          .data(wires)
+          .join("path")
+          .attr("class", (w) => `fwire ${w.c.x2.l.op}${w.c.x2 === hot ? " hot" : ""}`)
+          .attr("d", (w, i) => {
+            const tx = w.p.x + CW;
+            const ty = w.p.y + CH / 2;
+            const gx = Math.max(tx, w.c.cx + TW / 2) + 12 + (i % 6) * 6; // staggered within the column gap
+            return `M${w.c.cx + TW / 2},${w.c.cy} H${gx} V${ty} H${tx}`;
+          })
+          .attr("stroke", (w) => linkColor(w.c.x2.l));
+      };
       const drawChips = (x, y, shots, max, owner) => {
         const shown = shots.length > max ? shots.slice(0, max - 1) : shots;
         const g = chipLayer.append("g").attr("transform", `translate(${x},${y})`);
@@ -952,12 +1095,28 @@
           .attr("transform", (_x, i) => `translate(${i * (TW + 4)},0)`)
           .on("click", (ev, x2) => {
             ev.stopPropagation();
-            openGallery(x2);
+            if (x2.type !== "link") return openGallery(x2);
+            setPin(x2.t);
+            select(x2.l.from.id, "links");
+          })
+          .on("mouseenter", (ev, x2) => {
+            showTip(ev, x2.type === "link" ? linkTip(x2.l, x2.n) : galleryTip(x2), x2.type === "link");
+            if (x2.type === "link") drawFlowWires(x2);
           })
-          .on("mouseenter", (ev, x2) => showTip(ev, galleryTip(x2)))
           .on("mousemove", (ev) => moveTip(ev))
-          .on("mouseleave", hideTip);
-        cell.append("rect").attr("width", TW).attr("height", TH).attr("rx", 5);
+          .on("mouseleave", (ev, x2) => {
+            hideTip();
+            if (x2.type === "link") drawFlowWires(null);
+          });
+        shown.forEach((x2, i) => {
+          if (x2.type === "link") linkChips.push({ x2, cx: x + i * (TW + 4) + TW / 2, cy: y + TH / 2 });
+        });
+        cell
+          .append("rect")
+          .attr("width", TW)
+          .attr("height", TH)
+          .attr("rx", 5)
+          .attr("stroke", (x2) => (x2.type === "link" ? linkColor(x2.l) : null));
         cell
           .filter((x2) => x2.image)
           .append("image")
@@ -973,7 +1132,7 @@
           .attr("x", TW / 2)
           .attr("y", TH / 2 + 3.5)
           .attr("text-anchor", "middle")
-          .text((x2) => (x2.type === "snapshot" ? "{ }" : "file"));
+          .text((x2) => (x2.type === "link" ? linkGlyph(x2) : x2.type === "snapshot" ? "{ }" : "file"));
         let end = shown.length * (TW + 4);
         if (shots.length > shown.length) {
           const more = g
@@ -999,7 +1158,7 @@
             .attr("class", "flow-shot-t")
             .attr("x", end + 2)
             .attr("y", TH / 2 + 4)
-            .text(`${fmtRel(t)} · ${shots.length > 1 ? `${shots.length} snapshots` : esc(truncate(shots[0].name, 22))}`);
+            .text(`${fmtRel(t)} · ${shots.length > 1 ? chipCount(shots) : truncate(shots[0].name, 22)}`);
         }
       };
       for (const r of chipRows) {
@@ -1007,6 +1166,7 @@
         drawChips(r.x, r.y, r.shots, 6, owner);
       }
       for (const s of strips) drawChips(s.x, s.y, s.shots, Math.floor((CW - 12) / (TW + 4)), s.n);
+      drawFlowWires(null);
 
       flowPos = new Map([...pos].map(([id, p]) => [id, { x: p.x + CW / 2, y: p.y + CH / 2 }]));
       svg.call(flowZoom).on("dblclick.zoom", null);
@@ -1235,8 +1395,9 @@
     function detailSections(n) {
       const errs = model.errors.filter((e) => e.node === n);
       const params = schemaFields(n.v.inputSchema);
-      const evs = n.entries.filter((i) => i.kind !== "info");
+      const evs = n.entries.filter((i) => i.kind !== "info" && i.kind !== "link");
       const logs = n.entries.filter((i) => i.kind === "info" || i.kind === "error");
+      const lks = model.links.filter((l) => l.from === n || l.to === n);
       const shots = model.gallery.filter((x) => x.node === n);
       const asserts = n.entries.filter((i) => i.kind === "pass" || i.kind === "fail");
       const logLink = `<div class="acc-file">${svgIcon("file", ' width="14" height="14"')}<a href="${esc(fileUrl(n.v.logFile))}" title="${esc(n.v.logFile)}">${esc(basename(n.v.logFile))}</a></div>`;
@@ -1268,7 +1429,7 @@
           title: "Snapshots & files",
           count: shots.length,
           empty: !shots.length,
-          body: () => `<div class="shots">${shots.map((g) => shotHtml(g, n)).join("")}</div>`,
+          body: () => `<div class="dshots">${shots.map((g) => shotHtml(g, n)).join("")}</div>`,
         },
         {
           key: "events",
@@ -1277,6 +1438,13 @@
           empty: !evs.length,
           body: () => `<ul class="ev-list">${evs.map((i) => evLi(i, n)).join("")}</ul>`,
         },
+        {
+          key: "links",
+          title: "Links",
+          count: lks.length,
+          empty: !lks.length,
+          body: () => linksHtml(n, lks),
+        },
         {
           key: "logs",
           title: "Logs",
@@ -1295,10 +1463,54 @@
       ];
     }
 
+    /**
+     * The details panel's links: what `n` did to other actions and what they did to it. Ref
+     * calls fold into one row per (other action, method), with a count and their total time.
+     */
+    function linksHtml(n, lks) {
+      const rows = [];
+      const refs = new Map();
+      for (const l of lks) {
+        if (l.op === "ref") {
+          const k = `${l.from.id}\0${l.to.id}\0${l.key}`;
+          if (!refs.has(k)) {
+            refs.set(k, { l, n: 0, ms: 0 });
+            rows.push(refs.get(k));
+          }
+          const r = refs.get(k);
+          r.n++;
+          r.ms += l.ms || 0;
+        } else rows.push({ l, n: 1, ms: l.ms || 0 });
+      }
+      const name = (x) => `<b>${esc(displayName(x))}</b>`;
+      return `<ul class="ev-list">${rows
+        .map(({ l, n: count, ms }) => {
+          const out = l.from === n;
+          const text =
+            l.op === "once"
+              ? out
+                ? `waited for ${esc(l.key)} on ${name(l.to)} · ${esc(l.outcome)} after ${fmtDur(ms)}`
+                : `${name(l.from)} waited for ${esc(l.key)} · ${esc(l.outcome)} after ${fmtDur(ms)}`
+              : l.op === "cancel"
+                ? out
+                  ? `cancelled ${name(l.to)}`
+                  : `cancelled by ${name(l.from)}`
+                : out
+                  ? `${name(l.to)}.${esc(l.key)}() ×${count} · ${fmtDur(ms)}`
+                  : `${name(l.from)} called ${esc(l.key)}() ×${count} · ${fmtDur(ms)}`;
+          const color = l.op === "cancel" ? css("--cancel") : colorOf(out ? l.to : l.from);
+          return `<li data-link="${model.links.indexOf(l)}" style="cursor:pointer">
+            <span class="t">${fmtRel(l.t - n.start)}</span>
+            <span class="ev-ico" style="background:${alpha(color, 0.2)};color:${color}">${svgIcon(l.op === "cancel" ? "stop" : l.op === "once" ? "pulse" : "code")}</span>
+            <span class="m">${out ? "→ " : "← "}${text}</span></li>`;
+        })
+        .join("")}</ul>`;
+    }
+
     /** A snapshot or file in the details panel: a small thumb with its name and when it landed. */
     function shotHtml(g, n) {
       const i = model.gallery.indexOf(g);
-      return `<div class="shot" data-gallery="${i}" title="${esc(g.name)}">
+      return `<div class="dshot" data-gallery="${i}" title="${esc(g.name)}">
           ${thumbHtml(g)}
           <span class="nm">${esc(g.name)}</span>
           ${g.t != null ? `<span class="t">${fmtRel(g.t - n.start)}</span>` : ""}
@@ -1329,6 +1541,9 @@
       root.querySelectorAll("[data-gallery]").forEach((t) =>
         t.addEventListener("click", () => openGallery(model.gallery[+t.dataset.gallery]))
       );
+      root.querySelectorAll("[data-link]").forEach((t) =>
+        t.addEventListener("click", () => setPin(model.links[+t.dataset.link].t))
+      );
       root.querySelectorAll("[data-item]").forEach((t) =>
         t.addEventListener("click", () => openItem(model.items[+t.dataset.item]))
       );
@@ -1337,7 +1552,8 @@
     function openItem(item) {
       if (!item) return;
       setPin(item.t);
-      if (item.node && item.node.id !== state.selected) select(item.node.id, "events");
+      if (item.kind === "link") select(item.node.id, "links");
+      else if (item.node && item.node.id !== state.selected) select(item.node.id, "events");
       if (item.gallery) openGallery(item.gallery);
     }
     function setPin(t) {
@@ -1548,7 +1764,7 @@
           ? (i) => i.kind === "info" || i.kind === "error"
           : tab === "asserts"
             ? (i) => i.kind === "pass" || i.kind === "fail"
-            : (i) => i.kind !== "info";
+            : (i) => i.kind !== "info" && !(i.kind === "link" && i.e.link && i.e.link.op === "ref");
       const rows = [];
       for (let idx = 0; idx < model.items.length; idx++) {
         const i = model.items[idx];
@@ -1697,6 +1913,9 @@
     }
     function markTip(d) {
       const m = d.m;
+      if (m.kind === "link") {
+        return linkTip(m.link) + (d.more.length ? `<div class="ts" style="margin-top:4px">+${d.more.length} more within a few ms</div>` : "");
+      }
       const mk = MARK[m.kind] || MARK.event;
       const img = m.gallery && m.gallery.image ? `<img src="${model.asset(m.gallery.f.asset)}" alt="">` : "";
       const more = d.more.length ? `<div class="ts">+${d.more.length} more within a few ms</div>` : "";
@@ -2089,6 +2308,7 @@
             ${legendItem("--fail", "Failure / error", "dot")}
             ${legendItem("--cancel", "Cancelled", "dash")}
             ${legendItem("--accent", "Pinned time", "line")}
+            ${legendItem("--text-2", "Wait · cancel · ref call", "ring")}
           </div>
           <div class="muted" style="margin-top:12px;font-size:11px">Ctrl + wheel to zoom · drag to pan · double-click a bar to focus · ↑/↓ to step</div>
           </div>
@@ -2105,7 +2325,9 @@
     const sw =
       shape === "bar"
         ? `<span style="width:16px;height:9px;border-radius:3px;background:${c}"></span>`
-        : shape === "dash"
+        : shape === "ring"
+          ? `<span class="dot" style="width:11px;height:11px;background:var(--panel);box-shadow:inset 0 0 0 2px ${c}"></span>`
+          : shape === "dash"
           ? `<span style="width:16px;height:0;border-top:2px dashed ${c}"></span>`
           : shape === "line"
             ? `<span style="width:2px;height:14px;background:${c};margin:0 7px"></span>`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omkit",
-  "version": "0.8.16",
+  "version": "0.8.18",
   "description": "A tiny runtime for developer workflows: typed actions that pass runtime capabilities and emit typed events, under one run and one shared log. The operational/runtime layer to tskb's knowledge layer.",
   "type": "module",
   "main": "./dist/index.js",