omkit 0.8.11 → 0.8.12

package/README.md

@@ -189,7 +189,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 flame graph, a flow graph of the tree, per-action details, logs, assertions, and the run's snapshots and images. 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 flame graph, a flow graph of the tree, per-action details, logs, assertions, the run's snapshots and images, and each action's source (the `<>` button next to a block). 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/output/writers/ReportWriter.js

@@ -40,6 +40,7 @@ export async function writeReport(file, input) {
         folder: input.folder,
         projectRoot: root,
         sources: definitionSources(input.run.root, root),
+        code: await definitionCode(input.run.root),
         generatedAt: Date.now(),
         run: input.run,
         entries: input.entries,
@@ -58,29 +59,29 @@ function renderPage(input, payload, assets, code) {
     const blobs = assets
         .map((a) => `<script type="text/plain" id="${a.id}" data-mime="${a.mime}">${a.data}</script>`)
         .join("\n");
-    return `<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>${escapeHtml(title)}</title>
-<style>${code.css}</style>
-</head>
-<body>
-<div id="loader" role="status" aria-live="polite">
-  <div class="loader-card">
-    <div class="loader-spin"></div>
-    <div class="loader-title">${escapeHtml(title)}</div>
-    <div class="loader-step" id="loader-step">Loading the run record…</div>
-  </div>
-</div>
-<div id="app" hidden></div>
-<script id="omkit-data" type="application/json">${inertJson(payload)}</script>
-${blobs}
-<script>${inertScript(code.d3)}</script>
-<script>${inertScript(code.client)}</script>
-</body>
-</html>
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)}</title>
+<style>${code.css}</style>
+</head>
+<body>
+<div id="loader" role="status" aria-live="polite">
+  <div class="loader-card">
+    <div class="loader-spin"></div>
+    <div class="loader-title">${escapeHtml(title)}</div>
+    <div class="loader-step" id="loader-step">Loading the run record…</div>
+  </div>
+</div>
+<div id="app" hidden></div>
+<script id="omkit-data" type="application/json">${inertJson(payload)}</script>
+${blobs}
+<script>${inertScript(code.d3)}</script>
+<script>${inertScript(code.client)}</script>
+</body>
+</html>
 `;
 }
 async function collectFiles(input, assets) {
@@ -120,7 +121,11 @@ async function collectFiles(input, assets) {
             out.push({ ...base, size, text: await readFile(abs, "utf8") });
         }
         else {
-            out.push({ ...base, size, omitted: isText(meta.mime) ? `larger than ${mb(TEXT_CAP)}` : "binary" });
+            out.push({
+                ...base,
+                size,
+                omitted: isText(meta.mime) ? `larger than ${mb(TEXT_CAP)}` : "binary",
+            });
         }
     };
     for (const a of input.artifacts) {
@@ -153,7 +158,14 @@ async function collectSnapshots(input) {
             continue;
         const name = e.message.slice(0, split);
         const abs = e.message.slice(split + 3);
-        const base = { seq: ++seq, name, nodeId: e.nodeId, ts: e.ts, file: abs, rel: relTo(input.folder, abs) };
+        const base = {
+            seq: ++seq,
+            name,
+            nodeId: e.nodeId,
+            ts: e.ts,
+            file: abs,
+            rel: relTo(input.folder, abs),
+        };
         try {
             const raw = await readFile(abs, "utf8");
             if (raw.length > SNAPSHOT_CAP) {
@@ -220,6 +232,66 @@ function definitionSources(root, projectDir) {
     visit(root);
     return out;
 }
+/** Longest excerpt shown per definition; a body past this is cut, and says so. */
+const CODE_LINES = 300;
+/**
+ * Each distinct `definedAt` site → the source of the definition there: the whole top-level
+ * statement holding that line (`export const x = action(…)…run(…)`, or the `om(…).run(…)` call),
+ * found with the TypeScript parser so it is the real extent, not a guess at one. A site whose
+ * file is gone or unparseable gets a window of lines around it instead, or nothing.
+ */
+async function definitionCode(root) {
+    const sites = new Set();
+    const visit = (n) => {
+        if (n.definedAt)
+            sites.add(n.definedAt);
+        n.children.forEach(visit);
+    };
+    visit(root);
+    if (sites.size === 0)
+        return {};
+    // Loaded only here: the parser is heavy, and a run that never writes a report never pays for it.
+    const ts = (await import("typescript")).default;
+    const out = {};
+    const texts = new Map();
+    for (const site of sites) {
+        const m = /^(.*):(\d+)(?::\d+)?$/.exec(site);
+        if (!m)
+            continue;
+        const file = m[1];
+        const line = Number(m[2]);
+        if (!texts.has(file))
+            texts.set(file, await readFile(file, "utf8").catch(() => null));
+        const text = texts.get(file);
+        if (!text)
+            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 truncated = to - from + 1 > CODE_LINES;
+        out[site] = {
+            start: from,
+            text: lines.slice(from - 1, truncated ? from - 1 + CODE_LINES : to).join("\n"),
+            lang,
+            ...(truncated ? { truncated } : {}),
+        };
+    }
+    return out;
+}
 async function walk(dir, depth = 0) {
     if (depth > 4)
         return [];

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

@@ -292,6 +292,52 @@ table.list tr:hover td { background: var(--raise); }
 .menu button:hover { background: var(--raise); }
 .toast { position: fixed; bottom: 18px; left: 50%; transform: translateX(-50%); background: var(--raise); border: 1px solid var(--line); padding: 7px 14px; border-radius: 8px; z-index: 70; }
 
+/* ── title info, locate, defined-at, code popover ───────── */
+.title-row { display: flex; align-items: center; gap: 8px; min-width: 0; }
+.title-row h1 { min-width: 0; }
+.info-btn { flex: none; width: 22px; height: 22px; border: 0; border-radius: 50%; background: none; color: var(--text-3); display: grid; place-items: center; cursor: help; padding: 0; }
+.info-btn:hover, .info-btn:focus-visible { color: var(--accent); background: var(--accent-soft); }
+.info-btn svg { width: 17px; height: 17px; }
+.gal-item .cap .locate { margin-left: auto; width: 22px; height: 20px; }
+.kv .v.defined { flex-wrap: wrap; }
+.kv .v.defined .defined-name { color: var(--text-2); font-family: var(--mono); font-size: 12px; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+a.icon-btn { text-decoration: none; }
+.chart .code-btn, .flow-card .code-btn { cursor: pointer; opacity: 0; transition: opacity 0.12s; }
+.chart g.r:hover .code-btn, .chart g.r.sel .code-btn, .flow-card:hover .code-btn, .flow-card.selected .code-btn { opacity: 1; }
+.code-btn circle { fill: var(--panel); stroke: var(--text-3); stroke-width: 1.2; }
+.code-btn text { fill: var(--text-2); font: 700 9px var(--mono); pointer-events: none; }
+.code-btn:hover circle { stroke: var(--accent); }
+.code-btn:hover text { fill: var(--accent); }
+.chart line.pin.flash, .flame-view line.pin.flash { animation: pin-flash 0.6s ease-in-out 3; }
+.chart circle.mark.flash { animation: mark-flash 0.6s ease-in-out 3; transform-box: fill-box; transform-origin: center; }
+@keyframes pin-flash { 50% { stroke-width: 5; } }
+@keyframes mark-flash { 50% { transform: scale(1.9); } }
+.code-pop {
+  position: fixed; z-index: 58; width: 640px; max-width: 92vw; max-height: 70vh; display: flex; flex-direction: column;
+  background: var(--panel); border: 1px solid var(--line); border-radius: 10px; box-shadow: var(--shadow); overflow: hidden;
+}
+.code-pop .cp-head { display: flex; align-items: center; gap: 6px; padding: 6px 8px 6px 12px; background: var(--panel-2); border-bottom: 1px solid var(--line); }
+.code-pop .cp-path { font: 12px var(--mono); color: var(--text-2); min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.code-pop .cp-name { flex: 1; text-align: right; color: var(--text-3); font-size: 12px; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.code-pop .cp-body { overflow: auto; min-height: 0; }
+.code-pop .cp-code { font: 11.5px/1.65 var(--mono); padding: 8px 0; min-width: max-content; }
+.code-pop .cl { display: grid; grid-template-columns: 48px auto; white-space: pre; }
+.code-pop .cl.at { background: var(--accent-soft); }
+.code-pop .ln { color: var(--text-3); text-align: right; padding-right: 14px; user-select: none; }
+.code-pop .lc { padding-right: 16px; }
+.code-pop .cp-more { padding: 6px 14px 10px; font-size: 12px; }
+:root { --tk-c: #6f7a99; --tk-s: #7ee0a3; --tk-n: #f0b26b; --tk-k: #c792ea; --tk-f: #82aaff; --tk-t: #ffcb6b; }
+:root[data-theme="light"] { --tk-c: #6a737d; --tk-s: #116329; --tk-n: #b35900; --tk-k: #cf222e; --tk-f: #6639ba; --tk-t: #953800; }
+@media (prefers-color-scheme: light) {
+  :root:not([data-theme="dark"]) { --tk-c: #6a737d; --tk-s: #116329; --tk-n: #b35900; --tk-k: #cf222e; --tk-f: #6639ba; --tk-t: #953800; }
+}
+.tk-c { color: var(--tk-c); font-style: italic; }
+.tk-s { color: var(--tk-s); }
+.tk-n { color: var(--tk-n); }
+.tk-k { color: var(--tk-k); }
+.tk-f { color: var(--tk-f); }
+.tk-t { color: var(--tk-t); }
+
 @media (max-width: 1100px) {
   .bottom { grid-template-columns: minmax(0, 1fr); }
   .legend, .overview { display: none; }

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

@@ -40,6 +40,10 @@
     download: "M12 4v11M7 10l5 5 5-5M5 20h14",
     copy: "M9 9h11v11H9zM5 15V4h11",
     stop: "M6 6h12v12H6z",
+    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",
+    external: "M14 4h6v6M20 4l-9 9M18 14v6H4V6h6",
   };
   const svgIcon = (name, extra) =>
     `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"${
@@ -297,6 +301,11 @@
       zoomToDomain(Math.max(0, d0), Math.max(0, d0) + ms);
     });
     app.querySelector("#more").addEventListener("click", (ev) => openMenu(ev.currentTarget));
+    const info = app.querySelector("#om-info");
+    info.addEventListener("mouseenter", (ev) => showTip(ev, omTip(), true));
+    info.addEventListener("mousemove", (ev) => moveTip(ev));
+    info.addEventListener("mouseleave", hideTip);
+    info.addEventListener("click", () => select(model.root.id));
 
     // ── zoom behaviours ──
     const chartZoom = d3
@@ -496,9 +505,13 @@
           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");
+          cb.append("circle").attr("r", 9);
+          cb.append("text").attr("text-anchor", "middle").attr("y", 3.5).text("<>");
           return r;
         })
-        .attr("transform", (_n, i) => `translate(0,${i * ROW_H})`);
+        .attr("transform", (_n, i) => `translate(0,${i * ROW_H})`)
+        .classed("sel", (n) => n.id === state.selected);
 
       g.select("rect.bar")
         .attr("x", (n) => x(n.start))
@@ -530,7 +543,22 @@
         const left = Math.min(x0, flip ? lx - tw : lx) - 6;
         const right = Math.max(x0 + Math.max(w, 3), flip ? x0 : lx + tw) + 6;
         d3.select(this.parentNode).select("rect.hit").attr("x", left).attr("width", Math.max(16, right - left));
+        // the <> sits just past the block (or just before it, when that would leave the chart)
+        // …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")
+          .attr("transform", `translate(${cx},${BAR_Y + BAR_H / 2})`);
       });
+      g.select("g.code-btn")
+        .on("click", (ev, n) => {
+          ev.stopPropagation();
+          toggleCode(n, ev);
+        })
+        .on("mouseenter", (ev) => showTip(ev, "Show source"))
+        .on("mouseleave", hideTip);
       g.selectAll("rect.hit, text.bar-label").call(bindNode);
 
       g.select("g.marks").each(function (n) {
@@ -645,12 +673,15 @@
         .on("mouseleave", () => moveCursor(null));
       flameSvg.append("g").attr("class", "grid");
       flameSvg.append("g").attr("class", "cells");
+      flameSvg.append("line").attr("class", "pin").attr("stroke", css("--accent")).attr("stroke-width", 1.5).attr("y1", 0).attr("y2", 4000);
       flameSvg.append("line").attr("class", "cursor").attr("y1", 0).attr("y2", 4000).attr("visibility", "hidden");
       flameSvg.call(flameZoom).call(flameZoom.transform, state.zoom);
       redrawX();
     }
     function drawFlame(x) {
       if (!flameSvg) return;
+      const px = state.pin != null ? x(state.pin) : -10;
+      flameSvg.select("line.pin").attr("x1", px).attr("x2", px);
       const H = el.flame.clientHeight;
       const ticks = x.ticks(Math.max(2, Math.floor(W / 90)));
       flameSvg
@@ -693,6 +724,7 @@
 
     // ── flow view ──
     let flowG = null;
+    let flowPos = new Map();
     let flowBounds = null;
     function renderFlow() {
       d3.select(el.flow).selectAll("svg").remove();
@@ -752,6 +784,22 @@
         .attr("cy", 14)
         .attr("r", 4)
         .attr("fill", (d) => css(statusVar(d.data.status)));
+      const fcb = card
+        .filter((d) => hasCode(d.data))
+        .append("g")
+        .attr("class", "code-btn")
+        .attr("transform", `translate(${CW / 2},0)`)
+        .on("click", (ev, d) => {
+          ev.stopPropagation();
+          toggleCode(d.data, ev);
+        })
+        .on("mouseenter", (ev) => {
+          ev.stopPropagation();
+          showTip(ev, "Show source");
+        });
+      fcb.append("circle").attr("r", 9);
+      fcb.append("text").attr("text-anchor", "middle").attr("y", 3.5).text("<>");
+      flowPos = new Map(h.descendants().map((d) => [d.data.id, { x: d.y + CW / 2, y: d.x }]));
       svg.call(flowZoom);
       fitFlow(true);
     }
@@ -820,7 +868,10 @@
       state.details = true;
       el.main.classList.remove("no-details");
       el.tree.querySelectorAll(".row").forEach((r) => r.classList.toggle("selected", r.dataset.id === id));
-      if (chartSvg) chartSvg.selectAll("rect.bar").classed("selected", (n) => n.id === id);
+      if (chartSvg) {
+        chartSvg.selectAll("rect.bar").classed("selected", (n) => n.id === id);
+        chartSvg.selectAll("g.r").classed("sel", (n) => n.id === id);
+      }
       if (flameSvg) flameSvg.selectAll("rect.flame-rect").classed("selected", (n) => n.id === id);
       d3.select(el.flow).selectAll("g.flow-card").classed("selected", (d) => d.data.id === id);
       renderDetails();
@@ -829,7 +880,7 @@
       const pad = Math.max(n.end - n.start, 50) * 0.08;
       zoomToDomain(n.start - pad, n.end + pad);
     }
-    function revealRow(n) {
+    function revealRow(n, block) {
       let p = n.parent;
       let changed = false;
       while (p) {
@@ -838,7 +889,55 @@
       }
       if (changed && state.view === "timeline") renderTimeline();
       const row = el.tree.querySelector(`.row[data-id="${CSS.escape(n.id)}"]`);
-      if (row) row.scrollIntoView({ block: "nearest" });
+      if (row) row.scrollIntoView({ block: block || "nearest" });
+    }
+
+    /**
+     * Bring a gallery item into view in whichever graph is showing: select its node, pin its
+     * time, pan (keeping the zoom) so that time is on screen, and pulse its mark.
+     */
+    function locate(g) {
+      if (!g) return;
+      if (g.node) select(g.node.id, "snapshots");
+      if (state.view === "flow") {
+        if (g.node) centerFlowOn(g.node);
+        return;
+      }
+      if (g.t != null) {
+        state.pin = g.t;
+        const [a, b] = xz().domain();
+        if (g.t < a || g.t > b) {
+          const k = state.zoom.k;
+          const t = d3.zoomIdentity.translate(W / 2 - k * baseX(g.t), 0).scale(k);
+          const { z, sel } = activeZoom();
+          sel.call(z.transform, t);
+        } else redrawX();
+      }
+      if (g.node && state.view === "timeline") revealRow(g.node, "center");
+      flash(g);
+    }
+    function flash(g) {
+      const svgs = [chartSvg, flameSvg].filter(Boolean);
+      for (const s of svgs) {
+        s.selectAll("line.pin").classed("flash", false).node()?.getBoundingClientRect();
+        s.selectAll("line.pin").classed("flash", true);
+      }
+      if (chartSvg) {
+        const hit = chartSvg
+          .selectAll("circle.mark")
+          .filter((d) => d.m.gallery === g || d.more.some((m) => m.gallery === g));
+        hit.classed("flash", false).node()?.getBoundingClientRect();
+        hit.classed("flash", true);
+      }
+      setTimeout(() => d3.selectAll(".flash").classed("flash", false), 1800);
+    }
+    function centerFlowOn(n) {
+      const svg = d3.select(el.flow).select("svg");
+      const p = flowPos.get(n.id);
+      if (svg.empty() || !p) return;
+      const k = Math.max(0.8, d3.zoomTransform(svg.node()).k);
+      const t = d3.zoomIdentity.translate(el.flow.clientWidth / 2 - k * p.x, el.flow.clientHeight / 2 - k * p.y).scale(k);
+      svg.transition().duration(300).call(flowZoom.transform, t);
     }
 
     function renderDetails() {
@@ -866,7 +965,12 @@
             ${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"><a href="${esc(editorUrl(n.v.definedAt))}" title="Open ${esc(n.v.definedAt)} in VS Code">${esc(sourceOf(n))}</a><button class="icon-btn" data-copy-source title="Copy relative path (C)">${svgIcon("copy")}</button></div>` : ""}
+            ${n.v.definedAt ? `<div class="k">Defined at</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>
+              <span class="defined-name" >${esc(basename(sourceOf(n)))}</span>
+            </div>` : ""}
           </div>
           <div class="tabs">${tabs
             .map(([k, l]) => `<button class="tab ${state.detailTab === k ? "active" : ""}" data-tab="${k}">${l}</button>`)
@@ -874,7 +978,24 @@
           <div class="tabbody">${detailTabHtml(n)}</div>
         </div>`;
       const copySrc = el.details.querySelector("[data-copy-source]");
-      if (copySrc) copySrc.addEventListener("click", () => copySource(n));
+      if (copySrc) {
+        copySrc.addEventListener("click", () => copySource(n));
+        copySrc.addEventListener("mouseenter", (ev) =>
+          showTip(ev, `<div class="mono">${esc(sourceOf(n))}</div><div class="hint">Click (or press <kbd>C</kbd>) to copy</div>`)
+        );
+        copySrc.addEventListener("mousemove", (ev) => moveTip(ev));
+        copySrc.addEventListener("mouseleave", hideTip);
+      }
+      const showCode = el.details.querySelector("[data-show-code]");
+      if (showCode) {
+        showCode.addEventListener("click", (ev) => toggleCode(n, ev));
+        showCode.addEventListener("mouseenter", (ev) => showTip(ev, "Show source"));
+        showCode.addEventListener("mouseleave", hideTip);
+      }
+      el.details.querySelectorAll("[data-tip-text]").forEach((a) => {
+        a.addEventListener("mouseenter", (ev) => showTip(ev, esc(a.dataset.tipText)));
+        a.addEventListener("mouseleave", hideTip);
+      });
       el.details.querySelector(".x").addEventListener("click", () => {
         state.details = false;
         el.main.classList.add("no-details");
@@ -1002,6 +1123,14 @@
       body.querySelectorAll("tr[data-row]").forEach((tr) =>
         tr.addEventListener("click", () => openItem(model.items[+tr.dataset.row]))
       );
+      body.querySelectorAll("[data-locate]").forEach((b) => {
+        b.addEventListener("click", (ev) => {
+          ev.stopPropagation();
+          locate(model.gallery[+b.dataset.locate]);
+        });
+        b.addEventListener("mouseenter", (ev) => showTip(ev, `Show in the ${state.view === "flow" ? "flow" : "graph"}`));
+        b.addEventListener("mouseleave", hideTip);
+      });
     }
     function matches(...parts) {
       const q = state.filter.trim().toLowerCase();
@@ -1015,7 +1144,8 @@
         return `<div class="gallery">${g
           .map((x) => {
             const sub = x.type === "snapshot" ? `snapshot · ${x.node ? esc(displayName(x.node)) : ""}` : `${esc(x.f.mime)} · ${fmtSize(x.f.size)}${x.f.omitted ? " · not embedded" : ""}`;
-            return `<div class="gal-item">${thumbHtml(x)}<div class="cap"><span class="t">${x.t == null ? "–" : fmtTick(x.t)}</span><span class="n" title="${esc(x.name)}">${esc(x.name)}</span></div><div class="sz">${sub}</div></div>`;
+            const at = x.t != null || x.node ? `<button class="icon-btn locate" data-locate="${model.gallery.indexOf(x)}" aria-label="Show in graph">${svgIcon("locate")}</button>` : "";
+            return `<div class="gal-item">${thumbHtml(x)}<div class="cap"><span class="t">${x.t == null ? "–" : fmtTick(x.t)}</span><span class="n" title="${esc(x.name)}">${esc(x.name)}</span>${at}</div><div class="sz">${sub}</div></div>`;
           })
           .join("")}</div>`;
       }
@@ -1144,7 +1274,7 @@
     function nodeTip(n) {
       hovered = n; // the node `C` copies while its tooltip is up
       const v = n.v;
-      const shown = displayName(n);
+      const shown = n.depth === 0 ? model.data.name : displayName(n);
       const badges = [
         `<span class="badge"><span class="dot ${n.status}"></span>${esc(n.status)}</span>`,
         v.mcp ? `<span class="badge mcp" title="Exposed over MCP">MCP · ${esc(v.mcp.mode)}</span>` : "",
@@ -1171,6 +1301,10 @@
         ${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>` : ""}`;
     }
+    /** 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>`;
+    }
     function markTip(d) {
       const m = d.m;
       const mk = MARK[m.kind] || MARK.event;
@@ -1179,6 +1313,63 @@
       const extra = m.gallery && m.gallery.image ? `<div class="ts">${esc(m.gallery.f.rel)} · ${fmtSize(m.gallery.f.size)}</div>` : "";
       return `<div class="tt">${esc(mk.label)} · ${fmtRel(m.t)}</div>${img}<div>${esc(truncate(m.kind === "snapshot" || m.kind === "artifact" ? m.label : m.e.message, 260))}</div>${extra}${more}`;
     }
+    // ── source popover (the <> buttons) — click-toggled, like the tskb explorer's ──
+    const codeEl = document.createElement("div");
+    codeEl.className = "code-pop";
+    codeEl.hidden = true;
+    document.body.appendChild(codeEl);
+    let codeFor = null;
+    let codeAway = null;
+    function hasCode(n) {
+      return !!(n.v.definedAt && model.data.code && model.data.code[n.v.definedAt]);
+    }
+    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;
+      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>`
+      );
+      codeEl.innerHTML = `<div class="cp-head">
+          <span class="cp-path" title="${esc(site)}">${esc(rel)}<span class="muted">:${line || c.start}</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>
+          <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}`));
+      codeEl.querySelector('[data-a="close"]').addEventListener("click", closeCode);
+      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`;
+      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();
+      };
+      setTimeout(() => codeAway && document.addEventListener("mousedown", codeAway, true), 0);
+    }
+    function closeCode() {
+      codeFor = null;
+      codeEl.hidden = true;
+      if (codeAway) document.removeEventListener("mousedown", codeAway, true);
+      codeAway = null;
+    }
     let tipTimer = 0;
     let hovered = null;
     /** The file where `n` is defined, relative to the project root — no line. */
@@ -1242,6 +1433,7 @@
       resizeTimer = setTimeout(relayout, 120);
     });
     document.addEventListener("keydown", (e) => {
+      if (e.key === "Escape" && codeFor) return closeCode();
       if (e.target.closest && e.target.closest("input")) return;
       if (e.key === "+" || e.key === "=") zoomBy(1.6);
       else if (e.key === "-") zoomBy(1 / 1.6);
@@ -1278,7 +1470,10 @@
     return `
       <header class="top">
         <div class="titles">
-          <h1 title="${esc(model.data.folder)}">Run: ${esc(model.data.name)}</h1>
+          <div class="title-row">
+            <h1 title="${esc(model.data.folder)}">Run: ${esc(model.data.name)}</h1>
+            <button class="info-btn" id="om-info" aria-label="About this om">${svgIcon("info")}</button>
+          </div>
           <div class="meta"><span class="dot ${ok ? "ok" : "failed"}"></span><span>${ok ? "passed" : "failed"}</span>
             <span class="sep">•</span><span>${fmtDate(run.startedAt)}</span>
             <span class="sep">•</span><span title="body ${fmtDur(run.duration)} · record ${fmtDur(model.span)}">${fmtDur(run.duration)}</span>
@@ -1358,6 +1553,41 @@
     c.opacity = a;
     return c.formatRgb();
   }
+  const KEYWORDS = new Set(
+    "abstract as async await break case catch class const continue default delete do else enum export extends false finally for from function get if implements import in instanceof interface keyof let new null of private protected public readonly return satisfies set static super switch this throw true try type typeof undefined var void while yield".split(" ")
+  );
+  const TOKEN =
+    /(\/\/[^\n]*|\/\*[\s\S]*?\*\/)|(`(?:\\[\s\S]|[^`\\])*`|"(?:\\.|[^"\\\n])*"|'(?:\\.|[^'\\\n])*')|(\b\d[\d_]*(?:\.\d+)?(?:[eE][+-]?\d+)?n?\b)|([A-Za-z_$][\w$]*)/g;
+  /** Highlighted HTML per source line. Tokens that span lines are closed and reopened at each break. */
+  function highlight(text) {
+    const parts = [];
+    let last = 0;
+    let m;
+    TOKEN.lastIndex = 0;
+    while ((m = TOKEN.exec(text))) {
+      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[3]) cls = "tk-n";
+      else if (m[4]) {
+        if (KEYWORDS.has(m[4])) cls = "tk-k";
+        else if (/^\s*\(/.test(text.slice(TOKEN.lastIndex, TOKEN.lastIndex + 40))) cls = "tk-f";
+        else if (/^[A-Z]/.test(m[4])) cls = "tk-t";
+      }
+      parts.push([cls, m[0]]);
+      last = TOKEN.lastIndex;
+    }
+    if (last < text.length) parts.push([null, text.slice(last)]);
+    const lines = [""];
+    for (const [cls, chunk] of parts) {
+      chunk.split("\n").forEach((piece, i) => {
+        if (i > 0) lines.push("");
+        if (piece) lines[lines.length - 1] += cls ? `<span class="${cls}">${esc(piece)}</span>` : esc(piece);
+      });
+    }
+    return lines;
+  }
   function oneLine(v) {
     try {
       return typeof v === "string" ? v : JSON.stringify(v);

package/package.json

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