skillscript-runtime 0.30.0 → 0.31.1

package/dist/dashboard/spa/app.js

@@ -224,7 +224,7 @@ async function renderApprovals() {
     return `
       <tr>
         <td><a href="#skill/${encodeURIComponent(s.name)}"><strong>${esc(s.name)}</strong></a> ${whyBadge}<br>
-            <span style="color:#6c757d;font-size:0.85em;">${esc(s.description ?? "—")}</span></td>
+            <span style="color:var(--text-muted);font-size:0.85em;">${esc(s.description ?? "—")}</span></td>
         <td>${sigBadges}</td>
         <td>
           <a href="#skill/${encodeURIComponent(s.name)}">Review →</a>
@@ -463,7 +463,7 @@ async function renderSkillDetail(name) {
       ? `<div class="remediation" style="margin-top: 12px;"><strong>Approval token stale.</strong> ${esc(approval.reason ?? "")}. Re-transition to Approved to stamp a fresh token.</div>`
       : "";
     return `
-      <div style="margin-bottom: 8px;"><a href="#" onclick="event.preventDefault(); window.history.back();" style="font-size: 0.9em; color: #6c757d;">← Back</a></div>
+      <div style="margin-bottom: 8px;"><a href="#" onclick="event.preventDefault(); window.history.back();" style="font-size: 0.9em; color: var(--text-muted);">← Back</a></div>
       <h2>Skill: ${esc(metadata.name)} <span class="badge ${esc(metadata.status)}">${esc(metadata.status)}</span>${approvalBadge}</h2>
 
       <section>
@@ -471,14 +471,16 @@ async function renderSkillDetail(name) {
         <p>${esc(metadata.description ?? "(no description)")}</p>
         ${approvalBanner}
         ${renderStatusActions(name, metadata, approval)}
-        <div style="margin-top: 16px; border-top: 1px solid #eee; padding-top: 12px;">
+        <div style="margin-top: 16px; border-top: 1px solid var(--border); padding-top: 12px;">
           <button class="danger" onclick="deleteSkill('${esc(name).replace(/'/g, "\\'")}')">Delete skill</button>
-          <span style="color:#6c757d; font-size:0.85em; margin-left:8px;">permanent — no undo; warns if other skills reference it, then frees the name</span>
+          <span style="color:var(--text-muted); font-size:0.85em; margin-left:8px;">permanent — no undo; warns if other skills reference it, then frees the name</span>
         </div>
       </section>
 
       ${renderEffectfulFootprintPanel(contract?.effectful_footprint)}
 
+      ${renderSkillFlow(contract?.flow)}
+
       ${source ? renderSecuritySignalsPanel(source) : ""}
 
       <section>
@@ -488,8 +490,8 @@ async function renderSkillDetail(name) {
 
       ${renderComposesSection(name, source)}
 
-      <section>
-        <h2>Triggers (${triggersForSkill.length})</h2>
+      <details class="section collapsible">
+        <summary>Triggers (${triggersForSkill.length})</summary>
         ${triggersForSkill.length === 0
           ? `<div class="empty">No triggers registered for this skill.</div>`
           : `<table>
@@ -504,10 +506,10 @@ async function renderSkillDetail(name) {
                 `).join("")}
               </tbody>
             </table>`}
-      </section>
+      </details>
 
-      <section>
-        <h2>Metrics (24h)</h2>
+      <details class="section collapsible">
+        <summary>Metrics (24h)</summary>
         ${metrics
           ? `<dl class="kv">
               <dt>Fires</dt><dd>${metrics.fireCount}</dd>
@@ -516,10 +518,10 @@ async function renderSkillDetail(name) {
               <dt>Success rate</dt><dd>${(metrics.successRate * 100).toFixed(1)}%</dd>
             </dl>`
           : `<div class="empty">No traces recorded in window.</div>`}
-      </section>
+      </details>
 
-      <section>
-        <h2>Recent fires (${recent_fires.length})</h2>
+      <details class="section collapsible">
+        <summary>Recent fires (${recent_fires.length})</summary>
         ${recent_fires.length === 0
           ? `<div class="empty">No fires recorded.</div>`
           : recent_fires.map((fire) => {
@@ -528,26 +530,26 @@ async function renderSkillDetail(name) {
                 ? `<span class="badge ok">ok</span>`
                 : `<span class="badge error">err</span>`;
               return `
-                <div style="border-bottom: 1px solid #e6e8eb; padding: 12px 0;">
+                <div style="border-bottom: 1px solid var(--border); padding: 12px 0;">
                   <div style="display: flex; align-items: center; gap: 12px;">
                     ${status}
-                    <code style="font-size: 11px; color: #6c757d;">${esc(fire.trace_id.slice(0, 8))}</code>
+                    <code style="font-size: 11px; color: var(--text-muted);">${esc(fire.trace_id.slice(0, 8))}</code>
                     <span>${ts}</span>
-                    <span style="color: #6c757d; margin-left: auto;">${fire.duration_ms}ms · ${fire.ops.length} ops</span>
+                    <span style="color: var(--text-muted); margin-left: auto;">${fire.duration_ms}ms · ${fire.ops.length} ops</span>
                   </div>
                   ${fire.errors.map((e) => `
                     <div class="remediation">
                       <strong>${esc(e.class)}</strong> in ${esc(e.target)}/${esc(e.opKind)}: ${esc(e.message)}
-                      ${e.remediation ? `<div style="margin-top: 4px; color: #4a5158;">→ ${esc(e.remediation)}</div>` : ""}
+                      ${e.remediation ? `<div style="margin-top: 4px; color: var(--text-dim);">→ ${esc(e.remediation)}</div>` : ""}
                     </div>
                   `).join("")}
                 </div>
               `;
             }).join("")}
-      </section>
+      </details>
 
-      <section>
-        <h2>Version history (${versions.length})</h2>
+      <details class="section collapsible">
+        <summary>Version history (${versions.length})</summary>
         <table>
           <thead><tr><th>Version</th><th>Status</th><th>Changed at</th></tr></thead>
           <tbody>
@@ -560,7 +562,7 @@ async function renderSkillDetail(name) {
             `).join("")}
           </tbody>
         </table>
