@intentius/behold 0.7.0 → 0.9.0

package/web/app.js

@@ -9,7 +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,
+  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"));
@@ -63,6 +96,39 @@ function recolorNodesByCategory(ir) {
 }
 onThemeChange(() => recolorNodesByCategory());
 
+// #229, the one motion signature behold spends on data: a node whose drift
+// `_status` CHANGED between two renders pulses once in the colour it just
+// became. Node ids are stable across renders, so the diff is a single map
+// compare — no extra fetch, no per-node bookkeeping. The first render seeds the
+// map and pulses nothing (everything would "change"), and a lens switch that
+// swaps the id set pulses nothing either, since only ids present in BOTH
+// renders can have changed. The CSS keyframes + the reduced-motion guard live
+// in index.html.
+let lastStatusById = new Map();
+function markStatusChanges(ir, statusVar) {
+  const prev = lastStatusById;
+  const next = new Map();
+  for (const n of ir.nodes) {
+    const s = n.attrs && n.attrs._status;
+    if (s) next.set(n.id, s);
+  }
+  lastStatusById = next;
+  if (!prev.size) return;
+  const svg = document.querySelector("#graph svg");
+  if (!svg) return;
+  for (const g of svg.querySelectorAll("[data-node-id]")) {
+    const id = g.getAttribute("data-node-id");
+    const now = next.get(id);
+    if (!now || prev.get(id) === undefined || prev.get(id) === now) continue;
+    // The pulse wears the NEW status's hue, read through whichever vocabulary
+    // this graph is painted in — a node going foreign glows yellow in the drift
+    // overlay; a component that rolled back glows red in the component view,
+    // where the same `warn` means something else entirely.
+    g.style.setProperty("--pulse", statusVar[now] || "var(--pending)");
+    g.classList.add("status-changed");
+  }
+}
+
 // Static-export mode (`behold export`): the SPA runs off a pre-captured bundle
 // with no backend. Detect the flag the export injects, load its manifest, and
 // replay every read from `snapshots/` — the graph, zoom dial, radial, inspect,
@@ -126,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) {
@@ -141,7 +263,6 @@ function inspect(node) {
   const section = (title) => {
     const h = document.createElement("h3");
     h.textContent = title;
-    h.style.cssText = "font-size:11px;text-transform:uppercase;letter-spacing:.5px;color:var(--muted);margin:14px 0 6px";
     panel.appendChild(h);
     const dl = document.createElement("dl");
     panel.appendChild(dl);
@@ -149,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);
     };
   };
@@ -202,7 +323,6 @@ function inspect(node) {
   if (isComposite) {
     const h = document.createElement("h3");
     h.textContent = `members · ${node.attrs.members}`;
-    h.style.cssText = "font-size:11px;text-transform:uppercase;letter-spacing:.5px;color:var(--muted);margin:14px 0 6px";
     panel.appendChild(h);
     const loading = document.createElement("p");
     loading.style.color = "var(--muted)";
@@ -354,7 +474,7 @@ function inspect(node) {
         panel.appendChild(p);
         return;
       }
-      renderObserved(panel, j.observed, j.health); // #30 observed state + #26 health
+      renderObserved(panel, j.observed, j.health, j.healthDetail); // #30 observed state + #26/#226 health
       renderDiff(panel, j.diff); // #27 — drift since snapshot
       renderFieldDrift(panel, j.fieldDrift); // #87 — field-level (per-manager) drift
     });
@@ -388,24 +508,30 @@ const HEALTH_COLOR = {
 };
 
 // Render a node's observed live state (#30) + health verdict (#26).
