visualproof 0.3.0 → 0.4.1

package/README.md

@@ -9,6 +9,10 @@
 </p>
 <p align="center"><sub>Five Lean codebases, drawn by <code>visualproof artwork</code>.</sub></p>
 
+https://github.com/user-attachments/assets/98e435d6-f493-437d-b342-1833819c0b77
+
+<p align="center"><sub>A review of Sphere-Packing-Lean in 74 seconds. The whole tour — four minutes in thirteen chapters, with captions — is in the page under <b>?</b> → Tips, and <a href="https://visualproof-demo.yingte.io/#tips">on the live demo</a>.</sub></p>
+
 [![VisualProof on flt-regular, from the live demo: the TCB of flt_regular, its key declarations approved, an approval recorded at a meeting, the review plan pinned beside it](docs/images/board.webp)](https://visualproof-demo.yingte.io)
 
 <p align="center"><b>Live demo: <a href="https://visualproof-demo.yingte.io">https://visualproof-demo.yingte.io</a></b><br><sub>flt-regular in the middle of a review by three people and an AI assistant, read-only</sub></p>
@@ -20,6 +24,12 @@ Set up in your Lean codebase with agent prompt:
 Set up VisualProof (https://github.com/LucianoXu/VisualProof) for my Lean project, and give me the address to open.
 ```
 
+Or have your codebase drawn as a poster:
+```text
+Draw my Lean project as a poster with VisualProof (https://github.com/LucianoXu/VisualProof): pick its main theorem, light up what its statement rests on, and give me the PNG and the SVG.
+```
+What the agent does, step by step: [A poster from the command line](docs/MANUAL.md#a-poster-from-the-command-line).
+
 Set up manually:
 ```bash
 npm install --global visualproof
@@ -27,7 +37,9 @@ cd my-lean-project && lake build
 visualproof serve .
 ```
 
-It needs Node, elan and Poppler ([Requirements](#requirements)).
+It needs Node, elan and Poppler ([Requirements](#requirements)). On the first visit the page offers
+a short tour of your own project; `?` holds the tips — a film of a review on Sphere-Packing-Lean in
+thirteen scenes, with captions, and a row for each thing it does not show — and every key.
 
 ## See what a Lean theorem actually rests on
 
@@ -38,16 +50,26 @@ keep a record of the review.
 
 On [flt-regular](https://github.com/leanprover-community/flt-regular), Fermat's Last Theorem for
 regular primes. Of the project's
-273 declarations, two light up besides the theorem, `IsRegularPrime` and `IsRegularNumber`: with
-the Mathlib definitions they use, they are what you need to read to believe what it says.
+273 declarations, two light up besides the theorem, `IsRegularPrime` and `IsRegularNumber`: they
+are what you need to read to believe what it says. The Mathlib definitions they use light up too,
+trusted and assumed as Mathlib is, unless a review chooses to read them: the walk stops at the
+project's edge.
+
+<p align="center">
+  <img src="docs/images/tcb-view-theorem.webp" width="32%" alt="flt_regular alone, lit on the board">
+  <img src="docs/images/tcb-view-tcb.webp" width="32%" alt="the TCB of flt_regular: IsRegularPrime, IsRegularNumber and the Mathlib definitions they use, lit with the edges between them">
+  <img src="docs/images/tcb-view-keys.webp" width="32%" alt="the key declarations of flt_regular, IsRegularPrime and FermatLastTheoremFor, joined by dashed edges">
+</p>
+<p align="center"><sub>The theorem alone · what its statement rests on, its TCB · the few the review marked key, read first.<br>This review no longer trusts <code>Mathlib.NumberTheory</code>, so the definitions it holds that the statement means, <code>FermatLastTheoremFor</code> among them, are read too, and can be key.</sub></p>
 
 ## What it does
 
 - **The declaration graph** of a built Lean project, clustered by namespace or by file, and updated
   live as you rebuild.
-- **The TCB of any theorem**: the definitions its statement rests on, followed through their bodies,
-  instances and notation, and the axioms behind its proof. What lies only inside proofs is left
-  out, since Lean has checked it.
+- **The TCB of any theorem**: the project's definitions its statement rests on, followed through
+  their bodies, instances and notation, and the axioms its statement and proof use. What lies only
+  inside proofs is left out, since Lean has checked it; what lies outside the project, Mathlib's
+  definitions, is lit but trusted and assumed.
 - **A review together**: approve or comment on each declaration, mark targets and their key
   declarations, leave notes, link papers to declarations, and see what changed since an opinion was
   given. Everyone on the page sees it live.
@@ -57,7 +79,8 @@ the Mathlib definitions they use, they are what you need to read to believe what
 - **A printed document** of what a view holds: definitions in full, proofs left out, typeset with
   XeLaTeX.
 - **A picture of the board**, PNG or SVG up to poster size: from the page, from an agent's link, or
-  without a browser (`visualproof artwork <project> --recipe recipe.json`).
+  without a browser (`visualproof artwork <project> --recipe recipe.json`,
+  [step by step](docs/MANUAL.md#a-poster-from-the-command-line)).
 
 ## Requirements
 
@@ -80,8 +103,10 @@ places:
   `~/.local/share/visualproof/sites/<project>-<hash>/` (on macOS, under
   `~/Library/Application Support/visualproof/`). It cannot be derived again and holds secrets, so
   back it up and keep it out of git.
-- **The cache** (`--cache <dir>`) holds what a rebuild makes again. By default it is
-  `~/.cache/visualproof/` (on macOS, `~/Library/Caches/visualproof/`).
+- **The cache** (`--cache <dir>`) holds what a rebuild makes again, and the patch releases a server
+  took (`versions/`, with `updates.json`, the last check: code the server runs, so the cache is the
+  server's user's alone). By default it is `~/.cache/visualproof/` (on macOS,
+  `~/Library/Caches/visualproof/`).
 
 ## Reviewing with others
 
@@ -97,10 +122,26 @@ project with a read-only link (nothing changes, nobody sees the reader), or give
 token and a prompt. To put a project online for anyone, read-only, add `--public`. The server
 speaks plain HTTP: beyond a trusted network, put a TLS proxy in front. [SECURITY.md](SECURITY.md) says what the server trusts and what it exposes.
 
+## Updating
+
+A server keeps itself up to date with patch releases (`--updates auto`, the default): it asks npm
+once a day and takes a newer release of the same minor version, 0.4.1 after 0.4.0, at a quiet
+moment (nobody on a page and nothing running, a day later at the latest); the pages left open
+reload where they were. A newer minor version, which may change the command line or the site
+folder, is only announced — in the server's log, by `visualproof doctor` and in the About of the
+page's `?` — with the command it prints to install it, e.g.
+`npm install --global visualproof@0.5.0`; once it is installed, the server restarts into it by
+itself within ten minutes. `--updates notify` announces patch releases too, and `--updates off`
+never asks npm. 0.3.0 has no updater: upgrade it to 0.4.0 by hand
+([the manual](docs/MANUAL.md#updates)).
+
 ## Documentation
 
-- [The manual](docs/MANUAL.md): every part of the page, the review, views, history, the printed
-  document, collaboration, and how the TCB is computed.
+- **In the page**: the tour, offered on the first visit, and the tips under `?`: a film of a review
+  in thirteen scenes, each with a few words, and a row for the rest. They are the documentation to
+  start with.
+- [The manual](docs/MANUAL.md): how to start, the concepts, then every part of the page, the review,
+  views, history, the printed document, collaboration, and how the TCB is computed.
 - [The agents' API](docs/agent-api/README.md), which the server also serves to agents, topic by topic.
 - [SPEC/](SPEC/): the specification, and the design decisions behind each part.
 - [CONTRIBUTING.md](CONTRIBUTING.md), for working on VisualProof itself.

package/dist/assets/tips/tour.json

@@ -0,0 +1,289 @@
+{
+ "film": {
+  "file": "tour-9d4241345aaf.mp4",
+  "sha256": "9d4241345aaf68755b689fd0ba6b3139a2b077a68996361445b8098398079620",
+  "size": 53706647,
+  "width": 2560,
+  "height": 1600,
+  "duration": 238.96666666666667
+ },
+ "chapters": [
+  {
+   "id": "target",
+   "start": 0,
+   "end": 19.466666666666665
+  },
+  {
+   "id": "view",
+   "start": 19.466666666666665,
+   "end": 31.833333333333332
+  },
+  {
+   "id": "arrange",
+   "start": 31.833333333333332,
+   "end": 53.666666666666664
+  },
+  {
+   "id": "source",
+   "start": 53.666666666666664,
+   "end": 66.06666666666666
+  },
+  {
+   "id": "keys",
+   "start": 66.06666666666666,
+   "end": 92.8
+  },
+  {
+   "id": "checks",
+   "start": 92.8,
+   "end": 111.3
+  },
+  {
+   "id": "review",
+   "start": 111.3,
+   "end": 129.73333333333332
+  },
+  {
+   "id": "project",
+   "start": 129.73333333333332,
+   "end": 138.66666666666666
+  },
+  {
+   "id": "share",
+   "start": 138.66666666666666,
+   "end": 152
+  },
+  {
+   "id": "agent",
+   "start": 152,
+   "end": 171.33333333333334
+  },
+  {
+   "id": "library",
+   "start": 171.33333333333334,
+   "end": 199.73333333333332
+  },
+  {
+   "id": "export",
+   "start": 199.73333333333332,
+   "end": 219.23333333333332
+  },
+  {
+   "id": "artwork",
+   "start": 219.23333333333332,
+   "end": 238.96666666666667
+  }
+ ],
+ "captions": [
+  {
+   "start": 4.1,
+   "end": 7.9,
+   "text": "Search the theorem to review: press /."
+  },
+  {
+   "start": 7.9,
+   "end": 11.9,
+   "text": "There are two MainTheorems: take the one in Dim24."
+  },
+  {
+   "start": 11.9,
+   "end": 15.866666666666667,
+   "text": "Mark it as the target of the review."
+  },
+  {
+   "start": 15.866666666666667,
+   "end": 19.466666666666665,
+   "text": "The side panel lists the targets, with their progress."
+  },
+  {
+   "start": 19.466666666666665,
+   "end": 25.333333333333332,
+   "text": "Rests on · Uses: everything the theorem uses."
+  },
+  {
+   "start": 25.333333333333332,
+   "end": 28.833333333333332,
+   "text": "Zoom in: a view of just that, in a tab of its own."
+  },
+  {
+   "start": 28.833333333333332,
+   "end": 31.833333333333332,
+   "text": "The view is laid out for what it holds alone."
+  },
+  {
+   "start": 34.13333333333333,
+   "end": 39.5,
+   "text": "Drag a cluster with Ctrl held: it stays there, for everyone."
+  },
+  {
+   "start": 39.5,
+   "end": 46.53333333333333,
+   "text": "Or let the lock go with l, and drag without Ctrl."
+  },
+  {
+   "start": 46.53333333333333,
+   "end": 53.666666666666664,
+   "text": "Double-click a circle to fold it to a point; again to open."
+  },
+  {
+   "start": 53.666666666666664,
+   "end": 58.7,
+   "text": "Space opens the source of what is selected."
+  },
+  {
+   "start": 58.7,
+   "end": 62.5,
+   "text": "Rest on a name: Lean says what it is."
+  },
+  {
+   "start": 62.5,
+   "end": 66.06666666666666,
+   "text": "Click it to go there: its source, its panel."
+  },
+  {
+   "start": 66.06666666666666,
+   "end": 69.13333333333334,
+   "text": "Keys: the definitions that carry what it says."
+  },
+  {
+   "start": 69.13333333333334,
+   "end": 84.53333333333333,
+   "text": "Mark each as a key with the mouse, in its panel."
+  },
+  {
+   "start": 84.53333333333333,
+   "end": 92.8,
+   "text": "Rests on · Keys lights them, joined to the target."
+  },
+  {
+   "start": 93.4,
+   "end": 96.1,
+   "text": "Selection: the statement alone."
+  },
+  {
+   "start": 96.1,
+   "end": 98.9,
+   "text": "Least effort — you trust every name in it."
+  },
+  {
+   "start": 98.9,
+   "end": 101.36666666666666,
+   "text": "Keys: the few that carry the meaning."
+  },
+  {
+   "start": 101.36666666666666,
+   "end": 103.43333333333334,
+   "text": "Little effort, good confidence."
+  },
+  {
+   "start": 103.43333333333334,
+   "end": 105.63333333333334,
+   "text": "TCB: everything it rests on."
+  },
+  {
+   "start": 105.63333333333334,
+   "end": 107.63333333333334,
+   "text": "Most effort, most confidence."
+  },
+  {
+   "start": 107.63333333333334,
+   "end": 111.3,
+   "text": "Choose how far to read: the counts say what each costs."
+  },
+  {
+   "start": 111.3,
+   "end": 116.6,
+   "text": "Read a definition, then say what you think of it."
+  },
+  {
+   "start": 116.6,
+   "end": 125.96666666666667,
+   "text": "Approve it, with why: the comment stays with it."
+  },
+  {
+   "start": 125.96666666666667,
+   "end": 129.73333333333332,
+   "text": "The target's progress counts your approval."
+  },
+  {
+   "start": 129.73333333333332,
+   "end": 135.03333333333333,
+   "text": "The Project tab: the whole codebase."
+  },
+  {
+   "start": 135.03333333333333,
+   "end": 138.66666666666666,
+   "text": "Every board shows the same review."
+  },
+  {
+   "start": 138.66666666666666,
+   "end": 145.56666666666666,
+   "text": "Share → AI agent: a token, and a prompt for it."
+  },
+  {
+   "start": 145.56666666666666,
+   "end": 148.76666666666668,
+   "text": "Paste the prompt into your agent: it joins here."
+  },
+  {
+   "start": 148.76666666666668,
+   "end": 152,
+   "text": "The token is the agent's own: revoke it here."
+  },
+  {
+   "start": 152.7,
+   "end": 160.13333333333333,
+   "text": "Click the agent to follow it, and ask."
+  },
+  {
+   "start": 160.13333333333333,
+   "end": 165.83333333333334,
+   "text": "It reads the code, and takes your view along."
+  },
+  {
+   "start": 165.83333333333334,
+   "end": 171.33333333333334,
+   "text": "Its answer names what it explains."
+  },
+  {
+   "start": 172.13333333333333,
+   "end": 178.23333333333332,
+   "text": "Library: add a paper about the code."
+  },
+  {
+   "start": 178.23333333333332,
+   "end": 191.53333333333333,
+   "text": "Link it to the theorem, at its page."
+  },
+  {
+   "start": 191.53333333333333,
+   "end": 199.73333333333332,
+   "text": "Pin a note on the target: where to start."
+  },
+  {
+   "start": 199.73333333333332,
+   "end": 207.66666666666666,
+   "text": "Export prints a view: here, the target's TCB."
+  },
+  {
+   "start": 207.66666666666666,
+   "end": 212.26666666666668,
+   "text": "Drag a section to change the document's order."
+  },
+  {
+   "start": 212.26666666666668,
+   "end": 219.23333333333332,
+   "text": "Typeset: the PDF follows the order you set."
+  },
+  {
+   "start": 219.23333333333332,
+   "end": 224,
+   "text": "Artwork: the board as a picture to keep."
+  },
+  {
+   "start": 224,
+   "end": 235.36666666666667,
+   "text": "Frame it, then save it as PNG or SVG."
+  }
+ ]
+}

package/dist/mcp/visualproof-mcp.mjs

@@ -41,7 +41,9 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { basename, isAbsolute } from "node:path";
 import { createInterface } from "node:readline";
 
-const VERSION = "0.5.0";
+// the version of the VisualProof server it came from: the server writes its own here as it serves
+// the file (GET /api/agent/mcp)
+const VERSION = "0.0.0";
 /** the MCP revisions this server speaks, newest first; a client asking for another (a newer one,
  *  2026-07-28 among them, whose changes it does not make) is answered with the newest of these */
 const REVISIONS = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];

package/dist/server/agent.js

@@ -29,6 +29,9 @@
 import { historyEndpoints, historyWorld } from "./historyapi.js";
 import { PastBuilds } from "./pastdoc.js";
 import { spawnSync } from "node:child_process";
+import { packageVersion } from "./version.js";
+import { withoutReasons } from "../shared/timeline.js";
+import { childEnv } from "./children.js";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { gunzipSync } from "node:zlib";
@@ -817,7 +820,7 @@ export class AgentApi {
         const advise = !this.refuse(me, "advise");
         const byKey = new Map(this.endpoints.map((e) => [`${e.method} ${e.path}`, e]));
         return ok({
-            about: "VisualProof shows a Lean project's declarations, the TCB of its theorems (what a theorem's statement rests on) and the review people make of it. This is its API for AI agents.",
+            about: `VisualProof ${packageVersion()} shows a Lean project's declarations, the TCB of its theorems (what a theorem's statement rests on) and the review people make of it. This is its API for AI agents.`,
             you: {
                 name: me.name,
                 kind: me.kind,
@@ -1160,7 +1163,9 @@ export class AgentApi {
         if (typeof t !== "string")
             return t;
         try {
-            return { status: 200, body: null, text: { type: "text/javascript; charset=utf-8", body: readFileSync(MCP_FILE, "utf8") } };
+            // the file carries the version of the server it came from (UpdateSpec decision 11)
+            const body = readFileSync(MCP_FILE, "utf8").replace(/^const VERSION = "[^"\n]*";$/m, `const VERSION = ${JSON.stringify(packageVersion())};`);
+            return { status: 200, body: null, text: { type: "text/javascript; charset=utf-8", body } };
         }
         catch {
             return fail(404, "The MCP server is not beside this server.", "Use the HTTP API (GET /api/agent).");
@@ -2021,7 +2026,7 @@ export class AgentApi {
                 out.push({ ...rest, ...who, moved: ops.flatMap((o) => (o.op === "clear" ? [] : [o.key])).slice(0, 100), undoneBy: undone.get(e.id) ?? null });
             }
             else
-                out.push({ ...e, ...who });
+                out.push({ ...withoutReasons(e), ...who });
         }
         const about = (a.query.get("name") ?? "").trim();
         // a note is about the declarations it names; a link, about the declaration it is on, or was on
@@ -2895,7 +2900,7 @@ export class AgentApi {
             {
                 method: "GET", path: "/api/agent/activity", brief: "the timeline", about: "The timeline, oldest first: opinions and advice, targets and key marks, files of the library added, retitled, archived or restored and links made, edited or removed (all from the review's logs), builds, TCB changes, targets taken off, prefixes trusted or no longer, views saved, renamed, rescoped, deleted or laid out afresh, notes added to a view or taken out of it, notes, layouts and their undoing.",
                 params: { since: "an ISO time (e.g. the `now` of your last answer) or an event id: what came after", name: "optional: only what is about this declaration (opinions, advice, notes that name it, key marks, links on it; a target's own events)", limit: "default 100, at most 1000 (the newest)" },
-                returns: "{now, events: [{at, kind, by?, agent?, …}] oldest first, more}; kinds: opinion, target, key (a key declaration as marked now: target, name), build, tcb, untarget, trust, untrust, view (a view saved, renamed, rescoped, deleted or laid out afresh: what, view, name, was?, scope; or a note of the project added to it or taken out of it: what items, note, text, shown), note (a note on a view written, edited or deleted: what, view, title, note, text), file (a file of the library: what is added, edited — its title, wasTitle the one before —, archived or restored; sha, title), link (what is made, edited or removed; id, subject, label, file, and an edit's changed (subject, label, place), wasSubject?, wasLabel?, auto? where VisualProof carried it with a renamed cluster), layout (with moved and undoneBy), undo; relayout only in a timeline kept from before views",
+                returns: "{now, events: [{at, kind, by?, agent?, …}] oldest first, more}; kinds: opinion, target, key (a key declaration as marked now: target, name), build, tcb, untarget, trust, untrust, view (a view saved, renamed, rescoped, deleted or laid out afresh: what, view, name, was?, scope; or a note of the project added to it or taken out of it: what items, note, text, shown), note (a note on a view written, edited or deleted: what, view, title, note, text), file (a file of the library: what is added, edited — its title, wasTitle the one before —, archived or restored; sha, title), link (what is made, edited or removed; id, subject, label, file, and an edit's changed (subject, label, place), wasSubject?, wasLabel?, auto? where VisualProof carried it with a renamed cluster), layout (with moved and undoneBy), undo, tool (the VisualProof version serving the site changed: from, to, setAside?); relayout only in a timeline kept from before views",
                 run: (a) => this.activity(a),
             },
             {
@@ -3256,7 +3261,7 @@ export function commitOf(root) {
     if (was && now - was.at < 10_000)
         return was.commit;
     const git = (...args) => {
-        const r = spawnSync("git", ["-C", root, ...args], { encoding: "utf8", timeout: 5000, env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" }, stdio: ["ignore", "pipe", "ignore"] });
+        const r = spawnSync("git", ["-C", root, ...args], { encoding: "utf8", timeout: 5000, env: childEnv({ GIT_OPTIONAL_LOCKS: "0" }), stdio: ["ignore", "pipe", "ignore"] });
         return r.status === 0 ? r.stdout.trim() : null;
     };
     const hash = git("rev-parse", "HEAD");

package/dist/server/children.js

@@ -0,0 +1,85 @@
+// The programs the server runs and waits for — the extractor and the Lean programs' build, the
+// usage pass's `lake env`, Lean's language server, XeLaTeX, ImageMagick, Poppler, git, ps — kept
+// here while they run, so that a server stopping stops them (UpdateSpec decision 9) rather than
+// leave them working for nobody. Those that start programs of their own (Lake starts Lean, Lean's
+// server its workers, XeLaTeX kpathsea's, ImageMagick its delegates) run in a process group of
+// their own (`grouped`, spawn's `detached`), and are stopped with all they started; what is left
+// at the server's exit is ended at once. The usage pass's workers have a stop of their own
+// (server/usage.ts).
+const running = new Set();
+/** the children that lead a process group of their own */
+const groups = new WeakSet();
+/** spawn's `detached` for a program run as a group (`grouped`): its own process group, where the
+ *  platform has them */
+export const DETACH = process.platform !== "win32";
+/** Keep `child` as `tracked` does, as the leader of a process group of its own: spawned with
+ *  `detached: DETACH`, and stopped with every program it started. */
+export function grouped(child) {
+    if (DETACH)
+        groups.add(child);
+    return tracked(child);
+}
+/** End `child` with `signal`: where it leads a process group, the whole group. */
+export function end(child, signal = "SIGTERM") {
+    if (groups.has(child) && child.pid && child.exitCode === null) {
+        try {
+            process.kill(-child.pid, signal);
+            return;
+        }
+        catch {
+            // the group is gone: the child alone, if it is not
+        }
+    }
+    child.kill(signal);
+}
+// what still runs as the server's process ends goes with it
+process.once("exit", () => {
+    for (const c of running)
+        end(c, "SIGKILL");
+});
+/** Keep `child` until it exits; the same child, for `spawn(…)` to be wrapped in place. */
+export function tracked(child) {
+    running.add(child);
+    const gone = () => running.delete(child);
+    child.once("exit", gone);
+    child.once("error", gone);
+    return child;
+}
+/** The environment a program the server runs is given: the server's own, without what is the
+ *  server's alone (`VISUALPROOF_*`: the supervisor's word to it, its test hooks; UpdateSpec decision
+ *  9), with `extra` over it. */
+export function childEnv(extra = {}) {
+    const env = {};
+    for (const [k, v] of Object.entries(process.env))
+        if (!k.startsWith("VISUALPROOF_"))
+            env[k] = v;
+    return { ...env, ...extra };
+}
+/** How many tracked programs run now. */
+export function childCount() {
+    return running.size;
+}
+/** Ask every tracked program to end (SIGTERM), and end those still there after `graceMs`
+ *  (SIGKILL). Resolves once none runs, or at the end of the grace; the process waits for it. */
+export function stopChildren(graceMs = 2000) {
+    if (!running.size)
+        return Promise.resolve();
+    for (const c of running)
+        end(c, "SIGTERM");
+    return new Promise((resolve) => {
+        const t0 = Date.now();
+        const tick = setInterval(() => {
+            if (!running.size) {
+                clearInterval(tick);
+                return resolve();
+            }
+            if (Date.now() - t0 >= graceMs) {
+                for (const c of running)
+                    end(c, "SIGKILL");
+                running.clear();
+                clearInterval(tick);
+                resolve();
+            }
+        }, 50);
+    });
+}