@intentius/behold 0.18.0 → 0.19.0

package/web/index.html

@@ -163,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; }
@@ -339,6 +344,12 @@
          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 /
@@ -554,12 +565,23 @@
          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>

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);
+  });
+});