@intentius/behold 0.8.0 → 0.9.0

package/web/layout-store.js

@@ -9,10 +9,13 @@
 // dropped without a word (`applicable`).
 //
 // No DOM in here on purpose — this is the testable half of #228 (see
-// web/layout-store.test.js). app.js owns the pointer work and the SVG. The
-// second tier of the issue (a `.behold/layout.json` sidecar behind
-// `POST /api/layout`, so exports and snapshots honour the same deltas) is the
-// follow-up; this is the shape it will serialize.
+// web/layout-store.test.js). app.js owns the pointer work and the SVG.
+//
+// Two tiers, and the second one lands here too: `localStorage` (free, per
+// browser) and the `.behold/layout.json` sidecar behind `GET/POST /api/layout`
+// (shareable, versionable, and what a server-side export bakes in — see
+// src/layout.ts). `mergeLayouts` decides who wins when both have an opinion,
+// and every server call degrades to localStorage-only without a word.
 
 const PREFIX = "behold.layout";
 const NUM = ["dx", "dy", "dw", "dh"];
@@ -116,3 +119,160 @@ export function applicable(deltas, liveIds) {
   for (const [id, d] of Object.entries(normalize(deltas))) if (live.has(id)) out[id] = d;
   return out;
 }
+
+// --- The delta → SVG math ---------------------------------------------------
+// MUST stay identical to the copies in src/layout.ts, which is what bakes a
+// layout into a server-rendered export. web/layout-store.test.js imports both
+// modules and asserts they agree across a table of cases, so a drift fails a
+// test instead of quietly making an export disagree with the screen it came
+// from. (Same discipline as `canonicalKey`, mirrored in app.js and export.ts.)
+
+/** A node group's transform with its delta ridden on top of dagre's own. */
+export function nodeTransform(base, d) {
+  const dx = (d && d.dx) || 0;
+  const dy = (d && d.dy) || 0;
+  if (!dx && !dy) return base;
+  return `translate(${dx}, ${dy}) ${base}`.trim();
+}
+
+/** First and last coordinate pair of a path `d` — pinhole's own edge anchors. */
+export function pathAnchors(d) {
+  const n = String(d || "").match(/-?\d*\.?\d+(?:e[-+]?\d+)?/gi);
+  if (!n || n.length < 4) return null;
+  return { sx: +n[0], sy: +n[1], ex: +n[n.length - 2], ey: +n[n.length - 1] };
+}
+
+/** An edge whose ends moved: a straight line between the original anchors,
+ * each shifted by ITS OWN end's delta. #228 accepts the straight-line fallback
+ * explicitly; spline re-routing stays pinhole's job. */
+export function straightEdge(anchors, from, to) {
+  const { sx, sy, ex, ey } = anchors;
+  return `M ${sx + ((from && from.dx) || 0)} ${sy + ((from && from.dy) || 0)} L ${ex + ((to && to.dx) || 0)} ${ey + ((to && to.dy) || 0)}`;
+}
+
+// --- The containment clamp (#267) -------------------------------------------
+// A card may not leave the box that draws around it. The box is a claim the
+// estate makes — this namespace, this overlay — and a card floating outside one
+// reads as a claim chant never made. So a drag stops at the wall instead, and
+// "I need more room" means grow the box first (#245 already resizes them).
+//
+// No twin in src/layout.ts, unlike the three functions above: the server-side
+// bake does not reconstruct containment boxes (only pinhole's architecture
+// layout stamps them with a `data-group-id`, and not every lens uses it — see
+// wrapContainmentBoxes in web/app.js), so it has nothing to clamp against and
+// deliberately does not try.
+
+/** How far a card keeps off its container's edge, in viewBox units. */
+export const CLAMP_PAD = 8;
+
+/**
+ * `delta` clamped so `rect` — the node's ORIGINAL, un-displaced box — lands
+ * inside `bounds` minus `pad`. `{dw,dh}` ride through untouched; a clamp is
+ * about position.
+ *
+ * Missing or degenerate geometry returns the delta unchanged. That is the
+ * fail-open the DOM side needs: a graph pane that hasn't laid out yet measures
+ * nothing, and "no measurement" must mean "no clamp", not "everything snaps to
+ * the origin".
+ *
+ * A container with no room for the card (a box dragged smaller than its child)
+ * has an empty range; the card centres on that axis rather than being pinned to
+ * an arbitrary end of it.
+ */
+export function clampDelta(delta, rect, bounds, pad = CLAMP_PAD) {
+  const d = { ...(delta || {}) };
+  if (!rect || !bounds || !(rect.w >= 0) || !(rect.h >= 0) || !(bounds.w > 0) || !(bounds.h > 0)) return d;
+  d.dx = clampAxis(d.dx || 0, rect.x, rect.w, bounds.x, bounds.w, pad);
+  d.dy = clampAxis(d.dy || 0, rect.y, rect.h, bounds.y, bounds.h, pad);
+  return d;
+}
+
+function clampAxis(v, start, len, boundStart, boundLen, pad) {
+  const lo = boundStart + pad - start;
+  const hi = boundStart + boundLen - pad - (start + len);
+  if (!Number.isFinite(lo) || !Number.isFinite(hi) || !Number.isFinite(v)) return v;
+  if (hi < lo) return (lo + hi) / 2; // no room at all — centre, don't pick a wall
+  return Math.min(hi, Math.max(lo, v));
+}
+
+// --- The server tier --------------------------------------------------------
+
+/**
+ * The two tiers, merged for display. **Local wins where both have an id.**
+ *
+ * You are looking at this browser's picture: the drag you just did is in
+ * localStorage and must not be argued with by a sidecar someone else committed
+ * (or that you yourself pushed from another machine). An id only the server has
+ * still comes through — that is what makes a shared layout worth having — so
+ * the merge adds without ever overwriting. The reverse ordering would mean a
+ * `git pull` silently undoing a placement you can see on your screen.
+ *
+ * The stale-id rule is unchanged and applies after: `applicable` drops whatever
+ * is no longer in the graph, whichever tier it came from.
+ */
+export function mergeLayouts(local, server) {
+  return { ...normalize(server), ...normalize(local) };
+}
+
+/** The lens's deltas as the server has them (`{}` on any refusal), plus whether
+ * it would accept a write. No server, a static export, preview mode, a
+ * read-only project, a 404 from an older behold — all the same answer: this is
+ * a localStorage-only session, and nothing says so out loud. */
+export async function fetchServerLayout(fetchFn, lens) {
+  try {
+    const res = await fetchFn(`/api/layout?lens=${encodeURIComponent(lens)}`);
+    if (!res || !res.ok) return { deltas: {}, writable: false };
+    const body = await res.json();
+    return { deltas: normalize(body && body.deltas), writable: !!(body && body.writable) };
+  } catch {
+    return { deltas: {}, writable: false };
+  }
+}
+
+/** Push one lens's map to the sidecar. Resolves true iff it was stored.
+ * `keepalive` so a push flushed on the way out of the page (see `debounce`'s
+ * `flush`) still completes after the document is gone. */
+export async function postServerLayout(fetchFn, lens, deltas) {
+  try {
+    const res = await fetchFn("/api/layout", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ lens, deltas: normalize(deltas) }),
+      keepalive: true,
+    });
+    return !!(res && res.ok);
+  } catch {
+    return false;
+  }
+}
+
+/** A trailing-edge debouncer for the POST above: a drag emits a pointer-move
+ * storm and ends on the one write that matters. `flush()` runs a pending call
+ * now — what a page leaving mid-debounce needs, or the sidecar would miss the
+ * last placement the localStorage tier already has. Exported so the test can
+ * drive it with a fake clock rather than sleeping. */
+// The default timers are wrappers, not bare references: a detached
+// `setTimeout` is called with no `this` and Chrome answers that with an
+// "Illegal invocation" TypeError.
+export function debounce(fn, ms, setTimer = (cb, t) => setTimeout(cb, t), clearTimer = (id) => clearTimeout(id)) {
+  let t = null;
+  let last = null;
+  const run = (...args) => {
+    if (t !== null) clearTimer(t);
+    last = args;
+    t = setTimer(() => {
+      t = null;
+      last = null;
+      fn(...args);
+    }, ms);
+  };
+  run.flush = () => {
+    if (t === null) return;
+    clearTimer(t);
+    t = null;
+    const args = last || [];
+    last = null;
+    fn(...args);
+  };
+  return run;
+}

