visualproof 0.2.0 → 0.4.0

package/dist/server/usage.js

@@ -18,6 +18,7 @@
 // again. A module that cannot be elaborated is reported and keeps the text-based context and no
 // notation edges; the others are not held back by it.
 import { spawn } from "node:child_process";
+import { childEnv, DETACH, grouped } from "./children.js";
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
@@ -62,7 +63,8 @@ export function traceOptions(p, module) {
  *  Asked once per pass, and every worker started with it, rather than through `lake env` each. */
 function lakeEnv(root) {
     return new Promise((resolveP, reject) => {
-        const child = spawn("lake", ["env", "env", "-0"], { cwd: root, stdio: ["ignore", "pipe", "pipe"] });
+        // the server's own variables are not the workers': they are given this environment
+        const child = grouped(spawn("lake", ["env", "env", "-0"], { cwd: root, stdio: ["ignore", "pipe", "pipe"], detached: DETACH, env: childEnv() }));
         const out = [];
         let err = "";
         child.stdout.on("data", (b) => out.push(b));

package/dist/server/version.js

@@ -0,0 +1,183 @@
+// Versions: this package's own, and the ranges package.json's `engines` writes, as `visualproof
+// doctor` checks Node against them and a server checks a release it would take (server/updates.ts).
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+let own = null;
+/** The version of this package: read once, as the process started it, so that a package installed
+ *  over it meanwhile does not change what it says it runs (UpdateSpec decision 5). */
+export function packageVersion() {
+    return (own ??= JSON.parse(readFileSync(join(import.meta.dirname, "..", "..", "package.json"), "utf8")).version);
+}
+export function parseVersion(v) {
+    const m = /(\d+)\.(\d+)\.(\d+)/.exec(v);
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+export function cmp(a, b) {
+    for (let i = 0; i < 3; i++)
+        if (a[i] !== b[i])
+            return a[i] - b[i];
+    return 0;
+}
+/** npm's order: by the numbers, then a prerelease before its release, then the prerelease
+ *  identifiers one by one (numbers before words, numbers by value, words as text), fewer first. */
+function order(a, b) {
+    const c = cmp(a.v, b.v);
+    if (c)
+        return c;
+    if (!a.pre.length || !b.pre.length)
+        return (b.pre.length ? 1 : 0) - (a.pre.length ? 1 : 0);
+    for (let i = 0; i < Math.max(a.pre.length, b.pre.length); i++) {
+        const x = a.pre[i], y = b.pre[i];
+        if (x === undefined)
+            return -1;
+        if (y === undefined)
+            return 1;
+        if (x === y)
+            continue;
+        if (typeof x === "number" && typeof y === "number")
+            return x - y;
+        if (typeof x === "number")
+            return -1;
+        if (typeof y === "number")
+            return 1;
+        return x < y ? -1 : 1;
+    }
+    return 0;
+}
+/** Prerelease identifiers, as npm takes them: none empty, a number without a leading zero. */
+function prerelease(text) {
+    if (text === undefined)
+        return [];
+    const ids = text.split(".");
+    if (ids.some((id) => !/^[0-9A-Za-z-]+$/.test(id) || /^0\d+$/.test(id)))
+        return null;
+    return ids.map((id) => (/^\d+$/.test(id) ? Number(id) : id));
+}
+const NUM = "0|[1-9]\\d*";
+const PART = `(${NUM}|[xX*])`;
+const PARTIAL = new RegExp(`^v?${PART}(?:\\.${PART})?(?:\\.${PART})?(?:-([^+]+))?(?:\\+[0-9A-Za-z.-]+)?$`);
+function partial(text) {
+    const m = PARTIAL.exec(text);
+    if (!m)
+        return null;
+    const part = (x) => (x === undefined || /^[xX*]$/.test(x) ? null : Number(x));
+    const p = [part(m[1]), part(m[2]), part(m[3])];
+    // a wildcard leaves the parts after it wild (`1.x.3` is `1.x`)
+    for (let i = 1; i < 3; i++)
+        if (p[i - 1] === null)
+            p[i] = null;
+    const pre = prerelease(m[4]);
+    if (pre === null || (pre.length && p[2] === null))
+        return null;
+    return { p, pre };
+}
+/** the least version a partial one covers: a version written whole is itself; one with a wild part
+ *  (`22`, `22.18.x`) starts at its first prerelease (`22.0.0-0`), as npm's includePrerelease has it */
+const lower = (x) => ({ v: [x.p[0] ?? 0, x.p[1] ?? 0, x.p[2] ?? 0], pre: x.pre.length ? x.pre : x.p[2] === null ? [0] : [] });
+/** the first version past what a partial version covers (`1.2` covers 1.2.x: up to 1.3.0's first
+ *  prerelease, 1.3.0-0); null for `*` */
+function past(x) {
+    const [a, b, c] = x.p;
+    if (a === null)
+        return null;
+    if (b === null)
+        return { v: [a + 1, 0, 0], pre: [0] };
+    if (c === null)
+        return { v: [a, b + 1, 0], pre: [0] };
+    return { v: [a, b, c + 1], pre: [0] };
+}
+/** One comparator as npm reads it (node-semver's desugaring), as bounds; null where it is no comparator. */
+function bounds(op, text) {
+    const x = partial(text);
+    if (!x)
+        return null;
+    const lo = lower(x);
+    const hi = past(x);
+    const wild = x.p[2] === null;
+    switch (op) {
+        case "":
+        case "=":
+            // one version, or an x-range
+            return !wild ? [["=", lo]] : hi ? [[">=", lo], ["<", hi]] : [];
+        case ">=":
+            return [[">=", lo]];
+        case ">":
+            // past what it covers: `>1.2` is `>=1.3.0`; `>*`, nothing
+            return !wild ? [[">", lo]] : hi ? [[">=", hi]] : [["<", { v: [0, 0, 0], pre: [0] }]];
+        case "<":
+            return [["<", lo]];
+        case "<=":
+            return !wild ? [["<=", lo]] : hi ? [["<", hi]] : [];
+        case "~":
+        case "~>": {
+            // patches of the minor given (of the major, where only it is)
+            const [a, b] = x.p;
+            if (a === null)
+                return [];
+            return [[">=", lo], ["<", { v: b === null ? [a + 1, 0, 0] : [a, b + 1, 0], pre: [0] }]];
+        }
+        case "^": {
+            // the same leftmost part that is not zero
+            const [a, b, c] = x.p;
+            if (a === null)
+                return [];
+            const top = a > 0 || b === null ? [a + 1, 0, 0] : b > 0 || c === null ? [0, b + 1, 0] : [0, 0, c + 1];
+            return [[">=", lo], ["<", { v: top, pre: [0] }]];
+        }
+    }
+    return null;
+}
+/** an operator, spaces, a version: `>= 22.0.0` as `>=22.0.0`; never `> = 22` */
+const COMPARATOR = /^(<=|>=|<|>|=|\^|~>|~)?\s*([^\s<>=^~]+)\s*/;
+/** One alternative of a range (no `||`): a hyphen range, or comparators joined by spaces; null where
+ *  npm could not read it. */
+function alternative(text) {
+    const t = text.trim();
+    if (!t)
+        return [];
+    const hyphen = /^(\S+)\s+-\s+(\S+)$/.exec(t);
+    if (hyphen) {
+        const a = partial(hyphen[1]);
+        const b = partial(hyphen[2]);
+        if (!a || !b)
+            return null;
+        const top = b.p[2] === null ? past(b) : null;
+        return [[">=", lower(a)], ...(b.p[0] === null ? [] : top ? [["<", top]] : [["<=", lower(b)]])];
+    }
+    const out = [];
+    for (let rest = t; rest;) {
+        const m = COMPARATOR.exec(rest);
+        if (!m)
+            return null;
+        const b = bounds(m[1] ?? "", m[2]);
+        if (!b)
+            return null;
+        out.push(...b);
+        rest = rest.slice(m[0].length);
+    }
+    return out;
+}
+/** Whether `version` meets a range as package.json's `engines` writes one, as npm checks a Node
+ *  against engines (npm-install-checks: semver with includePrerelease): alternatives joined by
+ *  `||`, each a hyphen range (`22.18.0 - 24`) or comparators joined by spaces — `>=`, `>`, `<=`,
+ *  `<`, `=`, `^`, `~`, a version, an x-range (`22`, `22.x`, `22.18.*`, `*`) — an operator apart from
+ *  its version or not. An empty range, or one of spaces alone, is any version; one npm could not
+ *  read, in any of its alternatives, none. Prereleases in npm's order — 22.18.0 is past
+ *  22.18.0-rc.1, so `<=22.18.0-rc.1` excludes it — and a prerelease Node is taken as any version
+ *  (`24.0.0-rc.1` meets `>=22`; `22.0.0-rc.1` meets `22`, which starts at `22.0.0-0`). */
+export function satisfies(version, range) {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)(?:-([^+]+))?(?:\+.*)?$/.exec(version.trim());
+    const pre = m ? prerelease(m[4]) : null;
+    if (!m || pre === null)
+        return false;
+    const v = { v: [Number(m[1]), Number(m[2]), Number(m[3])], pre };
+    if (range === undefined || range === null || !range.trim())
+        return true;
+    const alts = range.split("||").map(alternative);
+    if (alts.some((a) => a === null))
+        return false;
+    return alts.some((bs) => bs.every(([op, w]) => {
+        const c = order(v, w);
+        return op === ">=" ? c >= 0 : op === ">" ? c > 0 : op === "<=" ? c <= 0 : op === "<" ? c < 0 : c === 0;
+    }));
+}

package/dist/server/view.js

@@ -3,7 +3,6 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { LAYOUT_VERSION } from "../shared/graph.js";
-import { gitSource } from "./history.js";
 import { layOutHere, layOutOffThread } from "./layoutthread.js";
 import { compiledTextHash } from "./status.js";
 import { versionBase, versions } from "./versions.js";
@@ -75,11 +74,6 @@ function viewParts(p, ex) {
     });
     return { nodes, edges };
 }
-/** The project's git source and commit as it is read, where it is a git repository. */
-function gitOf(root) {
-    const git = gitSource(root);
-    return git ? { git } : {};
-}
 function assemble(p, ex, nodes, edges, layouts) {
     const g = ex.graph;
     const meta = {
@@ -93,7 +87,6 @@ function assemble(p, ex, nodes, edges, layouts) {
             toolchain: p.toolchain,
             extractedAt: ex.at,
             extractMs: g.stats.ms,
-            ...gitOf(p.root),
         },
         modules: g.modules.map((m) => {
             const file = p.files.get(m.name) ?? null;

package/dist/server/views.js

@@ -161,6 +161,30 @@ function cleanMemory(x) {
             return null;
     return { set: m.set, mem: { nodes, clusters } };
 }
+/** The Project view as a site keeps it — its pins, folds, hidden levels and clustering — read and
+ *  nothing written (the artwork command, ExportSpec decision 21; the Views class sets aside a file
+ *  it cannot read): null where the site keeps none, or `why` where its views cannot be read. Pins
+ *  dropped under another way of laying out mean nothing in this one, as Views reads them. */
+export function readProjectView(siteDir, layoutVersion) {
+    const file = join(siteDir, "views.json");
+    if (!existsSync(file))
+        return { view: null };
+    try {
+        const raw = JSON.parse(readFileSync(file, "utf8"));
+        for (const r of Array.isArray(raw.views) ? raw.views : []) {
+            const v = readView(r);
+            if (typeof v === "string" || v.id !== PROJECT)
+                continue;
+            if (raw.layoutVersion !== layoutVersion)
+                v.pins = emptyLayouts();
+            return { view: v };
+        }
+        return { view: null };
+    }
+    catch (e) {
+        return { view: null, why: e instanceof Error ? e.message : String(e) };
+    }
+}
 export class Views {
     book;
     file;

package/dist/shared/artfonts.js

@@ -0,0 +1,81 @@
+// Text measured as an artwork's fonts draw it, without a browser (ExportSpec decision 21): the
+// advance widths of the faces the package ships (assets/webfonts/metrics.json, made by
+// scripts/artfonts.py), for a CSS font as a canvas takes it. A face stands for its family at the
+// nearest weight it is made at; a character it has not is measured in the faces that stand in for
+// it (Noto Sans, Noto Sans Math), as the renderer draws it from them. No kerning: the renderer the
+// command draws with is given none either.
+/** the families an artwork's fonts name that the package has not, and the face drawn for them: the
+ *  system's own for the board's names (web/src/canvas.ts FONT), and the generic ones */
+const STANDS_FOR = {
+    "-apple-system": "Source Sans 3",
+    "blinkmacsystemfont": "Source Sans 3",
+    "sf pro text": "Source Sans 3",
+    "inter": "Source Sans 3",
+    "segoe ui": "Source Sans 3",
+    "sans-serif": "Source Sans 3",
+    "system-ui": "Source Sans 3",
+    "georgia": "Source Serif 4",
+    "times new roman": "Source Serif 4",
+    "serif": "Source Serif 4",
+};
+/** A CSS font as a 2D context takes it ("italic 600 12px \"Jost\", sans-serif"): its slant, weight,
+ *  size in pixels, and families in order. */
+export function parseFont(font) {
+    const m = /^\s*((?:(?:italic|oblique|normal|bold|bolder|lighter|\d{3})\s+)*)([\d.]+)px(?:\/[^\s]+)?\s+(.+)$/i.exec(font);
+    if (!m)
+        return { style: "normal", weight: 400, px: 10, families: ["sans-serif"] };
+    const words = m[1].trim().toLowerCase().split(/\s+/).filter(Boolean);
+    const style = words.includes("italic") || words.includes("oblique") ? "italic" : "normal";
+    const num = words.find((w) => /^\d{3}$/.test(w));
+    const weight = num ? Number(num) : words.includes("bold") ? 700 : 400;
+    const families = m[3].split(",").map((f) => f.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
+    return { style, weight, px: Number(m[2]), families };
+}
+/** How wide `text` is in `font`, in pixels, as the package's faces draw it. */
+export function textMeasurer(metrics) {
+    const families = new Map();
+    for (const f of metrics.faces)
+        families.set(f.family.toLowerCase(), [...(families.get(f.family.toLowerCase()) ?? []), f]);
+    const chosen = new Map();
+    /** the face a font is drawn in: its first family the package has (or stands one in for), at the
+     *  slant asked where it is made in it, at the nearest weight */
+    const faceOf = (font) => {
+        const hit = chosen.get(font);
+        if (hit)
+            return hit;
+        const f = parseFont(font);
+        let set;
+        for (const fam of f.families) {
+            const k = fam.toLowerCase();
+            set = families.get(k) ?? families.get(STANDS_FOR[k]?.toLowerCase() ?? "");
+            if (set)
+                break;
+        }
+        set ??= families.get("source sans 3") ?? metrics.faces;
+        const slanted = set.filter((x) => x.style === f.style);
+        const pool = slanted.length ? slanted : set;
+        const face = pool.reduce((a, b) => (Math.abs(b.weight - f.weight) < Math.abs(a.weight - f.weight) ? b : a));
+        const out = { face, px: f.px };
+        chosen.set(font, out);
+        return out;
+    };
+    return (text, font) => {
+        const { face, px } = faceOf(font);
+        let w = 0;
+        for (const ch of text) {
+            const cp = String(ch.codePointAt(0));
+            let units = face.widths[cp];
+            let upm = face.unitsPerEm;
+            if (units === undefined)
+                for (const fb of metrics.fallback)
+                    if (fb.widths[cp] !== undefined) {
+                        units = fb.widths[cp];
+                        upm = fb.unitsPerEm;
+                        break;
+                    }
+            // a character no face has: about an en, as a renderer's missing glyph is drawn
+            w += ((units ?? face.unitsPerEm * 0.55) / upm) * px;
+        }
+        return w;
+    };
+}

package/dist/shared/artrecipe.js

@@ -0,0 +1,316 @@
+// An artwork recipe (ExportSpec decision 20, drafted 2026-10-15 for the owner's review): what a
+// picture of the board is, in words that hold on any project — a size by its name, names by a rule
+// ("the clusters to depth 1, and the targets"), targets and the selection by full name — so that
+// one recipe makes the same kind of picture of every codebase. An agent sends one
+// (POST /api/agent/artwork, server/agent.ts); the link it gets back carries it after `#`, and the
+// page that opens it resolves it against the board it opens on (web/src/main.ts, openRecipe) and
+// opens the artwork mode with what it says, saving the files where the link asks.
+import { ART_MAX_SIDE, ART_NAMES_BYTES, ART_RULED_BYTES, ART_STYLES, ART_TARGETS_BYTES, artNameId, cleanNames, FOOT_SIZE, SCHEMES, TITLE_CHARS, TITLE_SIZE } from "./collab.js";
+/** The sizes offered (web/src/artwork.ts, PRESETS), each in either orientation: given landscape;
+ *  `key`, a recipe's name for it. */
+export const ART_PRESETS = [
+    { key: "hd", name: "HD", w: 1920, h: 1080 },
+    { key: "4k", name: "4K", w: 3840, h: 2160 },
+    { key: "square", name: "Square", w: 4096, h: 4096 },
+    { key: "a3", name: "A3, 300 dpi", w: 4961, h: 3508 },
+    { key: "a2", name: "A2, 300 dpi", w: 7016, h: 4961 },
+];
+/** How a click selects, as the address names it (web/src/selection.ts, TOOLS): Selection; Rests on's
+ *  Uses, TCB, Keys and Direct; Used by. */
+export const RECIPE_MODES = ["plain", "deps", "tcb", "keys", "refs", "apps"];
+/** The most a recipe takes, in bytes of its JSON: the link carries it. */
+export const RECIPE_BYTES = 6000;
+const FIELDS = ["size", "orientation", "style", "theme", "transparent", "colouring", "border", "title", "subtitle", "titleSize", "footSize", "source", "names", "targets", "keys", "notes", "edges", "selection", "lit", "view"];
+const NAME_FIELDS = ["from", "clusters", "minShare", "targets", "decls", "omit"];
+/** A recipe as given, checked: each field as it says, nothing unknown (a field misspelt would
+ *  otherwise be a picture silently unlike the one meant). */
+export function readRecipe(v) {
+    const bad = (error, hint) => ({ error, hint });
+    if (!v || typeof v !== "object" || Array.isArray(v))
+        return bad("recipe is an object.", 'E.g. {"size": "a2", "orientation": "portrait", "names": {"clusters": 1}}.');
+    if (new TextEncoder().encode(JSON.stringify(v)).length > RECIPE_BYTES)
+        return bad(`A recipe is at most ${RECIPE_BYTES} bytes.`, "Name clusters by a depth rather than one by one.");
+    const o = v;
+    const unknown = Object.keys(o).filter((k) => !FIELDS.includes(k));
+    if (unknown.length)
+        return bad(`recipe has no field ${unknown.join(", ")}.`, `Its fields: ${FIELDS.join(", ")}.`);
+    const r = {};
+    const bool = (k) => {
+        if (o[k] === undefined)
+            return null;
+        if (typeof o[k] !== "boolean")
+            return `${k} is true or false.`;
+        r[k] = o[k];
+        return null;
+    };
+    const oneOf = (k, of) => {
+        if (o[k] === undefined)
+            return null;
+        if (!of.includes(o[k]))
+            return `${k} is ${of.join(", ")}.`;
+        r[k] = o[k];
+        return null;
+    };
+    const num = (k, least, most) => {
+        if (o[k] === undefined)
+            return null;
+        if (typeof o[k] !== "number" || !Number.isFinite(o[k]) || o[k] < least || o[k] > most)
+            return `${k} is a number from ${least} to ${most} (hundredths of the picture's height).`;
+        r[k] = o[k];
+        return null;
+    };
+    const text = (k) => {
+        if (o[k] === undefined)
+            return null;
+        if (o[k] !== null && (typeof o[k] !== "string" || o[k].length > TITLE_CHARS))
+            return `${k} is text of at most ${TITLE_CHARS} characters, "" for none, or null for the project's own.`;
+        r[k] = o[k];
+        return null;
+    };
+    const names = (x) => Array.isArray(x) && x.length <= 2000 && x.every((n) => typeof n === "string" && n.length > 0 && n.length <= 1000);
+    const fault = bool("transparent") ?? bool("border") ?? bool("source") ?? bool("keys") ?? bool("notes") ?? bool("lit") ??
+        oneOf("orientation", ["landscape", "portrait"]) ?? oneOf("style", ART_STYLES) ?? oneOf("theme", ["light", "dark"]) ??
+        oneOf("colouring", SCHEMES) ?? oneOf("edges", ["all", "selection", "none"]) ??
+        num("titleSize", TITLE_SIZE.least, TITLE_SIZE.most) ?? num("footSize", FOOT_SIZE.least, FOOT_SIZE.most) ?? text("title") ?? text("subtitle");
+    if (fault)
+        return bad(fault, "See GET /api/agent/docs/export, \"Artwork\".");
+    if (o.size !== undefined) {
+        const s = o.size;
+        if (typeof s === "string") {
+            if (!ART_PRESETS.some((p) => p.key === s))
+                return bad(`size ${s} is no size.`, `A size by name (${ART_PRESETS.map((p) => p.key).join(", ")}) or {w, h} in pixels.`);
+            r.size = s;
+        }
+        else {
+            const sw = s?.w, sh = s?.h;
+            const side = (x) => Number.isInteger(x) && x >= 16 && x <= ART_MAX_SIDE;
+            if (!side(sw) || !side(sh))
+                return bad(`size is a name or {w, h}: whole pixels from 16 to ${ART_MAX_SIDE}.`, `Names: ${ART_PRESETS.map((p) => p.key).join(", ")}.`);
+            r.size = { w: sw, h: sh };
+        }
+    }
+    if (o.names !== undefined) {
+        const n = o.names;
+        if (n === "board" || n === "clusters" || n === "none")
+            r.names = n;
+        else if (n && typeof n === "object" && !Array.isArray(n)) {
+            const m = n;
+            const extra = Object.keys(m).filter((k) => !NAME_FIELDS.includes(k));
+            if (extra.length)
+                return bad(`names has no field ${extra.join(", ")}.`, `Its fields: ${NAME_FIELDS.join(", ")}.`);
+            const rule = {};
+            if (m.from !== undefined) {
+                if (m.from !== "none" && m.from !== "board")
+                    return bad("names.from is none or board.", "From none: only what the rule names; from board: what the board writes, the rule's besides.");
+                rule.from = m.from;
+            }
+            if (m.clusters !== undefined) {
+                if (Number.isInteger(m.clusters) && m.clusters >= 0 && m.clusters <= 20)
+                    rule.clusters = m.clusters;
+                else if (names(m.clusters))
+                    rule.clusters = m.clusters;
+                else
+                    return bad("names.clusters is a depth (0: the top level) or a list of clusters' keys.", "E.g. 1: the top level and the clusters right under it.");
+            }
+            if (m.minShare !== undefined) {
+                if (typeof m.minShare !== "number" || !(m.minShare >= 0 && m.minShare <= 1))
+                    return bad("names.minShare is a share from 0 to 1.", "0.01: a cluster below the top named where it holds at least 1% of the project's declarations.");
+                rule.minShare = m.minShare;
+            }
+            if (m.targets !== undefined) {
+                if (typeof m.targets !== "boolean")
+                    return bad("names.targets is true or false.", "The shown targets' names.");
+                rule.targets = m.targets;
+            }
+            for (const k of ["decls", "omit"]) {
+                if (m[k] === undefined)
+                    continue;
+                if (!names(m[k]))
+                    return bad(`names.${k} is a list of names.`, k === "decls" ? "Declarations by full name." : "Clusters by key, declarations by full name.");
+                rule[k] = m[k];
+            }
+            r.names = rule;
+        }
+        else
+            return bad('names is "board", "clusters", "none" or a rule {from, clusters, minShare, targets, decls, omit}.', 'E.g. {"clusters": 1}: the top level and the clusters right under it, and the targets.');
+    }
+    if (o.targets !== undefined) {
+        const t = o.targets;
+        if (t === "all" || t === "none" || t === "faded")
+            r.targets = t;
+        else if (names(t))
+            r.targets = t;
+        else
+            return bad('targets is "all", "none", "faded" or a list of targets\' full names.', "Those named are marked, the others drawn as any declaration.");
+    }
+    if (o.selection !== undefined && o.selection !== null) {
+        const s = o.selection;
+        if (!s || typeof s !== "object" || typeof s.name !== "string" || !s.name || (s.mode !== undefined && !RECIPE_MODES.includes(s.mode)) || Object.keys(s).some((k) => k !== "name" && k !== "mode"))
+            return bad("selection is {name, mode?}: a declaration's full name, and how it is selected.", `mode: ${RECIPE_MODES.join(", ")} (default tcb).`);
+        r.selection = { name: s.name, ...(s.mode !== undefined ? { mode: s.mode } : {}) };
+    }
+    else if (o.selection === null)
+        r.selection = null;
+    if (o.view !== undefined && o.view !== null) {
+        if (typeof o.view !== "string" || !o.view || o.view.length > 200)
+            return bad("view is a view's id.", "GET /api/agent/views lists them; left out, the Project.");
+        r.view = o.view;
+    }
+    return { recipe: r };
+}
+/** the outside world's cluster, as a reader may call it */
+const EXTERNAL = "⟨external⟩";
+const keyOf = (k) => (k === "External" ? EXTERNAL : k.startsWith("External.") ? EXTERNAL + k.slice(8) : k);
+/** A recipe resolved against a board: everything it leaves out as a new artwork has it (4K
+ *  landscape, the board's look, light, names as the board writes them, every target marked). Names
+ *  are written from none: the clusters named by key, the declarations and the targets' names
+ *  wherever they fall (ArtworkLook `shownNames`), as names ticked by hand are; the clusters a depth
+ *  rule names — the outside world's own, and the project's down to the depth that hold `minShare`
+ *  of the project — only where they cover no name already written (`ruledNames`; the owner's
+ *  decision of 2026-10-15: names chosen by a rule never overlap). */
+export function resolveRecipe(r, b) {
+    const problems = [];
+    const preset = typeof r.size === "string" ? ART_PRESETS.find((p) => p.key === r.size) : ART_PRESETS[1];
+    const given = typeof r.size === "object" ? r.size : { w: preset.w, h: preset.h };
+    const portrait = r.orientation ? r.orientation === "portrait" : given.h > given.w;
+    const [long, short] = given.w >= given.h ? [given.w, given.h] : [given.h, given.w];
+    const { w, h } = portrait ? { w: short, h: long } : { w: long, h: short };
+    // what the recipe names that the board has not is said (`problems`); what is left out for room,
+    // counted (`left`); a target of the review the board has not — a target outlives its declaration's
+    // rename or removal — is left out unsaid, as the board leaves it
+    let left = 0;
+    const targetSet = new Set(b.targets);
+    const held = (n) => b.clusterOf(n) !== undefined;
+    let targets = "marked";
+    let shownTargets = [];
+    let marked = b.targets.filter(held);
+    if (r.targets === "none")
+        [targets, marked] = ["plain", []];
+    else if (r.targets === "faded")
+        targets = "highlight";
+    else if (Array.isArray(r.targets)) {
+        const unknown = r.targets.filter((t) => !targetSet.has(t));
+        if (unknown.length)
+            problems.push(`not targets of the review: ${unknown.join(", ")}`);
+        const off = r.targets.filter((t) => targetSet.has(t) && !held(t));
+        if (off.length)
+            problems.push(`targets not on the board: ${off.join(", ")}`);
+        const on = r.targets.filter((t) => targetSet.has(t) && held(t));
+        shownTargets = cleanNames(on, ART_TARGETS_BYTES);
+        left += new Set(on).size - shownTargets.length;
+        targets = "chosen";
+        marked = shownTargets;
+    }
+    // the names
+    let labels = "board";
+    let namesFrom = "board";
+    let shown = [];
+    let hidden = [];
+    let ruledIds = [];
+    const named = { clusters: [], ruled: [], decls: [] };
+    const n = r.names;
+    if (n === "board" || n === "clusters" || n === "none")
+        labels = n;
+    else if (n) {
+        labels = "chosen";
+        namesFrom = n.from ?? "none";
+        const omit = new Set((n.omit ?? []).map(keyOf));
+        const byKey = new Map(b.clusters.map((c, i) => [c.key, i]));
+        if (typeof n.clusters === "number") {
+            const least = Math.ceil((n.minShare ?? 0.01) * b.projectCount);
+            b.clusters.forEach((c) => {
+                if ((c.ext ? c.depth === 0 : c.depth <= n.clusters && c.count >= least) && !omit.has(c.key))
+                    named.ruled.push(c.key);
+            });
+        }
+        else if (Array.isArray(n.clusters)) {
+            for (const k of n.clusters) {
+                const key = keyOf(k);
+                if (!byKey.has(key))
+                    problems.push(`no cluster ${k} on the board`);
+                else if (!omit.has(key) && !named.clusters.includes(key))
+                    named.clusters.push(key);
+            }
+        }
+        // the targets' names (all on the board), and the declarations named
+        const decls = n.targets === false ? [] : [...marked];
+        for (const d of n.decls ?? []) {
+            if (!held(d))
+                problems.push(`no declaration ${d} on the board`);
+            else
+                decls.push(d);
+        }
+        for (const d of decls)
+            if (!omit.has(d) && !named.decls.includes(d))
+                named.decls.push(d);
+        const ids = [...named.clusters.map((k) => artNameId("cluster", k)), ...named.decls.map((d) => artNameId("decl", d))];
+        shown = cleanNames(ids, ART_NAMES_BYTES);
+        const ruled = named.ruled.map((k) => artNameId("cluster", k));
+        ruledIds = cleanNames(ruled, ART_RULED_BYTES);
+        left += ids.length + ruled.length - shown.length - ruledIds.length;
+        // what is named is what the artwork carries
+        const kept = new Set([...shown, ...ruledIds]);
+        named.clusters = named.clusters.filter((k) => kept.has(artNameId("cluster", k)));
+        named.ruled = named.ruled.filter((k) => kept.has(artNameId("cluster", k)));
+        named.decls = named.decls.filter((d) => kept.has(artNameId("decl", d)));
+        // from the board, what to leave out is said as hidden
+        if (namesFrom === "board")
+            hidden = cleanNames([...omit].map((k) => (byKey.has(k) ? artNameId("cluster", k) : artNameId("decl", k))), ART_NAMES_BYTES);
+    }
+    const look = {
+        w,
+        h,
+        scheme: r.colouring ?? "kind",
+        theme: r.theme ?? "light",
+        background: r.transparent ? "transparent" : "theme",
+        labels,
+        namesFrom,
+        hiddenNames: hidden,
+        shownNames: shown,
+        ruledNames: ruledIds,
+        edges: r.edges ?? "all",
+        notes: r.notes ?? true,
+        targets,
+        shownTargets,
+        keys: r.keys ?? true,
+        selection: r.lit ?? true,
+        source: r.source ?? false,
+        style: r.style ?? "board",
+        title: r.title ?? null,
+        subtitle: r.subtitle ?? null,
+        titleSize: r.titleSize ?? TITLE_SIZE.first,
+        footSize: r.footSize ?? FOOT_SIZE.first,
+        border: r.border ?? false,
+    };
+    return { look, named, left, problems };
+}
+/** A recipe as the link carries it after `#`: its JSON, base64url. */
+export function encodeRecipe(r) {
+    const bytes = new TextEncoder().encode(JSON.stringify(r));
+    let s = "";
+    for (const x of bytes)
+        s += String.fromCharCode(x);
+    return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/** A link's recipe, read back; null where it is none. */
+export function decodeRecipe(text) {
+    try {
+        const s = atob(text.replace(/-/g, "+").replace(/_/g, "/"));
+        return JSON.parse(new TextDecoder().decode(Uint8Array.from(s, (c) => c.charCodeAt(0))));
+    }
+    catch {
+        return null;
+    }
+}
+/** the address's word for the recipe, and for the files to save */
+export const RECIPE_PARAM = "art";
+export const SAVE_PARAM = "save";
+/** A fragment's recipe and the files it asks to save; null where it carries none. */
+export function recipeIn(hash) {
+    const p = new URLSearchParams(hash.startsWith("#") ? hash.slice(1) : hash);
+    const text = p.get(RECIPE_PARAM);
+    if (!text)
+        return null;
+    const save = (p.get(SAVE_PARAM) ?? "").split(",").filter((k) => k === "png" || k === "svg");
+    return { text, save: [...new Set(save)] };
+}