@intentius/behold 0.18.0 → 0.20.0

package/web/app.js

@@ -8,6 +8,9 @@
 // floating control panel's chrome (panel.js — drag/snap/collapse/tabs, persisted
 // 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 { createRefreshQueue } from "./refresh-queue.js";
+import { readCostLine } from "./read-cost.js";
+import { applyMemberFrame, pendingLine, stillPending } from "./pending.js";
 import { initTheme, mountThemePicker, readableOn, colorForCategory, onThemeChange, getTokens, getTheme, pinTokensFor } from "./theme.js";
 // #399 M2 / #401 M4 of #397: the colour-by modes' arithmetic and the
 // provenance badge's wording — every decision the behaviour overlay makes,
@@ -32,6 +35,7 @@ import {
   scaleEnds,
   totalsFor,
   totalsText,
+  deltaRows,
 } from "./behaviour-scale.js";
 import { addPanelTab, initPanel, setPanelTab, togglePanelCollapsed, isPanelCollapsed } from "./panel.js";
 // #254: the carve walkthrough's stepper — everything it DECIDES is a pure
@@ -199,6 +203,12 @@ function recolorNodesByCategory(ir) {
     // unpriced count has to agree with what is on the canvas.
     if (plan.mode !== "drift" && paint.unpriced) g.setAttribute("data-unpriced", "1");
     else g.removeAttribute("data-unpriced");
+    // #429: and the card an overlay never observed because its member has no
+    // live half. Only on an overlay: on the source graph NO card has a status
+    // and the mark would be on every one of them, saying nothing.
+    const onOverlay = !!(lastMeta && lastMeta.env);
+    const node = graphIr.nodes.find((n) => n.id === id);
+    g.toggleAttribute("data-no-live", onOverlay && !!node && !(node.attrs && node.attrs._status));
     // Classify each element ONCE by the pinhole token it rode on (data-cat role), then apply
     // the role's colour on every pass. This is what makes it recolour on theme switch: after
     // the first pass the fill is a hex (not a --pin-* var), so we must key off the marker, not
@@ -282,11 +292,11 @@ if (staticMode) {
 
 /** Canonical key for a read URL — path + the lens params (whitelisted, sorted)
  * that select a distinct snapshot. MUST match src/export.ts `canonicalKey`. */
-const LENS_PARAMS = ["collapse", "components", "detail", "env", "logical", "ops", "radial", "runtime", "tier"];
+const LENS_PARAMS = ["collapse", "components", "detail", "env", "logical", "ops", "radial", "runtime", "stacks", "tier"];
 function canonicalKey(path, params) {
   // Components + logical + ops views ignore detail/radial — drop them so they
   // match the single captured snapshot (MUST match src/export.ts).
-  const flat = params.get("components") === "1" || params.get("logical") === "1" || params.get("ops") === "1";
+  const flat = params.get("components") === "1" || params.get("logical") === "1" || params.get("ops") === "1" || params.get("stacks") === "1";
   const q = LENS_PARAMS.filter((k) => params.has(k) && !(flat && (k === "detail" || k === "radial")))
     .map((k) => `${k}=${params.get(k)}`)
     .join("&");
@@ -329,6 +339,29 @@ function vocabularyNote() {
   const v = lastMeta && lastMeta.vocabulary;
   return (v && v.note) || "";
 }
+// #396 item 5: the inspect pane's LIVE section prints `ownership` raw, and
+// `ownership` is a word two different readers write into the same field.
+// chant's live reader answers it from the resource's own marker — `owned` /
+// `foreign`, which is chant's contract for that field (chant graph-ir.d.ts).
+// src/choudoufu-live.ts has no marker to read: it writes the same two words for
+// choudoufu's `bound[]` and `unowned[]`, so an unowned card read `status:
+// unowned` and, two rows below it, `ownership: foreign` — chant's word for
+// choudoufu's state, the last of the four #393 item 8 did not reach.
+//
+// So this row joins the legend, the counts and the status row in being rendered
+// through the estate's own vocabulary rather than printed. Translated ONLY when
+// the estate's members are all of a kind that has its own words for these
+// colours (`vocabulary.of`): on a chant estate, and on a mixed one — which
+// keeps chant's words on the legend by design and says so in its tooltip — the
+// value is printed exactly as it is today, which is the point. The mapping is
+// value → the colour that value means → that colour's word, so it needs no
+// table of its own beyond the two words chant's field can hold.
+const OWNERSHIP_STATUS = { owned: "good", foreign: "warn" };
+function ownershipLabel(value) {
+  const v = lastMeta && lastMeta.vocabulary;
+  if (!v || !v.labels || !v.of || v.of === "chant" || v.of === "mixed") return value;
+  return v.labels[OWNERSHIP_STATUS[value]] || value;
+}
 // #404: whether a plan was read for this overlay, and how many cards it would
 // change. `{read: false}` and `{read: true, drifted: 0}` are DIFFERENT answers
 // — "nobody looked" versus "looked, nothing drifted" — and the legend must not
@@ -695,6 +728,15 @@ function inspect(node) {
   // statement about this entity is legible — and where a figure without its
   // provenance would be visible as the contract violation it is.
   renderBehaviourSection(section, blockOf(node));
+  // #402: what the FILE says this entity costs, beside what the account does.
+  // On a card the account no longer holds this is the only behaviour row, and
+  // it says so rather than reading as the card's cost.
+  const declared = node.attrs && node.attrs._behaviourDeclared;
+  if (declared && declared.cost) {
+    const add = section("behaviour · declared");
+    add("cost", figureWithBadge(fmtCost(declared.cost.perHour, declared.cost.currency), [declared], behaviourMeta()));
+    if (!blockOf(node)) add("live", "no live figure — the prediction of the account does not include this entity");
+  }
 
   // Render diff (#146's deferred half): what `chant helm diff <digest> <env>
   // --live --json` said about this chart's PINNED render. Never rely on the
@@ -708,7 +750,7 @@ function inspect(node) {
   if (node.physicalId || node.ownership) {
     const live = section("live");
     if (node.physicalId) live("physical id", node.physicalId);
-    if (node.ownership) live("ownership", node.ownership);
+    if (node.ownership) live("ownership", ownershipLabel(node.ownership)); // #396 item 5: the estate's own word for it
   } else if (liveStatus) {
     // The colour alone doesn't carry chant's verdict or its reasoning — spell
     // both out here (never rely on the node's colour alone, #57 accessibility
@@ -826,15 +868,22 @@ function inspect(node) {
   const attrKeys = Object.keys(node.attrs || {}).filter((k) => !k.startsWith("_") && !(k === "release" && release));
   if (attrKeys.length) {
     const decl = section("declared");
-    // #393 item 10: an UNOWNED choudoufu card leads with the write that adopts
-    // the object — the two marker tags choudoufu named (`adopt_tofu_estate` /
-    // `adopt_tofu_address`), or its own one-line command if a release ever
-    // sends one. behold composes neither (src/choudoufu-live.ts); this puts
-    // the line first and makes it copyable, the way the moves panel already
-    // does for a `live-mv` line. The paragraph explaining the omission — which
-    // used to be the whole section, with the tags under it as JSON — follows.
+    // #393 item 10: a choudoufu card that can be adopted leads with the write
+    // that does it — the two marker tags choudoufu named (`adopt_tofu_estate` /
+    // `adopt_tofu_address`), or its own one-line command when it sends one.
+    // behold composes neither (src/choudoufu-live.ts); this puts the line
+    // first and makes it copyable, the way the moves panel already does for a
+    // `live-mv` line. The paragraph explaining the omission follows.
+    //
+    // #413: both kinds reach here now. An UNOWNED row carries the marker pair,
+    // and an adoptable one carries choudoufu's own command — so the tooltip
+    // says which of the two this is rather than claiming tags either way.
     const adoptable = node.lexicon === "choudoufu" && typeof node.attrs.adopt === "string" ? "adopt" : null;
-    if (adoptable) copyableRow(decl, adoptable, node.attrs.adopt, "Copy the tags that adopt this object");
+    if (adoptable) {
+      const isCommand = /\s/.test(node.attrs.adopt.trim()) && !node.attrs.adopt.startsWith("tofu-estate=");
+      copyableRow(decl, adoptable, node.attrs.adopt,
+        isCommand ? "Copy the command that adopts this object" : "Copy the tags that adopt this object");
+    }
     for (const k of attrKeys) {
       if (k === adoptable) continue;
       decl(k, fmtValue(node.attrs[k]));
@@ -994,7 +1043,7 @@ function renderObserved(panel, o, health, healthDetail) {
   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);
-  if (o.ownership) add("ownership", o.ownership);
+  if (o.ownership) add("ownership", ownershipLabel(o.ownership)); // #396 item 5: same, off /api/diff
   if (o.lastUpdated) add("last updated", o.lastUpdated);
   // What the object's own controller says is wrong with it (#86, chant#1401).
   // Placed with health and status rather than among the attributes below,
@@ -1259,6 +1308,13 @@ const ZOOM_OPTS = [
   // same chant source), so it sits last, and only appears when the served
   // estate has actually emitted Ops — `opsAvailable`, from /api/project.
   ["zoom: ops", "ops"],
+  // The apply order (#426): the cross-stack ordering chant already computes at
+  // synthesis — which lexicon partition must apply before which. A different
+  // axis again, like `ops`: neither coarser nor finer than a resource, and the
+  // only stop whose edges are about TIME rather than reference. Single-project
+  // only and gated on `stacksCapable`, because two members' `aws` stacks are
+  // not one stack.
+  ["zoom: apply order", "stacks"],
 ];
 const ZOOM_DETAIL = { composites: 1, resources: 2, attributes: 3, runtime: 3 };
 /** How many emitted Ops the served estate has (0 = the stop doesn't exist).
@@ -1271,18 +1327,28 @@ let opsAvailable = 0;
  * Kubernetes tier that could only ever answer "nothing below the declaration
  * boundary". */
 let runtimeCapable = false;
+/** #422: the members whose live read has not landed yet, off the progressive
+ * overlay's `meta.pending`. Empty on every non-progressive load, which is every
+ * single-project serve and every static snapshot. */
+let pendingMembers = [];
+let pendingTotal = 0;
+/** #426: whether the apply-order stop is worth offering — /api/project's
+ * `stacksCapable`, which is false for an estate and for a single-lexicon
+ * project, where the answer could only ever be one box. */
+let stacksCapable = false;
 /** The zoom stops this project can actually offer — `runtime` needs an env AND
  * a member whose substrate has an owner chain, `ops` needs emitted op.json
  * files. Both the panel and ⌘K read this, so a stop never appears in one
  * surface and not the other. */
 function availableZooms() {
-  return ZOOM_OPTS.filter(([, z]) => (z === "runtime" ? Boolean(view.env) && runtimeCapable : z === "ops" ? opsAvailable > 0 : true));
+  return ZOOM_OPTS.filter(([, z]) => (z === "runtime" ? Boolean(view.env) && runtimeCapable : z === "ops" ? opsAvailable > 0 : z === "stacks" ? stacksCapable : true));
 }
 /** Current zoom value from (components, logical, ops, detail). */
 function zoomValue() {
   if (view.components) return "components";
   if (view.logical) return "logical";
   if (view.ops) return "ops";
+  if (view.stacks) return "stacks";
   if (view.runtime) return "runtime";
   return { 1: "composites", 2: "resources", 3: "attributes" }[view.detail] ?? "resources";
 }
@@ -1291,8 +1357,9 @@ function applyZoom(z) {
   view.components = z === "components";
   view.logical = z === "logical";
   view.ops = z === "ops";
+  view.stacks = z === "stacks";
   view.runtime = z === "runtime";
-  if (z !== "components" && z !== "logical" && z !== "ops") view.detail = ZOOM_DETAIL[z] ?? 2;
+  if (z !== "components" && z !== "logical" && z !== "ops" && z !== "stacks") view.detail = ZOOM_DETAIL[z] ?? 2;
 }
 
 // --- Floating control panel content ---------------------------------------
@@ -1539,12 +1606,21 @@ function renderCarveState(host, state) {
  */
 function copyableRow(add, key, text, title) {
   const wrap = document.createElement("span");
-  wrap.style.cssText = "display:flex;gap:6px;align-items:baseline;min-width:0";
+  // `center`, not `baseline`: an `overflow: hidden` flex item takes its bottom
+  // margin edge as its baseline, so the clipped line below would have dragged
+  // the copy button down with it.
+  wrap.style.cssText = "display:flex;gap:6px;align-items:center;min-width:0";
   const line = document.createElement("code");
   line.className = "grow";
-  line.style.cssText = "flex:1;min-width:0;overflow-wrap:anywhere";
+  // #396 item 7c: ONE line, clipped. `tofu-estate=… tofu-address=…` wrapped
+  // onto three lines in the 260px pane and pushed everything the card had to
+  // say off the bottom — for a string nobody reads off the screen anyway,
+  // because the copy button beside it is how it gets used. The whole of it is
+  // on this row's tooltip, on the button's, and in the clipboard.
+  line.style.cssText = "flex:1;min-width:0;white-space:nowrap;overflow:hidden;text-overflow:ellipsis";
   line.textContent = text;
-  const copy = actButton("copy", () => copyToClipboard(text, copy), title);
+  line.title = text;
+  const copy = actButton("copy", () => copyToClipboard(text, copy), title ? `${title}:\n${text}` : text);
   wrap.append(line, copy);
   add(key, wrap);
 }
@@ -1676,6 +1752,35 @@ function renderBehaviourTotals(host) {
   // precedence in one place rather than at each call site.
   row(b.total ? "estate · engine total" : "estate", all, b.sum, b.total, b.total ? "the engine stated this estate total itself; behold added nothing" : "behold's sum over the engine's per-entity figures");
   if (mode === "headroom") host.appendChild(panelMuted("min and median computed by behold over the engine's per-entity figures — no engine states a headroom aggregate."));
+  if (mode === "cost") renderBehaviourDelta(host, b);
+}
+
+/**
+ * Live versus declared (#402): what the account costs as it stands, what the
+ * file says it should, and the difference. Present only when the overlay was
+ * asked for at a traffic level, because both figures are predictions *at* one.
+ * The wording of every row is `deltaRows`' (web/behaviour-scale.js).
+ */
+function renderBehaviourDelta(host, b) {
+  const rows = deltaRows(b);
+  if (!rows.length) return;
+  host.appendChild(panelHeading(`live versus declared${b.at ? ` · at ${b.at.traffic}` : ""}`));
+  for (const t of rows) {
+    const r = document.createElement("div");
+    r.className = "behaviour-total";
+    const name = document.createElement("div");
+    name.className = "grow";
+    name.style.fontWeight = "600";
+    name.textContent = t.label;
+    r.appendChild(name);
+    for (const [word, text] of [["live", t.live], ["declared", t.declared], ["delta", t.delta]]) {
+      const line = document.createElement("div");
+      line.textContent = `${word} ${text}`;
+      r.appendChild(line);
+    }
+    host.appendChild(r);
+  }
+  host.appendChild(panelMuted("delta is live minus declared. A negative one means the account holds less than the file declares."));
 }
 
 function renderPanelScope() {
@@ -2073,6 +2178,23 @@ function renderPanelModel() {
     // bound and is already counted on the row above. The row appears only when
     // a plan was actually read; where it was not, the legend says so in words
     // and prints no number, because "0 drifted" would be a claim nobody made.
+    // #429: a card with NO `_status` at all. pinhole's painter falls back to
+    // `neutral` for an unrecognised value, `undefined` included, so a member
+    // with no live half — a Terraform root, whose `live`/`overlay`/`env` are
+    // stripped in src/terraform-member.ts — paints exactly like a card behold
+    // looked at and could not see. It is in no legend bucket either, so the
+    // colour claimed 37 unobserved cards on an estate whose legend counted 2.
+    //
+    // Named rather than folded into `unobserved`, because they are different
+    // claims: "I looked and could not see" against "there is nothing here to
+    // look at". Same argument #399 makes for an unpriced card, and the same
+    // answer — mark it, do not merely colour it.
+    const noLive = ir.nodes.filter((n) => !(n.attrs && n.attrs._status)).length;
+    if (noLive) {
+      const row = panelDotRow("var(--muted)", "no live half", String(noLive));
+      row.title = "These members declare no live half, so nothing observed them — which is not the same as unobserved, and not the same as absent.";
+      host.appendChild(row);
+    }
     const dm = driftMeta();
     if (dm && dm.read) {
       host.appendChild(panelDotRow("var(--degraded)", "drifted (the plan would change it)", String(dm.drifted)));
@@ -2462,6 +2584,36 @@ function markOperatorCards(ir) {
  * estates this can appear on the corner is free; the guard below still skips a
  * card that already carries one of those, rather than drawing over it.
  */
+/**
+ * The cards whose member is still being read (#422).
+ *
+ * The same post-render stamp `markCarvedCards`/`markDriftedCards` use, and for
+ * the same reason: pinhole's SVG arrives as a string and is replaced on every
+ * render, so a mark is re-applied here rather than asked for at layout time.
+ *
+ * A dashed outline and a muted corner rather than a fill, because the fill is
+ * the status channel and this card HAS no status yet — painting one would be
+ * the claim the whole milestone exists to avoid. `_pendingRead` rides its own
+ * attr for the same reason: a fifth `_status` value falls back to neutral in
+ * pinhole's painter, which reads as "unobserved", which is a different and
+ * wrong thing.
+ */
+function markPendingCards(ir) {
+  const svg = document.querySelector("#graph svg");
+  if (!svg) return;
+  for (const n of (ir && ir.nodes) || []) {
+    const g = svg.querySelector('[data-node-id="' + CSS.escape(n.id) + '"]');
+    if (!g) continue;
+    const pending = !!(n.attrs && n.attrs._pendingRead);
+    g.toggleAttribute("data-pending-read", pending);
+    if (pending && !g.querySelector("title")) {
+      const t = document.createElementNS("http://www.w3.org/2000/svg", "title");
+      t.textContent = "still reading this member — not yet observed";
+      g.appendChild(t);
+    }
+  }
+}
+
 function markDriftedCards(ir) {
   const svg = document.querySelector("#graph svg");
   if (!svg) return;
@@ -2559,6 +2711,11 @@ function renderStatusbar() {
   if (view.stack) parts.push(`stack: ${view.stack}`);
   if (axes.tier) parts.push(`tier: ${axes.tier}`);
   if (view.radial && !view.components && !view.logical && !view.ops) parts.push("radial");
+  // #422: what the picture is still waiting on, while it is waiting. Ahead of
+  // the zoom note, because a half-read estate is the more urgent fact about
+  // what is on screen.
+  const stillReading = pendingLine(pendingMembers, pendingTotal);
+  if (stillReading) parts.push(stillReading);
   el.textContent = parts.join(" · ");
   // #131: why this level rendered empty, or as the one below it. The server
   // decides (src/zoom-notes.ts) — the SPA never infers it, so the note always
@@ -3388,6 +3545,7 @@ function render(ir, svg, m) {
   markPlayhead(ir); // #284 item 2: same, for the step the run is sitting on
   markOperatorCards(ir); // #234 free rider: same, for the operating loop's home
   markDriftedCards(ir); // #404: same, for a bound card the plan would change — after the carve/operator stamps, so it can see and yield to them
+  markPendingCards(ir); // #422: and the cards whose member has not answered yet
   applyLayout(); // #228: last, so the hand-placed deltas ride on top of every other pass
   renderDial();
 }
@@ -3483,7 +3641,13 @@ function setupGraphViewBox(svg) {
   const a = (svg.getAttribute("viewBox") || "").split(/\s+/).map(Number);
   if (a.length === 4 && a.every((n) => !Number.isNaN(n))) {
     vbInit = a.slice();
-    vb = a.slice();
+    // #396 item 2: land on the fit that keeps the panel's footprint clear, not
+    // on the raw box — a re-render (a zoom change, an env change, the SSE
+    // re-pull) goes through here and never through fitGraph, so the first
+    // column would slide back under the panel at every one of them.
+    vb = fittedViewBox() || a.slice();
+    vbAtFit = true;
+    applyVB();
   } else {
     vbInit = vb = null;
   }
@@ -3494,11 +3658,178 @@ function currentSvg() {
 function applyVB() {
   const s = currentSvg();
   if (s && vb) s.setAttribute("viewBox", vb.join(" "));
+  scaleBoxLabels(); // #396 item 7b: box titles/badges keep a legible size at every zoom
+}
+
+// #396 item 2: the panel is `position: fixed` and floats OVER the graph pane
+// (index.html), so "fit the pane" put the leftmost column of cards underneath
+// it — a whole column of the terralith, half waterpark's `github` box — at
+// boot and after every re-render. The panel is furniture the reader cannot see
+// through, so the fit's target is the pane MINUS whatever the panel is
+// currently covering.
+//
+// Read at fit time, never remembered: the panel drags, docks to either side and
+// collapses to its tab bar, and a fit computed against where it used to be is
+// the same bug with a different offset. Collapsed or hidden → no footprint, and
+// the fit is the whole pane exactly as before.
+//
+// Horizontal only. The panel is a tall palette that docks left or right; a
+// top/bottom dock still leaves the full width, and insetting vertically for it
+// would shrink the graph for a strip the cards mostly clear anyway.
+const FIT_PANEL_MAX = 0.45; // the panel can never claim more than this of the pane
+
+function panelInsets(pane) {
+  const none = { left: 0, right: 0 };
+  const p = document.getElementById("panel");
+  if (!p || p.classList.contains("collapsed")) return none;
+  const cs = getComputedStyle(p);
+  if (cs.display === "none" || cs.visibility === "hidden" || Number(cs.opacity) === 0) return none;
+  const r = p.getBoundingClientRect();
+  if (!r.width || !r.height) return none;
+  // Nothing to inset for a panel that has been dragged clear of the graph pane.
+  if (r.bottom <= pane.top || r.top >= pane.bottom || r.right <= pane.left || r.left >= pane.right) return none;
+  const cap = pane.width * FIT_PANEL_MAX;
+  // Whichever side it is nearer to is the side it eats.
+  return (r.left + r.right) / 2 < (pane.left + pane.right) / 2
+    ? { left: Math.min(cap, Math.max(0, r.right - pane.left)), right: 0 }
+    : { left: 0, right: Math.min(cap, Math.max(0, pane.right - r.left)) };
+}
+
+/**
+ * The viewBox that fits the whole graph into the pane's UNCOVERED part.
+ *
+ * The returned box is given the pane's own aspect ratio, so `xMidYMid meet`
+ * letterboxes nothing and the pane's pixels map to viewBox units at one known
+ * scale: the graph is then placed by arithmetic — centred inside the band
+ * between the insets, centred vertically — instead of wherever `meet` would
+ * have dropped it. With no insets the result is pixel-identical to the old
+ * `vb = vbInit`, which is why nothing without a panel over it moves.
+ */
+function fittedViewBox() {
+  if (!vbInit) return null;
+  const host = document.getElementById("graph");
+  if (!host) return null;
+  const pane = host.getBoundingClientRect();
+  const [x0, y0, w0, h0] = vbInit;
+  if (!(pane.width > 0 && pane.height > 0 && w0 > 0 && h0 > 0)) return null;
+  const { left, right } = panelInsets(pane);
+  const band = Math.max(1, pane.width - left - right);
+  const s = Math.min(band / w0, pane.height / h0);
+  const vw = pane.width / s;
+  const vh = pane.height / s;
+  return [x0 - left / s - (band / s - w0) / 2, y0 - (vh - h0) / 2, vw, vh];
 }
+
 function fitGraph() {
-  if (vbInit) {
-    vb = vbInit.slice();
-    applyVB();
+  if (!vbInit) return;
+  vb = fittedViewBox() || vbInit.slice();
+  vbAtFit = true;
+  applyVB();
+}
+
+// #396 item 2: the fit now depends on the pane — its size, and what the panel
+// covers of it — where `vbInit` alone depended on neither, so a graph sitting
+// at fit has to be re-fitted when the pane moves under it. It moves more often
+// than a window resize: the statusbar's note wraps onto a second line, the
+// inspect pane is dragged wider, a panel tab's content grows. Only while the
+// view IS the fit: a pan or a zoom takes ownership of the viewBox, and nothing
+// here may pull it back out from under the reader's hands.
+let vbAtFit = false;
+function watchPaneForFit(host) {
+  if (typeof ResizeObserver === "undefined") return;
+  new ResizeObserver(() => {
+    if (vbAtFit) fitGraph();
+  }).observe(host);
+}
+
+// --- #396 item 7b: box titles and badges that survive the fit ---------------
+//
+// pinhole draws a group box's title at a flat `font-size="12"` and its badge at
+// `11`, in viewBox UNITS. That reads as 12px on a graph whose fit is 1:1 and as
+// 7px on terralith-4, whose box is 8000 units wide — the one label that says
+// which member 301 cards belong to, and the one that counts them, are the two
+// things on the canvas a person cannot read at the zoom they arrive at.
+//
+// So the label is given a floor in SCREEN pixels: its size in units is raised
+// by the inverse of the current scale until it renders at its natural size, and
+// never below it, so anything already legible is untouched (zoomed IN, the
+// attribute is left at 12 and grows with the graph, exactly as before). The
+// anchor never moves — x, y and `text-anchor` are pinhole's — so a title stays
+// welded to its box's top-left corner and a badge to its top-right through
+// every pan and zoom; only the type gets bigger.
+//
+// The floor yields to the box: a label may not grow past a fraction of the
+// box's height, nor past its width. A sub-box too small to hold readable type
+// at this zoom says so by staying small, rather than by writing across its
+// neighbours.
+const BOX_LABEL_GUTTER = 34; // units below a box's top edge that the title row occupies
+const BOX_LABEL_MAX_H = 8; // a label may be at most box height / this
+const BOX_LABEL_EM = 0.62; // rough advance width per char, as a fraction of the size
+
+let boxLabelCache = { svg: null, labels: [] };
+let boxLabelScale = null;
+
+/** The `<text>` elements pinhole put in each group box's title gutter, with the
+ * box they belong to and the size it drew them at. Matched by geometry rather
+ * than by sibling order: a box's optional identity mark sits between the title
+ * and the badge, and #228's layout pass lifts the rect and its title into a
+ * wrapper `<g>` after the render, so neither order nor a common parent holds.
+ * What geometry alone would let through — a card's own text, an edge chip's —
+ * is excluded by the ancestor it sits under. */
+function boxLabelsOf(svg) {
+  if (boxLabelCache.svg === svg) return boxLabelCache.labels;
+  const labels = [];
+  const boxes = [];
+  for (const rect of svg.querySelectorAll("rect[data-group-id]")) {
+    const b = {
+      x: parseFloat(rect.getAttribute("x")),
+      y: parseFloat(rect.getAttribute("y")),
+      w: parseFloat(rect.getAttribute("width")),
+      h: parseFloat(rect.getAttribute("height")),
+    };
+    if ([b.x, b.y, b.w, b.h].every((n) => Number.isFinite(n))) boxes.push(b);
+  }
+  if (boxes.length) {
+    for (const t of svg.querySelectorAll("text")) {
+      const x = parseFloat(t.getAttribute("x"));
+      const y = parseFloat(t.getAttribute("y"));
+      // pinhole's own size, stashed the first time so a re-index can never
+      // read a size this pass already raised as if it were the natural one.
+      const base = parseFloat(t.dataset.pinFont ?? t.getAttribute("font-size"));
+      if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(base)) continue;
+      // Not a card's own text (inside its `g[data-node-id]`), not an edge
+      // chip's (inside the edge's `g`), not a radial wedge label behold adds
+      // itself. What is left at a box's title row IS the box's title row.
+      if (t.closest("[data-node-id], [data-edge-from], [data-edge-to], #radial-labels")) continue;
+      const box = boxes.find((b) => y > b.y && y <= b.y + BOX_LABEL_GUTTER && x >= b.x - 2 && x <= b.x + b.w + 2);
+      if (!box) continue;
+      t.dataset.pinFont = String(base);
+      labels.push({ el: t, box, base });
+    }
+  }
+  boxLabelCache = { svg, labels };
+  boxLabelScale = null;
+  return labels;
+}
+
+/** Re-size every box label for the current zoom. Cheap and idempotent: the
+ * scale is remembered, so the pan handler's stream of `applyVB` calls (which
+ * move the viewBox without changing its width) touches no attribute at all. */
+function scaleBoxLabels() {
+  const svg = currentSvg();
+  if (!svg || !vb) return;
+  const labels = boxLabelsOf(svg);
+  if (!labels.length) return;
+  const pane = svg.getBoundingClientRect();
+  if (!(pane.width > 0 && pane.height > 0)) return;
+  const scale = Math.min(pane.width / vb[2], pane.height / vb[3]);
+  if (!(scale > 0) || scale === boxLabelScale) return;
+  boxLabelScale = scale;
+  for (const l of labels) {
+    const chars = Math.max(4, (l.el.textContent || "").length);
+    const cap = Math.max(l.base, Math.min(l.box.h / BOX_LABEL_MAX_H, l.box.w / (chars * BOX_LABEL_EM)));
+    const size = Math.max(l.base, Math.min(l.base / scale, cap));
+    l.el.setAttribute("font-size", String(Math.round(size * 10) / 10));
   }
 }
 
@@ -3537,6 +3868,7 @@ function revealNode(id) {
   const w = Math.min(vbInit[2], Math.max(box.width * REVEAL_CARDS_ACROSS, vbInit[2] / 60));
   const h = w * (vbInit[3] / vbInit[2]);
   vb = [box.x + box.width / 2 - w / 2, box.y + box.height / 2 - h / 2, w, h];
+  vbAtFit = false;
   applyVB();
   return true;
 }
@@ -3555,6 +3887,7 @@ function ensureZoomControls(host) {
   }
   if (zoomWired) return;
   zoomWired = true;
+  watchPaneForFit(host);
   host.addEventListener(
     "wheel",
     (e) => {
@@ -3576,6 +3909,7 @@ function ensureZoomControls(host) {
       vb[1] = cy - ((cy - vb[1]) * nh) / vb[3];
       vb[2] = nw;
       vb[3] = nh;
+      vbAtFit = false;
       applyVB();
     },
     { passive: false },
@@ -3608,6 +3942,7 @@ function ensureZoomControls(host) {
     }
     vb[0] -= (dx / r.width) * vb[2];
     vb[1] -= (dy / r.height) * vb[3];
+    vbAtFit = false;
     px = e.clientX;
     py = e.clientY;
     applyVB();
@@ -4211,7 +4546,8 @@ function renderPreconditionError(body) {
 }
 
 // Fetch the current view (source graph, or the picked env's live overlay).
-async function load(opts = {}) {
+const load = createRefreshQueue(loadOnce);
+async function loadOnce(opts = {}, isCurrent = () => true) {
   const meta = document.getElementById("meta");
   // A background settle re-pull (post-apply) shouldn't flash the meta/overlay.
   if (!opts.quiet) {
@@ -4230,6 +4566,14 @@ async function load(opts = {}) {
       // cross-substrate entity overlay, which components never use.
       q.set("components", "1");
       if (view.env) q.set("env", view.env);
+    } else if (view.stacks) {
+      // The apply-order lens (#426): chant's cross-stack ordering, built fresh
+      // for the same reason the ops lens is — it reads none of the entity
+      // knobs. No env (it is computed at synthesis, with no substrate), no
+      // detail, no radial. Tier rides along because a project's source can
+      // branch on one, which can change which lexicons it partitions into.
+      q = new URLSearchParams({ stacks: "1" });
+      if (view.tier) q.set("tier", view.tier);
     } else if (view.ops) {
       // The ops lens (#284): the declared Ops, read from each Op's emitted
       // op.json. Built fresh rather than layered onto the entity lenses,
@@ -4263,6 +4607,11 @@ async function load(opts = {}) {
     } else if (view.env) {
       endpoint = "/api/overlay";
       q.set("env", view.env);
+      // #422: draw the estate from source at once and recolour each member as
+      // its own live read lands, instead of a blank canvas until the slowest
+      // one finishes. The server only honours it for a composed estate, and
+      // never in a static snapshot, where there is no stream to follow.
+      if (!staticMode) q.set("progressive", "1");
       // The runtime tier (#86) descends below the declaration boundary. It is
       // live-only by nature — owner-referenced children exist in the cluster,
       // never in your source — so it rides the overlay and means nothing
@@ -4294,6 +4643,7 @@ async function load(opts = {}) {
     }
     const res = await apiFetch(`${endpoint}?${q}`);
     const body = await res.json();
+    if (!isCurrent()) return; // a newer view/event is pending; do not paint the old result
     if (!res.ok) {
       // #72: a classified precondition failure (lint gate, not installed, a
       // tier that needs credentials) gets the calmer entry/error card instead
@@ -4314,13 +4664,19 @@ async function load(opts = {}) {
       autoZoomFallback = false;
       applyZoom("resources");
       renderStatusbar();
-      return load(opts);
+      return loadOnce(opts, isCurrent);
     }
     autoZoomFallback = false;
+    // #422: a progressive answer names the members it is still reading, and
+    // the `member` stream above clears them one at a time. Any other answer
+    // resets it, so a switch away from a progressive load never leaves a stale
+    // "still reading" claim on screen.
+    pendingMembers = body.meta && body.meta.mode === "progressive" ? [...(body.meta.pending || [])] : [];
+    pendingTotal = pendingMembers.length;
     render(body.ir, body.svg, body.meta);
   } catch (err) {
     // A background settle poll must not blow away a good graph on a transient error.
-    if (!opts.quiet) {
+    if (!opts.quiet && isCurrent()) {
       // 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).
@@ -4434,6 +4790,7 @@ async function initPickers() {
   // honestly open. Both are read before the first load() below, so a non-chant
   // estate never paints the components apology on its way to a picture.
   runtimeCapable = !!info.runtimeCapable;
+  stacksCapable = !!info.stacksCapable;
   const boot = bootZoom(info.memberKinds);
   if (boot !== "components") {
     applyZoom(boot);
@@ -4460,20 +4817,39 @@ initPickers();
 // No backend in a static export → no live event stream; a no-op keeps the
 // `events.addEventListener(...)` wiring below harmless.
 const events = staticMode ? { addEventListener() {} } : new EventSource("/api/events");
-// Post-op settle re-pull: an apply's CLI can exit while the last stacks are still
-// flipping to *_COMPLETE, so the immediate reload catches a few components mid-
-// deploy ("all done, 3 still pending"). Quietly re-pull a couple more times so
-// the graph lands on the final colours without a manual Re-check live.
-let settleTimers = [];
-function scheduleSettle() {
-  settleTimers.forEach(clearTimeout);
-  settleTimers = [3000, 8000, 15000].map((ms) => setTimeout(() => load({ quiet: true }), ms));
-}
+// One notification requests one refresh. Further notifications during a slow
+// read collapse to one follow-up; no wall-clock timers multiply estate scans.
+// #422: one frame per member as its live read settles. Payload-carrying, like
+// `apply` and `run` — the node set is already on screen, so this is id ->
+// status and the client repaints in place. Nothing is re-fetched: a refetch
+// here would re-run the whole estate read this stream exists to narrate.
+events.addEventListener("member", (e) => {
+  let frame;
+  try {
+    frame = JSON.parse(e.data);
+  } catch {
+    return;
+  }
+  // The live pass itself failed. Say so on the now-line and stop claiming the
+  // remaining members are still arriving, because nothing more is coming.
+  if (frame.error) {
+    pendingMembers = [];
+    nowline(`the estate read failed — ${frame.error}`);
+    renderStatusbar();
+    return;
+  }
+  if (!lastGraphIr) return;
+  const moved = applyMemberFrame(lastGraphIr, frame);
+  pendingMembers = stillPending(pendingMembers, frame);
+  if (moved.length) recolorNodesByCategory(lastGraphIr);
+  markPendingCards(lastGraphIr);
+  renderStatusbar();
+});
+
 events.addEventListener("changed", () => {
   bulkDiffCache = null; // an op ran → per-node live state may have changed
   load();
   loadSubstrates(); // a bring-up (or any op) finished → re-detect readiness
-  scheduleSettle();
 });
 
 // Substrate readiness (M5, #54): is each substrate the project needs actually
@@ -4610,11 +4986,19 @@ setInterval(() => {
 // can't fire a second pull while one's in flight. Ref-counted — nested loads
 // (graph + CI + resources) only lift the scrim when the last finishes.
 let loadingDepth = 0;
+// #421: what the LAST read cost, shown while this one runs. The person watching
+// the scrim wants to know whether to wait or go away, and behold has never told
+// them. Fetched after a load settles rather than during one — asking the server
+// how slow it is while it is being slow helps nobody — so the line always
+// describes the previous read and never guesses at this one.
+let lastReadCost = null;
 function showLoading(msg) {
   loadingDepth++;
   const o = document.getElementById("loading-overlay");
   if (!o) return;
   document.getElementById("loading-msg").textContent = msg || "loading…";
+  const cost = document.getElementById("loading-cost");
+  if (cost) cost.textContent = lastReadCost || "";
   o.hidden = false;
 }
 function hideLoading() {
@@ -4622,6 +5006,27 @@ function hideLoading() {
   if (loadingDepth > 0) return;
   const o = document.getElementById("loading-overlay");
   if (o) o.hidden = true;
+  void refreshReadCost();
+}
+
+// One cheap call on counters, never on the read path. `?reads=1` is what makes
+// that true: the bare route also runs the full doctor diagnosis, whose substrate
+// probes spawn docker/gh/helm/k3d with no timeout, and this runs after every
+// load settles. A cost line is never worth breaking a load over, so every
+// failure here leaves the previous line standing.
+//
+// A static export has no backend to ask and no reads to report, so it does not
+// ask. Without this guard the bundle logs a 404 on every page load and relies on
+// the fetch failing to stay silent, which is an outcome rather than a rule.
+async function refreshReadCost() {
+  if (staticMode) return;
+  try {
+    const res = await fetch("/api/doctor?reads=1");
+    if (!res.ok) return;
+    lastReadCost = readCostLine((await res.json()).reads);
+  } catch {
+    /* no line rather than a wrong one */
+  }
 }
 
 // #259: the op stream is chant's own stdout, and an Op that reports as JSON