-function renderObserved(panel, o, health) {
+function renderObserved(panel, o, health, healthDetail) {
   if (!o) return; // pending/foreign nodes have no observed record in the diff
   const h = document.createElement("h3");
   h.textContent = "observed";
-  h.style.cssText = "font-size:11px;text-transform:uppercase;letter-spacing:.5px;color:var(--muted);margin:14px 0 6px";
   panel.appendChild(h);
   const dl = document.createElement("dl");
   const add = (k, v, color) => {
     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);
   };
   // Health first — the "is it well?" verdict, distinct from drift. Absent when
   // the substrate reports no status (not fabricated).
-  if (health && health !== "unknown") add("health", health, HEALTH_COLOR[health]);
+  // #226: for an Argo Application or a Flux object the verdict comes from the
+  // controller's own conditions, and `healthDetail` is the sentence it read
+  // there — `Ready=False (BuildFailed)`, `health=Degraded, sync=OutOfSync`.
+  // Appended to the verdict rather than given its own row, because it is the
+  // same claim said precisely.
+  if (health && health !== "unknown") {
+    add("health", healthDetail ? `${health} — ${healthDetail}` : health, HEALTH_COLOR[health]);
+  }
   if (o.type) add("type", o.type);
   if (o.status) add("status", o.status, HEALTH_COLOR[health] || undefined);
   if (o.physicalId) add("physical id", o.physicalId);
@@ -420,11 +546,16 @@ function renderObserved(panel, o, health) {
   // 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);
 }
@@ -448,7 +579,6 @@ const DIFF_LABEL = {
 function renderDiff(panel, diff) {
   const h = document.createElement("h3");
   h.textContent = "drift";
-  h.style.cssText = "font-size:11px;text-transform:uppercase;letter-spacing:.5px;color:var(--muted);margin:14px 0 6px";
   panel.appendChild(h);
   if (!diff) {
     const p = document.createElement("p");
@@ -466,7 +596,7 @@ function renderDiff(panel, diff) {
   // this address makes that visible). Monospace so a request path scans.
   if (diff.queried) {
     const q = document.createElement("p");
-    q.style.cssText = "color:var(--muted);font:11px/1.4 ui-monospace,monospace;overflow-wrap:anywhere;margin-top:2px";
+    q.className = "queried"; // mono + muted, styled with the rest of the pane's scale
     q.textContent = `queried: ${diff.queried} → ${diff.category === "missing" ? "not found" : "read failed"}`;
     panel.appendChild(q);
   }
@@ -509,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);
@@ -539,7 +671,6 @@ function renderFieldDrift(panel, fieldDrift) {
   if (!fieldDrift.drifted.length && !fieldDrift.accepted.length) return; // deep ran, nothing to report for this node
   const h = document.createElement("h3");
   h.textContent = "field ownership";
-  h.style.cssText = "font-size:11px;text-transform:uppercase;letter-spacing:.5px;color:var(--muted);margin:14px 0 6px";
   panel.appendChild(h);
   const dl = document.createElement("dl");
   for (const ch of fieldDrift.drifted) {
@@ -553,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) {
@@ -561,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);
@@ -579,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);
     });
   }
 }
@@ -734,7 +869,7 @@ function renderPanelView() {
   lanes.href = "/lanes";
   lanes.textContent = "lanes →";
   lanes.title = "The time-lanes view — captured frames of this graph over time";
-  lanes.style.cssText = "color:var(--pending);text-decoration:none;font-size:12px";
+  lanes.style.cssText = "color:var(--pending);text-decoration:none;font-size:var(--t-body)";
   row.appendChild(lanes);
   tools.appendChild(row);
 }
