visualproof 0.2.0 → 0.4.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;
@@ -601,7 +607,7 @@ button.o-trust:hover { color: var(--accent); background: var(--code-bg); }
 #windows > * { pointer-events: auto; }
 /* a popover lies above the windows: it was opened last, and goes on a press anywhere else. Those
    inside a bar raise the bar with them while they are open */
-#bar:has(#share-pop:not([hidden]), #results:not([hidden]), #who-menu:not([hidden])), #viewbar:has(#views-menu:not([hidden]), #focus-menu:not([hidden])), #zoom:has(#eyes-pop:not([hidden])) { z-index: 36; }
+#bar:has(#share-pop:not([hidden]), #results:not([hidden]), #who-menu:not([hidden]), #help-menu:not([hidden])), #viewbar:has(#views-menu:not([hidden]), #focus-menu:not([hidden])), #zoom:has(#eyes-pop:not([hidden])) { z-index: 36; }
 /* a source window (web/src/sourcewin.ts): floating, not modal; as large as its code needs until the
    reader moves or resizes it (floatwin.ts sets its place, and its bounds while it is fitted to its
    code), scrolling down beyond that */
@@ -1955,6 +1961,9 @@ a.link:hover { text-decoration: underline; }
 .tour-text { font-size: 13px; line-height: 1.5; color: var(--text); }
 .tour-actions { display: flex; align-items: center; gap: 6px; margin-top: 14px; }
 .tour-gap { flex: 1; }
+/* the TCB step's three views of one theorem (GuideSpec decision 2) */
+.tour-seg { display: inline-flex; margin: 0 0 8px; }
+@media (prefers-reduced-motion: reduce) { .tour-shade, .tour-spot, .tour-card { transition: none; } }
 #help { position: fixed; inset: 0; z-index: 45; display: flex; align-items: center; justify-content: center; background: rgba(0, 0, 0, 0.22); }
 .help-box { width: min(660px, calc(100vw - 32px)); max-height: calc(100vh - 48px); overflow: auto; outline: none; }
 .help-head { display: flex; justify-content: space-between; align-items: center; }
@@ -1967,6 +1976,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);
@@ -1982,6 +1992,183 @@ kbd {
   color: var(--text-2); font: 600 14px var(--font); cursor: pointer;
 }
 .help-btn:hover { border-color: var(--accent); color: var(--accent); }
