visualproof 0.2.0 → 0.3.0

package/dist/web/src/visits.js

@@ -0,0 +1,174 @@
+// The reader's visitors laid on the board's scene (ViewSpec decision 27, the owner's decision of
+// 2026-10-11): each in its own place in the cluster hierarchy, the clusters it needs added as
+// temporary ones (web/src/visitors.ts, planVisitors), the outermost of them in the deepest cluster the
+// board draws, at a spot chosen once.
+//
+// Making room: what a visitor brings goes where its cluster has free room, nearest the declarations it
+// has references with; where the cluster has none, against its rim where it covers least, and what it
+// covers makes way, as from a drop, the circle growing only where that cannot fit (web/src/scene.ts,
+// setHeld). Nothing of it is a pin or the board's: when the visitors go, every place comes back.
+//
+// A spot is in its cluster's coordinates and carried to followers with the trail (PresenceView), so a
+// follower draws the temporary clusters where the leader does; the rest — which clusters, nested how,
+// packed how — is a function of the visitors and the board, the same on every page.
+import { LEAF_R } from "./scene.js";
+import { freeSpot, packPlan, planVisitors, rimSpot } from "./visitors.js";
+/** How far outside what it holds a cluster's circle is drawn (web/src/scene.ts, computeExtents). */
+const DRAWN_MARGIN = 6;
+/** Whether a declaration's name is a namespace too, on a board whose declarations are `names` (the
+ *  outside world's left out), the visitors' among them: a structure then sits in its own namespace's
+ *  cluster, as the board would draw it (shared/layout.ts, pathOf). */
+export function prefixTest(g, visitors) {
+    const memo = new Map();
+    return (name) => {
+        let hit = memo.get(name);
+        if (hit !== undefined)
+            return hit;
+        const head = `${name}.`;
+        hit = visitors.some((v) => v.startsWith(head));
+        for (let i = 0; !hit && i < g.n; i++)
+            if (!g.isExt(i) && g.nodes[i].name.startsWith(head))
+                hit = true;
+        memo.set(name, hit);
+        return hit;
+    };
+}
+/** Where the visitors `vs` belong on a board (web/src/visitors.ts, planVisitors): its layout `L` by
+ *  `mode`, the levels `hidden`, its graph `g`. */
+export function planOn(L, mode, hidden, g, vs) {
+    const drawn = new Map(L.clusters.map((c, k) => [c.key, k]));
+    return planVisitors(mode, drawn, new Set(hidden), vs, prefixTest(g, vs.map((v) => v.name)));
+}
+/** The board's clusters round the places of the visitors `chosen` (indices of the trail): the folded
+ *  ones among them open for the reader while those are selected (ViewSpec decision 27). */
+export function openFor(plan, parent, chosen) {
+    const out = new Set();
+    for (const k of chosen)
+        for (let c = plan.at[k]?.in ?? -1; c >= 0; c = parent[c])
+            out.add(c);
+    return out;
+}
+/** Place the visitors `vs` (the trail, oldest first) on a board as `plan` says (planOn): its layout
+ *  `L`, its scene `S` as the board arranges it. An item keeps the place its oldest visitor has in
+ *  that cluster; one with none is given a spot — in the order its oldest visitor came, so that a newer
+ *  one never moves an older one — where `ok` (a spot of the world and a radius) finds no cluster's
+ *  name written. */
+export function placeVisits(S, L, plan, vs, ok = () => true) {
+    const names = vs.map((v) => v.name);
+    const pack = packPlan(plan, names);
+    const keyOf = (c) => (c < 0 ? "" : L.clusters[c].key);
+    // the outermost items, and which visitors each holds
+    const items = [];
+    const ofTemp = new Map();
+    plan.temps.forEach((t, k) => {
+        if (t.up >= 0)
+            return;
+        ofTemp.set(k, items.length);
+        items.push({ in: t.in, temp: k, visitor: -1, at: [0, 0], r: pack.r[k], slot: 0 });
+    });
+    const item = plan.at.map((a, k) => {
+        if (a.up < 0) {
+            items.push({ in: a.in, temp: -1, visitor: k, at: [0, 0], r: LEAF_R, slot: 0 });
+            return items.length - 1;
+        }
+        let t = a.up;
+        while (plan.temps[t].up >= 0)
+            t = plan.temps[t].up;
+        return ofTemp.get(t);
+    });
+    const members = items.map(() => []);
+    item.forEach((j, k) => members[j].push(k));
+    // in the order their oldest visitors came
+    const order = items.map((_, j) => j).sort((a, b) => members[a][0] - members[b][0]);
+    const placed = new Map();
+    for (const j of order) {
+        const it = items[j];
+        const kept = members[j].map((k) => vs[k].place).find((p) => p && p.in === keyOf(it.in));
+        if (kept)
+            it.at = [kept.at[0], kept.at[1]];
+        else {
+            const room = S.roomOf(it.in);
+            // a sub-cluster's circle is drawn a little outside what it holds (Scene, computeExtents)
+            const bodies = [...S.discsIn(it.in).map((d) => (d.r > LEAF_R ? { ...d, r: d.r + DRAWN_MARGIN } : d)), ...(placed.get(it.in) ?? []).map((o) => ({ x: o.at[0], y: o.at[1], r: o.r }))];
+            // towards the declarations it has references with, as the board arranges them
+            const [ox, oy] = S.anchorWorld(it.in);
+            let sx = 0, sy = 0, m = 0;
+            for (const k of members[j])
+                for (const i of vs[k].near) {
+                    const [cx, cy] = S.anchorWorld(S.nodeCluster[i]);
+                    sx += cx + S.ancNX[i];
+                    sy += cy + S.ancNY[i];
+                    m++;
+                }
+            const prefer = m ? [sx / m - ox, sy / m - oy] : [0, 0];
+            const okHere = (x, y) => ok(ox + x, oy + y, it.r);
+            it.at = freeSpot(bodies, room, it.r, prefer, okHere) ?? rimSpot(bodies, room, it.r, prefer);
+        }
+        const list = placed.get(it.in) ?? [];
+        it.slot = list.length;
+        list.push(it);
+        placed.set(it.in, list);
+    }
+    const held = new Map();
+    for (const [c, list] of placed)
+        held.set(c, list.map((o) => ({ x: o.at[0], y: o.at[1], r: o.r })));
+    const places = item.map((j) => ({ in: keyOf(items[j].in), at: [items[j].at[0], items[j].at[1]] }));
+    return { plan, pack, items, item, places, held };
+}
+export function visitWorld(V, S) {
+    const T = V.plan.temps.length, K = V.plan.at.length;
+    const W = { tx: new Float64Array(T), ty: new Float64Array(T), tr: new Float64Array(T), trep: new Int32Array(T), vx: new Float64Array(K), vy: new Float64Array(K), vrep: new Int32Array(K) };
+    const centre = (it) => {
+        const at = S.heldAt.get(it.in);
+        const hx = at ? at[2 * it.slot] : it.at[0], hy = at ? at[2 * it.slot + 1] : it.at[1];
+        if (it.in < 0)
+            return [hx, hy, 1];
+        const s = S.scale[it.in];
+        return [S.cwx[it.in] + hx * s, S.cwy[it.in] + hy * s, s];
+    };
+    const scaleOf = (c) => (c < 0 ? 1 : S.scale[c]);
+    const repOf = (c) => (c < 0 ? -1 : S.rep[c]);
+    for (let t = 0; t < T; t++) {
+        const tc = V.plan.temps[t];
+        const s = scaleOf(tc.in);
+        if (tc.up < 0) {
+            const it = V.items[V.items.findIndex((x) => x.temp === t)];
+            [W.tx[t], W.ty[t]] = centre(it);
+        }
+        else {
+            W.tx[t] = W.tx[tc.up] + V.pack.x[t] * s;
+            W.ty[t] = W.ty[tc.up] + V.pack.y[t] * s;
+        }
+        W.tr[t] = V.pack.r[t] * s;
+        W.trep[t] = repOf(tc.in);
+    }
+    for (let k = 0; k < K; k++) {
+        const a = V.plan.at[k];
+        if (a.up >= 0) {
+            const s = scaleOf(a.in);
+            W.vx[k] = W.tx[a.up] + V.pack.vx[k] * s;
+            W.vy[k] = W.ty[a.up] + V.pack.vy[k] * s;
+        }
+        else
+            [W.vx[k], W.vy[k]] = centre(V.items[V.item[k]]);
+        W.vrep[k] = repOf(a.in);
+    }
+    return W;
+}
+/** A visitor's chain of position ids up to the top level, as its edges are bundled through the
+ *  hierarchy (web/src/bundles.ts, joinChains): itself, its temporary clusters, the board's clusters
+ *  round it — or, hidden in a folded cluster's card, that card and the clusters round it. Ids past the
+ *  scene's (`base` = clusters and declarations) are the visitors' own: a temporary cluster t at
+ *  base + t, a visitor k at base + temps + k. */
+export function visitChain(V, W, S, base, k) {
+    const out = [];
+    const a = V.plan.at[k];
+    if (W.vrep[k] < 0) {
+        out.push(base + V.plan.temps.length + k);
+        for (let t = a.up; t >= 0; t = V.plan.temps[t].up)
+            out.push(base + t);
+    }
+    for (let c = W.vrep[k] >= 0 ? W.vrep[k] : a.in; c >= 0; c = S.parent[c])
+        out.push(c);
+    return out;
+}

