@intentius/behold 0.17.0 → 0.19.0

package/web/cross-env.js

@@ -0,0 +1,58 @@
+// #234's last remainder — the cross-environment half of "is prod running what
+// staging tested", the pure half (tested the way web/release.js and
+// web/run-playhead.js are — no DOM). The payload is /api/components/compare's
+// `{env, to, comparisons}`, each comparison chant's own CrossEnvComparison:
+// `same` decided on the COMPARABLE identity (inputDigest ?? digest per side —
+// a pinned helm deploy's bytes legitimately differ per cluster), `comparedOn`
+// present when the input side spoke, digests always visible.
+
+/** Tone vocabulary matches the component palette: good / warn / neutral. */
+export function comparisonRow(c) {
+  const missingA = !c.digestA;
+  const missingB = !c.digestB;
+  if (missingA && missingB) {
+    return { component: c.component, tone: "neutral", verdict: "unrecorded", detail: `no release recorded in ${c.envA} or ${c.envB}` };
+  }
+  if (missingA || missingB) {
+    const where = missingA ? c.envA : c.envB;
+    return { component: c.component, tone: "neutral", verdict: "unrecorded", detail: `no release recorded in ${where}` };
+  }
+  if (c.same) {
+    // The honest wording: matching inputs with differing bytes is still
+    // "same" — that is chant#1243's contract, and saying "same bytes" here
+    // would claim more than the ledger does.
+    const inputDecided = !!c.comparedOn && c.comparedOn.a === c.comparedOn.b && c.digestA !== c.digestB;
+    return {
+      component: c.component,
+      tone: "good",
+      verdict: inputDecided ? "same inputs" : "same",
+      detail: inputDecided
+        ? `built from the same inputs (${short(c.comparedOn.a)}); rendered bytes differ per cluster, as pinned deploys do`
+        : `same digest in both (${short(c.digestA)})`,
+    };
+  }
+  return {
+    component: c.component,
+    tone: "warn",
+    verdict: "differs",
+    detail: `${c.envA}: ${short(c.digestA)} · ${c.envB}: ${short(c.digestB)}`,
+  };
+}
+
+/** One line for the section header: the counts, worst-tone-first. */
+export function comparisonSummary(payload) {
+  const rows = (payload.comparisons || []).map(comparisonRow);
+  if (!rows.length) return { text: `no components recorded in ${payload.env} or ${payload.to}`, tone: "neutral" };
+  const differs = rows.filter((r) => r.tone === "warn").length;
+  const unrecorded = rows.filter((r) => r.tone === "neutral").length;
+  const same = rows.length - differs - unrecorded;
+  if (differs) return { text: `${differs} of ${rows.length} differ from ${payload.to}`, tone: "warn" };
+  if (same === rows.length) return { text: `all ${rows.length} running what ${payload.to} tested`, tone: "good" };
+  return { text: `${same} same as ${payload.to}, ${unrecorded} unrecorded`, tone: "neutral" };
+}
+
+function short(digest) {
+  if (!digest) return "—";
+  const hex = digest.startsWith("sha256:") ? digest.slice(7) : digest;
+  return hex.slice(0, 12);
+}

