visualproof 0.2.0 → 0.4.0

package/README.md

@@ -1,21 +1,75 @@
 # VisualProof
 
-**See what a Lean theorem actually rests on.**
+<p align="center">
+  <a href="https://github.com/math-inc/Sphere-Packing-Lean"><img src="docs/images/artwork-sphere-packing.webp" width="19%" alt="Sphere Packing"></a>
+  <a href="https://github.com/leanprover-community/flt-regular"><img src="docs/images/artwork-flt-regular.webp" width="19%" alt="FLT Regular"></a>
+  <a href="https://github.com/AlexKontorovich/PrimeNumberTheoremAnd"><img src="docs/images/artwork-prime-numbers.webp" width="19%" alt="Prime Numbers"></a>
+  <a href="https://github.com/openai/NavierStokesAndEuler"><img src="docs/images/artwork-navier-stokes.webp" width="19%" alt="Navier–Stokes"></a>
+  <a href="https://github.com/cedar-policy/cedar-spec"><img src="docs/images/artwork-cedar.webp" width="19%" alt="Cedar"></a>
+</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>
+
+## Try it
+
+Set up in your Lean codebase with agent prompt:
+```text
+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
+cd my-lean-project && lake build
+visualproof serve .
+```
+
+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
 
 Lean checks that a proof is correct. It cannot check that the theorem says what you mean: that the
 definitions in its statement mean what their names suggest. VisualProof shows exactly which
 definitions those are, so that people, and AI agents, can read them, review them together, and
 keep a record of the review.
 
-<!-- A screenshot or a short video of the board goes here. -->
+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`: 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.
@@ -24,6 +78,9 @@ keep a record of the review.
 - **History**: every build is kept, and a past board can be browsed.
 - **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`,
+  [step by step](docs/MANUAL.md#a-poster-from-the-command-line)).
 
 ## Requirements
 
@@ -36,28 +93,6 @@ keep a record of the review.
 The project must have been built with `lake build`: VisualProof only reads what the build left,
 and never builds it.
 
-## Try it
-
-VisualProof is not on npm yet: install its `visualproof` command from a checkout, which packs it
-as npm would. Here it is on [flt-regular](https://github.com/leanprover-community/flt-regular),
-Fermat's Last Theorem for regular primes, built on Mathlib:
-
-```bash
-git clone https://github.com/LucianoXu/VisualProof
-(cd VisualProof && npm install && npm pack && npm install --global ./visualproof-*.tgz)
-
-git clone https://github.com/leanprover-community/flt-regular
-(cd flt-regular && git checkout bd81b78ba6 && lake exe cache get && lake build)
-
-visualproof doctor flt-regular     # what is missing, if anything, and what to do
-visualproof serve flt-regular
-```
-
-Open http://127.0.0.1:4173/. Choose the *Rests on* tool (`2`), find `flt_regular` with the search
-(`/`), and click it on the board. Of the project's 297 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 the theorem says.
-
 ## Where it keeps things
 
 It writes nothing into the project, and nothing into its own checkout. It keeps everything in two
@@ -68,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
 
@@ -85,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.
@@ -96,5 +149,7 @@ speaks plain HTTP: beyond a trusted network, put a TLS proxy in front. [SECURITY
 ## License and citation
 
 VisualProof is licensed under Apache-2.0 ([LICENSE](LICENSE)). The fonts in `src/assets/fonts/`
-are JuliaMono, under the SIL Open Font License. If you use VisualProof in your work, please cite
-it ([CITATION.cff](CITATION.cff)).
+are JuliaMono; those in `src/assets/webfonts/`, which artworks are drawn in, are Source Sans 3,
+Source Serif 4, Jost, Noto Sans and Noto Sans Math. All are under the SIL Open Font License, whose
+text is beside them. If you use VisualProof in your work, please cite it
+([CITATION.cff](CITATION.cff)).

package/dist/assets/tips/tour.json

@@ -0,0 +1,289 @@
+{
+ "film": {
+  "file": "tour-d98aa9f30925.mp4",
+  "sha256": "d98aa9f309254c0591ebd3bde6107750f4e1881c3fdd12d3824631daec0ce940",
+  "size": 53705683,
+  "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/assets/webfonts/LICENSE-Noto.txt

@@ -0,0 +1,95 @@
+Noto Sans: Copyright 2015 Google LLC. All Rights Reserved.
+Noto Sans Math: Copyright 2018 Google LLC. All Rights Reserved.
+(The files ttf/noto-sans.ttf and ttf/noto-sans-math.ttf hold a subset of each.)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.