package/dist/web/style.css

@@ -438,6 +438,12 @@ body.art-moving :is(#bar .brand, #bar .library-wrap, #export-btn, #activity-btn,
 }
 .sw-review .rv-text { min-height: calc(5 * 1.45em + 12px); }
 .rv-actions { display: flex; flex-wrap: wrap; align-items: center; gap: 6px; }
+/* whom the opinion is for (ReviewSpec decision 8): a name beside the buttons; while it is another
+   person's, a coloured line over the box says so */
+.rv-for { display: inline-flex; align-items: center; gap: 5px; margin-left: auto; font-size: 11.5px; color: var(--text-2); white-space: nowrap; }
+.rv-for-in { width: 9em; font: 12px var(--font); color: var(--text); background: var(--surface-solid); border: 1px solid var(--line); border-radius: 6px; padding: 3px 6px; }
+.rv-for-on { margin: 0 0 6px; padding: 5px 9px; border-radius: 7px; font-size: 12px; color: var(--accent); background: color-mix(in srgb, var(--accent) 12%, transparent); border: 1px solid color-mix(in srgb, var(--accent) 35%, transparent); }
+.rv-for-on[hidden] { display: none; }
 .rv-btn {
   border: 1px solid var(--line); background: var(--surface-solid); color: var(--text); font: 12px var(--font);
   padding: 4px 10px; border-radius: 7px; cursor: pointer;
@@ -1967,6 +1973,7 @@ a.link:hover { text-decoration: underline; }
 /* the reader's "Open in editor" template, under the keys */
 .help-editor, .help-about { display: flex; flex-direction: column; gap: 6px; margin-top: 16px; padding-top: 12px; border-top: 1px solid var(--line); }
 .help-note { color: var(--text-2); font-size: 12px; line-height: 1.45; }
+.help-note a { color: var(--accent); }
 .help-note code { font: 11px var(--mono); background: var(--code-bg); padding: 1px 4px; border-radius: 4px; overflow-wrap: anywhere; }
 .help-input {
   font: 12.5px var(--mono); color: var(--text); background: var(--surface-solid); border: 1px solid var(--line);

package/docs/agent-api/README.md

@@ -85,7 +85,7 @@ parameters and answer.
 | [following](following.md) | where people are, your own view, links to it, asking to follow, what people see |
 | [views](views.md) | the query language, views, places on the board, pins and undo |
 | [library](library.md) | papers and images, their pages, links to them |
-| [export](export.md) | a view's document: its model, typesetting, its files |
+| [export](export.md) | a view's document: its model, typesetting, its files; a picture (artwork) |
 | [history](history.md) | the timeline, the builds kept, diffs, renames, the lost-and-found |
 | [talking](talking.md) | your inbox, replies, your status line, your state, the conversation |
 | [mcp](mcp.md) | the MCP server: installing it, its tools and their actions, `wait_for_message` |

package/docs/agent-api/export.md

@@ -1,7 +1,7 @@
 # Exported documents
 
-A view's document, read as JSON or typeset as a PDF. Any level: it only reads. MCP: `export`
-(`model`, `typeset`, `job`, `file`).
+A view's document, read as JSON or typeset as a PDF; and a picture of the board ([Artwork](#artwork)).
+Any level: it only reads. MCP: `export` (`model`, `typeset`, `job`, `file`, `artwork`).
 
 ## What it holds
 
@@ -118,3 +118,42 @@ kept). 503: no XeLaTeX.
   typeset it again (`.tex`, style file, fonts). **409** with `Retry-After: 2` while running, 409 if
   failed, 404 if unknown or gone from the cache. E.g.
   `curl -fsSK ~/.visualproof/curl.cfg "$VP/api/agent/export/file?id=<id>" -o doc.pdf`.
+
+## Artwork
+
+`POST /api/agent/artwork {recipe, save?}`: a link that opens the board as a picture in the artwork mode, as a **recipe** says, in words that
+hold on any project: one recipe makes the same kind of picture of every codebase. The page that
+opens it draws the picture and, with `save` (`png`, `svg`, `png,svg`), saves the files there once
+the board is still; nothing comes back to the server. The link holds no key (a script enters with
+it: `scripts/artwork-batch.mjs` in VisualProof's repository).
+
+```json
+{ "recipe": { "size": "a2", "orientation": "portrait", "theme": "light", "border": true,
+    "names": { "clusters": 1 }, "targets": ["Lib.mainTheorem"],
+    "selection": { "name": "Lib.mainTheorem", "mode": "tcb" }, "keys": false, "notes": false,
+    "source": true, "title": "Lib", "subtitle": "One line about the work" }, "save": "png,svg" }
+```
+
+Every field is optional; left out, as a new artwork has it.
+
+- `size`: `hd`, `4k` (default), `square`, `a3`, `a2` (300 dpi), or `{w, h}`; `orientation`;
+  `style` (`board`, `cells`, `stars`); `theme` (`light`, `dark`), `transparent`; `colouring`
+  (`kind`, `status`); `border`; `title`, `subtitle` (null: the project's own; `""`: none),
+  `titleSize`, `footSize` (hundredths of the height); `source` (git source and commit).
+- `names`: `board`, `clusters`, `none`, or a rule `{clusters, minShare, targets, decls, omit,
+  from}`: `clusters` a depth (0: the top level) or keys; a depth names the outside world and the
+  clusters holding at least `minShare` of the project (default 0.01), each written only where it
+  covers no name already written (`ruled`), never over another; keys, `decls` (full names) and
+  `targets` (default true: the marked targets' names) written wherever they fall; `omit` keys or
+  names; `from` `none` (default) or `board`.
+- `targets`: `all` (default), `none`, `faded`, or a list of targets marked alone. `keys`, `notes`:
+  default true. `edges`: `all` (under a selection, the rest faint), `selection`, `none`.
+- `selection`: `{name, mode}` (`mode` as `POST view`'s; default `tcb`), lit while `lit` (default
+  true). `view`: a view's id; left out, the Project.
+
+Answer: `{ok, link, length, size, names: {clusters, decls, ruled}, targets, selection, left, note}`;
+`left`: names or targets beyond what an artwork carries, left out. Saving both files, the page says
+the browser may ask to allow several downloads. 400: a field unknown or wrong; 404: a name, target,
+cluster or view the recipe names that the board has not (`problems`; a target of the review the
+graph no longer has is left out unsaid).
+

package/docs/agent-api/history.md

@@ -20,7 +20,8 @@ name bare).
 Every event with a `by` has `agent`. `by` is null on a `view`, `note` or `undo` event done without a
 name (a private reader's; their opinions, targets, key marks and trust keep their name).
 
-- Review's logs (no `id`): `opinion`, `target`, `key` (as marked now: `target`, `name`), `file`
+- Review's logs (no `id`): `opinion` (`recordedBy`: who typed it for `by`, at one screen), `target`,
+  `key` (as marked now: `target`, `name`), `file`
   (`what` added, edited, archived or restored; `sha`, `title` then, `wasTitle` before an edit),
   `link` (`what` made, edited or removed; `id`, `subject`, `label`, `file`; an edit's `changed`
   (of `subject`, `label`, `place`), `wasSubject`, `wasLabel`, and `auto` if VisualProof carried it

package/docs/agent-api/mcp.md

@@ -40,7 +40,7 @@ Each wraps the endpoints of a topic, which says what their answers hold. `*`: th
 | `library` | `list`, `file`, `text`, `search`, `page`, `clip`, `save`; `add_url`, `add_file`, `edit`, `archive` (advise) | `library/…`, [library](library.md) |
 | `links` | `list`; `make`, `edit`, `remove` (advise) | `GET links`, `POST link`, `link/edit`, `unlink`, [library](library.md) |
 | `history` | `snapshots`, `diff`, `moves`, `last`, `lost`, `archived`; `attach`, `unmove`, `archive` (full) | `history/…`, [history](history.md) |
-| `export` | `model`, `typeset`, `job`, `file` | `export`, `export/job`, `export/file`, [export](export.md) |
+| `export` | `model`, `typeset`, `job`, `file`, `artwork` | `export`, `export/job`, `export/file`, `artwork`, [export](export.md) |
 
 Paths are under `/api/agent/`. `GET /api/agent/history/graph` has no tool (it is large: ask it over
 HTTP when you need a past build's whole graph).

package/docs/agent-api/reading.md

@@ -36,7 +36,8 @@ Everything about one declaration; here `include=print` while Lean loads:
 - `axioms`: all its proof and definition reach; `nonStandardAxioms`: beyond the standard three
   (`sorryAx`). `review`: `opinions` (people's latest) and `advice` (agents', `yours: true`), one
   each; `onPresentVersion: false`: on an earlier version; `verified: true`: from someone invited by
-  a personal link, `by` their name now; `trustedBy`: covering prefixes, or `["standard axiom"]`.
+  a personal link, `by` their name now; `recordedBy`: typed for `by` by that person, at one screen
+  (theirs all the same); `trustedBy`: covering prefixes, or `["standard axiom"]`.
 - `editedSinceCompiled`: file differs from what was compiled (null outside the project); `keyFor`,
   `inTcbOf`: targets it is key for, whose TCB holds it; `usesDirect`, `usedBy.direct`: what it
   refers to by name, what refers to it (`uses`, `users` list them); `usedBy.all`: all reaching it,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "visualproof",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "See a Lean codebase's declaration graph and the TCB of its theorems.",
   "license": "Apache-2.0",
@@ -20,6 +20,7 @@
     "build": "node scripts/build.mjs",
     "prepack": "npm run build",
     "serve": "node src/server/main.ts serve",
+    "showcase": "node scripts/showcase.mjs",
     "typecheck": "tsc --noEmit -p .",
     "test": "node --test --import ./test/setup.ts \"test/*.test.ts\"",
     "test:toolchains": "node scripts/test-toolchains.mjs",
@@ -29,6 +30,7 @@
     "node": "^22.18.0 || >=24.2.0"
   },
   "dependencies": {
+    "@resvg/resvg-wasm": "2.6.2",
     "d3-hierarchy": "^3.1.2",
     "pdfjs-dist": "6.3.289"
   },