-      </section>
+      </details>
     `;
   } catch (err) {
     return `<h2>Skill: ${esc(name)}</h2><section><div class="empty">Failed to load: ${esc(err.message)}</div></section>`;
@@ -710,6 +712,153 @@ function renderHighlightedSkillBody(source) {
   return body;
 }
 
+// ─── Control-flow "what it does" diagram ─────────────────────────────────
+// The orientation layer for a NON-PROGRAMMER approver: an SVG flowchart of the
+// skill's actual steps, built from skill_preflight's contract.flow (targets →
+// boxes, ops → step rows, loops/branches indented). Each target is a box; the
+// boxes stack top-to-bottom in dependency order, joined by arrows. It sits in
+// the always-open decision surface under "What this skill touches" — but it is
+// NOT the decision surface. A tidy diagram can still gloss a dangerous arg, so
+// the concrete effects (the footprint + Source) remain the artifact to approve;
+// this answers "what is it doing, in order?" for someone who can't read
+// skillscript. Steps that change data / run commands get a colored marker.
+function renderSkillFlow(flow) {
+  if (!flow || !Array.isArray(flow.lanes) || flow.lanes.length === 0) return ""; // body-only skill — nothing to diagram
+  return `
+    <section>
+      <h2>What it does, step by step</h2>
+      <p class="flow-caption">A diagram of the actual steps, top to bottom. A ● marks steps that <em>change data</em> or <em>run commands</em>. The exact effects to approve are in “What this skill touches” and the source below.</p>
+      <div class="flow-scroll">${flowSvg(flow)}</div>
+      ${flow.truncated ? `<p class="flow-caption">Large skill — showing the first 40 stages.</p>` : ""}
+    </section>
+  `;
+}
+
+// Flatten a lane's nested steps into flat rows with an indent depth, so the SVG
+// lays them out as simple text lines. Loop bodies and branch arms become deeper
+// rows under their heading.
+function flattenFlowRows(steps, depth, out) {
+  for (const s of steps) {
+    // A conditional: its "If …" / "Otherwise" arms are self-describing, so skip
+    // the redundant container heading and show the arms directly.
+    if (Array.isArray(s.branches)) {
+      for (const b of s.branches) {
+        out.push({ label: b.label, tone: "normal", depth, isBranch: true });
+        flattenFlowRows(b.steps, depth + 1, out);
+      }
+      continue;
+    }
+    out.push({ label: s.label, detail: s.detail, tone: s.tone, ref: s.ref, produces: s.produces, depth });
+    // A loop keeps its "For each …" heading, with the body indented under it.
+    if (Array.isArray(s.children)) flattenFlowRows(s.children, depth + 1, out);
+  }
+  return out;
+}
+
+function truncate(s, max) {
+  if (max < 2) return "";
+  return s.length <= max ? s : s.slice(0, max - 1) + "…";
+}
+
+function flowSvg(flow) {
+  const BOX_W = 340, ROW_H = 22, TITLE_H = 30, PAD_Y = 10, GAP_X = 30, GAP_Y = 46, MARGIN = 10, INDENT = 14, CHAR_W = 6.6;
+
+  const byId = new Map();
+  const boxes = flow.lanes.map((lane) => {
+    const rows = flattenFlowRows(lane.steps, 0, []);
+    const h = TITLE_H + Math.max(rows.length, 1) * ROW_H + PAD_Y;
+    const box = { lane, rows, h };
+    byId.set(lane.id, box);
+    return box;
+  });
+
+  // Longest-path layering: a target's dependencies sit in the layer above it, so
+  // reading top-to-bottom follows execution order (deps run first). Siblings (a
+  // shared dependency's dependents) land in the same layer, side by side — the
+  // real branch/merge shape rather than a fake vertical chain.
+  const layer = new Map(boxes.map((b) => [b.lane.id, 0]));
+  for (let it = 0; it < boxes.length; it++) {
+    let changed = false;
+    for (const b of boxes) {
+      let mx = 0;
+      for (const d of b.lane.deps || []) if (byId.has(d)) mx = Math.max(mx, layer.get(d) + 1);
+      if (mx !== layer.get(b.lane.id)) { layer.set(b.lane.id, mx); changed = true; }
+    }
+    if (!changed) break;
+  }
+  const maxLayer = Math.max(0, ...boxes.map((b) => layer.get(b.lane.id)));
+  const byLayer = Array.from({ length: maxLayer + 1 }, () => []);
+  boxes.forEach((b) => byLayer[layer.get(b.lane.id)].push(b));
+  const layerW = byLayer.map((ls) => (ls.length ? ls.length * BOX_W + (ls.length - 1) * GAP_X : 0));
+  const maxLayerW = Math.max(0, ...layerW);
+
+  const pos = new Map();
+  let ly = MARGIN;
+  byLayer.forEach((ls, L) => {
+    const startX = MARGIN + (maxLayerW - layerW[L]) / 2;
+    ls.forEach((b, i) => pos.set(b.lane.id, { x: startX + i * (BOX_W + GAP_X), y: ly }));
+    ly += Math.max(0, ...ls.map((b) => b.h)) + GAP_Y;
+  });
+  const totalW = maxLayerW + MARGIN * 2;
+  const totalH = ly - GAP_Y + MARGIN;
+
+  // Arrows point from a dependency (above) down into the step that needs it.
+  const arrows = boxes.flatMap((b) => {
+    const p = pos.get(b.lane.id);
+    return (b.lane.deps || []).map((d) => {
+      const pd = pos.get(d);
+      if (!pd) return "";
+      const x1 = pd.x + BOX_W / 2, y1 = pd.y + byId.get(d).h;
+      const x2 = p.x + BOX_W / 2, y2 = p.y;
+      const my = (y1 + y2) / 2;
+      return `<path class="flow-arrow" d="M ${x1} ${y1} C ${x1} ${my}, ${x2} ${my}, ${x2} ${y2}" marker-end="url(#flow-arrowhead)"/>`;
+    });
+  });
+
+  // The entry/default target is what runs when you invoke the skill — always
+  // flag it so it's never ambiguous which box is the one. When it has
+  // dependencies it runs LAST (everything feeds it), so it's the "result";
+  // when it has none it's simply the "default" (single-target skills).
+  const boxSvg = boxes.map((b) => {
+    const p = pos.get(b.lane.id);
+    const { lane } = b;
+    const entryWord = lane.deps && lane.deps.length ? "result" : "default";
+    const badge = lane.isEntry ? `<tspan class="flow-box-badge"> · ${entryWord}</tspan>` : "";
+    const tip = lane.isEntry ? `<title>The target that runs when you invoke this skill${lane.deps && lane.deps.length ? " — after the steps it depends on" : ""}.</title>` : "";
+    let g = `<g class="flow-box${lane.isEntry ? " flow-box-entry" : ""}">
+      ${tip}<rect x="${p.x}" y="${p.y}" width="${BOX_W}" height="${b.h}" rx="8"/>
+      <line class="flow-box-rule" x1="${p.x}" y1="${p.y + TITLE_H}" x2="${p.x + BOX_W}" y2="${p.y + TITLE_H}"/>
+      <text class="flow-box-title" x="${p.x + 12}" y="${p.y + 20}">${esc(lane.id)}${badge}</text>`;
+    (b.rows.length ? b.rows : [{ label: "Nothing to do.", tone: "normal", depth: 0 }]).forEach((r, ri) => {
+      const rowY = p.y + TITLE_H + ri * ROW_H + 16;
+      const dot = (r.tone === "mutation" || r.tone === "shell")
+        ? `<tspan class="flow-dot flow-dot-${r.tone}">● </tspan>` : "";
+      const rowX = p.x + 14 + r.depth * INDENT;
+      const producesTxt = r.produces ? ` → ${r.produces}` : "";
+      // Budget the main text in PIXELS, reserving room for the ● marker and the
+      // monospace "→ VAR" so nothing overruns the box's right border. CHAR_W is
+      // deliberately generous (chars render narrower) so we under-fill rather
+      // than let the border bisect the text.
+      const reservedPx = 18 + (dot ? 13 : 0) + producesTxt.length * 6.8;
+      const budget = Math.max(6, Math.floor((BOX_W - (rowX - p.x) - reservedPx) / CHAR_W));
+      const text = truncate(r.label + (r.detail ? " — " + r.detail : ""), budget);
+      const cls = "flow-row" + (r.isBranch ? " flow-row-branch" : "");
+      const produces = r.produces ? `<tspan class="flow-produces">${esc(producesTxt)}</tspan>` : "";
+      const rowSvg = `<text class="${cls}" x="${rowX}" y="${rowY}">${dot}${esc(text)}${produces}</text>`;
+      g += r.ref && r.ref.skill
+        ? `<a href="#skill/${encodeURIComponent(r.ref.skill)}" class="flow-row-link">${rowSvg}</a>`
+        : rowSvg;
+    });
+    return g + `</g>`;
+  });
+
+  return `<svg class="flow-svg" viewBox="0 0 ${totalW} ${totalH}" width="${totalW}" height="${totalH}" role="img" aria-label="Skill step diagram">
+      <defs><marker id="flow-arrowhead" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto">
+        <path class="flow-arrowhead-path" d="M0 0 L10 5 L0 10 z"/></marker></defs>
+      ${arrows.join("")}${boxSvg.join("")}
+    </svg>`;
+}
+
 // v0.18.9 — security signals summary panel. Glance-first surface
 // showing aggregated counts so a reviewer knows WHAT to look for before
 // scanning the body. Pairs with renderHighlightedSkillBody() (the
@@ -1056,8 +1205,12 @@ function extractCompositionRefs(source) {
 
 function renderComposesSection(currentName, source) {
   const refs = extractCompositionRefs(source);
+  // Conditional decision-surface section: a composed child is part of the blast
+  // radius, so when present it renders as an open section. When the skill
+  // composes nothing there's nothing approval-relevant to show — hide it
+  // entirely rather than spend a section on an empty state.
   if (refs.length === 0) {
-    return `<section><h2>Composes</h2><div class="empty">This skill doesn't compose other skills (no <code>execute_skill</code> or <code>inline</code> refs).</div></section>`;
+    return "";
   }
   return `
     <section>
@@ -1065,12 +1218,12 @@ function renderComposesSection(currentName, source) {
       <div style="display: flex; flex-direction: column; gap: 6px;">
         ${refs.map((r) => `
           <details data-compose-ref="${esc(r.kind)}:${esc(r.name)}" data-parent="${esc(currentName)}">