+/* the help menu (GuideSpec decision 8): the tips, the keys, the tour; then what the project and
+   VisualProof are, said in it */
+.help-wrap { position: relative; display: flex; }
+#help-menu {
+  position: absolute; top: 38px; right: 0; width: min(340px, calc(100vw - 24px)); padding: 6px; border-radius: 14px; z-index: 40;
+  display: flex; flex-direction: column; background: color-mix(in srgb, var(--surface-solid) 96%, transparent);
+  box-shadow: 0 0 0 1px var(--line), var(--shadow-lg);
+}
+#help-menu[hidden] { display: none; }
+.hm-item {
+  display: flex; flex-direction: column; gap: 2px; width: 100%; padding: 7px 10px; border: 0; border-radius: 9px;
+  background: transparent; color: var(--text); font: 13px var(--font); text-align: left; text-decoration: none; cursor: pointer;
+}
+.hm-item:hover, .hm-item:focus-visible { background: var(--code-bg); outline: none; }
+.hm-item[aria-disabled="true"] { cursor: default; }
+.hm-item[aria-disabled="true"]:hover { background: none; }
+.hm-t { font-weight: 500; }
+.hm-h { font-size: 11.5px; font-weight: 600; color: var(--text-2); text-transform: uppercase; letter-spacing: 0.04em; }
+.hm-d { font-size: 12px; line-height: 1.4; color: var(--text-2); }
+.hm-d code { font: 11px var(--mono); background: var(--code-bg); padding: 1px 4px; border-radius: 4px; overflow-wrap: anywhere; }
+.hm-sep { height: 1px; margin: 5px 4px; background: var(--line); }
+.hm-link { color: var(--accent); }
+/* the tour has pointed at the tips: a dot on the help until the menu is first opened */
+.help-btn.has-dot, #more-btn.has-dot { position: relative; }
+.help-btn.has-dot::after, #more-btn.has-dot::after {
+  content: ""; position: absolute; top: -1px; right: -1px; width: 8px; height: 8px; border-radius: 50%;
+  background: var(--accent); box-shadow: 0 0 0 2px var(--surface-solid);
+}
+
+/* the sheet's tabs: the tips first, then the keys (GuideSpec decision 8) */
+.help-tabs { display: inline-flex; }
+.help-tabs button { padding: 4px 14px; font-size: 13px; }
+.help-pane { display: flex; flex-direction: column; gap: 12px; margin-top: 12px; }
+.help-pane[hidden] { display: none; }
+/* the Tips tab (GuideSpec decisions 5–8): the tour film with its chapters, then the tips it does not
+   show, one row each. On a larger screen the sheet is as wide as the film needs, within the window */
+@media (min-width: 641px) {
+  .help-box:has([data-help-pane="tips"]:not([hidden])) { width: min(1340px, calc(100vw - 48px)); }
+}
+.help-pane [hidden] { display: none !important; }
+.tips-filter { font-family: var(--font); }
+.tips-list { display: flex; flex-direction: column; gap: 14px; }
+.tips-group { display: flex; flex-direction: column; gap: 6px; }
+/* a part of the panel with the ⓘ of its tip beside its heading (GuideSpec decision 15) */
+.sec-row { display: flex; align-items: center; gap: 4px; }
+.sec-row > .sec-h { flex: 1; min-width: 0; }
+.p-info { flex: none; width: 22px; height: 22px; border: none; border-radius: 50%; background: none; color: var(--text-3); font-size: 14px; cursor: pointer; }
+.p-info:hover { color: var(--accent); background: var(--code-bg); }
+@keyframes tip-flash { from { box-shadow: 0 0 0 3px color-mix(in srgb, var(--accent) 60%, transparent); } to { box-shadow: 0 0 0 3px transparent; } }
+/* the film: the player, its chapters beside it (under it, where the sheet is narrow) */
+.film-h { font-weight: 650; font-size: 15px; letter-spacing: -0.01em; }
+.film { display: grid; grid-template-columns: minmax(0, 960px) minmax(240px, 320px); gap: 16px; align-items: start; }
+@media (max-width: 1100px) { .film { grid-template-columns: minmax(0, 1fr); } }
+/* the film is light: in the dark theme, a thin frame of the theme's own, so that it does not glare */
+.film-stage { outline: none; border-radius: 12px; }
+.film-stage:focus-visible { box-shadow: 0 0 0 2px color-mix(in srgb, var(--accent) 60%, transparent); }
+.film-frame { position: relative; aspect-ratio: 16 / 10; border-radius: 12px; overflow: hidden; background: #f5f5f7; border: 1px solid var(--line); box-shadow: var(--shadow); }
+:root[data-theme="dark"] .film-frame { border: 6px solid #2c2c2e; box-shadow: 0 0 0 1px var(--line), var(--shadow); }
+:root[data-theme="dark"] .film-video, :root[data-theme="dark"] .film-still { filter: brightness(0.92); }
+.film-video, .film-still { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: contain; display: block; }
+/* the controls over the film: play, captions, larger — light, as the film is */
+.film-controls { position: absolute; left: 12px; right: 12px; bottom: 12px; display: flex; align-items: center; gap: 8px; pointer-events: none; }
+.film-controls button {
+  pointer-events: auto; min-width: 36px; height: 36px; padding: 0 10px; border-radius: 18px; border: 1px solid rgba(0, 0, 0, 0.08);
+  background: rgba(255, 255, 255, 0.86); color: #1d1d1f; font: 600 13px var(--font); box-shadow: var(--shadow); cursor: pointer;
+  backdrop-filter: blur(10px);
+}
+.film-controls button:hover { color: var(--accent); }
+.film-controls [data-film-cc][aria-pressed="false"] { color: #a1a1a6; text-decoration: line-through; }
+.film-gap { flex: 1; }
+/* a caption: over the film at the bottom, in the page's own type, a soft pill readable on the light film */
+.film-video::cue { color: transparent; background: transparent; }
+.film-cc {
+  position: absolute; left: 50%; bottom: 60px; transform: translateX(-50%); max-width: min(78%, 760px); padding: 6px 14px;
+  border-radius: 14px; background: rgba(255, 255, 255, 0.84); color: #1d1d1f; font: 500 14px/1.4 var(--font); text-align: center;
+  box-shadow: 0 2px 10px rgba(0, 0, 0, 0.12); backdrop-filter: blur(10px); pointer-events: none;
+}
+/* the film while the server fetches it: said quietly, over the poster */
+.film-wait {
+  position: absolute; left: 50%; top: 50%; transform: translate(-50%, -50%); padding: 6px 14px; border-radius: 14px;
+  background: rgba(255, 255, 255, 0.84); color: #6e6e73; font: 500 13px/1.4 var(--font); box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
+  backdrop-filter: blur(10px); pointer-events: none;
+}
+.film-controls button[disabled] { opacity: 0.45; cursor: default; }
+/* a chapter's captions where the film does not play them: listed under its words */
+.film-cues { margin: 2px 0 0; padding-left: 16px; color: var(--text-2); font-size: 12px; line-height: 1.45; display: flex; flex-direction: column; gap: 2px; }
+.film-side { display: flex; flex-direction: column; gap: 6px; min-width: 0; }
+.film-list-btn { display: none; align-self: flex-start; }
+/* large: the film fills the sheet, its chapters beside it (folded away at a press); then the screen */
+.help-box.film-large { width: calc(100vw - 48px); height: calc(100vh - 48px); max-height: none; }
+.help-box.film-large [data-help-pane="tips"] > :not([data-film]) { display: none; }
+.help-box.film-large .film { grid-template-columns: minmax(0, 1fr) minmax(240px, 320px); align-items: start; }
+.help-box.film-large .film.list-hidden { grid-template-columns: minmax(0, 1fr); }
+.help-box.film-large .film.list-hidden .film-list { display: none; }
+.help-box.film-large .film-list-btn { display: inline-flex; padding: 4px 10px; border-radius: 8px; border: 1px solid var(--line); background: var(--surface-solid); color: var(--text-2); font: 12.5px var(--font); cursor: pointer; }
+.help-box.film-large .film-frame, .help-box.film-large .film-bar { width: min(100%, calc((100vh - 230px) * 1.6)); margin-left: auto; margin-right: auto; }
+.help-box.film-large .film-cc { font-size: 19.5px; bottom: 70px; padding: 8px 18px; border-radius: 18px; }
+@media (max-width: 1100px) { .help-box.film-large .film { grid-template-columns: minmax(0, 1fr); } }
+.film-stage:fullscreen { background: #000; display: flex; flex-direction: column; justify-content: center; padding: 24px; }
+.film-stage:fullscreen .film-frame { width: min(100%, calc((100vh - 80px) * 1.6)); margin: 0 auto; border: none; }
+.film-stage:fullscreen .film-cc { font-size: 24px; bottom: 80px; }
+.film-stage:fullscreen .film-bar { width: min(100%, calc((100vh - 80px) * 1.6)); margin: 8px auto 0; }
+.film-stage:fullscreen .film-track { background: rgba(255, 255, 255, 0.22); }
+/* under the player, a segment per chapter: the one playing fills */
+.film-bar { display: flex; gap: 3px; margin-top: 6px; }
+.film-seg { flex-basis: 0; flex-shrink: 1; padding: 5px 0; border: none; background: none; cursor: pointer; min-width: 4px; }
+.film-track { display: block; height: 5px; border-radius: 3px; background: var(--line); overflow: hidden; }
+.film-seg:hover .film-track { background: color-mix(in srgb, var(--accent) 22%, var(--line)); }
+.film-fill { display: block; height: 100%; background: var(--accent); transform-origin: left; transform: scaleX(0); }
+/* the chapters: one row each, the one playing open */
+.film-list { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 2px; }
+.film-item { border: 1px solid transparent; border-radius: 12px; }
+.film-item.on { border-color: var(--line); background: var(--surface-solid); box-shadow: var(--shadow); }
+.film-card { display: flex; gap: 10px; align-items: baseline; padding: 7px 10px; border-radius: 11px; cursor: pointer; outline: none; }
+.film-card:hover { background: var(--code-bg); }
+.film-item.on .film-card:hover { background: none; }
+.film-card:focus-visible { box-shadow: 0 0 0 2px color-mix(in srgb, var(--accent) 60%, transparent); }
+.film-n { flex: none; width: 1.4em; text-align: right; color: var(--text-3); font-size: 12px; font-variant-numeric: tabular-nums; }
+.film-item.on .film-n { color: var(--accent); font-weight: 600; }
+.film-title { font-weight: 600; font-size: 13px; }
+.film-body { display: flex; flex-direction: column; gap: 6px; padding: 0 12px 11px calc(1.4em + 20px); }
+/* the tips the film does not show: a row each, its title and its first line; one open */
+.refs-head { display: flex; align-items: center; gap: 12px; margin-top: 10px; }
+.refs-head .help-h { margin: 0; }
+.refs-head .tips-filter { flex: 1; max-width: 320px; margin-left: auto; }
+.refs { display: flex; flex-direction: column; border: 1px solid var(--line); border-radius: 12px; overflow: hidden; background: var(--surface-solid); }
+.ref + .ref { border-top: 1px solid var(--line); }
+.ref.flash { animation: tip-flash 1.6s ease-out; }
+@media (prefers-reduced-motion: reduce) { .ref.flash { animation: none; box-shadow: inset 0 0 0 2px color-mix(in srgb, var(--accent) 60%, transparent); } }
+.ref-head { display: flex; gap: 12px; align-items: baseline; width: 100%; padding: 9px 12px; border: none; background: none; text-align: left; font: inherit; color: var(--text); cursor: pointer; }
+.ref-head:hover { background: var(--code-bg); }
+.ref-title { flex: none; font-weight: 600; font-size: 13px; }
+.ref-line { flex: 1; min-width: 0; color: var(--text-2); font-size: 12.5px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.ref.open .ref-line { display: none; }
+.ref-body { display: flex; flex-direction: column; gap: 6px; padding: 0 12px 12px; }
+.ref-clip video { display: block; width: 100%; max-height: 70vh; border-radius: 10px; background: #f5f5f7; object-fit: contain; }
+.tip-title { font-weight: 650; font-size: 13.5px; letter-spacing: -0.01em; }
+.tip-text { font-size: 12.5px; line-height: 1.45; color: var(--text-2); }
+.tip-text b { color: var(--text); font-weight: 600; }
+.tip-acts { display: flex; gap: 12px; margin-top: 2px; font-size: 12.5px; }
+.tip-acts a { color: var(--accent); text-decoration: none; }
+.tip-new { font-size: 10.5px; font-weight: 600; color: var(--accent); border: 1px solid color-mix(in srgb, var(--accent) 45%, transparent); border-radius: 999px; padding: 0 6px; vertical-align: 1px; }
+.tips-off { display: flex; align-items: center; gap: 6px; }
+.help-update { margin-top: 6px; color: var(--text); }
+.help-about.flash { animation: tip-flash 1.6s ease-out; border-radius: 8px; }
+/* a tip in place, beside its control, its arrow pointing at it (GuideSpec decision 9) */
+#intip {
+  position: fixed; left: 0; top: 0; z-index: 44; width: min(280px, calc(100vw - 16px)); padding: 11px 13px 10px;
+  border-radius: 12px; background: var(--surface-solid); box-shadow: var(--shadow-lg);
+}
+#intip::before {
+  content: ""; position: absolute; left: calc(var(--arrow-x, 50%) - 6px); top: -6px; width: 12px; height: 12px;
+  background: var(--surface-solid); transform: rotate(45deg); border-left: 1px solid var(--line); border-top: 1px solid var(--line);
+}
+#intip.above::before { top: auto; bottom: -6px; border: none; border-right: 1px solid var(--line); border-bottom: 1px solid var(--line); }
+.intip-title { font-weight: 650; font-size: 13.5px; margin-bottom: 4px; }
+.intip-text { font-size: 12.5px; line-height: 1.45; color: var(--text-2); }
+.intip-text b { color: var(--text); font-weight: 600; }
+.intip-acts { display: flex; justify-content: flex-end; gap: 6px; margin-top: 10px; }
+/* the welcome of a first visit (GuideSpec decision 1): beside the side panel, over the legend; it
+   folds into the dot on ? */
+#welcome {
+  position: fixed; left: 300px; bottom: 64px; z-index: 44; width: min(360px, calc(100vw - 24px)); padding: 14px 16px 12px;
+  border-radius: 14px; background: var(--surface-solid); box-shadow: var(--shadow-lg);
+  transform-origin: top right; transition: transform 0.36s cubic-bezier(0.4, 0, 0.2, 1), opacity 0.36s;
+}
+#welcome.folding { opacity: 0; }
+@media (prefers-reduced-motion: reduce) { #welcome { transition: none; } }
+.wel-title { font-weight: 700; font-size: 15px; letter-spacing: -0.01em; margin-bottom: 4px; }
+.wel-text { font-size: 13px; line-height: 1.45; color: var(--text-2); }
+.wel-acts { display: flex; align-items: center; gap: 6px; margin-top: 12px; }
+/* What's new, once: at the bottom, in the middle, quiet (GuideSpec decision 11) */
+#whatsnew {
+  position: fixed; left: 50%; bottom: 56px; transform: translateX(-50%); z-index: 44; display: flex; align-items: center; gap: 4px;
+  padding: 4px 6px 4px 14px; border-radius: 999px; background: var(--surface-solid); box-shadow: var(--shadow);
+}
+.news-open { border: none; background: none; color: var(--accent); font: 600 13px var(--font); cursor: pointer; padding: 4px 0; }
 
 /* the zoom buttons: the bottom right of the canvas, beside the panel when it is open */
 #zoom {
@@ -2434,6 +2621,8 @@ span.tm-row { color: var(--text-2); cursor: default; }
   #more-badge { position: absolute; top: -5px; right: -5px; }
   #more-pop { position: fixed; top: 58px; right: 8px; width: min(260px, calc(100vw - 16px)); z-index: 46; border-radius: 14px; padding: 6px; display: flex; flex-direction: column; background: var(--surface-solid); box-shadow: 0 0 0 0.5px var(--line), var(--shadow-lg); }
   #more-pop[hidden] { display: none; }
+  /* the help menu, from ⋯ → Help: at the top right, as ⋯'s own */
+  #help-menu { position: fixed; top: 58px; right: 8px; z-index: 46; background: var(--surface-solid); }
   .more-item { display: flex; align-items: center; gap: 10px; min-height: 44px; padding: 0 12px; border: 0; border-radius: 10px; background: none; color: var(--text); font: 15px var(--font); text-align: left; }
   .more-item:active { background: var(--code-bg); }
   .more-item svg { flex: none; width: 18px; height: 18px; color: var(--text-2); fill: none; stroke: currentColor; stroke-width: 1.6; stroke-linecap: round; stroke-linejoin: round; }
@@ -2479,6 +2668,12 @@ span.tm-row { color: var(--text-2); cursor: default; }
   #eyes-pop kbd { display: none; }
   .help-touch .help-row { grid-template-columns: 116px minmax(0, 1fr); font-size: 14px; padding: 5px 0; }
   .help-touch .help-g { color: var(--text); font-weight: 600; }
+  .film { grid-template-columns: minmax(0, 1fr); }
+  .refs-head .tips-filter { max-width: none; }
+  #whatsnew { bottom: calc(64px + env(safe-area-inset-bottom)); }
+  /* over the bottom of the screen, where the sheet comes up */
+  #welcome { left: 8px; right: 8px; width: auto; bottom: calc(64px + env(safe-area-inset-bottom)); }
+  .wel-acts { flex-wrap: wrap; }
   #zoom #zoom-in, #zoom #zoom-out { display: none; }
   #foot { left: 8px; bottom: calc(8px + env(safe-area-inset-bottom)); }
   /* under the view bar, the review strip, then the selection bar (--strip-h: main.ts) */

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, or `refs`, what it uses directly; 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
@@ -32,7 +33,8 @@ name (a private reader's; their opinions, targets, key marks and trust keep thei
   `note` its id, `text` then, `shown` whether the view shows it by it), `note` (`what` created,
   edited or deleted; `view`, `title` for a view's own note, "" for a project note; `note` its id;
   `text` after, or before a deletion; `carried` `{mode, from, to}` where a build carried a project
-  note to the cluster its declarations moved to, an edit by VisualProof).
+  note to the cluster its declarations moved to, an edit by VisualProof), `tool` (the VisualProof
+  version serving the site changed: `from`, `to`; `setAside`, a version that failed).
 
 ## History
 
@@ -50,7 +52,7 @@ on a saved graph (`--graph`): 404. MCP: `history` (`snapshots`, `diff`, `moves`,
   "current": 2, "diskBytes": 415893 }
 ```
 
-Oldest first. `at`: when the build finished (newest `.olean`); `approx`: only an extraction made
+Oldest first. `tool`: the VisualProof version that read it. `at`: when the build finished (newest `.olean`); `approx`: only an extraction made
 before the history dates it. `commit`: checked out when read (`dirty`: `.lean` files differed;
 `guessed`: imported, the last commit before it). `missing`: modules not read (unknown at that
 build, not gone). `bytes`: `new` written to keep it, `all` its files. `renames`: found against the

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.4.0",
   "type": "module",
   "description": "See a Lean codebase's declaration graph and the TCB of its theorems.",
   "license": "Apache-2.0",
@@ -20,15 +20,19 @@
     "build": "node scripts/build.mjs",
     "prepack": "npm run build",
     "serve": "node src/server/main.ts serve",
+    "showcase": "node scripts/showcase.mjs",
+    "tips:record": "node scripts/tips-record.mjs",
     "typecheck": "tsc --noEmit -p .",
     "test": "node --test --import ./test/setup.ts \"test/*.test.ts\"",
     "test:toolchains": "node scripts/test-toolchains.mjs",
+    "test:updates": "node scripts/test-updates.mjs",
     "golden:update": "VP_GOLDEN_UPDATE=1 node --test --import ./test/setup.ts test/compat.test.ts"
   },
   "engines": {
     "node": "^22.18.0 || >=24.2.0"
   },
   "dependencies": {
+    "@resvg/resvg-wasm": "2.6.2",
     "d3-hierarchy": "^3.1.2",
     "pdfjs-dist": "6.3.289"
   },