package/web/layout-store.test.js

@@ -1,20 +1,34 @@
 // #228: the hand-layout delta store, checked without a browser. The pointer
 // work and the SVG live in app.js and are covered by smoke/ui-smoke.mjs; every
 // rule that decides WHAT gets stored and under which key lives here.
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import {
   applicable,
+  clampDelta,
   clearLayout,
+  CLAMP_PAD,
+  debounce,
+  fetchServerLayout,
   isEmpty,
   layoutKey,
   lensKeyOf,
+  mergeLayouts,
+  nodeTransform,
   normalize,
+  pathAnchors,
+  postServerLayout,
   projectKeyOf,
   readLayout,
   setDelta,
   slug,
+  straightEdge,
   writeLayout,
 } from "./layout-store.js";
+// The server half of #228 — imported here on purpose: this is the one file
+// that can hold both copies of the delta→SVG math at once (tsconfig excludes
+// web/, so a src/*.test.ts couldn't import the browser module), and the
+// parity block at the bottom is what keeps them from drifting.
+import * as server from "../src/layout.ts";
 
 /** A localStorage stand-in; `fail` makes every operation throw (private mode). */
 function fakeStorage(seed = {}, fail = false) {
@@ -161,3 +175,214 @@ describe("storage", () => {
     expect(readLayout(s, layoutKey("/e", "logical"))).toEqual({ a: { dy: 2 } });
   });
 });