-            <summary style="cursor: pointer; padding: 8px 12px; background: #f6f8fa; border-radius: 4px; font-family: monospace;">
+            <summary style="cursor: pointer; padding: 8px 12px; background: var(--surface-2); border-radius: 4px; font-family: monospace;">
               <span class="badge ${r.kind === "execute_skill" ? "ok" : "info"}" style="margin-right: 8px;">${esc(r.kind)}</span>
               <strong>${esc(r.name)}</strong>
-              <span style="color: #6c757d; margin-left: 8px; font-size: 0.85em;">${r.kind === "execute_skill" ? "(runtime invocation)" : "(compile-time data inline)"}</span>
+              <span style="color: var(--text-muted); margin-left: 8px; font-size: 0.85em;">${r.kind === "execute_skill" ? "(runtime invocation)" : "(compile-time data inline)"}</span>
             </summary>
-            <div class="compose-panel" style="padding: 12px 16px; border-left: 2px solid #e6e8eb; margin-left: 12px; margin-top: 8px;">
+            <div class="compose-panel" style="padding: 12px 16px; border-left: 2px solid var(--border); margin-left: 12px; margin-top: 8px;">
               <div class="empty">Loading contract…</div>
             </div>
           </details>
@@ -1115,10 +1268,10 @@ function renderContractPanel(name, kind, meta, inlinedBody) {
   const returns = Array.isArray(meta.returns) && meta.returns.length > 0
     ? `<dl class="kv"><dt>Returns (<code># Returns:</code>)</dt><dd>${meta.returns.map((r) => `<code>${esc(r)}</code>`).join(", ")}</dd></dl>`
     : `<dl class="kv"><dt>Returns</dt><dd><span class="empty">(no declared <code># Returns:</code> — caller sees <code>outputs</code> + <code>transcript</code> only)</span></dd></dl>`;
-  const authorBadge = meta.author ? ` <span style="color: #6c757d; font-size: 0.85em;">by ${esc(meta.author)}</span>` : "";
+  const authorBadge = meta.author ? ` <span style="color: var(--text-muted); font-size: 0.85em;">by ${esc(meta.author)}</span>` : "";
   const drillLink = `<a href="#skill/${encodeURIComponent(name)}" style="font-size: 0.85em;">Open in detail view →</a>`;
   const inlineBodyBlock = inlinedBody !== null
-    ? `<details style="margin-top: 12px;"><summary style="cursor: pointer; color: #6c757d; font-size: 0.85em;">Inlined body (bakes at compile)</summary><pre style="margin-top: 8px; font-size: 12px;">${esc(inlinedBody)}</pre></details>`
+    ? `<details style="margin-top: 12px;"><summary style="cursor: pointer; color: var(--text-muted); font-size: 0.85em;">Inlined body (bakes at compile)</summary><pre style="margin-top: 8px; font-size: 12px;">${esc(inlinedBody)}</pre></details>`
     : "";
   return `
     <div style="font-size: 0.95em;">
@@ -1153,18 +1306,30 @@ async function renderCurrentView() {
     link.classList.toggle("active", link.getAttribute("href") === `#${hash}`);
   }
 