package/web/cross-env.test.js

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "vitest";
+import { comparisonRow, comparisonSummary } from "./cross-env.js";
+
+const cmp = (over) => ({ component: "web", envA: "prod", envB: "staging", digestA: "sha256:aaaa1111bbbb2222", digestB: "sha256:aaaa1111bbbb2222", same: true, ...over });
+
+describe("comparisonRow (#234 — is prod running what staging tested)", () => {
+  it("same digest in both reads good, with the digest named", () => {
+    const r = comparisonRow(cmp({}));
+    expect(r).toMatchObject({ tone: "good", verdict: "same" });
+    expect(r.detail).toContain("aaaa1111bbbb");
+  });
+
+  it("matching inputs with differing bytes says SAME INPUTS — never claims same bytes (pinned helm, chant#1243)", () => {
+    const r = comparisonRow(cmp({
+      digestA: "sha256:prod-bytes",
+      digestB: "sha256:staging-bytes",
+      same: true,
+      comparedOn: { a: "sha256:inputs", b: "sha256:inputs" },
+    }));
+    expect(r.tone).toBe("good");
+    expect(r.verdict).toBe("same inputs");
+    expect(r.detail).toContain("rendered bytes differ per cluster");
+  });
+
+  it("differing identities read warn, both digests visible", () => {
+    const r = comparisonRow(cmp({ digestB: "sha256:other", same: false }));
+    expect(r).toMatchObject({ tone: "warn", verdict: "differs" });
+    expect(r.detail).toContain("prod");
+    expect(r.detail).toContain("staging");
+  });
+
+  it("a missing side is UNRECORDED (neutral) and names where — never painted as drift", () => {
+    const r = comparisonRow(cmp({ digestB: undefined, same: false }));
+    expect(r).toMatchObject({ tone: "neutral", verdict: "unrecorded" });
+    expect(r.detail).toContain("staging");
+    expect(comparisonRow(cmp({ digestA: undefined, digestB: undefined, same: false })).detail).toContain("prod or staging");
+  });
+});
+
+describe("comparisonSummary", () => {
+  const payload = (comparisons) => ({ env: "prod", to: "staging", comparisons });
+
+  it("worst tone first: any differ makes the line warn with the count", () => {
+    const s = comparisonSummary(payload([cmp({}), cmp({ component: "api", digestB: "sha256:x", same: false })]));
+    expect(s).toEqual({ text: "1 of 2 differ from staging", tone: "warn" });
+  });
+
+  it("all same is the good line the question wants answered", () => {
+    const s = comparisonSummary(payload([cmp({}), cmp({ component: "api" })]));
+    expect(s).toEqual({ text: "all 2 running what staging tested", tone: "good" });
+  });
+
+  it("unrecorded components temper the claim instead of hiding in either count", () => {
+    const s = comparisonSummary(payload([cmp({}), cmp({ component: "api", digestB: undefined, same: false })]));
+    expect(s).toEqual({ text: "1 same as staging, 1 unrecorded", tone: "neutral" });
+  });
+
+  it("an empty ledger pair says so", () => {
+    expect(comparisonSummary(payload([]))).toEqual({ text: "no components recorded in prod or staging", tone: "neutral" });
+  });
+});

package/web/index.html

@@ -4,6 +4,14 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>behold</title>
+    <!-- #393: "nothing in the browser console" includes the 404 every page
+         load has always fetched for itself. behold ships no icon file and its
+         static export copies only web/, so the mark is a data URI rather than a
+         route or an asset: no request, and the exported page keeps it. -->
+    <link
+      rel="icon"
+      href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Ccircle cx='8' cy='8' r='6' fill='none' stroke='%23a6adc8' stroke-width='1.6'/%3E%3Ccircle cx='8' cy='8' r='2.2' fill='%23a6adc8'/%3E%3C/svg%3E"
+    />
     <style>
       /* Pre-paint fallback (#229). These are the DEFAULT theme's tokens —
          Catppuccin Mocha run through theme.js's tokensFor() — not a palette of
@@ -155,6 +163,11 @@
         cursor: progress; }
       #loading-overlay[hidden] { display: none; }
       #loading-overlay #loading-msg { font: var(--t-body)/1.4 var(--font-mono); color: var(--muted); }
+      /* #421: what the last read cost, for the person waiting on this one.
+         Quieter than the message above it — an estimate, never a promise. */
+      #loading-overlay #loading-cost { font: var(--t-caption)/1.4 var(--font-mono); color: var(--muted);
+        opacity: 0.75; }
+      #loading-overlay #loading-cost:empty { display: none; }
       #loading-overlay .spinner { width: 34px; height: 34px; border-radius: 50%;
         border: 3px solid var(--line); border-top-color: var(--focus);
         animation: spin 0.7s linear infinite; }
@@ -313,6 +326,31 @@
       #panel .grow { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
       #panel .tag { color: var(--muted); font: var(--t-caption)/1.5 var(--font-mono); white-space: nowrap; }
 