+
+// --- The server tier (#228, second half) ------------------------------------
+
+describe("mergeLayouts", () => {
+  it("local wins where both tiers have the same id", () => {
+    expect(mergeLayouts({ api: { dx: 10 } }, { api: { dx: -99 } })).toEqual({ api: { dx: 10 } });
+  });
+
+  it("an id only the sidecar has still comes through — that's the point of sharing", () => {
+    expect(mergeLayouts({ api: { dx: 10 } }, { worker: { dy: 4 } })).toEqual({ api: { dx: 10 }, worker: { dy: 4 } });
+  });
+
+  it("is the whole server layout when nothing is local (a fresh browser)", () => {
+    expect(mergeLayouts({}, { api: { dx: 1 } })).toEqual({ api: { dx: 1 } });
+  });
+
+  it("normalizes both sides, so junk from either can't reach the SVG", () => {
+    expect(mergeLayouts({ a: { dx: 0 } }, { b: "nope", c: { dy: 3 } })).toEqual({ c: { dy: 3 } });
+  });
+});
+
+describe("fetchServerLayout", () => {
+  const res = (body, ok = true) => ({ ok, json: async () => body });
+
+  it("asks for one lens and normalizes what comes back", async () => {
+    const fetchFn = vi.fn(async () => res({ lens: "components", deltas: { api: { dx: "5" }, junk: { dx: 0 } }, writable: true }));
+    expect(await fetchServerLayout(fetchFn, "components")).toEqual({ deltas: { api: { dx: 5 } }, writable: true });
+    expect(fetchFn).toHaveBeenCalledWith("/api/layout?lens=components");
+  });
+
+  it("encodes the lens key (a stack name can be anything)", async () => {
+    const fetchFn = vi.fn(async () => res({ deltas: {}, writable: false }));
+    await fetchServerLayout(fetchFn, "resources+stack-edge");
+    expect(fetchFn).toHaveBeenCalledWith("/api/layout?lens=resources%2Bstack-edge");
+  });
+
+  it("a refusal is an empty, unwritable answer — never a throw", async () => {
+    expect(await fetchServerLayout(async () => res({ error: "read-only" }, false), "components")).toEqual({ deltas: {}, writable: false });
+    expect(await fetchServerLayout(async () => {
+      throw new Error("offline");
+    }, "components")).toEqual({ deltas: {}, writable: false });
+  });
+});
+
+describe("postServerLayout", () => {
+  it("posts the normalized lens map as JSON", async () => {
+    const fetchFn = vi.fn(async () => ({ ok: true }));
+    expect(await postServerLayout(fetchFn, "components", { api: { dx: 3, dy: 0 } })).toBe(true);
+    const [url, init] = fetchFn.mock.calls[0];
+    expect(url).toBe("/api/layout");
+    expect(init.method).toBe("POST");
+    expect(init.headers["content-type"]).toBe("application/json");
+    expect(init.keepalive).toBe(true); // survives a flush on the way out of the page
+    expect(JSON.parse(init.body)).toEqual({ lens: "components", deltas: { api: { dx: 3 } } });
+  });
+
+  it("a rejection is false, not an exception (offline is fine — localStorage has it)", async () => {
+    expect(await postServerLayout(async () => ({ ok: false }), "components", {})).toBe(false);
+    expect(
+      await postServerLayout(async () => {
+        throw new Error("offline");
+      }, "components", {}),
+    ).toBe(false);
+  });
+});
+
+describe("clampDelta — a card stays inside the box drawn around it (#267)", () => {
+  // The smoke stub's own geometry: a 150×64 card at (40,80) in a 580×220 box
+  // at (20,40). Same numbers as smoke/stub.mjs, so a failure here and a failure
+  // there are the same failure.
+  const card = { x: 40, y: 80, w: 150, h: 64 };
+  const box = { x: 20, y: 40, w: 580, h: 220 };
+
+  it("leaves a delta that keeps the card inside alone", () => {
+    expect(clampDelta({ dx: 50, dy: 30 }, card, box)).toEqual({ dx: 50, dy: 30 });
+  });
+
+  it("stops at the wall minus the padding, on every side", () => {
+    expect(clampDelta({ dx: -900, dy: -900 }, card, box)).toEqual({ dx: 20 + CLAMP_PAD - 40, dy: 40 + CLAMP_PAD - 80 });
+    expect(clampDelta({ dx: 900, dy: 900 }, card, box)).toEqual({ dx: 600 - CLAMP_PAD - 190, dy: 260 - CLAMP_PAD - 144 });
+  });
+
+  it("clamps one axis without touching the other", () => {
+    expect(clampDelta({ dx: 900, dy: 10 }, card, box)).toEqual({ dx: 402, dy: 10 });
+  });
+
+  it("carries {dw,dh} through — a clamp is about position", () => {
+    expect(clampDelta({ dx: 900, dy: 0, dw: 5, dh: 6 }, card, box)).toEqual({ dx: 402, dy: 0, dw: 5, dh: 6 });
+  });
+
+  it("centres the card when the container has no room for it at all", () => {
+    const tiny = { x: 100, y: 100, w: 50, h: 20 };
+    const got = clampDelta({ dx: 900, dy: -900 }, card, tiny);
+    expect(got.dx + card.x + card.w / 2).toBeCloseTo(tiny.x + tiny.w / 2);
+    expect(got.dy + card.y + card.h / 2).toBeCloseTo(tiny.y + tiny.h / 2);
+  });
+
+  it("fails OPEN on missing geometry — no measurement means no clamp", () => {
+    expect(clampDelta({ dx: 900, dy: 900 }, null, box)).toEqual({ dx: 900, dy: 900 });
+    expect(clampDelta({ dx: 900, dy: 900 }, card, null)).toEqual({ dx: 900, dy: 900 });
+    expect(clampDelta({ dx: 900, dy: 900 }, card, { x: 0, y: 0, w: 0, h: 0 })).toEqual({ dx: 900, dy: 900 });
+  });
+
+  it("a growing box loosens the clamp; a shrinking one tightens it", () => {
+    const grown = { ...box, w: box.w + 100 };
+    expect(clampDelta({ dx: 900, dy: 0 }, card, grown).dx).toBe(clampDelta({ dx: 900, dy: 0 }, card, box).dx + 100);
+  });
+
+  it("normalizes away to nothing when the clamp lands on zero", () => {
+    // setDelta is what the drag actually calls; a clamped-to-origin delta must
+    // prune like any other no-op, not persist as `{dx: 0, dy: 0}`.
+    expect(setDelta({}, "api", clampDelta({ dx: 0, dy: 0 }, card, box))).toEqual({});
+  });
+});
+
+describe("debounce", () => {
+  const fakeTimers = () => {
+    const timers = [];
+    return { timers, set: (cb) => timers.push(cb) - 1, clear: (i) => (timers[i] = null), run: () => timers.forEach((cb) => cb && cb()) };
+  };
+
+  it("fires once, with the last arguments — a drag is one write, not sixty", () => {
+    const t = fakeTimers();
+    const fn = vi.fn();
+    const d = debounce(fn, 100, t.set, t.clear);
+    d("a");
+    d("b");
+    d("c");
+    t.run();
+    expect(fn.mock.calls).toEqual([["c"]]);
+  });
+
+  it("flush runs a pending call now — what a page leaving mid-debounce needs", () => {
+    const t = fakeTimers();
+    const fn = vi.fn();
+    const d = debounce(fn, 100, t.set, t.clear);
+    d("a");
+    d.flush();
+    expect(fn.mock.calls).toEqual([["a"]]);
+    t.run(); // the cancelled timer must not fire it a second time
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("flush with nothing pending does nothing", () => {
+    const t = fakeTimers();
+    const fn = vi.fn();
+    debounce(fn, 100, t.set, t.clear).flush();
+    expect(fn).not.toHaveBeenCalled();
+  });
+});
+
+// --- Parity with src/layout.ts ----------------------------------------------
+// The client paints the deltas in the browser; the server bakes the same ones
+// into an exported SVG. If these two ever disagree, an export stops matching
+// the screen it was taken from — silently. So they are checked against each
+// other here, on the same table.
+describe("the delta→SVG math matches the server's copy", () => {
+  const CASES = [
+    ["translate(40, 80)", { dx: 12, dy: -4 }],
+    ["translate(40, 80) scale(0.9)", { dx: 0.5, dy: 0 }],
+    ["", { dx: 3, dy: 4 }],
+    ["translate(1, 2)", { dx: 0, dy: 0 }],
+    ["translate(1, 2)", { dw: 20, dh: 10 }],
+    ["translate(1, 2)", {}],
+  ];
+  it("nodeTransform", () => {
+    for (const [base, d] of CASES) expect(nodeTransform(base, d)).toBe(server.nodeTransform(base, d));
+    expect(nodeTransform("translate(40, 80)", { dx: 12, dy: -4 })).toBe("translate(12, -4) translate(40, 80)");
+    expect(nodeTransform("translate(1, 2)", { dw: 5 })).toBe("translate(1, 2)");
+  });
+
+  it("pathAnchors", () => {
+    const DS = ["M 115 112 C 115 112, 305 112, 305 112", "M1 2L3 4", "M 1e2 -3.5 L 7 8", "M 1 2", "", null];
+    for (const d of DS) expect(pathAnchors(d)).toEqual(server.pathAnchors(d));
+    expect(pathAnchors("M 115 112 C 115 112, 305 112, 305 112")).toEqual({ sx: 115, sy: 112, ex: 305, ey: 112 });
+  });
+
+  it("straightEdge", () => {
+    const a = { sx: 115, sy: 112, ex: 305, ey: 112 };
+    for (const [from, to] of [
+      [{ dx: 10, dy: 5 }, undefined],
+      [undefined, { dx: -2.5, dy: 0 }],
+      [{ dx: 1 }, { dy: 2 }],
+      [undefined, undefined],
+    ]) {
+      expect(straightEdge(a, from, to)).toBe(server.straightEdge(a, from, to));
+    }
+    expect(straightEdge(a, { dx: 10, dy: 5 }, undefined)).toBe("M 125 117 L 305 112");
+  });
+
+  it("slug and normalize agree, so a key written by one is read by the other", () => {
+    for (const s of ["/estates/stub-estate", "Resources+Radial", "///", "", "stack-edge"]) expect(slug(s)).toBe(server.slug(s));
+    for (const raw of [{ a: { dx: 1, dy: 0 } }, { a: { dx: "12.5" } }, { a: 5 }, null, "nope", { a: { dx: NaN } }]) {
+      expect(normalize(raw)).toEqual(server.normalizeDeltas(raw));
+    }
+  });
+
+  it("the lens key the client stores under is the one the server derives from a request", () => {
+    const q = (s) => new URLSearchParams(s);
+    expect(server.lensFromQuery(q("components=1"))).toBe(lensKeyOf({ zoom: "components" }));
+    expect(server.lensFromQuery(q("logical=1"))).toBe(lensKeyOf({ zoom: "logical" }));
+    expect(server.lensFromQuery(q("env=prod&runtime=1&detail=3"))).toBe(lensKeyOf({ zoom: "runtime" }));
+    expect(server.lensFromQuery(q("detail=1"))).toBe(lensKeyOf({ zoom: "composites" }));
+    expect(server.lensFromQuery(q("detail=3"))).toBe(lensKeyOf({ zoom: "attributes" }));
+    expect(server.lensFromQuery(q(""))).toBe(lensKeyOf({ zoom: "resources" }));
+    expect(server.lensFromQuery(q("detail=2&radial=1"))).toBe(lensKeyOf({ zoom: "resources", radial: true }));
+    expect(server.lensFromQuery(q("detail=2&stack=edge"))).toBe(lensKeyOf({ zoom: "resources", stack: "edge" }));
+    // The env is in neither — an overlay recolours the same nodes (#228).
+    expect(server.lensFromQuery(q("components=1&env=prod&tier=dev"))).toBe(server.lensFromQuery(q("components=1")));
+  });
+});

package/web/panel.js

@@ -122,6 +122,34 @@ export function setPanelTab(tab, { expand = true } = {}) {
   }
 }
 
+/**
+ * #254: add a tab the markup doesn't ship — the Carve walkthrough, which only
+ * exists when the server is serving one. Mounted at runtime rather than hidden
+ * in index.html so no other project grows a dead tab (and so a persisted
+ * `tab: "carve"` can never strand someone on an empty section: the tab isn't
+ * there to be restored). Returns the section element to render into; calling it
+ * twice is a no-op that returns the same one.
+ */
+export function addPanelTab(id, label, title) {
+  if (!panel) return null;
+  const existing = panel.querySelector(`#panel-body section[data-tab="${id}"]`);
+  if (existing) return existing;
+  const b = document.createElement("button");
+  b.dataset.tab = id;
+  b.textContent = label;
+  if (title) b.title = title;
+  b.addEventListener("click", () => setPanelTab(id));
+  // Before the ⌘K pill + collapse chevron, which are not tabs.
+  document.getElementById("panel-tabs").insertBefore(b, document.getElementById("hintk"));
+  const section = document.createElement("section");
+  section.dataset.tab = id;
+  document.getElementById("panel-body").appendChild(section);
+  // The new button starts inactive; the section starts hidden. Re-applying the
+  // current tab keeps the two in step whatever it happens to be.
+  setPanelTab(state.tab, { expand: false });
+  return section;
+}
+
 function setCollapsed(on) {
   state.collapsed = !!on;
   panel.classList.toggle("collapsed", state.collapsed);

package/web/theme.js

@@ -32,6 +32,18 @@ export function readableOn(bg) { return isDark(bg) ? "#ffffff" : "#000000"; }
 // --- OKLCH (perceptual hue rotation for category counts > palette slots) --
 const s2l = (c) => ((c /= 255) <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
 const l2s = (c) => { const v = c <= 0.0031308 ? c * 12.92 : 1.055 * c ** (1 / 2.4) - 0.055; return clamp(v, 0, 1) * 255; };
+// A real WCAG contrast ratio (#240) — sRGB→linear via s2l (the same EOTF step
+// hexToOklch already does below), unlike the quick luminance() above, which
+// skips gamma correction and is only good enough for a light/dark coin-flip
+// (isDark/readableOn). The floor --muted has to clear is a real accessibility
+// number, and luminance()'s shortcut proved too far off it on the exact
+// palette that opened this issue (Darkermatrix: quick metric said 3.03,
+// actual WCAG was 2.13) to be worth the savings.
+function relLuminance(hex) { const [r, g, b] = hexToRgb(hex).map(s2l); return 0.2126 * r + 0.7152 * g + 0.0722 * b; }
+export function contrast(a, b) {
+  const A = relLuminance(a), B = relLuminance(b);
+  return (Math.max(A, B) + 0.05) / (Math.min(A, B) + 0.05);
+}
 export function hexToOklch(hex) {
   const [R, G, B] = hexToRgb(hex).map(s2l);
   const l = Math.cbrt(0.4122214708 * R + 0.5363325363 * G + 0.0514459929 * B);
@@ -61,6 +73,46 @@ export function desaturate(hex, k) {
   return oklchToHex({ L, C: C * k, H });
 }
 
+// #240: the same guaranteed-visible trick #229 used for --active (push OKLCH
+// L away from a reference until it clears a bar), generalised from a fixed L
+// delta to an actual contrast() floor — because unlike --active's "just don't
+// land on the same fill", secondary text has a real legibility target.
+//
+// Tries `dark`'s intended direction first (lighter text on a dark theme,
+// darker on a light one — the direction a person would actually pick, and
+// the one #229's --active push uses). luminance() isn't gamma-corrected, so
+// its contrast() ratio is asymmetric in a way real perceived contrast isn't
+// — it overstates how much headroom the near-black end has. Chasing that
+// headroom blindly is how a dark theme's muted text ends up pushed to
+// near-black-on-dark-panel, technically clearing the ratio while reading as
+// invisible. So the "chase more headroom" fallback only fires if the
+// intended direction's own gamut-limited walk can't reach the floor at all
+// (a saturated, nominally-dark bg like Hot Dog Stand's red, whose panel ends
+// up mid-bright once mixed toward fg) — never as a first choice. Chroma
+// eases toward 0 as L walks away so a saturated start doesn't clip out of
+// gamut and stall short of the target.
+function pushForContrast(hex, against, floor, dark) {
+  if (contrast(hex, against) >= floor) return hex;
+  const tok = hexToOklch(hex);
+  const walk = (dir) => {
+    let best = hex, bestRatio = contrast(hex, against);
+    for (let step = 1; step <= 100; step++) {
+      const t = step / 100;
+      const L = clamp(tok.L + dir * step * 0.01, 0, 1);
+      const out = oklchToHex({ L, C: tok.C * (1 - t * 0.6), H: tok.H });
+      const ratio = contrast(out, against);
+      if (ratio > bestRatio) { bestRatio = ratio; best = out; }
+      if (ratio >= floor) return { hex: out, ratio, reached: true };
+      if (L === 0 || L === 1) break;
+    }
+    return { hex: best, ratio: bestRatio, reached: false };
+  };
+  const primary = walk(dark ? 1 : -1);
+  if (primary.reached) return primary.hex;
+  const fallback = walk(dark ? -1 : 1);
+  return fallback.ratio > primary.ratio ? fallback.hex : primary.hex;
+}
+
 // --- behold's semantic tokens derived from a theme -----------------------
 // Drift states are ANCHORED to palette slots so "coloured by drift" stays meaningful across
 // every theme (green=managed … red=degraded); only the shades change. Chrome is derived from
@@ -93,7 +145,11 @@ export function tokensFor(th) {
     panel,
     line: desaturate(fgMix(0.16), 0.75),
     fg: th.fg,
-    muted: desaturate(fgMix(0.5), 0.75),
+    // #240: secondary text needs an actual floor, not just "quieter than
+    // fg" — a handful of low-range palettes (Darkermatrix and friends) mix
+    // fg/panel close enough that the quieted 0.5 mix reads at ~1.25:1.
+    // Push its OKLCH L away from --panel's until it clears 3:1.
+    muted: pushForContrast(desaturate(fgMix(0.5), 0.75), panel, 3, th.dark),
     edge: fgMix(0.32),
     // The structural border — the panel shell, the pane edge, the footer rule.
     // Tinted by the palette's OWN bright-black slot instead of being one more