+  // Preserve scroll across a same-view re-render (the 30s poll) — and skip the
+  // "Loading…" flash in that case. On navigation to a different view, let scroll
+  // reset to the top as usual.
+  const newView = hash.startsWith("skill/")
+    ? `skill/${decodeURIComponent(hash.slice("skill/".length))}`
+    : hash;
+  const sameView = newView === currentView;
+  const scrollY = window.scrollY;
+  const restore = () => { if (sameView) window.scrollTo(0, scrollY); };
+
   if (hash.startsWith("skill/")) {
     const name = decodeURIComponent(hash.slice("skill/".length));
     currentView = `skill/${name}`;
-    main.innerHTML = "Loading…";
+    if (!sameView) main.innerHTML = "Loading…";
     main.innerHTML = await renderSkillDetail(name);
+    restore();
     return;
   }
 
   currentView = hash;
   if (hash === "approvals") {
-    main.innerHTML = "Loading…";
+    if (!sameView) main.innerHTML = "Loading…";
     main.innerHTML = await renderApprovals();
+    restore();
     return;
   }
   switch (hash) {
@@ -1175,13 +1340,34 @@ async function renderCurrentView() {
     case "security":   main.innerHTML = renderSecurity(); break;
     default: main.innerHTML = `<section><div class="empty">Unknown view: ${esc(hash)}</div></section>`;
   }
+  restore();
 }
 
 window.addEventListener("hashchange", renderCurrentView);
 window.addEventListener("DOMContentLoaded", () => {
+  initThemeToggle();
   startPolling();
 });
 
