omkit 0.8.12 → 0.8.14

package/README.md

@@ -185,7 +185,7 @@ flakyBackgroundJob().result.catch((e) => console.warn("job failed, carrying on",
 
 Every action's output, events, asserts, snapshots, and lifecycle land on **one timeline** — streamed live to the terminal (curated milestones) and written to a per-run folder:
 
-- `result.json` — the run's tree, per-node status, verdict, and curated artifacts. Each node also carries what its definition declared about itself: the `.describe()` summary, the `.mcp()` exposure, and the `.args()` schema as JSON Schema.
+- `result.json` — the run's tree, per-node status, verdict, and curated artifacts. Each node also carries what its definition declared about itself: the `.describe()` summary, the `.mcp()` exposure, and the `.args()` schema as JSON Schema. Each node also records what it returned (`value`, or a `valueNote` when it was too large or not JSON) and `calledAt`, the line that launched it, so a built-in step (a `prompt`, a `command`) points back at your code rather than omkit's, and a `step(...)` is defined at the line where you wrote it.
 - `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.

package/dist/core/ActionRun.d.ts

@@ -47,6 +47,8 @@ export declare class ActionRun<Result = unknown, Events extends object = object,
     readonly tags: string[];
     /** What the definition said about itself (`.describe()`, `.mcp()`, `.args()`); for the record. */
     meta: ActionMeta | undefined;
+    /** `file:line` of the call that launched this node (absent for the root). */
+    calledAt: string | undefined;
     /** The captured args this node ran with (for the log header); set at run start. */
     args: readonly unknown[];
     readonly children: ActionRun[];

package/dist/core/ActionRun.js

@@ -20,6 +20,8 @@ export class ActionRun {
     tags = [];
     /** What the definition said about itself (`.describe()`, `.mcp()`, `.args()`); for the record. */
     meta;
+    /** `file:line` of the call that launched this node (absent for the root). */
+    calledAt;
     /** The captured args this node ran with (for the log header); set at run start. */
     args = [];
     children = [];

package/dist/core/ExecutionTree.js

@@ -139,6 +139,7 @@ export class ExecutionTree {
             bubble: (message) => this.append(parent, "child", id, message),
         });
         node.meta = spec.meta;
+        node.calledAt = spec.calledAt;
         parent.children.push(node);
         this.registry.push(node);
         // Launch reference — the parent's pointer to the child's own (absolute) log, plus where
@@ -378,6 +379,7 @@ export class ExecutionTree {
             uuid: node.uuid,
             name: node.name,
             definedAt: node.definedAt,
+            ...(node.calledAt === undefined ? {} : { calledAt: node.calledAt }),
             path: node.path,
             parentId: node.parentId,
             tags: [...node.tags],
@@ -389,6 +391,7 @@ export class ExecutionTree {
             duration: node.duration,
             logFile: this.logFile(node.path),
             ...this.metaView(node),
+            ...valueView(node.value),
             children: node.children.map((child) => this.nodeView(child)),
         };
     }
@@ -504,6 +507,36 @@ const messageOf = (error) => error instanceof Error ? (error.stack ?? error.mess
  * body may hand back anything — a capability handle, a cyclic object — and the run must
  * still write its record; a value that does not survive JSON is dropped, not fatal.
  */
+/** A node's return value is recorded up to this many characters of JSON. */
+const VALUE_CAP = 512 * 1024;
+/**
+ * What a node returned, for the record: the value itself when JSON can carry it and it fits,
+ * otherwise a one-line note saying what it was — so "returned a Page" is still on the record.
+ */
+function valueView(value) {
+    if (value === undefined)
+        return {};
+    const kind = value === null
+        ? "null"
+        : typeof value === "object"
+            ? (value.constructor?.name ?? "object")
+            : typeof value;
+    let text;
+    try {
+        text = JSON.stringify(value);
+    }
+    catch {
+        text = undefined;
+    }
+    if (text === undefined)
+        return { valueNote: `${kind} (not JSON)` };
+    if (text.length > VALUE_CAP) {
+        return {
+            valueNote: `${kind}, ${Math.round(text.length / 1024)} KB of JSON — too large to record`,
+        };
+    }
+    return { value: JSON.parse(text) };
+}
 function serialisable(value) {
     if (value === undefined)
         return undefined;

package/dist/core/action.js

@@ -55,7 +55,9 @@ class Builder {
         };
         const exec = body;
         const create = (...args) => {
-            const spec = { name, args, tags: [], body: exec, definedAt, meta };
+            // where this launch was written — for a battery, the user's call rather than its definition
+            const calledAt = callerSite();
+            const spec = { name, args, tags: [], body: exec, definedAt, calledAt, meta };
             return ExecutionTree.require().launch(spec);
         };
         return Object.assign(create, {
@@ -121,7 +123,9 @@ class ArgsBuilder {
         };
         const exec = body;
         const create = (...args) => {
-            const spec = { name, args, tags: [], body: exec, definedAt, meta };
+            // where this launch was written — for a battery, the user's call rather than its definition
+            const calledAt = callerSite();
+            const spec = { name, args, tags: [], body: exec, definedAt, calledAt, meta };
             return ExecutionTree.require().launch(spec);
         };
         return Object.assign(create, {

package/dist/core/step.js

@@ -1,4 +1,5 @@
-import { action } from "./action.js";
+import { callerSite } from "../foundation/callsite.js";
+import { ExecutionTree } from "./ExecutionTree.js";
 /**
  * An inline anonymous action: creates a child node under the ambient current
  * action and runs `fn` as that node — own id/path/log, tags, error boundary — with
@@ -7,6 +8,17 @@ import { action } from "./action.js";
  * units use `action(...)`.
  */
 export function step(name, fn) {
+    // An inline action is defined where it is written — the `step(...)` call — so that is its
+    // site, not this file (which is what routing through `action(name).run(fn)` would record).
+    const site = callerSite();
+    const spec = {
+        name,
+        args: [],
+        tags: [],
+        body: fn,
+        definedAt: site,
+        calledAt: site,
+    };
     // `.result` already resolves the value and rejects on failure/cancel — exactly step's contract.
-    return action(name).run(fn)().result;
+    return ExecutionTree.require().launch(spec).result;
 }

package/dist/core/types.d.ts

@@ -241,6 +241,8 @@ export interface LaunchSpec {
     readonly definedAt: string | undefined;
     /** What the definition declared about itself — carried onto the node for the run record. */
     readonly meta?: ActionMeta;
+    /** `file:line` of the call that launched this instance; carried onto the node for the record. */
+    readonly calledAt?: string;
 }
 /**
  * A definition's self-description, as it travels onto each node it launches: what

package/dist/output/writers/ReportWriter.js

@@ -41,6 +41,7 @@ export async function writeReport(file, input) {
         projectRoot: root,
         sources: definitionSources(input.run.root, root),
         code: await definitionCode(input.run.root),
+        library: librarySites(input.run.root),
         generatedAt: Date.now(),
         run: input.run,
         entries: input.entries,
@@ -223,15 +224,81 @@ async function projectRoot(folder) {
 function definitionSources(root, projectDir) {
     const out = {};
     const visit = (n) => {
-        if (n.definedAt && !(n.definedAt in out)) {
-            const file = n.definedAt.replace(/:\d+(:\d+)?$/, "");
-            out[n.definedAt] = path.relative(projectDir, file).split(path.sep).join("/") || file;
+        for (const site of [n.definedAt, n.calledAt]) {
+            if (!site || site in out)
+                continue;
+            const file = site.replace(/:\d+(:\d+)?$/, "");
+            out[site] = path.relative(projectDir, file).split(path.sep).join("/") || file;
         }
         n.children.forEach(visit);
     };
     visit(root);
     return out;
 }
+/**
+ * The deepest statement containing `pos`. For an action's `.run(…)` line that is the whole
+ * `export const x = action(…)…` statement (nothing nests the chain); for a call site inside a
+ * body — `await step("x", async () => …)`, `await command(…)` — it is that one statement, the
+ * callback included, rather than the om that happens to contain it.
+ */
+function innermostStatement(ts, sf, pos) {
+    let found;
+    const visit = (node) => {
+        if (pos < node.getStart(sf) || pos >= node.getEnd())
+            return;
+        const parent = node.parent;
+        if (parent?.statements?.includes(node))
+            found = node;
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(sf, visit);
+    return found;
+}
+/**
+ * The 1-based line range to show for a site: its innermost statement, or — when the file will
+ * not parse or nothing encloses the line — a window around it.
+ */
+function excerptRange(ts, file, text, line, total) {
+    try {
+        const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
+        const lineStart = sf.getPositionOfLineAndCharacter(Math.min(line, sf.getLineStarts().length) - 1, 0);
+        // the line's first token, so indentation doesn't fall outside the statement it opens
+        const pos = lineStart + (/^\s*/.exec(text.slice(lineStart))?.[0].length ?? 0);
+        const stmt = innermostStatement(ts, sf, pos);
+        if (stmt) {
+            return {
+                from: sf.getLineAndCharacterOfPosition(stmt.getStart(sf, true)).line + 1,
+                to: sf.getLineAndCharacterOfPosition(stmt.getEnd()).line + 1,
+            };
+        }
+    }
+    catch {
+        /* fall back to the window around the line */
+    }
+    return { from: Math.max(1, line - 10), to: Math.min(total, line + 20) };
+}
+/** omkit's own package folder — `src/output/writers` (or `dist/…`) is three levels in. */
+const OMKIT_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+/**
+ * Sites inside omkit itself or an installed package — a battery's definition or a step's
+ * wrapper — where the viewer shows the user's call instead of library source.
+ */
+function librarySites(root) {
+    const out = new Set();
+    const inside = (file) => {
+        const rel = path.relative(OMKIT_DIR, file);
+        return (!rel.startsWith("..") && !path.isAbsolute(rel)) || /[\\/]node_modules[\\/]/.test(file);
+    };
+    const visit = (n) => {
+        for (const site of [n.definedAt, n.calledAt]) {
+            if (site && inside(site.replace(/:\d+(:\d+)?$/, "")))
+                out.add(site);
+        }
+        n.children.forEach(visit);
+    };
+    visit(root);
+    return [...out];
+}
 /** Longest excerpt shown per definition; a body past this is cut, and says so. */
 const CODE_LINES = 300;
 /**
@@ -245,6 +312,8 @@ async function definitionCode(root) {
     const visit = (n) => {
         if (n.definedAt)
             sites.add(n.definedAt);
+        if (n.calledAt)
+            sites.add(n.calledAt);
         n.children.forEach(visit);
     };
     visit(root);
@@ -267,21 +336,7 @@ async function definitionCode(root) {
             continue;
         const lang = /\.[cm]?tsx?$/i.test(file) ? "ts" : "js";
         const lines = text.split(/\r?\n/);
-        let from = Math.max(1, line - 10);
-        let to = Math.min(lines.length, line + 20);
-        try {
-            const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
-            const pos = sf.getPositionOfLineAndCharacter(Math.min(line, sf.getLineStarts().length) - 1, 0);
-            const stmt = sf.statements.find((s) => s.getStart(sf) <= pos && pos < s.getEnd()) ??
-                sf.statements.find((s) => s.getFullStart() <= pos && pos < s.getEnd());
-            if (stmt) {
-                from = sf.getLineAndCharacterOfPosition(stmt.getStart(sf, true)).line + 1;
-                to = sf.getLineAndCharacterOfPosition(stmt.getEnd()).line + 1;
-            }
-        }
-        catch {
-            /* fall back to the window around the line */
-        }
+        const { from, to } = excerptRange(ts, file, text, line, lines.length);
         const truncated = to - from + 1 > CODE_LINES;
         out[site] = {
             start: from,

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

@@ -337,6 +337,36 @@ a.icon-btn { text-decoration: none; }
 .tk-k { color: var(--tk-k); }
 .tk-f { color: var(--tk-f); }
 .tk-t { color: var(--tk-t); }
+.tk-p { color: var(--tk-f); }
+
+/* ── popover tabs, prompt panel, flow snapshot strip ───── */
+.code-pop .cp-tabs { display: flex; gap: 2px; padding: 0 8px; border-bottom: 1px solid var(--line); background: var(--panel-2); }
+.code-pop .cp-tabs .tab { padding: 6px 9px; font-size: 12px; }
+.pp { padding: 12px 14px 14px; display: grid; gap: 10px; }
+.pp-q { font-size: 14px; font-weight: 600; white-space: pre-wrap; }
+.pp-grid { display: grid; grid-template-columns: 76px minmax(0, 1fr); gap: 4px 10px; font-size: 12px; }
+.pp-k { color: var(--text-3); font-size: 12px; }
+.pp-choices { margin: 0; padding-left: 18px; }
+.pp-choices li.picked { color: var(--accent); font-weight: 600; }
+.pp-answer { display: grid; gap: 6px; justify-items: start; }
+.pp-answer pre { width: 100%; }
+.tip .tprompt { font-weight: 600; white-space: pre-wrap; margin-bottom: 4px; }
+.flow-shots .shot { cursor: pointer; }
+.flow-shots .shot rect { fill: var(--panel-2); stroke: var(--line); }
+.flow-shots .shot:hover rect { stroke: var(--accent); }
+.flow-shots .shot text { fill: var(--text-3); font: 600 9px var(--mono); pointer-events: none; }
+
+/* ── returned values ───────────────────────────────────── */
+.code-btn path { fill: none; stroke: var(--text-2); stroke-width: 2.6; stroke-linecap: round; stroke-linejoin: round; pointer-events: none; }
+.code-btn:hover path { stroke: var(--accent); }
+.cp-tools { display: flex; align-items: center; justify-content: space-between; gap: 10px; padding: 6px 10px 6px 14px; border-bottom: 1px solid var(--line-soft); font-size: 12px; }
+.btn.small { padding: 3px 9px; font-size: 12px; }
+.btn.small svg { width: 13px; height: 13px; }
+.code-box { border: 1px solid var(--line-soft); border-radius: 8px; background: var(--panel-2); overflow: auto; max-height: 60vh; }
+.code-box .cp-code, .code-pop .cp-code { font: 11.5px/1.65 var(--mono); padding: 8px 0; min-width: max-content; }
+.code-box .cl { display: grid; grid-template-columns: 40px auto; white-space: pre; }
+.code-box .ln { color: var(--text-3); text-align: right; padding-right: 12px; user-select: none; }
+.code-box .lc { padding-right: 14px; }
 
 @media (max-width: 1100px) {
   .bottom { grid-template-columns: minmax(0, 1fr); }

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

@@ -43,6 +43,7 @@
     info: "M12 3a9 9 0 1 0 0 18 9 9 0 0 0 0-18zM12 11v5M12 8h.01",
     locate: "M12 5a7 7 0 1 0 0 14 7 7 0 0 0 0-14zM12 2v3M12 19v3M2 12h3M19 12h3M12 10.5a1.5 1.5 0 1 0 0 3 1.5 1.5 0 0 0 0-3z",
     code: "M8 7l-5 5 5 5M16 7l5 5-5 5",
+    ret: "M9 10l-4 4 4 4M5 14h11a4 4 0 0 0 4-4V5",
     external: "M14 4h6v6M20 4l-9 9M18 14v6H4V6h6",
   };
   const svgIcon = (name, extra) =>
@@ -505,9 +506,12 @@
           r.append("rect").attr("class", "bar").attr("rx", 5).attr("y", BAR_Y).attr("height", BAR_H);
           r.append("text").attr("class", "bar-label").attr("y", BAR_Y + BAR_H / 2 + 4);
           r.append("g").attr("class", "marks");
-          const cb = r.append("g").attr("class", "code-btn");
+          const cb = r.append("g").attr("class", "code-btn src");
           cb.append("circle").attr("r", 9);
           cb.append("text").attr("text-anchor", "middle").attr("y", 3.5).text("<>");
+          const rb = r.append("g").attr("class", "code-btn ret");
+          rb.append("circle").attr("r", 9);
+          rb.append("path").attr("d", ICON.ret).attr("transform", "translate(-6,-6) scale(0.5)");
           return r;
         })
         .attr("transform", (_n, i) => `translate(0,${i * ROW_H})`)
@@ -547,18 +551,33 @@
         // …and, for a block spanning the chart, inside it right after its label
         const cx =
           right + 8 <= W - 10 ? right + 8 : left - 8 >= 10 ? left - 8 : Math.min(W - 12, (flip ? x0 : lx + tw) + 14);
-        d3.select(this.parentNode)
-          .select("g.code-btn")
-          .style("display", hasCode(n) ? null : "none")
+        // buttons stack away from the block: rightward when they sit after it, leftward before it
+        const dir = right + 8 <= W - 10 || left - 8 < 10 ? 1 : -1;
+        const src = hasCode(n);
+        const row = d3.select(this.parentNode);
+        row
+          .select("g.code-btn.src")
+          .style("display", src ? null : "none")
           .attr("transform", `translate(${cx},${BAR_Y + BAR_H / 2})`);
+        row
+          .select("g.code-btn.ret")
+          .style("display", hasValue(n) ? null : "none")
+          .attr("transform", `translate(${src ? cx + dir * 21 : cx},${BAR_Y + BAR_H / 2})`);
       });
-      g.select("g.code-btn")
+      g.select("g.code-btn.src")
         .on("click", (ev, n) => {
           ev.stopPropagation();
           toggleCode(n, ev);
         })
         .on("mouseenter", (ev) => showTip(ev, "Show source"))
         .on("mouseleave", hideTip);
+      g.select("g.code-btn.ret")
+        .on("click", (ev, n) => {
+          ev.stopPropagation();
+          toggleCode(n, ev, "value", true);
+        })
+        .on("mouseenter", (ev, n) => showTip(ev, `Returned: <span class="mono">${esc(valuePreview(n, 80))}</span>`))
+        .on("mouseleave", hideTip);
       g.selectAll("rect.hit, text.bar-label").call(bindNode);
 
       g.select("g.marks").each(function (n) {
@@ -733,7 +752,10 @@
       const h = d3.hierarchy(model.root, (n) => n.children);
       const CW = 210;
       const CH = 46;
-      d3.tree().nodeSize([CH + 18, CW + 70])(h);
+      // cards that took snapshots carry a strip of them underneath, so leave room for it
+      const shotsOf = (n) => model.gallery.filter((g) => g.node === n);
+      const SH = model.gallery.some((g) => g.node) ? 36 : 0;
+      d3.tree().nodeSize([CH + 18 + SH, CW + 70])(h);
       let minX = Infinity;
       let maxX = -Infinity;
       let maxY = 0;
@@ -799,6 +821,76 @@
         });
       fcb.append("circle").attr("r", 9);
       fcb.append("text").attr("text-anchor", "middle").attr("y", 3.5).text("<>");
+      const frb = card
+        .filter((d) => hasValue(d.data))
+        .append("g")
+        .attr("class", "code-btn ret")
+        .attr("transform", (d) => `translate(${CW / 2 + (hasCode(d.data) ? 22 : 0)},0)`)
+        .on("click", (ev, d) => {
+          ev.stopPropagation();
+          toggleCode(d.data, ev, "value", true);
+        })
+        .on("mouseenter", (ev, d) => {
+          ev.stopPropagation();
+          showTip(ev, `Returned: <span class="mono">${esc(valuePreview(d.data, 80))}</span>`);
+        });
+      frb.append("circle").attr("r", 9);
+      frb.append("path").attr("d", ICON.ret).attr("transform", "translate(-6,-6) scale(0.5)");
+      const TW = 46;
+      const TH = 28;
+      const strip = card
+        .filter((d) => shotsOf(d.data).length > 0)
+        .append("g")
+        .attr("class", "flow-shots")
+        .attr("transform", `translate(6,${CH + 4})`);
+      strip.each(function (d) {
+        const shots = shotsOf(d.data);
+        const fit = Math.floor((CW - 12) / (TW + 4));
+        const shown = shots.length > fit ? shots.slice(0, fit - 1) : shots;
+        const g = d3.select(this);
+        const cell = g
+          .selectAll("g.shot")
+          .data(shown)
+          .join("g")
+          .attr("class", "shot")
+          .attr("transform", (_x, i) => `translate(${i * (TW + 4)},0)`)
+          .on("click", (ev, x) => {
+            ev.stopPropagation();
+            openGallery(x);
+          })
+          .on("mouseenter", (ev, x) => {
+            ev.stopPropagation();
+            showTip(ev, galleryTip(x));
+          })
+          .on("mousemove", (ev) => moveTip(ev))
+          .on("mouseleave", hideTip);
+        cell.append("rect").attr("width", TW).attr("height", TH).attr("rx", 4);
+        cell
+          .filter((x) => x.image)
+          .append("image")
+          .attr("href", (x) => model.asset(x.f.asset))
+          .attr("x", 1)
+          .attr("y", 1)
+          .attr("width", TW - 2)
+          .attr("height", TH - 2)
+          .attr("preserveAspectRatio", "xMidYMid slice");
+        cell
+          .filter((x) => !x.image)
+          .append("text")
+          .attr("x", TW / 2)
+          .attr("y", TH / 2 + 3.5)
+          .attr("text-anchor", "middle")
+          .text((x) => (x.type === "snapshot" ? "{ }" : "file"));
+        if (shots.length > shown.length) {
+          const more = g.append("g").attr("class", "shot more").attr("transform", `translate(${shown.length * (TW + 4)},0)`)
+            .on("click", (ev) => {
+              ev.stopPropagation();
+              select(d.data.id, "snapshots");
+            });
+          more.append("rect").attr("width", TW).attr("height", TH).attr("rx", 4);
+          more.append("text").attr("x", TW / 2).attr("y", TH / 2 + 3.5).attr("text-anchor", "middle").text(`+${shots.length - shown.length}`);
+        }
+      });
       flowPos = new Map(h.descendants().map((d) => [d.data.id, { x: d.y + CW / 2, y: d.x }]));
       svg.call(flowZoom);
       fitFlow(true);
@@ -946,6 +1038,7 @@
       const tabs = [
         ["overview", "Overview"],
         ["args", "Args"],
+        ...(hasValue(n) ? [["value", "Return"]] : []),
         ["events", `Events`],
         ["logs", "Logs"],
         ["snapshots", "Snapshots"],
@@ -965,10 +1058,11 @@
             ${n.v.description ? `<div class="k">Summary</div><div class="v">${esc(n.v.description.summary)}</div>` : ""}
             ${n.v.mcp ? `<div class="k">MCP</div><div class="v"><span class="badge-inline">${esc(n.v.mcp.mode)}</span></div>` : ""}
             <div class="k">Path</div><div class="v">${esc(n.v.path)}</div>
-            ${n.v.definedAt ? `<div class="k">Defined at</div><div class="v defined">
+            ${userSite(n) ? `<div class="k">${siteLabel(n)}</div><div class="v defined">
               <button class="icon-btn" data-copy-source aria-label="Copy relative path">${svgIcon("copy")}</button>
               ${hasCode(n) ? `<button class="icon-btn" data-show-code aria-label="Show source">${svgIcon("code")}</button>` : ""}
-              <a class="icon-btn" href="${esc(editorUrl(n.v.definedAt))}" aria-label="Open in VS Code" data-tip-text="Open in VS Code">${svgIcon("external")}</a>
+              ${hasValue(n) ? `<button class="icon-btn" data-show-value aria-label="Show returned value">${svgIcon("ret")}</button>` : ""}
+              <a class="icon-btn" href="${esc(editorUrl(userSite(n)))}" aria-label="Open in VS Code" data-tip-text="Open in VS Code">${svgIcon("external")}</a>
               <span class="defined-name" >${esc(basename(sourceOf(n)))}</span>
             </div>` : ""}
           </div>
@@ -986,6 +1080,13 @@
         copySrc.addEventListener("mousemove", (ev) => moveTip(ev));
         copySrc.addEventListener("mouseleave", hideTip);
       }
+      const showValue = el.details.querySelector("[data-show-value]");
+      if (showValue) {
+        showValue.addEventListener("click", (ev) => toggleCode(n, ev, "value", true));
+        showValue.addEventListener("mouseenter", (ev) => showTip(ev, `Returned: <span class="mono">${esc(valuePreview(n, 80))}</span>`));
+        showValue.addEventListener("mouseleave", hideTip);
+      }
+      wireValue(el.details, n);
       const showCode = el.details.querySelector("[data-show-code]");
       if (showCode) {
         showCode.addEventListener("click", (ev) => toggleCode(n, ev));
@@ -1012,6 +1113,9 @@
 
     function detailTabHtml(n) {
       const tab = state.detailTab;
+      if (tab === "value") {
+        return hasValue(n) ? `<div class="code-box">${valueHtml(n)}</div>` : '<div class="muted">Returned nothing.</div>';
+      }
       if (tab === "args") {
         const params = schemaFields(n.v.inputSchema);
         const schema = params.length ? `<div class="section-title">Schema</div><div class="params">${params.map(paramHtml).join("")}</div><div class="section-title">Values</div>` : "";
@@ -1284,23 +1388,38 @@
         ["Duration", fmtDur(n.duration)],
         ["When", `${fmtRel(n.start)} → ${fmtRel(n.end)}`],
         v.tags.length ? ["Tags", esc(v.tags.join(" · "))] : null,
-        v.definedAt ? ["Defined", `<span class="mono">${esc(sourceOf(n))}</span>`] : null,
+        userSite(n) ? [siteLabel(n) === "Called at" ? "Called" : "Defined", `<span class="mono">${esc(sourceOf(n))}</span>`] : null,
+        hasValue(n) ? ["Returns", `<span class="mono">${esc(valuePreview(n, 90))}</span>`] : null,
         n.children.length ? ["Children", String(n.children.length)] : null,
         n.marks.length ? ["Events", String(n.marks.length)] : null,
       ].filter(Boolean);
-      const args = v.args && v.args.length ? truncate(oneLine(v.args.length === 1 ? v.args[0] : v.args), 220) : "";
+      const args = !promptOf(n) && v.args && v.args.length ? truncate(oneLine(v.args.length === 1 ? v.args[0] : v.args), 220) : "";
       const params = schemaFields(v.inputSchema);
+      const pr = promptOf(n);
+      const promptRows = pr
+        ? `<div class="sec">Prompt</div><div class="tprompt">${esc(truncate(pr.message || "", 200))}</div>${
+            pr.answer ? `<div class="tkv"><span class="k">Answer</span><span class="mono">${esc(truncate(typeof pr.answer.value === "string" ? pr.answer.value : oneLine(pr.answer.value), 120))}</span>${pr.answer.via ? `<span class="k">Via</span><span>${esc(pr.answer.via)}</span>` : ""}</div>` : ""
+          }`
+        : "";
       const fails = model.run.failures.filter((f) => f.action === n.id || f.action === n.name || f.action === v.path);
       return `<div class="tt">${esc(shown)}</div>
         ${shown !== n.name ? `<div class="ts mono">${esc(truncate(n.name, 140))}</div>` : ""}
         <div class="badges">${badges}</div>
         ${v.description ? `<div class="summary">${esc(v.description.summary)}</div>` : '<div class="summary muted">No description.</div>'}
         <div class="tkv">${rows.map(([k, val]) => `<span class="k">${k}</span><span>${val}</span>`).join("")}</div>
+        ${promptRows}
         ${params.length ? `<div class="sec">Args schema</div><div class="params">${params.map(paramHtml).join("")}</div>` : ""}
         ${args ? `<div class="sec">Args</div><div class="mono small">${esc(args)}</div>` : ""}
         ${v.definedAt ? '<div class="hint">Press <kbd>C</kbd> to copy the path</div>' : ""}
         ${fails.length ? `<div class="sec fail">Failed</div><div class="mono small">${esc(truncate(String(fails[0].error).split(String.fromCharCode(10))[0], 200))}</div>` : ""}`;
     }
+    function galleryTip(x) {
+      const img = x.image ? `<img src="${model.asset(x.f.asset)}" alt="">` : "";
+      const body = x.type === "snapshot"
+        ? `<div class="mono small">${esc(truncate(x.s.value !== undefined ? oneLine(x.s.value) : x.s.text || "", 200))}</div>`
+        : `<div class="ts">${esc(x.f.mime)} · ${fmtSize(x.f.size)}</div>`;
+      return `<div class="tt">${esc(x.name)}${x.t != null ? ` · ${fmtRel(x.t)}` : ""}</div>${img}${body}`;
+    }
     /** The om itself: its node tooltip, plus where the run's record lives. */
     function omTip() {
       return `${nodeTip(model.root)}<div class="sec">Run folder</div><div class="mono small">${esc(model.data.folder)}</div>`;
@@ -1319,48 +1438,149 @@
     codeEl.hidden = true;
     document.body.appendChild(codeEl);
     let codeFor = null;
+    let codeTab = null;
     let codeAway = null;
+    /** A site inside omkit or an installed package — library source, not the user's. */
+    function isLib(site) {
+      return !!(site && model.data.library && model.data.library.includes(site));
+    }
+    /**
+     * The site worth showing for `n`: where it is defined, unless that is library source (a
+     * battery, a prompt), in which case the user's call that launched it.
+     */
+    function userSite(n) {
+      const { definedAt, calledAt } = n.v;
+      if (definedAt && !isLib(definedAt)) return definedAt;
+      if (calledAt && !isLib(calledAt)) return calledAt;
+      return definedAt || calledAt;
+    }
+    function siteLabel(n) {
+      return userSite(n) === n.v.definedAt ? "Defined at" : "Called at";
+    }
+    function codeOf(site) {
+      return site && model.data.code ? model.data.code[site] : undefined;
+    }
+    /** The popover's tabs for `n`, most useful first. */
+    function codeTabs(n) {
+      const tabs = [];
+      if (promptOf(n)) tabs.push({ key: "prompt", label: "Prompt" });
+      if (hasValue(n)) tabs.push({ key: "value", label: "Returned" });
+      const mine = userSite(n);
+      if (codeOf(mine)) tabs.push({ key: "user", label: siteLabel(n) === "Called at" ? "Call site" : "Source", site: mine });
+      const def = n.v.definedAt;
+      if (def && def !== mine && codeOf(def)) tabs.push({ key: "def", label: isLib(def) ? "Definition (omkit)" : "Definition", site: def });
+      return tabs;
+    }
     function hasCode(n) {
-      return !!(n.v.definedAt && model.data.code && model.data.code[n.v.definedAt]);
+      return codeTabs(n).some((t) => t.key !== "value");
     }
-    function toggleCode(n, ev) {
-      if (codeFor === n.id) return closeCode();
-      const site = n.v.definedAt;
-      const c = model.data.code && model.data.code[site];
-      if (!c) return;
-      hideTip();
-      codeFor = n.id;
+    function relOf(site) {
+      return (model.data.sources && model.data.sources[site]) || String(site).replace(/:\d+(:\d+)?$/, "");
+    }
+    function hasValue(n) {
+      return n.v.value !== undefined || !!n.v.valueNote;
+    }
+    function valuePreview(n, max) {
+      if (n.v.value === undefined) return n.v.valueNote || "";
+      return truncate(oneLine(n.v.value), max);
+    }
+    /** The returned value in the code view: pretty JSON, highlighted, numbered, copyable. */
+    function valueHtml(n) {
+      if (n.v.value === undefined) {
+        return `<div class="pp"><div class="muted">${esc(n.v.valueNote || "Returned nothing.")}</div></div>`;
+      }
+      const text = json(n.v.value);
+      const lines = highlight(text);
+      const kind = Array.isArray(n.v.value) ? `array · ${n.v.value.length} items` : n.v.value === null ? "null" : typeof n.v.value === "object" ? `object · ${Object.keys(n.v.value).length} keys` : typeof n.v.value;
+      return `<div class="cp-tools"><span class="muted">${esc(kind)} · ${lines.length} line${lines.length > 1 ? "s" : ""} · ${fmtSize(text.length)}</span>
+          <button class="btn solo small" data-a="copy-json">${svgIcon("copy")}Copy JSON</button></div>
+        <div class="cp-code">${lines
+          .map((html, i) => `<div class="cl"><span class="ln">${i + 1}</span><span class="lc">${html || " "}</span></div>`)
+          .join("")}</div>`;
+    }
+    function wireValue(root, n) {
+      const b = root.querySelector('[data-a="copy-json"]');
+      if (b) b.addEventListener("click", () => copy(json(n.v.value), "Copied the returned value"));
+    }
+    function codeHtml(site) {
+      const c = codeOf(site);
       const line = Number((/:(\d+)(?::\d+)?$/.exec(site) || [])[1]);
-      const rel = sourceOf(n);
       const lines = highlight(c.text).map(
         (html, i) => `<div class="cl${c.start + i === line ? " at" : ""}"><span class="ln">${c.start + i}</span><span class="lc">${html || " "}</span></div>`
       );
+      return `<div class="cp-code">${lines.join("")}</div>${c.truncated ? '<div class="muted cp-more">Cut short — open the file for the rest.</div>' : ""}`;
+    }
+    function promptHtml(p) {
+      const choices = p.choices && p.choices.length
+        ? `<div class="pp-k">Choices</div><div class="pp-v"><ol class="pp-choices">${p.choices
+            .map((c) => {
+              const value = typeof c === "string" ? c : c.value;
+              const label = typeof c === "string" ? c : c.label;
+              const picked = p.answer && p.answer.value === value;
+              return `<li class="${picked ? "picked" : ""}">${esc(label)}${label !== value ? ` <span class="muted">(${esc(value)})</span>` : ""}</li>`;
+            })
+            .join("")}</ol></div>`
+        : "";
+      const answer = p.answer
+        ? `<div class="pp-answer"><span class="pp-k">Answer</span><pre class="code">${esc(typeof p.answer.value === "string" ? p.answer.value : json(p.answer.value))}</pre>${
+            p.answer.via ? `<span class="badge-inline">via ${esc(p.answer.via)}</span>` : ""
+          }</div>`
+        : '<div class="muted">No answer recorded.</div>';
+      return `<div class="pp">
+        <div class="pp-q">${esc(p.message || "(no message)")}</div>
+        ${p.hint ? `<div class="mono small">${esc(p.hint)}</div>` : ""}
+        <div class="pp-grid">
+          <div class="pp-k">Kind</div><div class="pp-v">${esc(p.kind)}</div>
+          ${p.def !== undefined ? `<div class="pp-k">Default</div><div class="pp-v mono">${esc(oneLine(p.def))}</div>` : ""}
+          ${p.timeoutMs !== undefined ? `<div class="pp-k">Timeout</div><div class="pp-v">${p.timeoutMs > 0 && isFinite(p.timeoutMs) ? fmtDur(p.timeoutMs) : "none"}</div>` : ""}
+          ${choices}
+        </div>
+        ${answer}
+      </div>`;
+    }
+    function toggleCode(n, ev, want, toggle) {
+      // the <> closes whatever is open on its node; the return button closes only its own tab
+      if (codeFor === n.id && (!want || (toggle && codeTab === want))) return closeCode();
+      const tabs = codeTabs(n);
+      if (!tabs.length) return;
+      const tab = tabs.find((t) => t.key === want) || tabs.find((t) => t.key !== "value") || tabs[0];
+      codeTab = tab.key;
+      hideTip();
+      const reopen = codeFor !== n.id;
+      codeFor = n.id;
+      const site = tab.site || userSite(n);
+      const rel = site ? relOf(site) : "";
+      const line = site ? (/:(\d+)(?::\d+)?$/.exec(site) || [])[1] : "";
       codeEl.innerHTML = `<div class="cp-head">
-          <span class="cp-path" title="${esc(site)}">${esc(rel)}<span class="muted">:${line || c.start}</span></span>
+          ${site ? `<span class="cp-path" title="${esc(site)}">${esc(rel)}<span class="muted">${line ? ":" + line : ""}</span></span>
           <button class="icon-btn" data-a="copy" aria-label="Copy path">${svgIcon("copy")}</button>
-          <a class="icon-btn" href="${esc(editorUrl(site))}" aria-label="Open in VS Code">${svgIcon("external")}</a>
+          <a class="icon-btn" href="${esc(editorUrl(site))}" aria-label="Open in VS Code">${svgIcon("external")}</a>` : ""}
           <span class="cp-name">${esc(displayName(n))}</span>
           <button class="icon-btn" data-a="close" aria-label="Close">${svgIcon("close")}</button>
         </div>
-        <div class="cp-body"><div class="cp-code">${lines.join("")}</div>${
-          c.truncated ? '<div class="muted cp-more">Cut short — open the file for the rest.</div>' : ""
-        }</div>`;
-      codeEl.querySelector('[data-a="copy"]').addEventListener("click", () => copy(rel, `Copied ${rel}`));
+        ${tabs.length > 1 ? `<div class="cp-tabs">${tabs.map((t) => `<button class="tab ${t === tab ? "active" : ""}" data-tab="${t.key}">${esc(t.label)}</button>`).join("")}</div>` : ""}
+        <div class="cp-body">${tab.key === "prompt" ? promptHtml(promptOf(n)) : tab.key === "value" ? valueHtml(n) : codeHtml(site)}</div>`;
+      wireValue(codeEl, n);
+      const cp = codeEl.querySelector('[data-a="copy"]');
+      if (cp) cp.addEventListener("click", () => copy(rel, `Copied ${rel}`));
       codeEl.querySelector('[data-a="close"]').addEventListener("click", closeCode);
+      codeEl.querySelectorAll(".cp-tabs .tab").forEach((b) => b.addEventListener("click", () => toggleCode(n, null, b.dataset.tab)));
       codeEl.hidden = false;
-      const x = ev && ev.clientX != null ? ev.clientX : window.innerWidth / 2;
-      const y = ev && ev.clientY != null ? ev.clientY : window.innerHeight / 3;
-      const w = codeEl.offsetWidth;
-      const h = codeEl.offsetHeight;
-      const left = x + 14 + w > window.innerWidth - 8 ? x - w - 14 : x + 14;
-      const top = y + 14 + h > window.innerHeight - 8 ? y - h - 14 : y + 14;
-      codeEl.style.left = `${Math.max(8, left)}px`;
-      codeEl.style.top = `${Math.max(8, top)}px`;
+      if (reopen) {
+        const x = ev && ev.clientX != null ? ev.clientX : window.innerWidth / 2;
+        const y = ev && ev.clientY != null ? ev.clientY : window.innerHeight / 3;
+        const w = codeEl.offsetWidth;
+        const h = Math.min(codeEl.offsetHeight, window.innerHeight * 0.7);
+        const left = x + 14 + w > window.innerWidth - 8 ? x - w - 14 : x + 14;
+        const top = y + 14 + h > window.innerHeight - 8 ? y - h - 14 : y + 14;
+        codeEl.style.left = `${Math.max(8, left)}px`;
+        codeEl.style.top = `${Math.max(8, top)}px`;
+      }
       const at = codeEl.querySelector(".cl.at");
       if (at) at.scrollIntoView({ block: "center" });
       if (codeAway) document.removeEventListener("mousedown", codeAway, true);
       codeAway = (e) => {
-        if (!codeEl.contains(e.target) && !e.target.closest(".code-btn, [data-show-code]")) closeCode();
+        if (!codeEl.contains(e.target) && !e.target.closest(".code-btn, [data-show-code], [data-show-value]")) closeCode();
       };
       setTimeout(() => codeAway && document.addEventListener("mousedown", codeAway, true), 0);
     }
@@ -1372,11 +1592,10 @@
     }
     let tipTimer = 0;
     let hovered = null;
-    /** The file where `n` is defined, relative to the project root — no line. */
+    /** The file worth opening for `n` (see {@link userSite}), relative to the project root — no line. */
     function sourceOf(n) {
-      const site = n.v.definedAt;
-      if (!site) return "";
-      return (model.data.sources && model.data.sources[site]) || site.replace(/:\d+(:\d+)?$/, "");
+      const site = userSite(n);
+      return site ? relOf(site) : "";
     }
     function copySource(n) {
       const src = n && sourceOf(n);
@@ -1568,7 +1787,7 @@
       if (m.index > last) parts.push([null, text.slice(last, m.index)]);
       let cls = null;
       if (m[1]) cls = "tk-c";
-      else if (m[2]) cls = "tk-s";
+      else if (m[2]) cls = /^\s*:/.test(text.slice(TOKEN.lastIndex, TOKEN.lastIndex + 8)) ? "tk-p" : "tk-s";
       else if (m[3]) cls = "tk-n";
       else if (m[4]) {
         if (KEYWORDS.has(m[4])) cls = "tk-k";
@@ -1622,12 +1841,48 @@
       f.def !== undefined ? `<span class="pd">= ${esc(truncate(f.def, 24))}</span>` : ""
     }${f.desc ? `<div class="pdesc">${esc(f.desc)}</div>` : ""}</div>`;
   }
+  /**
+   * What a `prompt` battery node asked and got back: its options (the node's one argument) plus
+   * the `prompt` / `answer` events it emitted. `null` for anything that is not a prompt.
+   */
+  function promptOf(n) {
+    if (n._prompt !== undefined) return n._prompt;
+    n._prompt = null;
+    if (n.name !== "prompt" || n.depth === 0) return null;
+    const opts = (n.v.args && n.v.args[0] && typeof n.v.args[0] === "object" ? n.v.args[0] : {}) || {};
+    let message = opts.message;
+    let answer = null;
+    for (const it of n.entries) {
+      if (it.e.level !== "event") continue;
+      if (it.e.message.startsWith("prompt · ")) message = it.e.message.slice("prompt · ".length);
+      else if (it.e.message.startsWith("answer · ")) {
+        try {
+          answer = JSON.parse(it.e.message.slice("answer · ".length));
+        } catch {
+          answer = { value: it.e.message.slice("answer · ".length) };
+        }
+      }
+    }
+    if (message === undefined && !answer) return null;
+    n._prompt = {
+      message,
+      kind: opts.kind || "input",
+      hint: opts.hint,
+      choices: opts.choices,
+      def: opts.default,
+      timeoutMs: opts.timeoutMs,
+      answer,
+    };
+    return n._prompt;
+  }
   function truncate(s, n) {
     n = Math.max(1, Math.floor(n));
     return s.length > n ? `${s.slice(0, Math.max(1, n - 1))}…` : s;
   }
   function displayName(n) {
     if (n.depth === 0) return "main";
+    const p = promptOf(n);
+    if (p && p.message) return `prompt: ${truncate(p.message, 48)}`;
     const tag = n.v.tags && n.v.tags[0];
     // Battery steps are named after their kind (`command`, `chromePage`); their first tag
     // is what the om called them, which is the more useful label.

package/dist/output/writers/views.d.ts

@@ -9,6 +9,8 @@ export interface NodeView {
     readonly name: string;
     /** `file:line` where the action was defined (the `.run(...)` site); absent for the root. */
     readonly definedAt?: string;
+    /** `file:line` of the call that launched this node; absent for the root. */
+    readonly calledAt?: string;
     readonly path: string;
     readonly parentId: string | null;
     readonly tags: readonly string[];
@@ -29,6 +31,10 @@ export interface NodeView {
     };
     /** The definition's `.args()` schema as JSON Schema; absent without one. */
     readonly inputSchema?: unknown;
+    /** What the node returned, when JSON can carry it; absent for `undefined` and for failures. */
+    readonly value?: unknown;
+    /** Why a returned value is not in {@link value}: what it was, and that it was too big or not JSON. */
+    readonly valueNote?: string;
     readonly children: readonly NodeView[];
 }
 /** A curated artifact, as projected into `result.json`. Data-only — no core import. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omkit",
-  "version": "0.8.12",
+  "version": "0.8.14",
   "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",