@intentius/behold 0.7.0 → 0.9.0

package/web/layout-store.js

@@ -0,0 +1,278 @@
+// The hand-layout delta store (#228) — what a dragged node or a resized
+// containment box remembers, and where.
+//
+// Deltas, never absolute positions. The graph is chant's and the layout is
+// yours, and that ordering must not invert: a stored `{dx,dy}` is an offset
+// from whatever dagre decided on THIS render, so a node that legitimately
+// moved in the source still lands under your offset instead of pinning itself
+// to a stale coordinate. A delta whose node id is gone from the graph is
+// 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.
+//
+// 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"];
+
+/** A path or a lens name → one flat, readable key segment. */
+export function slug(s) {
+  return (
+    String(s ?? "")
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "") || "unknown"
+  );
+}
+
+/** The storage key for one project + lens: `behold.layout.<project>.<lens>`. */
+export function layoutKey(projectKey, lens) {
+  return `${PREFIX}.${slug(projectKey)}.${slug(lens)}`;
+}
+
+/** The project half of the key, from /api/project's payload (see initPickers). */
+export function projectKeyOf(info) {
+  return slug(info && info.projectDir);
+}
+
+/**
+ * The lens half of the key. `?logical=1` and the plain graph must keep
+ * independent layouts (#228's acceptance), and so must radial vs. straight and
+ * one stack vs. another — every one of those re-lays the graph out from
+ * scratch, so a delta from one means nothing in another. The env is
+ * deliberately NOT in the key: picking an env recolours the same nodes, it
+ * doesn't re-place them, and losing your layout on an overlay flip would be
+ * the wrong trade.
+ */
+export function lensKeyOf({ zoom, radial, stack } = {}) {
+  return [zoom || "graph", radial ? "radial" : null, stack ? `stack-${stack}` : null].filter(Boolean).join("+");
+}
+
+/** Coerce arbitrary parsed JSON into `{id: {dx,dy,dw,dh}}` of finite non-zero numbers. */
+export function normalize(raw) {
+  const out = {};
+  if (!raw || typeof raw !== "object") return out;
+  for (const [id, d] of Object.entries(raw)) {
+    if (!id || !d || typeof d !== "object") continue;
+    const clean = {};
+    for (const k of NUM) {
+      const v = Number(d[k]);
+      if (Number.isFinite(v) && v !== 0) clean[k] = v;
+    }
+    if (Object.keys(clean).length) out[id] = clean;
+  }
+  return out;
+}
+
+/** True when nothing is hand-placed — drives whether the reset control shows. */
+export function isEmpty(deltas) {
+  return Object.keys(normalize(deltas)).length === 0;
+}
+
+/** Read one key. Unparseable, missing, or a storage that throws → `{}`. */
+export function readLayout(storage, key) {
+  try {
+    return normalize(JSON.parse(storage.getItem(key) || "{}"));
+  } catch {
+    return {};
+  }
+}
+
+/** Write one key (an empty layout removes it rather than storing `{}`). */
+export function writeLayout(storage, key, deltas) {
+  const d = normalize(deltas);
+  try {
+    if (Object.keys(d).length) storage.setItem(key, JSON.stringify(d));
+    else storage.removeItem(key);
+  } catch {
+    /* private mode, quota, a static export off file:// — layout is a nicety */
+  }
+  return d;
+}
+
+export function clearLayout(storage, key) {
+  try {
+    storage.removeItem(key);
+  } catch {
+    /* see writeLayout */
+  }
+}
+
+/** Replace one id's delta, returning a NEW map. An all-zero delta is pruned. */
+export function setDelta(deltas, id, delta) {
+  const next = normalize(deltas);
+  const clean = normalize({ [id]: delta })[id];
+  if (clean) next[id] = clean;
+  else delete next[id];
+  return next;
+}
+
+/** Drop deltas whose id is no longer in the graph — silently, per #228. */
+export function applicable(deltas, liveIds) {
+  const live = liveIds instanceof Set ? liveIds : new Set(liveIds || []);
+  const out = {};
+  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

@@ -0,0 +1,388 @@
+// #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, 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) {
+  const map = new Map(Object.entries(seed));
+  return {
+    map,
+    getItem(k) {
+      if (fail) throw new Error("nope");
+      return map.has(k) ? map.get(k) : null;
+    },
+    setItem(k, v) {
+      if (fail) throw new Error("nope");
+      map.set(k, v);
+    },
+    removeItem(k) {
+      if (fail) throw new Error("nope");
+      map.delete(k);
+    },
+  };
+}
+
+describe("keys", () => {
+  it("slugs a project dir and a lens into one readable key", () => {
+    expect(layoutKey("/estates/stub-estate", "components")).toBe("behold.layout.estates-stub-estate.components");
+  });
+
+  it("takes the project half from /api/project's projectDir", () => {
+    expect(projectKeyOf({ projectDir: "/Users/me/work/My Estate" })).toBe("users-me-work-my-estate");
+    expect(projectKeyOf(null)).toBe("unknown");
+    expect(projectKeyOf({})).toBe("unknown");
+  });
+
+  it("gives the logical lens and the plain graph independent keys (#228 acceptance)", () => {
+    const p = "/estates/x";
+    expect(layoutKey(p, lensKeyOf({ zoom: "logical" }))).not.toBe(layoutKey(p, lensKeyOf({ zoom: "resources" })));
+  });
+
+  it("separates radial from straight, and one stack from another", () => {
+    expect(lensKeyOf({ zoom: "resources", radial: true })).toBe("resources+radial");
+    expect(lensKeyOf({ zoom: "resources", stack: "edge" })).toBe("resources+stack-edge");
+    expect(lensKeyOf({ zoom: "resources" })).toBe("resources");
+    expect(layoutKey("/e", lensKeyOf({ zoom: "resources", radial: true }))).not.toBe(layoutKey("/e", lensKeyOf({ zoom: "resources" })));
+  });
+
+  it("keeps the env OUT of the key — an overlay recolours, it does not re-place", () => {
+    expect(lensKeyOf({ zoom: "components", env: "prod" })).toBe(lensKeyOf({ zoom: "components" }));
+  });
+
+  it("never produces an empty segment", () => {
+    expect(slug("///")).toBe("unknown");
+    expect(layoutKey("", "")).toBe("behold.layout.unknown.unknown");
+  });
+});
+
+describe("normalize", () => {
+  it("keeps finite non-zero deltas only", () => {
+    expect(normalize({ a: { dx: 10, dy: 0, dw: 4 } })).toEqual({ a: { dx: 10, dw: 4 } });
+  });
+
+  it("drops junk without throwing", () => {
+    expect(normalize(null)).toEqual({});
+    expect(normalize("nope")).toEqual({});
+    expect(normalize({ a: 5, b: null, c: { dx: NaN }, d: { dx: "x" }, e: { nope: 1 } })).toEqual({});
+  });
+
+  it("parses numeric strings (JSON round-trips are not always clean)", () => {
+    expect(normalize({ a: { dx: "12.5" } })).toEqual({ a: { dx: 12.5 } });
+  });
+
+  it("isEmpty ignores entries that normalize away", () => {
+    expect(isEmpty({ a: { dx: 0, dy: 0 } })).toBe(true);
+    expect(isEmpty({ a: { dx: 1 } })).toBe(false);
+  });
+});
+
+describe("setDelta", () => {
+  it("replaces one id and leaves the rest alone", () => {
+    const next = setDelta({ a: { dx: 1 }, b: { dy: 2 } }, "a", { dx: 9, dy: 9 });
+    expect(next).toEqual({ a: { dx: 9, dy: 9 }, b: { dy: 2 } });
+  });
+
+  it("prunes an id dragged back to where dagre put it", () => {
+    expect(setDelta({ a: { dx: 1 } }, "a", { dx: 0, dy: 0 })).toEqual({});
+  });
+
+  it("does not mutate its input", () => {
+    const before = { a: { dx: 1 } };
+    setDelta(before, "a", { dx: 4 });
+    expect(before).toEqual({ a: { dx: 1 } });
+  });
+
+  it("carries a box's size delta alongside its position delta", () => {
+    expect(setDelta({}, "box:vpc", { dx: 3, dy: 0, dw: 40, dh: -20 })).toEqual({ "box:vpc": { dx: 3, dw: 40, dh: -20 } });
+  });
+});
+
+describe("applicable", () => {
+  it("silently drops a delta for a node that left the estate", () => {
+    expect(applicable({ gone: { dx: 5 }, here: { dy: 3 } }, ["here"])).toEqual({ here: { dy: 3 } });
+  });
+
+  it("takes a Set as well as an array", () => {
+    expect(applicable({ a: { dx: 1 } }, new Set(["a"]))).toEqual({ a: { dx: 1 } });
+  });
+
+  it("is a no-op filter when nothing is live", () => {
+    expect(applicable({ a: { dx: 1 } }, [])).toEqual({});
+  });
+});
+
+describe("storage", () => {
+  it("round-trips through a storage", () => {
+    const s = fakeStorage();
+    const key = layoutKey("/estates/x", "components");
+    writeLayout(s, key, { api: { dx: 12, dy: -4 } });
+    expect(readLayout(s, key)).toEqual({ api: { dx: 12, dy: -4 } });
+  });
+
+  it("removes the key rather than storing an empty layout", () => {
+    const s = fakeStorage();
+    writeLayout(s, "k", { api: { dx: 1 } });
+    writeLayout(s, "k", {});
+    expect(s.map.has("k")).toBe(false);
+    expect(readLayout(s, "k")).toEqual({});
+  });
+
+  it("survives a corrupt value", () => {
+    expect(readLayout(fakeStorage({ k: "{not json" }), "k")).toEqual({});
+  });
+
+  it("survives a storage that throws (private mode, quota, file://)", () => {
+    const s = fakeStorage({}, true);
+    expect(() => writeLayout(s, "k", { a: { dx: 1 } })).not.toThrow();
+    expect(readLayout(s, "k")).toEqual({});
+    expect(() => clearLayout(s, "k")).not.toThrow();
+  });
+
+  it("clearLayout drops just this lens's key", () => {
+    const s = fakeStorage();
+    writeLayout(s, layoutKey("/e", "components"), { a: { dx: 1 } });
+    writeLayout(s, layoutKey("/e", "logical"), { a: { dy: 2 } });
+    clearLayout(s, layoutKey("/e", "components"));
+    expect(readLayout(s, layoutKey("/e", "components"))).toEqual({});
+    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")));
+  });
+});