@intentius/behold 0.8.0 → 0.9.0

package/web/app.js

@@ -9,11 +9,40 @@
 // position), and the theme picker into the panel's View-tab slot (a stable element
 // renderPanelView never rewrites, so the select mounts once and survives re-renders).
 import { initTheme, mountThemePicker, readableOn, colorForCategory, onThemeChange, getTokens } from "./theme.js";
-import { initPanel, setPanelTab, togglePanelCollapsed, isPanelCollapsed } from "./panel.js";
+import { addPanelTab, initPanel, setPanelTab, togglePanelCollapsed, isPanelCollapsed } from "./panel.js";
+// #254: the carve walkthrough's stepper — everything it DECIDES is a pure
+// function in there; this file owns the fetches, the graph selection, and the
+// "carved" marker the last step leaves on a card.
+import { CARVE_STEPS, blockedReason, initialCarveState, renderCarvePanel } from "./carve-steps.js";
 // #228: the hand-layout delta store — everything about WHAT gets remembered and
 // under which key. The pointer work and the SVG surgery stay here (see the
 // "Hand layout" section below).
-import { applicable, clearLayout, isEmpty, layoutKey, lensKeyOf, projectKeyOf, readLayout, setDelta, writeLayout } from "./layout-store.js";
+import {
+  applicable,
+  clampDelta,
+  clearLayout,
+  debounce,
+  fetchServerLayout,
+  isEmpty,
+  layoutKey,
+  lensKeyOf,
+  mergeLayouts,
+  nodeTransform,
+  pathAnchors,
+  postServerLayout,
+  projectKeyOf,
+  readLayout,
+  setDelta,
+  straightEdge,
+  writeLayout,
+} from "./layout-store.js";
+// #259: every JSON value this page shows goes through one renderer — pretty
+// printed, collapsible, copyable per subtree. `valueCell`/`pairCell` below are
+// the call-site shorthands: a container becomes the tree, a scalar stays text.
+import { isContainer, jsonCell, renderJson, scalarText } from "./json-view.js";
+// #268: the demo catalog's presentation — what a catalog row's button says
+// about it (disabled + reason, or the fetch it would do).
+import { fetchDemos, demoLabel, demoTitle, demoProgress } from "./demos.js";
 initTheme();
 initPanel();
 mountThemePicker(document.getElementById("panel-theme"));
@@ -163,12 +192,68 @@ const ARTIFACT_STATUS_LABEL = { good: "installed", warn: "installed, not healthy
 // A declared attribute value may be a cross-resource reference ({$ref:"x.y"}) —
 // the "static infra refs" — rather than a concrete value. Render those readably;
 // concrete values (present once a resource is provisioned) show as-is.
+// #259: everything else that isn't a scalar becomes the collapsible tree rather
+// than a flat one-line JSON.stringify — a declared `spec` used to wrap six times
+// and say nothing about its shape.
 function fmtValue(v) {
-  if (v && typeof v === "object") {
-    if (typeof v.$ref === "string") return "→ " + v.$ref;
-    return JSON.stringify(v);
+  if (v && typeof v === "object" && typeof v.$ref === "string") return "→ " + v.$ref;
+  return valueCell(v);
+}
+
+/**
+ * A `<dd>` body for one value: an object or an array becomes the collapsible
+ * tree, a scalar keeps the pane's plain voice — `deploy/api`, not
+ * `"deploy/api"`. Quoting is JSON's punctuation and belongs inside a tree, not
+ * beside a label, so this is NOT json-view's own `jsonCell` (which quotes; the
+ * value PAIRS below want that, since they always did).
+ */
+function valueCell(v) {
+  return isContainer(v) ? renderJson(v) : String(v);
+}
+
+/** Put a value into a `<dd>`: a rendered JSON tree is appended, a scalar's text
+ * is set. Every `add`/`section` setter in this pane funnels through here (#259). */
+function setCell(dd, v) {
+  if (v instanceof Node) dd.appendChild(v);
+  else dd.textContent = v;
+}
+
+/**
+ * The pane shows values in PAIRS as often as alone — old → new (drift),
+ * declared · live (field ownership), baseline · live (accepted deviation).
+ * Two scalars keep the one-line form the pane always had. If either side is an
+ * object or an array it becomes a collapsible tree, and an arrow wedged between
+ * two trees reads as neither — so the pair stacks into labelled rows instead
+ * (#259). `lead` is the sentence that precedes a field-drift pair ("owned by
+ * hpa-controller — drifted"); it keeps its own line in the stacked form.
+ * Returns a Node or a string, for setCell.
+ */
+function pairCell(aLabel, a, bLabel, b, opts = {}) {
+  const { lead = "", arrow = false } = opts;
+  if (!isContainer(a) && !isContainer(b)) {
+    const one = arrow ? `${scalarText(a)} → ${scalarText(b)}` : `${aLabel}: ${scalarText(a)} · ${bLabel}: ${scalarText(b)}`;
+    return lead ? `${lead} — ${one}` : one;
   }
-  return String(v);
+  const wrap = document.createElement("div");
+  if (lead) {
+    const p = document.createElement("div");
+    p.textContent = lead;
+    wrap.appendChild(p);
+  }
+  for (const [label, v] of [
+    [aLabel, a],
+    [bLabel, b],
+  ]) {
+    const row = document.createElement("div");
+    row.className = "pair-row";
+    const tag = document.createElement("span");
+    tag.className = "pair-label";
+    tag.textContent = label;
+    row.appendChild(tag);
+    setCell(row, jsonCell(v));
+    wrap.appendChild(row);
+  }
+  return wrap;
 }
 
 function inspect(node) {
@@ -185,7 +270,7 @@ function inspect(node) {
       const dt = document.createElement("dt");
       dt.textContent = k;
       const dd = document.createElement("dd");
-      dd.textContent = v;
+      setCell(dd, v);
       dl.append(dt, dd);
     };
   };
@@ -433,7 +518,7 @@ function renderObserved(panel, o, health, healthDetail) {
     const dt = document.createElement("dt");
     dt.textContent = k;
     const dd = document.createElement("dd");
-    dd.textContent = v;
+    setCell(dd, v);
     if (color) dd.style.color = color;
     dl.append(dt, dd);
   };
@@ -461,11 +546,16 @@ function renderObserved(panel, o, health, healthDetail) {
   // none.
   const conditions = o.attributes?.conditions;
   if (Array.isArray(conditions)) {
-    for (const c of conditions) add("condition", String(c), "var(--degraded)");
+    // Usually chant sends these pre-rendered as sentences; a substrate that
+    // sends the raw condition object gets the tree instead of `[object Object]`.
+    for (const c of conditions) add("condition", valueCell(c), "var(--degraded)");
   }
+  // #259: an observed attribute is whatever the substrate reported — a k8s
+  // `spec`, a nested `loadBalancer`, an array of ports. All of it collapsible
+  // now, instead of one flat JSON.stringify line per key.
   for (const [k, v] of Object.entries(o.attributes || {})) {
     if (k === "conditions") continue; // rendered above, one line each
-    add(k, typeof v === "object" ? JSON.stringify(v) : String(v));
+    add(k, valueCell(v));
   }
   panel.appendChild(dl);
 }
@@ -549,7 +639,9 @@ function renderDiff(panel, diff) {
     const dt = document.createElement("dt");
     dt.textContent = ch.path;
     const dd = document.createElement("dd");
-    dd.textContent = `${JSON.stringify(ch.oldValue)} → ${JSON.stringify(ch.newValue)}`;
+    // #259: a drifted `spec` used to be two flat JSON blobs either side of an
+    // arrow; now each side is its own collapsible tree with its own copy.
+    setCell(dd, pairCell("was", ch.oldValue, "now", ch.newValue, { arrow: true }));
     dl.append(dt, dd);
   }
   panel.appendChild(dl);
@@ -592,7 +684,7 @@ function renderFieldDrift(panel, fieldDrift) {
     // holding it is somebody editing around the pipeline. Both are `changed`.
     // Absent on every substrate but k8s, where the line reads as it always did.
     const owned = ch.owner ? `owned by ${ch.owner} — ` : "";
-    dd.textContent = `${owned}${FIELD_KIND_LABEL[ch.kind] || ch.kind} — declared: ${JSON.stringify(ch.declared)} · live: ${JSON.stringify(ch.live)}`;
+    setCell(dd, pairCell("declared", ch.declared, "live", ch.live, { lead: `${owned}${FIELD_KIND_LABEL[ch.kind] || ch.kind}` }));
     dl.append(dt, dd);
   }
   for (const ch of fieldDrift.accepted) {
@@ -600,7 +692,7 @@ function renderFieldDrift(panel, fieldDrift) {
     dt.textContent = ch.path;
     dt.style.color = "var(--muted)";
     const dd = document.createElement("dd");
-    dd.textContent = `accepted deviation — baseline: ${JSON.stringify(ch.baseline)} · live: ${JSON.stringify(ch.live)}`;
+    setCell(dd, pairCell("baseline", ch.baseline, "live", ch.live, { lead: "accepted deviation" }));
     dl.append(dt, dd);
   }
   panel.appendChild(dl);
@@ -618,6 +710,10 @@ function wire(ir) {
       host.querySelectorAll(".sel").forEach((n) => n.classList.remove("sel"));
       g.classList.add("sel");
       inspect(node);
+      // #254: in carve mode a click is also the walkthrough's Pick step — the
+      // inspect pane already shows the score arithmetic the lens spelled out,
+      // and the stepper picks up the same node.
+      carvePick(node);
     });
   }
 }