+      /* The provenance badge (#401, M4 of #397): who stated this figure, to
+         what tolerance, and whether it is modeled from list prices or
+         validated against a bill. Boxed rather than plain muted text, because
+         it rides BESIDE a number and has to read as a label on that number
+         rather than as more of it — and it sits on every figure the behaviour
+         overlay shows, in the panel and in the inspect pane alike, so it is
+         styled for both. `help` cursor: the hover carries "modeled, not
+         billed", which is the sentence #397 turns on. */
+      .behaviour-badge { color: var(--muted); font: var(--t-caption)/1.4 var(--font-mono);
+        border: 1px solid var(--line); border-radius: var(--r-ctl); padding: 0 5px;
+        white-space: nowrap; cursor: help; flex: none; }
+      #panel .behaviour-total { display: flex; flex-direction: column; gap: 1px; padding: 3px 0;
+        font: var(--t-caption)/1.5 var(--font-mono); }
+      #panel .behaviour-ramp { margin: 4px 0 2px; }
+      /* A card nothing priced keeps the drift overlay's neutral fill (#399) —
+         and says so, faintly, so the grey is legible as "not looked at" rather
+         than as the low end of the scale. */
+      #graph [data-unpriced="1"] { opacity: 0.82; }
+      /* #429: a member with no live half, on an overlay. Distinct from the
+         neutral fill it would otherwise be indistinguishable from — a dashed
+         edge says "nothing observed this" where neutral says "looked, could
+         not see". */
+      #graph [data-no-live] rect { stroke-dasharray: 2 4; }
+      #graph [data-no-live] { opacity: 0.75; }
+
       /* Substrate readiness (M5, #54) — one row per substrate on the panel's
          Substrates tab: status dot + name + state, with its actions (bring up /
          reset / run pipeline) visible inline again. #73 moved those into ⌘K;
@@ -424,6 +462,13 @@
          here", not "something is wrong". */
       #graph [data-node-id].operator-home rect:first-of-type { stroke: var(--pending); stroke-width: 2; }
 
+      /* #404: a bound choudoufu card the plan would change in place. A DASHED
+         --degraded edge, deliberately not a fill: the fill is the ownership
+         verdict and attribute drift never moves it, so the two signals have to
+         live in different channels. Dashed rather than solid so it reads apart
+         from .carved's and .operator-home's solid strokes at a glance. */
+      #graph [data-node-id].plan-drifted rect:first-of-type { stroke: var(--degraded); stroke-width: 2; stroke-dasharray: 4 3; }
+
       /* The step the playhead sits on, on the graph itself — the ops lens marks
          it `_playhead` and the card wears a dashed edge, so "here" reads
          differently from "this one is done". */
@@ -515,13 +560,28 @@
         font: var(--t-body)/1.5 var(--font-mono);
         cursor: pointer; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
       #pal-list .row.sel { background: var(--pending); color: var(--pal-sel-fg, var(--fg)); }
+      /* A node row's second line (#393): the member and the kind, which is what
+         tells two same-named addresses in two members apart. Inherits the row's
+         colour so the selected row stays readable on --pending. */
+      #pal-list .row .sub { font-size: var(--t-caption); opacity: 0.66; margin-top: 1px; }
       #pal-list .empty { padding: 8px 11px; color: var(--muted); font-size: var(--t-body); }
-    </style>
+    
+    /* #422: a card whose member is still being read. Dashed and dimmed, never
+       filled — the fill is the status channel and this card has no status yet,
+       so colouring it would claim an observation behold has not made. */
+    #graph [data-pending-read] { opacity: 0.55; }
+    #graph [data-pending-read] rect { stroke-dasharray: 4 3; }
+    @media (prefers-reduced-motion: no-preference) {
+      #graph [data-pending-read] { animation: pending-breathe 2.4s ease-in-out infinite; }
+      @keyframes pending-breathe { 0%, 100% { opacity: 0.45; } 50% { opacity: 0.68; } }
+    }
+</style>
   </head>
   <body>
     <div id="loading-overlay" hidden>
       <div class="spinner"></div>
       <span id="loading-msg">loading…</span>