@@ -768,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;
@@ -837,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(
@@ -940,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() {
@@ -1005,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() {
@@ -1210,7 +1576,7 @@ function renderDial() {
     }
     host.style.display = "flex";
     const hint = document.createElement("span");
-    hint.style.cssText = "font-size:11px;color:var(--muted);align-self:center";
+    hint.style.cssText = "font-size:var(--t-caption);color:var(--muted);align-self:center";
     hint.textContent = "observe → reconcile → apply needs an environment — pick one in ⌘K (env: …)";
     host.appendChild(hint);
     // A pipeline run (#163) is env-less — its progress still belongs here.
@@ -1283,7 +1649,7 @@ function renderApplyPicker() {
   wrap.style.gap = "6px";
   const sel = document.createElement("select");
   sel.style.cssText =
-    "background:var(--panel);color:var(--fg);border:1px solid var(--line);border-radius:6px;padding:3px 8px;font-size:12px";
+    "background:var(--well);color:var(--fg);border:1px solid var(--line);border-radius:var(--r-ctl);padding:3px 8px;font-size:var(--t-body)";
   sel.add(new Option("all components", "all"));
   for (const name of componentChoices) sel.add(new Option(applyOptionLabel(name), name));
   const go = button("Apply →", "", () => {
@@ -1405,7 +1771,7 @@ function renderApplyProgress(state) {
   const wrap = document.createElement("div");
   wrap.style.cssText = "display:flex;flex-direction:column;gap:6px;width:100%;margin-top:4px";
   const summary = document.createElement("div");
-  summary.style.cssText = `font-size:11px;color:${APPLY_STATUS_COLOR[state.status] || "var(--muted)"}`;
+  summary.style.cssText = `font-size:var(--t-caption);color:${APPLY_STATUS_COLOR[state.status] || "var(--muted)"}`;
   // A pipeline run (#163) reuses this whole panel — same shape, different
   // executor — and says so instead of claiming to be an apply.
   summary.textContent = `${state.kind || "apply"}: ${state.status}`;
@@ -1414,14 +1780,14 @@ function renderApplyProgress(state) {
     const row = document.createElement("div");
     row.style.cssText = "display:flex;align-items:center;gap:8px;flex-wrap:wrap";
     const label = document.createElement("span");
-    label.style.cssText = `font-size:11px;color:${APPLY_STATUS_COLOR[w.status] || "var(--muted)"};min-width:52px`;
+    label.style.cssText = `font-size:var(--t-caption);color:${APPLY_STATUS_COLOR[w.status] || "var(--muted)"};min-width:52px`;
     label.textContent = `wave ${w.wave}`;
     row.appendChild(label);
     for (const cname of w.components) {
       const c = (state.components || []).find((x) => x.component === cname) || { status: "pending" };
       const color = APPLY_STATUS_COLOR[c.status] || "var(--muted)";
       const chip = document.createElement("span");
-      chip.style.cssText = `border:1px solid ${color};color:${color};border-radius:6px;padding:2px 8px;font-size:11px`;
+      chip.style.cssText = `border:1px solid ${color};color:${color};border-radius:var(--r-ctl);padding:2px 8px;font-size:var(--t-caption)`;
       const detail = [c.phase, c.step].filter(Boolean).join(" · ");
       chip.textContent = `${cname}${detail ? " · " + detail : ""} (${c.status})`;
       if (c.error) chip.title = c.error;
@@ -1657,6 +2023,7 @@ function render(ir, svg, m) {
   // green — the SVG's own :root shadows behold's override within the graph subtree.
   g.innerHTML = svg.replace(/:root\s*\{[^{}]*--pin-[^{}]*\}/g, "");
   recolorNodesByCategory(ir); // #62: category-hued fills from the theme's full palette
+  markStatusChanges(ir, componentStatus ? COMPONENT_STATUS_VAR : DRIFT_STATUS_VAR); // #229
   const svgEl = g.querySelector("svg");
   if (svgEl) {
     // Drop pinhole's fixed pixel size so the viewBox drives sizing; behold then
@@ -1676,6 +2043,8 @@ 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();
 }
 
@@ -1833,6 +2202,11 @@ function ensureZoomControls(host) {
   let py = 0;
   host.addEventListener("mousedown", (e) => {
     if (!vb) return;
+    // #228: pan is the default on empty ground, but a node card (or a box's
+    // title / resize handle) belongs to the layout drag — starting a pan too
+    // would move the graph out from under the thing you grabbed. The layout
+    // drag owns the panMoved latch for the rest of the gesture.
+    if (layoutTargetOf(e)) return;
     drag = true;
     panMoved = false;
     px = e.clientX;
@@ -1862,6 +2236,553 @@ function ensureZoomControls(host) {
   });
 }
 
+// --- Hand layout (#228): drag a node, resize a containment box -------------
+// dagre is a good first draft and a bad final layout. A pointer-drag on a card
+// writes a {dx,dy} for that `data-node-id`; a corner handle on a containment
+// box writes {dw,dh} (and its title drags the box). The deltas live in
+// localStorage per project + lens (web/layout-store.js) and are re-applied at
+// 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;
+//   * an edge touching a displaced node is redrawn as a STRAIGHT line between
+//     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.
+//     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), currentLensKey());
+}
+
+/** 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.
+ *
+ * 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 (!(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];
+    let title = null;
+    for (let el = rect.nextElementSibling; el; el = el.nextElementSibling) {
+      const tag = el.tagName.toLowerCase();
+      if (tag === "rect" || (tag === "g" && (el.hasAttribute("data-node-id") || el.hasAttribute("data-edge-from")))) break;
+      members.push(el);
+      if (tag === "text") {
+        title = el;
+        break;
+      }
+    }
+    // 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.
+    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");
+    handle.setAttribute("opacity", "0"); // CSS reveals it on hover; a static export never shows it
+    const grip = document.createElementNS(SVGNS, "rect");
+    grip.setAttribute("width", String(handleSize));
+    grip.setAttribute("height", String(handleSize));
+    grip.setAttribute("rx", "3");
+    grip.setAttribute("fill", "var(--focus)");
+    const tip = document.createElementNS(SVGNS, "title");
+    tip.textContent = "Drag to resize this box. Children don't move with it — that's the next layout's job.";
+    handle.append(tip, grip);
+    g.appendChild(handle);
+    boxes.set(id, { g, rect, handle, x, y, w0: w, h0: h, size: handleSize });
+  }
+  return boxes;
+}
+
+/** Park the corner handle at the box's current bottom-right. */
+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") || "", 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");
+    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 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, 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);
+  }
+  for (const e of layoutIndex.edges) {
+    const a = layoutDeltas[e.from];
+    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 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.
+  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();
+}
+
+/** 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;
+  const resize = el.closest("[data-layout-resize]");
+  if (resize) return { kind: "resize", id: resize.getAttribute("data-layout-resize") };
+  const move = el.closest("[data-layout-move]");
+  if (move) return { kind: "move", id: move.getAttribute("data-layout-move") };
+  const node = el.closest("[data-node-id]");
+  if (node) return { kind: "move", id: node.getAttribute("data-node-id") };
+  return null;
+}
+
+/** What (if anything) a pointerdown grabbed. Also the pan handler's bail test. */
+function layoutTargetOf(e) {
+  const direct = layoutTargetIn(e.target);
+  if (direct) return direct;
+  // An edge can swallow the grab: wireEdgeHighlight raises every edge on a
+  // hovered card to the top of the SVG, and pinhole's 14-wide transparent
+  // hit-path is anchored at the card's own centre — so by the time the pointer
+  // is down, the edge you just lit is lying across the card you meant to move.
+  // Look through the stack for the card underneath instead of giving up.
+  if (!e.target || typeof e.target.closest !== "function" || !e.target.closest("g[data-edge-from]")) return null;
+  for (const el of document.elementsFromPoint(e.clientX, e.clientY)) {
+    const t = layoutTargetIn(el);
+    if (t) return t;
+  }
+  return null;
+}
+
+/** Screen pixels → viewBox units at the current zoom. */
+function userPerPixel(svgEl) {
+  const m = svgEl.getScreenCTM && svgEl.getScreenCTM();
+  if (m && m.a && m.d) return { x: 1 / m.a, y: 1 / m.d };
+  const r = svgEl.getBoundingClientRect();
+  return vb && r.width && r.height ? { x: vb[2] / r.width, y: vb[3] / r.height } : { x: 1, y: 1 };
+}
+
+function ensureLayoutDrag(host) {
+  if (layoutWired) return;
+  layoutWired = true;
+  host.addEventListener("pointerdown", (e) => {
+    if (e.button !== 0 || !layoutIndex) return;
+    const t = layoutTargetOf(e);
+    if (!t || !currentSvg()) return;
+    layoutDrag = { ...t, x0: e.clientX, y0: e.clientY, base: layoutDeltas[t.id] || {}, moved: false };
+    // The same latch pan uses (wire()'s click-inspect bails on it): claim it on
+    // grab so a drag is never also a click, and so the NEXT plain click on a
+    // node isn't swallowed by a stale `true` from the gesture before it.
+    panMoved = false;
+    // Deliberately no preventDefault(): cancelling pointerdown suppresses the
+    // compatibility mouse events, and click-inspect rides on those. The pan is
+    // held off by its own guard instead, and the text selection a drag would
+    // otherwise smear across the graph by `user-select: none` on the SVG.
+  });
+  window.addEventListener("pointermove", (e) => {
+    if (!layoutDrag) return;
+    const svgEl = currentSvg();
+    if (!svgEl) return;
+    const px = e.clientX - layoutDrag.x0;
+    const py = e.clientY - layoutDrag.y0;
+    if (!layoutDrag.moved && Math.abs(px) + Math.abs(py) <= 3) return;
+    layoutDrag.moved = true;
+    panMoved = true;
+    const s = userPerPixel(svgEl);
+    const dx = px * s.x;
+    const dy = py * s.y;
+    const b = layoutDrag.base;
+    const next =
+      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 };
+    // #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", () => {
+    if (!layoutDrag) return;
+    const moved = layoutDrag.moved;
+    layoutDrag = null;
+    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"));
+  });
+}
+
+/** The "↺ layout" control beside ⤢ fit — shown only while something is hand-placed. */
+function ensureLayoutReset(host) {
+  if (!host) return;
+  let btn = document.getElementById("layout-reset");
+  if (!btn || btn.parentElement !== host) {
+    btn = document.createElement("button");
+    btn.id = "layout-reset";
+    btn.textContent = "↺ layout";
+    btn.title =
+      "Drop the hand-placed layout for this project + this lens and go back to dagre's. " +
+      "(A resized box never reflows what's inside it — only the next layout does that.)";
+    btn.addEventListener("click", (e) => {
+      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);
+      nowline("↺ layout reset — back to dagre's placement");
+    });
+    host.appendChild(btn);
+  }
+  btn.style.display = isEmpty(layoutDeltas) ? "none" : "";
+}
+
 // Precondition-failure codes (#72) → a short, human title for the entry/error
 // screen below. Mirrors every `code` a read route's structured error can
 // carry (src/server.ts RouteErrorCode: chant.ts's lint/not-installed/eval,
@@ -1874,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,
@@ -1904,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);
 }
 
@@ -1986,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 {
@@ -2053,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 || [];
@@ -2213,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;
 }
@@ -2238,7 +3207,7 @@ function showToast(msg, ok) {
   }
   const t = document.createElement("div");
   const color = ok ? "var(--managed)" : "var(--degraded)";
-  t.style.cssText = `background:var(--panel);color:var(--fg);border:1px solid ${color};border-left:4px solid ${color};border-radius:8px;padding:8px 12px;font-size:12px;box-shadow:0 4px 16px rgba(0,0,0,.35);cursor:pointer;white-space:pre-wrap`;
+  t.style.cssText = `background:var(--panel);color:var(--fg);border:1px solid ${color};border-left:4px solid ${color};border-radius:var(--r-ctl);padding:8px 12px;font-size:var(--t-body);box-shadow:0 6px 18px color-mix(in srgb, var(--shadow) 50%, transparent);cursor:pointer;white-space:pre-wrap`;
   t.textContent = msg;
   t.onclick = () => t.remove();
   host.appendChild(t);
@@ -2319,7 +3288,7 @@ async function openRollback(btn) {
   wrap.style.cssText = "display:flex;gap:6px;align-self:center";
   const sel = document.createElement("select");
   sel.style.cssText =
-    "background:var(--panel);color:var(--fg);border:1px solid var(--line);border-radius:6px;padding:4px 8px;font-size:12px;max-width:340px";
+    "background:var(--well);color:var(--fg);border:1px solid var(--line);border-radius:var(--r-ctl);padding:4px 8px;font-size:var(--t-body);max-width:340px";
   for (const c of commits) sel.add(new Option(`${c.sha} · ${c.subject} (${c.date})`, c.sha));
   const go = button("Roll back →", "", () => {
     const to = sel.value;
@@ -2363,7 +3332,7 @@ async function initActions() {
     const pill = document.createElement("span");
     pill.textContent = `● static snapshot${manifest && manifest.capturedAt ? " · " + manifest.capturedAt.slice(0, 16).replace("T", " ") : ""}`;
     pill.title = "An exported, read-only snapshot — no live observe or deploy.";
-    pill.style.cssText = "align-self:center;font-size:11px;color:var(--muted);border:1px solid var(--line);border-radius:6px;padding:2px 8px";
+    pill.style.cssText = "align-self:center;font:var(--t-caption)/1.4 var(--font-mono);color:var(--muted);border:1px solid var(--line);border-radius:var(--r-ctl);padding:2px 8px";
     bar.appendChild(pill);
     previewMode = true;
     return; // nothing else in the bar is a read
@@ -2395,7 +3364,7 @@ async function initActions() {
       local.emulators.map((e) => `${e.lexicon} ${e.name} @ ${e.endpoint}`).join("; ") +
       ". Deploys and the overlay observe them — no cloud creds.";
     pill.style.cssText =
-      "align-self:center;font-size:11px;color:var(--managed);border:1px solid var(--managed);border-radius:6px;padding:2px 8px";
+      "align-self:center;font:var(--t-caption)/1.4 var(--font-mono);color:var(--managed);border:1px solid var(--managed);border-radius:var(--r-ctl);padding:2px 8px";
     bar.appendChild(pill);
   }
   // Auto-sync banner (#29) — make an active self-heal loop visible, not silent.
@@ -2404,7 +3373,7 @@ async function initActions() {
     pill.textContent = `⟳ auto-sync: ${autoSync}`;
     pill.title = `On polled drift, behold triggers the ${autoSync === "apply" ? "ApplyOp (heal)" : "ReconcileOp (adopt)"}. Gated applies still wait for Approve.`;
     pill.style.cssText =
-      "align-self:center;font-size:11px;color:var(--pending);border:1px solid var(--pending);border-radius:6px;padding:2px 8px";
+      "align-self:center;font:var(--t-caption)/1.4 var(--font-mono);color:var(--pending);border:1px solid var(--pending);border-radius:var(--r-ctl);padding:2px 8px";
     bar.appendChild(pill);
   }
   opsApply = ops.find((o) => o.kind === "apply") ?? null;
@@ -2451,7 +3420,7 @@ async function initActions() {
   // its deploy path is Apply all, not committed Ops).
   if (ops.length === 0 && !previewMode && !opsInitialEnv) {
     const hint = document.createElement("span");
-    hint.style.cssText = "color:var(--muted);font-size:11px;align-self:center";
+    hint.style.cssText = "color:var(--muted);font-size:var(--t-caption);align-self:center";
     hint.textContent = "no Ops — commit an *.op.ts (ApplyOp / ReconcileOp / any deploy Op) to act";
     hint.title = "behold triggers committed Ops on your executor. Add one to enable Deploy / Adopt / Run.";
     bar.appendChild(hint);
@@ -2520,7 +3489,7 @@ events.addEventListener("pr", (e) => {
     slot.id = "pr-link";
     slot.target = "_blank";
     slot.rel = "noopener";
-    slot.style.cssText = "color:var(--managed);text-decoration:none;font-size:12px;align-self:center";
+    slot.style.cssText = "color:var(--managed);text-decoration:none;font-size:var(--t-body);align-self:center";
     document.getElementById("actions").after(slot);
   }
   slot.href = url;
@@ -2582,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) {