@@ -807,26 +903,54 @@ async function revealProject(dir) {
 // client-side list and cache is project-scoped, so a clean boot is the honest
 // way to re-seed all of it.
 async function switchProject(dir) {
-  showLoading(`switching to ${pathBasename(dir)}…`);
+  return postSwitch("/api/project/open", { dir }, `switching to ${pathBasename(dir)}…`, "switch");
+}
+
+// #268: load a bundled demo and serve it. Same treatment as a project switch —
+// it IS one, after a copy/clone + install the server runs on the click. The
+// body carries the catalog NAME; the server never takes a path here.
+async function openDemo(demo) {
+  if (!demo.satisfiable) return;
+  return postSwitch("/api/demos/open", { name: demo.name }, demoProgress(demo), "demo");
+}
+
+// The switch itself: a JSON POST behind the loading scrim, then a reload on
+// success. Shared by the recents/path switch and the demo catalog above.
+async function postSwitch(url, body, message, what) {
+  showLoading(message);
   try {
-    const r = await fetch("/api/project/open", {
+    const r = await fetch(url, {
       method: "POST",
       headers: { "content-type": "application/json" },
-      body: JSON.stringify({ dir }),
+      body: JSON.stringify(body),
     });
     const j = await r.json();
     if (!r.ok || j.error) {
       hideLoading();
-      showToast("✗ switch: " + (j.error || r.statusText), false);
+      showToast(`✗ ${what}: ` + (j.error || r.statusText), false);
       return;
     }
     location.reload();
   } catch (e) {
     hideLoading();
-    showToast("✗ switch: " + e.message, false);
+    showToast(`✗ ${what}: ` + e.message, false);
   }
 }
 
+// #268: the bundled catalog, fetched once per page. `null` until it lands (the
+// first Scope render kicks it off and re-renders when it does), then a list —
+// empty on a server that doesn't serve the route, which renders no group.
+let demoCatalog = null;
+let demoCatalogPending = false;
+function primeDemoCatalog() {
+  if (demoCatalogPending) return;
+  demoCatalogPending = true;
+  fetchDemos().then((demos) => {
+    demoCatalog = demos;
+    renderPanelScope();
+  });
+}
+
 function renderPanelScope() {
   const host = document.getElementById("tab-scope");
   if (!host) return;
@@ -876,6 +1000,19 @@ function renderPanelScope() {
     });
     row.append(input, go);
     host.appendChild(row);
+    // #268: the bundled demo catalog, under recents — every demo `behold demo
+    // --list` names, one click from wherever you are. An entry whose
+    // prerequisites are missing renders disabled with the reason on it, and one
+    // that would clone from the network says so before it runs.
+    if (demoCatalog === null) primeDemoCatalog();
+    else if (demoCatalog.length) {
+      host.appendChild(panelHeading("demos"));
+      for (const d of demoCatalog) {
+        const b = panelOpt(demoLabel(d), false, () => openDemo(d), demoTitle(d));
+        if (!d.satisfiable || d.switchable === false) b.disabled = true;
+        host.appendChild(b);
+      }
+    }
   }
   host.appendChild(panelHeading("environment"));
   host.appendChild(
@@ -979,6 +1116,7 @@ function selectNode(id) {
   const g = host.querySelector(`[data-node-id="${CSS.escape(id)}"]`);
   if (g) g.classList.add("sel");
   inspect(node);
+  carvePick(node);
 }
 
 function renderPanelModel() {
@@ -1044,10 +1182,199 @@ function renderPanelModel() {
   }
 }
 
+// ---------------------------------------------------------------------------
+// The carve walkthrough (#254, M1.5 of #230)
+//
+// A Carve tab appears only when /api/project says this server is in carve mode,
+// and its two ACTION steps light up only when it also says a demo copy is
+// behind it (`carve.demo.runnable`) — a plain `behold carve report.json` gets
+// the same six steps with the runs honestly greyed out, rather than buttons
+// that 403.
+//
+// The walkthrough's state lives here and nowhere else: no session on the
+// server, exactly as #254 asks. Reload and you're back at Advise, with whatever
+// the previous run wrote still sitting in the demo copy.
+// ---------------------------------------------------------------------------
+let carveInfo = null; // /api/project's `carve` block (report meta + demo, or null)
+let carveReport = null; // the raw report off /api/carve — the boundary lists live here
+let carveState = initialCarveState();
+let carveHost = null; // the panel section, mounted on first sight of carve mode
+const carvedIds = new Set(); // addresses the walkthrough has taken all the way through
+
+function carveMode() {
+  return !!carveInfo;
+}
+
+/** The stepper's wiring. Everything that talks to the network or the graph. */
+const carveActions = {
+  go(index) {
+    const id = CARVE_STEPS[index] && CARVE_STEPS[index].id;
+    if (!id) return;
+    if (blockedReason(carveState, id)) return;
+    carveState.step = index;
+    carveState.error = null;
+    renderPanelCarve();
+  },
+  select(address) {
+    selectNode(address); // the same path a graph click takes — inspect included
+  },
+  reset() {
+    carveState = initialCarveState();
+    renderPanelCarve();
+  },
+  markHandoff() {
+    carveState.handoff = true;
+    if (carveState.pick) {
+      carvedIds.add(carveState.pick.node.id);
+      markCarvedCards();
+    }
+    carveState.step = CARVE_STEPS.findIndex((s) => s.id === "done");
+    renderPanelCarve();
+  },
+  runEmit: () => runCarveStep("emit"),
+  runBridge: () => runCarveStep("bridge"),
+  copy(text, el) {
+    const done = () => {
+      el.dataset.copied = "1";
+      const was = el.textContent;
+      el.textContent = "copied ✓";
+      setTimeout(() => {
+        el.textContent = was;
+      }, 1200);
+    };
+    if (navigator.clipboard && navigator.clipboard.writeText) navigator.clipboard.writeText(text).then(done, done);
+    else done();
+  },
+};
+
+/** Run one of the two safe steps. Both are POSTs with a `{select}` body; both
+ * answer either their result or #193's `{error, code, remedy}`. */
+async function runCarveStep(which) {
+  if (carveState.busy || !carveState.pick) return;
+  carveState.busy = which;
+  carveState.error = null;
+  renderPanelCarve();
+  try {
+    const res = await fetch(`/api/carve/${which}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ select: carveState.pick.node.id }),
+    });
+    const body = await res.json().catch(() => ({ error: `${which} returned an unreadable body`, remedy: "" }));
+    if (!res.ok || body.error) {
+      carveState.error = { step: which, ...body };
+      showToast(`✗ carve ${which}: ${body.error || res.status}`, false);
+    } else {
+      carveState[which] = body;
+      // Deliberately does NOT advance. The result IS the step — the emitted
+      // source and the lint verdict, the proposed patch — and skipping past it
+      // to the next button would hide the thing the run was for. The "next"
+      // control unlocks; pressing it stays the viewer's move.
+      showToast(`✓ carve ${which} — wrote into ${(carveInfo.demo && carveInfo.demo.outLabel) || "the demo copy"}`, true);
+    }
+  } catch (err) {
+    carveState.error = { step: which, error: String((err && err.message) || err), remedy: "Is the behold server still running?" };
+  } finally {
+    carveState.busy = null;
+    renderPanelCarve();
+  }
+}
+
+/** A picked card becomes the walkthrough's subject. Called from the graph's
+ * click handler and from selectNode(), so the panel rows and the cards agree. */
+function carvePick(node) {
+  if (!carveMode()) return;
+  const resource = (carveReport && carveReport.resources ? carveReport.resources : []).find((r) => r.address === node.id) || null;
+  const pickStep = CARVE_STEPS.findIndex((s) => s.id === "pick");
+  // A NEW pick invalidates the runs that were about the old one — showing one
+  // resource's emitted source under another's name is the one way this panel
+  // could actively lie — and drops the walkthrough back to Pick, wherever it
+  // had got to. Re-clicking the SAME card is just a re-select and moves
+  // nothing, so reading a card mid-walkthrough costs no progress.
+  if (!carveState.pick || carveState.pick.node.id !== node.id) {
+    carveState.emit = null;
+    carveState.bridge = null;
+    carveState.handoff = false;
+    carveState.error = null;
+    carveState.step = pickStep;
+  } else if (carveState.step < pickStep) {
+    carveState.step = pickStep;
+  }
+  carveState.pick = { node, resource };
+  renderPanelCarve();
+}
+
+/** The "carved" marker the last step leaves on the card — a class the CSS
+ * paints plus a small label. Re-applied after every render, because the SVG is
+ * replaced wholesale on each load. The full morph (the box sliding out of the
+ * Terraform boundary and into the chant project beside last month's carves) is
+ * the follow-up; this is the honest still frame of it. */
+function markCarvedCards() {
+  const svg = document.querySelector("#graph svg");
+  if (!svg || !carvedIds.size) return;
+  for (const g of svg.querySelectorAll("[data-node-id]")) {
+    const id = g.getAttribute("data-node-id");
+    if (!carvedIds.has(id) || g.querySelector('[data-carved="1"]')) continue;
+    g.classList.add("carved");
+    // Measured, not read off attributes: pinhole sizes the card from its
+    // content and doesn't always stamp width/height, and a missing attribute
+    // read as 0 parks the label at the group's origin — which is off the card
+    // entirely (seen in the browser before this was measured instead).
+    const rect = g.querySelector("rect");
+    const box = rect && rect.getBBox ? rect.getBBox() : null;
+    const tag = document.createElementNS("http://www.w3.org/2000/svg", "text");
+    tag.setAttribute("data-carved", "1");
+    // Inside the card's own box, bottom-right — the one corner the terraform
+    // presentation pack leaves empty.
+    tag.setAttribute("x", String((box ? box.x + box.width : 150) - 10));
+    tag.setAttribute("y", String((box ? box.y + box.height : 60) - 9));
+    tag.setAttribute("text-anchor", "end");
+    tag.setAttribute("font-size", "11");
+    tag.setAttribute("font-weight", "600");
+    tag.setAttribute("fill", "var(--managed)");
+    tag.textContent = "✓ carved → chant";
+    g.appendChild(tag);
+  }
+}
+
+function renderPanelCarve() {
+  if (!carveMode()) return;
+  if (!carveHost) {
+    carveHost = addPanelTab("carve", "Carve", "The peel walkthrough: advise → pick → emit → bridge → handoff → done.");
+    if (!carveHost) return;
+    carveHost.id = "tab-carve";
+  }
+  renderCarvePanel(
+    carveHost,
+    carveState,
+    { carve: carveInfo, demo: carveInfo && carveInfo.demo, report: carveReport, renderJson },
+    carveActions,
+  );
+}
+
+/** Carve mode's one extra fetch: the raw report, for the per-resource boundary
+ * lists the graph IR deliberately doesn't carry. Best-effort — the stepper
+ * degrades to the counts in the IR's own attrs. */
+async function loadCarveReport() {
+  if (!carveMode()) return;
+  try {
+    carveReport = await apiFetch("/api/carve").then((r) => r.json());
+  } catch {
+    carveReport = null;
+  }
+  renderPanelCarve();
+  // A readiness marker, so a test can wait for the extra fetch instead of
+  // racing it. The panel itself never waits: `cutSummary` falls back to the
+  // counts the IR node already carries, which is what the report would have
+  // told it anyway on a chant that publishes no edge lists.
+  if (carveHost) carveHost.dataset.report = carveReport ? "1" : "0";
+}
+
 function renderPanel() {
   renderPanelView();
   renderPanelScope();
   renderPanelModel();
+  if (carveMode()) renderPanelCarve();
 }
 
 function renderStatusbar() {
@@ -1716,6 +2043,7 @@ function render(ir, svg, m) {
   ensureBackToInfra(g);
   wire(ir);
   if (view.radial && !view.components && !view.logical) addRadialLabels(ir);
+  markCarvedCards(); // #254: the SVG is replaced per render — re-stamp the marker
   applyLayout(); // #228: last, so the hand-placed deltas ride on top of every other pass
   renderDial();
 }
@@ -1916,6 +2244,14 @@ function ensureZoomControls(host) {
 // the end of every render(), so the graph underneath stays chant's and a
 // delta for a node that left the estate is simply not applied.
 //
+// Two tiers now (#228's second half): localStorage, and the project's own
+// `.behold/layout.json` behind GET/POST /api/layout. On load the server's map
+// merges UNDER the local one (`mergeLayouts` — the drag you can see always
+// wins); on a finished gesture the current lens is POSTed, debounced. A server
+// that refuses — a static export, preview mode, a read-only project, an older
+// behold with no such route — leaves the localStorage tier working exactly as
+// it did before, and says nothing.
+//
 // What this does NOT do, said plainly rather than faked:
 //   * a resized box does not reflow its children — that is dagre's job on the
 //     next layout, and the reset control's tooltip says so;
@@ -1923,51 +2259,86 @@ function ensureZoomControls(host) {
 //     its original anchor points, each shifted by its own node's delta. #228
 //     accepts the straight-line fallback; spline re-routing is pinhole's job.
 //     An edge with both ends where dagre put them keeps its bezier untouched.
-//   * nothing is written to the server. The second tier of #228 (a
-//     `.behold/layout.json` sidecar behind POST /api/layout, so a server-side
-//     export honours the same deltas) is the follow-up half.
+//     Everything anchored TO that edge rides with it (#267): both paths in the
+//     group — the visible line and pinhole's fat transparent hit-path — and the
+//     `viaAttr` chip, which lands on the new midpoint (see edgeLabelOf).
+//     A box's title needs nothing: pinhole paints it at the rect's top-left
+//     corner, which is the one corner a resize never moves, and a box move
+//     translates the whole wrapper group the title is already inside.
+//   * the server bakes {dx,dy} into an exported SVG but not a box's {dw,dh} —
+//     only pinhole's ARCHITECTURE boxes carry an id to bake against, and a bake
+//     that worked on some lenses and not others would be worse than none
+//     (src/layout.ts says the same at more length).
 let layoutIndex = null; // {nodes,boxes,edges} for the SVG currently on screen
 let layoutDeltas = {}; // the deltas in force for the current key
 let layoutDrag = null; // the gesture in flight
 let layoutWired = false;
+// The sidecar tier, cached per lens: one GET when a lens is first shown, not
+// one per render (render() runs on every SSE nudge and every settle poll).
+let layoutServer = { lens: null, deltas: {}, writable: false };
 
 /** The storage key for the project + lens on screen; null before /api/project lands. */
 function currentLayoutKey() {
   if (!projectInfo) return null;
-  return layoutKey(projectKeyOf(projectInfo), lensKeyOf({ zoom: zoomValue(), radial: view.radial, stack: view.stack }));
+  return layoutKey(projectKeyOf(projectInfo), currentLensKey());
 }
 
-/** First and last coordinate pair of a path `d` — pinhole's own edge anchors. */
-function pathAnchors(d) {
-  const n = String(d || "").match(/-?\d*\.?\d+(?:e[-+]?\d+)?/gi);
-  if (!n || n.length < 4) return null;
-  return { sx: +n[0], sy: +n[1], ex: +n[n.length - 2], ey: +n[n.length - 1] };
+/** The lens half of the key — also what /api/layout is keyed by (the project
+ * half is implicit there: the sidecar lives inside the project). */
+function currentLensKey() {
+  return lensKeyOf({ zoom: zoomValue(), radial: view.radial, stack: view.stack });
 }
 
 /**
  * Wrap each containment box in a `<g data-layout-box>` and give it a corner
  * handle, once per rendered SVG.
  *
- * FRAGILE BY CONSTRUCTION, and knowingly so: pinhole's `Canvas.groupBox` emits
- * a bare `<rect rx=…>` immediately followed by its title `<text>`, as a direct
- * child of the `<svg>` — no group, no `data-group-id` to match on. So behold
- * matches the structure, exactly the way addGitlabWaveBadges already has to.
- * The discriminators: a positive `rx` (the two page-background rects have
- * none), a `<text>` as the next non-badge sibling, and svg-root parentage (a
- * card's rect lives inside `[data-node-id]`, an edge-label's inside its own
- * `<g>`). The real fix is upstream — a `data-group-id` on the box — and until
- * pinhole stamps one, prefer the attribute here the moment it exists.
+ * TWO WAYS TO FIND A BOX, in that order (#250):
+ *
+ * 1. `rect[data-group-id]` — pinhole stamps the container key on an
+ *    architecture group box from 0.3.3 (pinhole#103/#104), the same hook
+ *    `data-node-id` gives a card. That key is also what the box's delta is
+ *    stored under, so a box keeps its size when its title changes and two
+ *    boxes that happen to read alike stay separate placements.
+ * 2. The structural match #245 shipped, kept for one release as a fallback and
+ *    then deleted. It is still load-bearing, not dead weight: `layoutArchitecture`
+ *    is the only pinhole layout that sets `GroupBox.id`, so the wave/stack/
+ *    container boxes `renderGraph` draws (src/render.ts) arrive with a title
+ *    and nothing else. FRAGILE BY CONSTRUCTION and knowingly so — the
+ *    discriminators are a positive `rx` (the two page-background rects have
+ *    none), a `<text>` as the next non-badge sibling, and svg-root parentage
+ *    (a card's rect lives inside `[data-node-id]`, an edge-label's inside its
+ *    own `<g>`), exactly the way addGitlabWaveBadges still has to.
+ *
+ * Identification runs over a DOM nothing has moved yet and the wrapping happens
+ * after: both paths read `nextElementSibling`, and inserting a wrapper mid-walk
+ * would put one box's `<g>` in the middle of the next box's member run.
+ *
+ * MIGRATION, said plainly: a box that gains an id changes storage key —
+ * `layoutArchitecture` titles a box `<id>  ·  <kind>`, so `box:vpc  ·  VPC`
+ * becomes `box:vpc` — and `applicable` drops the old key on the next render.
+ * That is a deliberate one-time loss of hand-set box sizes on the logical
+ * views, taken rather than carrying a key-rewriting migration for a delta that
+ * is cosmetic and one drag to redo. Node placements are untouched: they were
+ * always keyed by `data-node-id`.
  */
 function wrapContainmentBoxes(svgEl) {
   const boxes = new Map();
   const handleSize = Math.max(12, Math.round((vbInit ? vbInit[2] : 1000) / 90));
+  const found = [];
+  const claimed = new Set();
   for (const rect of [...svgEl.children]) {
     if (rect.tagName.toLowerCase() !== "rect") continue;
+    const groupId = (rect.getAttribute("data-group-id") || "").trim();
     const x = parseFloat(rect.getAttribute("x"));
     const y = parseFloat(rect.getAttribute("y"));
     const w = parseFloat(rect.getAttribute("width"));
     const h = parseFloat(rect.getAttribute("height"));
-    if (!(parseFloat(rect.getAttribute("rx")) > 0) || !(w > 0) || !(h > 0) || Number.isNaN(x) || Number.isNaN(y)) continue;
+    if (!(w > 0) || !(h > 0) || Number.isNaN(x) || Number.isNaN(y)) continue;
+    // The `rx` sniff is the fallback's discriminator only. An id'd rect has
+    // already said what it is, and hardening a shape pinhole never promised
+    // would be the same mistake this issue exists to undo.
+    if (!groupId && !(parseFloat(rect.getAttribute("rx")) > 0)) continue;
     // Collect rect → title, stepping over anything already stamped between
     // them (the GitLab wave badge), and bail at the next box or card.
     const members = [rect];
@@ -1981,17 +2352,28 @@ function wrapContainmentBoxes(svgEl) {
         break;
       }
     }
-    if (!title) continue;
-    const id = `box:${(title.textContent || "").trim() || boxes.size}`;
-    if (boxes.has(id)) continue;
+    // An untitled box is only knowable by its attribute — the structural path
+    // has literally nothing else to go on, and a titleless id'd box keeps its
+    // resize handle and simply has no drag-by-title. It also keeps nothing but
+    // its own rect: the walk above only stops at a title, so without one it has
+    // swept up whatever pinhole painted next, which is not this box's to move.
+    if (!title && !groupId) continue;
+    const id = `box:${groupId || (title.textContent || "").trim() || found.length}`;
+    if (claimed.has(id)) continue;
+    claimed.add(id);
+    found.push({ id, rect, members: title ? members : [rect], title, x, y, w, h });
+  }
+  for (const { id, rect, members, title, x, y, w, h } of found) {
     const g = document.createElementNS(SVGNS, "g");
     g.setAttribute("data-layout-box", id);
     rect.parentNode.insertBefore(g, rect);
     members.forEach((m) => g.appendChild(m));
     // The title doubles as the box's move handle — the interior stays pan
     // territory, which on a logical view is most of the canvas.
-    title.setAttribute("data-layout-move", id);
-    title.setAttribute("cursor", "move");
+    if (title) {
+      title.setAttribute("data-layout-move", id);
+      title.setAttribute("cursor", "move");
+    }
     const handle = document.createElementNS(SVGNS, "g");
     handle.setAttribute("data-layout-resize", id);
     handle.setAttribute("cursor", "nwse-resize");
@@ -2015,38 +2397,178 @@ function positionBoxHandle(b, w, h) {
   b.handle.setAttribute("transform", `translate(${b.x + w - b.size - 3}, ${b.y + h - b.size - 3})`);
 }
 
+/** A box's rect as it stands right now: pinhole's, plus whatever the hand did to
+ * it. One definition for the painter and for the clamp, so growing a box really
+ * does buy its children room (#267) and cannot drift from what you can see. */
+function boxRect(b, d) {
+  return {
+    x: b.x + ((d && d.dx) || 0),
+    y: b.y + ((d && d.dy) || 0),
+    w: Math.max(b.size * 3, b.w0 + ((d && d.dw) || 0)),
+    h: Math.max(b.size * 3, b.h0 + ((d && d.dh) || 0)),
+  };
+}
+
+/** Screen pixels → this SVG's own user units, as a function. Null when the SVG
+ * isn't laid out (a hidden pane, a detached document) — and a null mapper means
+ * no measured geometry, which the clamp reads as "don't clamp". */
+function userSpaceMapper(svgEl) {
+  const m = svgEl.getScreenCTM && svgEl.getScreenCTM();
+  if (!m || typeof svgEl.createSVGPoint !== "function") return null;
+  const inv = m.inverse();
+  const pt = svgEl.createSVGPoint();
+  return (x, y) => {
+    pt.x = x;
+    pt.y = y;
+    return pt.matrixTransform(inv);
+  };
+}
+
+/** An element's box in SVG user units. MEASURED, not parsed off attributes:
+ * pinhole's cards carry absolute coordinates and no transform, the smoke stub's
+ * carry a `translate()`, and a measurement holds either without this code
+ * knowing which. Only ever taken on a freshly rendered SVG, before any delta is
+ * painted — it is the dagre-placed rect the clamp reasons about. */
+function userRect(el, toUser) {
+  if (!toUser || typeof el.getBoundingClientRect !== "function") return null;
+  const r = el.getBoundingClientRect();
+  if (!(r.width > 0) || !(r.height > 0)) return null;
+  const a = toUser(r.left, r.top);
+  const b = toUser(r.right, r.bottom);
+  return { x: Math.min(a.x, b.x), y: Math.min(a.y, b.y), w: Math.abs(b.x - a.x), h: Math.abs(b.y - a.y) };
+}
+
+/**
+ * The chip pinhole paints on a labelled edge (`project`, `sourceRef`,
+ * `selector` — the IR edge's `viaAttr`), or null if this edge has none.
+ *
+ * HOW THE TWO ARE ASSOCIATED, and why it is what it is: `renderSvg` emits
+ * `Canvas.edge(...)` and then, for a labelled edge, `Canvas.edgeLabel(...)` —
+ * an ANONYMOUS `<g><rect rx="9"/><text>…</text></g>` carrying no edge identity
+ * whatsoever. There is no id, no data attribute, no shared class. What is left
+ * is document order (the chip is the edge group's next element sibling) and the
+ * one piece of content the two provably share: the chip's text IS the edge
+ * group's `data-edge-via` value. Behold requires BOTH before it will move
+ * anything, so a pinhole that stops emitting chips, reorders them, or slips
+ * something between the pair leaves the label untouched rather than dragging an
+ * unrelated group around the canvas.
+ *
+ * Read at index time and kept as an element reference, never re-derived:
+ * wireEdgeHighlight's `raise()` re-appends a hovered edge group to the end of
+ * the SVG, so the sibling link is gone the instant a pointer crosses an edge.
+ *
+ * The real fix is upstream, and it is the same ask boxes made and won in
+ * pinhole 0.3.3 (`data-group-id`, #250): stamp the chip with the edge it
+ * belongs to. The moment pinhole emits a `data-edge-*` pairing on the label
+ * group, prefer it here the way wrapContainmentBoxes now prefers the attribute.
+ */
+function edgeLabelOf(g) {
+  const via = (g.getAttribute("data-edge-via") || "").trim();
+  if (!via) return null;
+  const next = g.nextElementSibling;
+  if (!next || next.tagName.toLowerCase() !== "g") return null;
+  if (next.hasAttribute("data-node-id") || next.hasAttribute("data-edge-from")) return null;
+  const text = next.querySelector("text");
+  if (!text || (text.textContent || "").trim() !== via) return null;
+  return next;
+}
+
 /** Index the freshly rendered SVG: node groups, containment boxes, edge paths. */
 function indexLayout(svgEl) {
+  const toUser = userSpaceMapper(svgEl);
   const nodes = new Map();
   for (const el of svgEl.querySelectorAll("[data-node-id]")) {
     const id = el.getAttribute("data-node-id");
-    if (!nodes.has(id)) nodes.set(id, { el, base: el.getAttribute("transform") || "" });
+    if (!nodes.has(id)) nodes.set(id, { el, base: el.getAttribute("transform") || "", rect: userRect(el, toUser) });
   }
   const edges = [];
   for (const g of svgEl.querySelectorAll("g[data-edge-from]")) {
     const paths = [...g.querySelectorAll("path")];
     if (!paths.length) continue;
     const d0 = paths[0].getAttribute("d");
-    edges.push({ from: g.getAttribute("data-edge-from"), to: g.getAttribute("data-edge-to"), paths, d0, anchors: pathAnchors(d0) });
+    const label = edgeLabelOf(g);
+    edges.push({
+      from: g.getAttribute("data-edge-from"),
+      to: g.getAttribute("data-edge-to"),
+      paths,
+      d0,
+      anchors: pathAnchors(d0),
+      label,
+      labelBase: label ? label.getAttribute("transform") || "" : "",
+    });
   }
   layoutIndex = { nodes, boxes: wrapContainmentBoxes(svgEl), edges };
 }
 
+/**
+ * The box a card sits in, geometrically — the containment is visual and nothing
+ * in the DOM says which card belongs to which box. The SMALLEST box whose
+ * CURRENT rect covers the card's original centre wins, so a card in a namespace
+ * nested inside a cluster clamps to the namespace, not the cluster.
+ *
+ * `current` is the load-bearing word: growing a box is the sanctioned way to
+ * make room, so the wall a drag stops at has to be the box as it is now.
+ */
+function containerOf(rect) {
+  if (!layoutIndex || !rect) return null;
+  const cx = rect.x + rect.w / 2;
+  const cy = rect.y + rect.h / 2;
+  let best = null;
+  for (const [id, b] of layoutIndex.boxes) {
+    const r = boxRect(b, layoutDeltas[id]);
+    if (cx < r.x || cx > r.x + r.w || cy < r.y || cy > r.y + r.h) continue;
+    if (!best || r.w * r.h < best.w * best.h) best = r;
+  }
+  return best;
+}
+
+/** A node's delta, clamped to whatever contains it: its box, or failing that
+ * the canvas pinhole drew (`vbInit` — the graph's own extent, NOT the panned
+ * and zoomed `vb`, which is just where you happen to be looking).
+ *
+ * Nodes only. A box's own gesture is the escape hatch, so clamping a box would
+ * put the only way to make room behind the wall it enforces. And an id with no
+ * measured rect is returned untouched — see clampDelta on failing open. */
+function clampNodeDelta(id, delta) {
+  const n = layoutIndex && layoutIndex.nodes.get(id);
+  if (!n || !n.rect) return delta;
+  const canvas = vbInit ? { x: vbInit[0], y: vbInit[1], w: vbInit[2], h: vbInit[3] } : null;
+  const bounds = containerOf(n.rect) || canvas;
+  return bounds ? clampDelta(delta, n.rect, bounds) : delta;
+}
+
+/** Bring every stored node delta back inside its container. Clamped, never
+ * discarded (#267): a placement made before this rule existed — or against a
+ * box someone has since shrunk — keeps everything about it except the part that
+ * escaped. Box deltas are read as-is, which is why this runs after they land. */
+function clampStoredDeltas(deltas) {
+  if (!layoutIndex) return deltas;
+  let out = deltas;
+  for (const id of layoutIndex.nodes.keys()) {
+    const d = out[id];
+    if (!d || (!d.dx && !d.dy)) continue;
+    const c = clampNodeDelta(id, d);
+    if (c.dx !== (d.dx || 0) || c.dy !== (d.dy || 0)) out = setDelta(out, id, { ...d, dx: c.dx, dy: c.dy });
+  }
+  return out;
+}
+
 /** Paint `layoutDeltas` onto the indexed SVG. Idempotent: always from the original. */
 function renderLayout() {
   if (!layoutIndex) return;
   for (const [id, n] of layoutIndex.nodes) {
-    const d = layoutDeltas[id];
-    const t = d && (d.dx || d.dy) ? `translate(${d.dx || 0}, ${d.dy || 0}) ${n.base}`.trim() : n.base;
+    const t = nodeTransform(n.base, layoutDeltas[id] || {});
     if (t) n.el.setAttribute("transform", t);
     else n.el.removeAttribute("transform");
   }
   for (const [id, b] of layoutIndex.boxes) {
     const d = layoutDeltas[id] || {};
-    const w = Math.max(b.size * 3, b.w0 + (d.dw || 0));
-    const h = Math.max(b.size * 3, b.h0 + (d.dh || 0));
+    const { w, h } = boxRect(b, d);
     b.rect.setAttribute("width", String(w));
     b.rect.setAttribute("height", String(h));
+    // The title rides inside this same group, and pinhole anchors it to the
+    // rect's top-left — the one corner a resize leaves alone — so a box's
+    // caption never detaches from its box (#267 asked; nothing to fix).
     if (d.dx || d.dy) b.g.setAttribute("transform", `translate(${d.dx || 0}, ${d.dy || 0})`);
     else b.g.removeAttribute("transform");
     positionBoxHandle(b, w, h);
@@ -2056,30 +2578,88 @@ function renderLayout() {
     const z = layoutDeltas[e.to];
     if ((!a && !z) || !e.anchors) {
       if (e.paths[0].getAttribute("d") !== e.d0) e.paths.forEach((p) => p.setAttribute("d", e.d0));
+      placeEdgeLabel(e, 0, 0);
       continue;
     }
-    const { sx, sy, ex, ey } = e.anchors;
-    const d = `M ${sx + ((a && a.dx) || 0)} ${sy + ((a && a.dy) || 0)} L ${ex + ((z && z.dx) || 0)} ${ey + ((z && z.dy) || 0)}`;
+    const d = straightEdge(e.anchors, a, z);
+    // EVERY path in the group: the visible line and pinhole's 14-wide
+    // transparent hit-path both, so the edge you can grab stays under the edge
+    // you can see.
     e.paths.forEach((p) => p.setAttribute("d", d));
+    // The chip was painted at the midpoint of the two anchors, so the midpoint
+    // of the re-anchored line is that point plus the MEAN of the two ends'
+    // deltas. No re-reading of the chip's own coordinates, and no assumption
+    // about how pinhole spelled them.
+    placeEdgeLabel(e, (((a && a.dx) || 0) + ((z && z.dx) || 0)) / 2, (((a && a.dy) || 0) + ((z && z.dy) || 0)) / 2);
   }
 }
 
+/** Shift an edge's label chip by `(sx,sy)`, from its painted position. Composed
+ * onto whatever transform it was painted with (none, today) and removed when
+ * the shift is zero — so this is idempotent, like the rest of renderLayout. */
+function placeEdgeLabel(e, sx, sy) {
+  if (!e.label) return;
+  const t = nodeTransform(e.labelBase, { dx: sx, dy: sy });
+  if (t) e.label.setAttribute("transform", t);
+  else e.label.removeAttribute("transform");
+}
+
 /** Re-index the SVG, load this lens's deltas, paint them. Called from render(). */
 function applyLayout() {
   const svgEl = currentSvg();
   const host = document.getElementById("graph");
   if (!svgEl || !host) return;
   indexLayout(svgEl);
+  reloadLayoutDeltas();
+  ensureLayoutReset(host);
+  ensureLayoutDrag(host);
+  const lens = currentLensKey();
+  if (currentLayoutKey() && layoutServer.lens !== lens) pullServerLayout(lens);
+}
+
+/** Recompute both tiers onto the SVG already indexed, and repaint. Separate
+ * from applyLayout() because it must NOT re-index: renderLayout paints from
+ * each node's ORIGINAL transform, so re-indexing an already-painted SVG would
+ * take the displaced transform as the new base and apply the delta twice. */
+function reloadLayoutDeltas() {
+  if (!layoutIndex) return;
   const key = currentLayoutKey();
+  const lens = currentLensKey();
   // Stale ids are dropped on apply, not on write: a lens the user hasn't
   // opened in a while shouldn't have its deltas quietly deleted because this
   // render happened to be a different projection of the same estate.
-  layoutDeltas = key ? applicable(readLayout(localStorage, key), [...layoutIndex.nodes.keys(), ...layoutIndex.boxes.keys()]) : {};
+  const merged = key ? mergeLayouts(readLayout(localStorage, key), layoutServer.lens === lens ? layoutServer.deltas : {}) : {};
+  layoutDeltas = applicable(merged, [...layoutIndex.nodes.keys(), ...layoutIndex.boxes.keys()]);
+  layoutDeltas = clampStoredDeltas(layoutDeltas);
   renderLayout();
-  ensureLayoutReset(host);
-  ensureLayoutDrag(host);
 }
 
+/** One GET per lens. Whatever comes back is merged UNDER the local tier and
+ * repainted; a refusal is cached as an empty, unwritable answer, so a serve
+ * with no sidecar (or no server at all) costs exactly one request per lens. */
+async function pullServerLayout(lens) {
+  layoutServer = { lens, deltas: {}, writable: false }; // claim it first — no request storm
+  const got = await fetchServerLayout(apiFetch, lens);
+  if (layoutServer.lens !== lens) return; // the view moved on while we waited
+  layoutServer = { lens, ...got };
+  if (!Object.keys(got.deltas).length || currentLensKey() !== lens) return;
+  reloadLayoutDeltas();
+  ensureLayoutReset(document.getElementById("graph"));
+}
+
+/** Push the current lens to the sidecar, once the hand has stopped moving.
+ * Nothing here is load-bearing: `writable` false (static export, preview mode,
+ * read-only project, older behold) simply never pushes, and a failed push is
+ * not reported — the localStorage tier already has it. */
+const pushServerLayout = debounce((lens, deltas) => {
+  if (staticMode || !layoutServer.writable || layoutServer.lens !== lens) return;
+  postServerLayout((url, init) => fetch(url, init), lens, deltas);
+}, 600);
+// A reload (or a tab closing) within the debounce window would otherwise drop
+// the last placement on the floor — localStorage has it, the sidecar wouldn't.
+// The push rides `keepalive`, so it survives the document.
+window.addEventListener("pagehide", () => pushServerLayout.flush());
+
 /** The grabbable thing at or above `el`, if any. */
 function layoutTargetIn(el) {
   if (!el || typeof el.closest !== "function") return null;
@@ -2151,7 +2731,11 @@ function ensureLayoutDrag(host) {
       layoutDrag.kind === "resize"
         ? { dx: b.dx || 0, dy: b.dy || 0, dw: (b.dw || 0) + dx, dh: (b.dh || 0) + dy }
         : { dx: (b.dx || 0) + dx, dy: (b.dy || 0) + dy, dw: b.dw || 0, dh: b.dh || 0 };
-    layoutDeltas = setDelta(layoutDeltas, layoutDrag.id, next);
+    // #267: the card stops at its box's wall while the pointer keeps going. A
+    // no-op for a box id and for a resize, and the box's CURRENT size is what
+    // is read — so widening a box mid-session immediately buys its children the
+    // room, no re-render needed.
+    layoutDeltas = setDelta(layoutDeltas, layoutDrag.id, clampNodeDelta(layoutDrag.id, next));
     renderLayout();
   });
   window.addEventListener("pointerup", () => {
@@ -2161,6 +2745,10 @@ function ensureLayoutDrag(host) {
     if (!moved) return;
     const key = currentLayoutKey();
     if (key) writeLayout(localStorage, key, layoutDeltas);
+    // The sidecar gets the WHOLE lens map, not the one id that moved: it is a
+    // per-lens document, and the local tier is the authority the user is
+    // looking at. Debounced, so a drag is one write and not sixty.
+    if (key) pushServerLayout(currentLensKey(), layoutDeltas);
     ensureLayoutReset(document.getElementById("graph"));
   });
 }
@@ -2180,6 +2768,11 @@ function ensureLayoutReset(host) {
       e.stopPropagation();
       const key = currentLayoutKey();
       if (key) clearLayout(localStorage, key);
+      // Both tiers, or it isn't a reset: clearing only localStorage would let
+      // the next merge pull the sidecar's deltas straight back in.
+      const lens = currentLensKey();
+      layoutServer = { lens, deltas: {}, writable: layoutServer.lens === lens && layoutServer.writable };
+      pushServerLayout(lens, {});
       layoutDeltas = {};
       renderLayout();
       ensureLayoutReset(host);
@@ -2202,6 +2795,10 @@ const PRECONDITION_TITLE = {
   // #193: behold was pointed at a directory that isn't a chant project at all
   // — the first screen must say so, not draw a blank graph.
   "no-project": "This isn't a chant project",
+  // #252: carve mode is served a `chant carve advise --json` report, not a
+  // project — so a bad file is a bad REPORT, and the card must not blame chant
+  // for failing to evaluate a project that was never involved.
+  "carve-report": "This isn't a carve report",
 };
 
 // A precondition failure — the lint gate, a not-installed/no-typegen project,
@@ -2232,6 +2829,18 @@ function renderPreconditionError(body) {
     remedy.textContent = body.remedy;
     card.appendChild(remedy);
   }
+  // #259: the rest of the /api error payload. The card above is the human
+  // reading — code, error, remedy — but the server sends more than those three
+  // (chant's argv, exit code, the endpoint it queried), and until now that
+  // detail was simply dropped on the floor. Collapsed by default so the calm
+  // card stays calm, copyable in one gesture for a bug report.
+  const raw = document.createElement("div");
+  raw.className = "precondition-error-raw";
+  const label = document.createElement("div");
+  label.className = "precondition-error-rawlabel";
+  label.textContent = "response payload";
+  raw.append(label, renderJson(body, { openDepth: -1 }));
+  card.appendChild(raw);
   host.appendChild(card);
 }
 
@@ -2314,7 +2923,15 @@ async function load(opts = {}) {
   } catch (err) {
     // A background settle poll must not blow away a good graph on a transient error.
     if (!opts.quiet) {
-      document.getElementById("graph").innerHTML = `<div class="err">graph failed: ${err.message}</div>`;
+      // Text, never innerHTML — `err.message` embeds chant's own stderr, which
+      // is not ours to interpolate as markup (the sibling precondition card has
+      // said so since #72; this branch had been left behind).
+      const graph = document.getElementById("graph");
+      graph.innerHTML = "";
+      const box = document.createElement("div");
+      box.className = "err";
+      box.textContent = `graph failed: ${err.message}`;
+      graph.appendChild(box);
       meta.textContent = "error";
     }
   } finally {
@@ -2381,6 +2998,13 @@ async function initPickers() {
   // with none leaves `view.stack` (and the picker + status tag) null.
   stacks = info.stacks || [];
   view.stack = stacks[0] || null;
+  // #254: carve mode declares itself here. The Carve tab is mounted at runtime
+  // (panel.js's addPanelTab), so nothing else grows a dead tab.
+  carveInfo = info.carve || null;
+  if (carveMode()) {
+    renderPanelCarve();
+    loadCarveReport();
+  }
   axes = { tier: info.tier || null, target: info.target || null };
   environments = info.environments || [];
   tiers = info.tiers || [];
@@ -2541,11 +3165,28 @@ function hideLoading() {
   if (o) o.hidden = true;
 }
 
+// #259: the op stream is chant's own stdout, and an Op that reports as JSON
+// (a plan summary, a run report, an unrecognized `--progress-json` line that
+// src/op-runner.ts didn't filter out) used to land here as one unbroken line.
+// Parse it; if it IS a JSON object or array, show the collapsible tree instead.
+// Anything else — every ordinary human log line — is untouched text.
+function asJsonPayload(line) {
+  const s = String(line).trim();
+  if (!(s.startsWith("{") || s.startsWith("["))) return null;
+  try {
+    const v = JSON.parse(s);
+    return isContainer(v) ? v : null;
+  } catch {
+    return null;
+  }
+}
+
 function nowline(line) {
   const p = document.getElementById("nowline");
   p.style.display = "block";
-  const d = document.createElement("div");
-  d.textContent = line;
+  const payload = asJsonPayload(line);
+  const d = payload ? renderJson(payload) : document.createElement("div");
+  if (!payload) d.textContent = line;
   p.appendChild(d);
   p.scrollTop = p.scrollHeight;
 }
@@ -2910,6 +3551,22 @@ function paletteCommands() {
   for (const b of document.querySelectorAll("#panel-tabs button[data-tab]")) {
     c.push([`Panel: ${b.textContent}`, () => setPanelTab(b.dataset.tab)]);
   }
+  // #254: the walkthrough's steps get palette twins like every other control.
+  // Blocked steps are listed with their reason rather than hidden — "why can't
+  // I do that yet" is the question the palette should be able to answer.
+  if (carveMode()) {
+    CARVE_STEPS.forEach((s, i) => {
+      const why = blockedReason(carveState, s.id);
+      c.push([
+        `Carve: ${i + 1}. ${s.label}${why ? ` — ${why}` : ""}`,
+        () => {
+          if (why) return showToast(why, false);
+          setPanelTab("carve");
+          carveActions.go(i);
+        },
+      ]);
+    });
+  }
 
   // Lens/zoom switches (#56, #63) — replaces the old header zoom picker.
   for (const [label, v] of ZOOM_OPTS) {