+// Dark/light toggle. The initial theme is set before paint by the inline script
+// in index.html; this wires the header button to flip + persist it.
+function initThemeToggle() {
+  const btn = document.getElementById("theme-toggle");
+  if (!btn) return;
+  const paint = (theme) => {
+    document.documentElement.setAttribute("data-theme", theme);
+    btn.textContent = theme === "dark" ? "☀" : "☾";
+    btn.setAttribute("aria-label", theme === "dark" ? "Switch to light mode" : "Switch to dark mode");
+    btn.setAttribute("title", theme === "dark" ? "Switch to light mode" : "Switch to dark mode");
+  };
+  paint(document.documentElement.getAttribute("data-theme") === "dark" ? "dark" : "light");
+  btn.addEventListener("click", () => {
+    const next = document.documentElement.getAttribute("data-theme") === "dark" ? "light" : "dark";
+    try { localStorage.setItem("skillscript-theme", next); } catch (e) { /* private mode */ }
+    paint(next);
+  });
+}
+
 // ─── Utils ──────────────────────────────────────────────────────────────────
 
 function esc(s) {

package/dist/dashboard/spa/index.html

@@ -5,6 +5,21 @@
     <meta name="viewport" content="width=device-width,initial-scale=1" />
     <title>skillscript-runtime · dashboard</title>
     <link rel="stylesheet" href="/styles.css" />
+    <script>
+      // Set the theme before first paint (no flash). Stored preference wins;
+      // otherwise follow the OS setting. The header toggle updates the same key.
+      (function () {
+        try {
+          var t = localStorage.getItem("skillscript-theme");
+          if (t !== "light" && t !== "dark") {
+            t = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+          }
+          document.documentElement.setAttribute("data-theme", t);
+        } catch (e) {
+          document.documentElement.setAttribute("data-theme", "light");
+        }
+      })();
+    </script>
   </head>
   <body>
     <header>
@@ -18,6 +33,7 @@
         <a href="#security">Security</a>
       </nav>
       <div id="poll-status" aria-live="polite"></div>
+      <button id="theme-toggle" class="theme-toggle" type="button" aria-label="Toggle dark mode" title="Toggle dark mode"></button>
     </header>
     <div id="secured-banner"></div>
     <main id="main"></main>