+      <span id="loading-cost"></span>
     </div>
     <div id="app">
       <div id="graph"></div>
@@ -577,7 +637,7 @@
     <!-- Command palette (⌘K / Ctrl+K, #73) — the spicypath FG-036 shape
          (../spicypath/src/index.html): input + filtered list, driven entirely
          by app.js's paletteCommands()/palRender()/openPalette()/closePalette(). -->
-    <div id="palette"><div class="box"><input id="pal-input" placeholder="type a command…   (Esc to close)" autocomplete="off"><div id="pal-list"></div></div></div>
+    <div id="palette"><div class="box"><input id="pal-input" placeholder="type a command, or an address…   (Esc to close)" autocomplete="off"><div id="pal-list"></div></div></div>
     <script type="module" src="./app.js"></script>
   </body>
 </html>

package/web/pending.js

@@ -0,0 +1,67 @@
+// The picture while it is still arriving (#422, M3 of #419).
+//
+// An estate whose slowest member takes two minutes showed nothing for two
+// minutes, including the members that answered in three seconds. The server's
+// `?progressive=1` answers at once with every member composed from its SOURCE,
+// each node carrying `_pendingRead`, and then broadcasts one `member` frame per
+// live read as it settles. This module is the pure half of applying those.
+//
+// Pending is its own claim. `_unobserved` means behold looked and could not
+// see; neutral means the plan did not mention it; this means the read has not
+// finished. A viewer that blurs them is the thing behold exists not to be, so
+// the pending mark is a separate attr and a separate treatment, never a fifth
+// status colour — pinhole's painter takes a closed set and silently falls back
+// to neutral for anything else, which is "unobserved", the exact wrong answer.
+
+/**
+ * Fold one `member` frame into the graph IR on screen.
+ *
+ * Returns the ids whose status actually moved, so the caller repaints those and
+ * leaves the rest of the SVG alone — the node set never changes here, which is
+ * what keeps dagre out of it and stops cards jumping under the reader.
+ *
+ * Mutates `ir` in place, because it IS the IR the renderer holds.
+ */
+export function applyMemberFrame(ir, frame) {
+  if (!ir || !frame || !frame.member || !frame.statuses) return [];
+  const moved = [];
+  for (const node of ir.nodes || []) {
+    const next = frame.statuses[node.id];
+    if (next === undefined) continue;
+    const attrs = node.attrs || (node.attrs = {});
+    const was = attrs._status;
+    delete attrs._pendingRead;
+    attrs._status = next;
+    // A member whose live read failed comes back with its reason, and that is
+    // a different card from one that simply finished: unobserved, not pending
+    // and not absent.
+    if (frame.unobserved) attrs._unobserved = frame.unobserved;
+    else delete attrs._unobserved;
+    if (was !== next) moved.push(node.id);
+  }
+  return moved;
+}
+
+/** Which members the picture is still waiting on, after a frame lands. */
+export function stillPending(pending, frame) {
+  if (!Array.isArray(pending)) return [];
+  if (!frame || !frame.member) return [...pending];
+  return pending.filter((m) => m !== frame.member);
+}
+
+/**
+ * The line for the reader while the estate arrives.
+ *
+ * Null once nothing is pending — the caller clears rather than printing a
+ * finished-sounding sentence, because the ordinary status line already says
+ * what the estate is.
+ */
+export function pendingLine(pending, total) {
+  if (!Array.isArray(pending) || pending.length === 0) return null;
+  const done = Math.max(0, (total ?? pending.length) - pending.length);
+  const scope = total ? `${done} of ${total} members read` : `${pending.length} members still reading`;
+  // Named, not counted, while the list is short enough to read: "waiting on
+  // team-a" is actionable and "3 pending" is not.
+  const who = pending.length <= 3 ? ` — waiting on ${pending.join(", ")}` : "";
+  return `${scope}${who}`;
+}

package/web/pending.test.js

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+import { applyMemberFrame, pendingLine, stillPending } from "./pending.js";
+
+const ir = () => ({
+  nodes: [
+    { id: "team-a/bucket", attrs: { _pendingRead: true } },
+    { id: "team-a/role", attrs: { _pendingRead: true } },
+    { id: "team-b/bucket", attrs: { _pendingRead: true } },
+  ],
+});
+
+describe("applyMemberFrame (#422)", () => {
+  it("clears pending and paints only the member that landed", () => {
+    const graph = ir();
+    const moved = applyMemberFrame(graph, { member: "team-a", statuses: { "team-a/bucket": "good", "team-a/role": "warn" } });
+
+    expect(moved.sort()).toEqual(["team-a/bucket", "team-a/role"]);
+    expect(graph.nodes[0].attrs).toEqual({ _status: "good" });
+    expect(graph.nodes[1].attrs).toEqual({ _status: "warn" });
+    // The member that has not answered is untouched, and still says so.
+    expect(graph.nodes[2].attrs).toEqual({ _pendingRead: true });
+  });
+
+  it("carries a failed member's reason, which is not the same as pending", () => {
+    const graph = ir();
+    applyMemberFrame(graph, { member: "team-b", unobserved: "no credentials", statuses: { "team-b/bucket": "neutral" } });
+    // Unobserved is "I looked and could not see"; pending was "I have not
+    // finished looking". The card must stop claiming the second one.
+    expect(graph.nodes[2].attrs).toEqual({ _status: "neutral", _unobserved: "no credentials" });
+  });
+
+  it("reports nothing moved when the status is what it already was", () => {
+    const graph = { nodes: [{ id: "a", attrs: { _status: "good" } }] };
+    expect(applyMemberFrame(graph, { member: "m", statuses: { a: "good" } })).toEqual([]);
+    expect(graph.nodes[0].attrs._status).toBe("good");
+  });
+
+  it("ignores a malformed frame rather than throwing over the picture", () => {
+    expect(applyMemberFrame(ir(), null)).toEqual([]);
+    expect(applyMemberFrame(ir(), { member: "x" })).toEqual([]);
+    expect(applyMemberFrame(null, { member: "x", statuses: {} })).toEqual([]);
+  });
+});
+
+describe("what is still arriving", () => {
+  it("drops the member that landed", () => {
+    expect(stillPending(["a", "b", "c"], { member: "b", statuses: {} })).toEqual(["a", "c"]);
+  });
+
+  it("names them while the list is short enough to read", () => {
+    expect(pendingLine(["team-a", "team-b"], 5)).toBe("3 of 5 members read — waiting on team-a, team-b");
+  });
+
+  it("counts them once naming would be a wall of text", () => {
+    expect(pendingLine(["a", "b", "c", "d"], 11)).toBe("7 of 11 members read");
+  });
+
+  it("says nothing once nothing is pending", () => {
+    expect(pendingLine([], 5)).toBeNull();
+    expect(pendingLine(undefined, 5)).toBeNull();
+  });
+});

package/web/read-cost.js

@@ -0,0 +1,49 @@
+// What the last read cost, as one line (#421, M2 of #419).
+//
+// The person staring at the loading scrim has exactly one question — is this
+// three seconds or three minutes — and behold has never answered it. #420's
+// ledger knows; this turns it into a sentence.
+//
+// The number reported is the SLOWEST recent member read, not the sum. An estate
+// read fans out under a shared budget (src/estate.ts) and finishes when its last
+// member does, so the slowest member is what the wall clock actually follows.
+// Summing would report a number no one ever waits for.
+
+/** Whole-second durations, because nobody waiting cares about milliseconds. */
+export function humanMs(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return null;
+  const s = Math.round(ms / 1000);
+  if (s < 1) return "under a second";
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  const rest = s % 60;
+  return rest ? `${m}m ${rest}s` : `${m}m`;
+}
+
+/**
+ * One line for the scrim, or null when there is nothing honest to say.
+ *
+ * Null rather than a zero or a guess: this is the same rule the rest of behold
+ * holds to about absent figures. A fresh server with no reads behind it says
+ * nothing, and preview mode — which gets the totals and not the samples — says
+ * nothing too, because "slowest member" is a claim about members.
+ */
+export function readCostLine(reads) {
+  const recent = reads && Array.isArray(reads.recent) ? reads.recent : null;
+  if (!recent || recent.length === 0) return null;
+  const slowest = recent.reduce((worst, r) => (r && r.runningMs > worst.runningMs ? r : worst), recent[0]);
+  const took = humanMs(slowest.runningMs);
+  if (!took) return null;
+  const members = new Set(recent.map((r) => r.dir)).size;
+  const who = [slowest.dir, slowest.what].filter(Boolean).join(" ");
+  const scope = members === 1 ? "1 member" : `${members} members`;
+  // A member the ledger cannot see is named rather than dropped. Only chant
+  // reads pass ReadScheduler; a choudoufu member spawns its own binary, so on a
+  // mixed estate the slowest member may be one of the ones missing here. Saying
+  // "slowest 3s" while a 60s member went unmeasured is the claim behold refuses
+  // to make anywhere else, and the clause is what keeps this line honest.
+  const blind = Number.isInteger(reads.unmeasured) && reads.unmeasured > 0
+    ? ` · ${reads.unmeasured} not measured`
+    : "";
+  return `last read: ${scope}, slowest ${took}${who ? ` (${who})` : ""}${blind}`;
+}

package/web/read-cost.test.js

@@ -0,0 +1,76 @@
+import { describe, expect, it } from "vitest";
+import { humanMs, readCostLine } from "./read-cost.js";
+
+const sample = (over = {}) => ({ dir: "monolith", what: "graph --live", live: true, queuedMs: 0, runningMs: 1000, outcome: "completed", ...over });
+
+describe("humanMs", () => {
+  it("rounds to whole seconds and names a sub-second read rather than showing 0s", () => {
+    expect(humanMs(400)).toBe("under a second");
+    expect(humanMs(1499)).toBe("1s");
+    expect(humanMs(59_400)).toBe("59s");
+  });
+
+  it("breaks a minute out, and drops a zero remainder", () => {
+    expect(humanMs(60_000)).toBe("1m");
+    expect(humanMs(147_000)).toBe("2m 27s");
+    expect(humanMs(120_000)).toBe("2m");
+  });
+
+  it("refuses a number it cannot render", () => {
+    expect(humanMs(NaN)).toBeNull();
+    expect(humanMs(-1)).toBeNull();
+    expect(humanMs(undefined)).toBeNull();
+  });
+});
+
+describe("readCostLine (#421)", () => {
+  it("reports the slowest member, because that is what the wall clock follows", () => {
+    // Summing these would say 2m 30s, a number nobody ever waits for: the reads
+    // overlap under the shared budget and the estate is done when the last is.
+    const reads = { recent: [
+      sample({ dir: "monolith", runningMs: 3_000 }),
+      sample({ dir: "team-a", runningMs: 147_000 }),
+      sample({ dir: "team-b", runningMs: 500 }),
+    ] };
+    expect(readCostLine(reads)).toBe("last read: 3 members, slowest 2m 27s (team-a graph --live)");
+  });
+
+  it("counts members rather than reads — a member read twice is one member", () => {
+    const reads = { recent: [
+      sample({ dir: "monolith", what: "graph", runningMs: 900 }),
+      sample({ dir: "monolith", what: "graph --live", runningMs: 4_000 }),
+    ] };
+    expect(readCostLine(reads)).toBe("last read: 1 member, slowest 4s (monolith graph --live)");
+  });
+
+  it("says nothing rather than zero when there is nothing behind it", () => {
+    expect(readCostLine(null)).toBeNull();
+    expect(readCostLine({})).toBeNull();
+    expect(readCostLine({ recent: [] })).toBeNull();
+  });
+
+  it("says nothing in preview mode, where the totals arrive without the samples", () => {
+    // "Slowest member" is a claim about members, and preview mode deliberately
+    // withholds them (src/server.ts). Totals alone cannot answer it.
+    expect(readCostLine({ runs: 12, live: { runs: 6, runningMs: 900_000 } })).toBeNull();
+  });
+});
+
+describe("the members the ledger cannot see (#421)", () => {
+  it("names them rather than reporting a slowest it did not measure", () => {
+    // A choudoufu member spawns its own binary and never reaches ReadScheduler,
+    // so "slowest 3s" beside an unmeasured 60s member would be a false claim.
+    const line = readCostLine({ unmeasured: 2, recent: [sample({ dir: "app", runningMs: 3000 })] });
+    expect(line).toBe("last read: 1 member, slowest 3s (app graph --live) · 2 not measured");
+  });
+
+  it("says nothing extra when every member was measured", () => {
+    const line = readCostLine({ unmeasured: 0, recent: [sample({ dir: "app", runningMs: 3000 })] });
+    expect(line).toBe("last read: 1 member, slowest 3s (app graph --live)");
+  });
+
+  it("says nothing extra when the field is absent, as an older payload has it", () => {
+    const line = readCostLine({ recent: [sample({ dir: "app", runningMs: 3000 })] });
+    expect(line).toBe("last read: 1 member, slowest 3s (app graph --live)");
+  });
+});

package/web/refresh-queue.js

@@ -0,0 +1,26 @@
+// One active refresh and one pending refresh, regardless of how many events
+// arrive. All callers wait for the latest requested view to finish loading.
+export function createRefreshQueue(run) {
+  let active;
+  let pending;
+  let revision = 0;
+  return (options = {}) => {
+    revision++;
+    pending = { ...options, quiet: pending ? !!pending.quiet && !!options.quiet : !!options.quiet };
+    if (!active) {
+      active = Promise.resolve().then(async () => {
+        try {
+          while (pending) {
+            const next = pending;
+            pending = undefined;
+            const current = revision;
+            await run(next, () => current === revision);
+          }
+        } finally {
+          active = undefined;
+        }
+      });
+    }
+    return active;
+  };
+}

package/web/refresh-queue.test.js

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import { createRefreshQueue } from "./refresh-queue.js";
+
+function deferred() {
+  let resolve;
+  const promise = new Promise((done) => { resolve = done; });
+  return { promise, resolve };
+}
+
+describe("browser refresh queue", () => {
+  it("a slow read plus an event burst makes one follow-up, never overlapping reads", async () => {
+    const first = deferred(), second = deferred();
+    let active = 0, peak = 0;
+    const calls = [], current = [];
+    const load = createRefreshQueue(async (opts, isCurrent) => {
+      peak = Math.max(peak, ++active);
+      calls.push(opts); current.push(isCurrent);
+      await (calls.length === 1 ? first : second).promise;
+      active--;
+    });
+    const initial = load();
+    await Promise.resolve();
+    const burst = Array.from({ length: 20 }, () => load({ quiet: true }));
+    load({ quiet: false }); load({ quiet: true });
+    expect(calls).toHaveLength(1);
+    expect(current[0]()).toBe(false); // suppress the superseded response
+    first.resolve();
+    await Promise.resolve(); await Promise.resolve();
+    expect(calls).toHaveLength(2);
+    expect(calls[1].quiet).toBe(false); // foreground request wins
+    expect(current[1]()).toBe(true);
+    second.resolve();
+    await Promise.all([initial, ...burst]);
+    expect(peak).toBe(1);
+    expect(calls).toHaveLength(2);
+  });
+
+  it("one change event makes exactly one read", async () => {
+    let calls = 0;
+    const load = createRefreshQueue(async () => { calls++; });
+    await load();
+    expect(calls).toBe(1);
+    await load(); // a later notification remains fresh
+    expect(calls).toBe(2);
+  });
+
+  it("a failed load does not wedge future refreshes", async () => {
+    let calls = 0;
+    const load = createRefreshQueue(async () => { if (++calls === 1) throw new Error("offline"); });
+    await expect(load()).rejects.toThrow("offline");
+    await load();
+    expect(calls).toBe(2);
+  });
+});