visualproof 0.6.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. package/README.md +2 -2
  2. package/dist/assets/tips/phone-fingers.light.mp4 +0 -0
  3. package/dist/assets/tips/phone-fingers.light.webp +0 -0
  4. package/dist/assets/tips/tour-agent.webp +0 -0
  5. package/dist/assets/tips/tour-arrange.webp +0 -0
  6. package/dist/assets/tips/tour-artwork.webp +0 -0
  7. package/dist/assets/tips/tour-checks.webp +0 -0
  8. package/dist/assets/tips/tour-export.webp +0 -0
  9. package/dist/assets/tips/tour-keys.webp +0 -0
  10. package/dist/assets/tips/tour-library.webp +0 -0
  11. package/dist/assets/tips/tour-project.webp +0 -0
  12. package/dist/assets/tips/tour-review.webp +0 -0
  13. package/dist/assets/tips/tour-share.webp +0 -0
  14. package/dist/assets/tips/tour-source.webp +0 -0
  15. package/dist/assets/tips/tour-target.webp +0 -0
  16. package/dist/assets/tips/tour-view.webp +0 -0
  17. package/dist/assets/tips/tour.json +90 -90
  18. package/dist/assets/tips/tour.webp +0 -0
  19. package/dist/extractor/Extract.lean +13 -3
  20. package/dist/server/agent.js +104 -2881
  21. package/dist/server/agentactivity.js +72 -0
  22. package/dist/server/agentadvice.js +128 -0
  23. package/dist/server/agentdocs.js +1 -1
  24. package/dist/server/agententry.js +180 -0
  25. package/dist/server/agentexport.js +469 -0
  26. package/dist/server/agentfollow.js +412 -0
  27. package/dist/server/agentgraph.js +128 -0
  28. package/dist/server/agentlean.js +144 -0
  29. package/dist/server/agentlibrary.js +1 -1
  30. package/dist/server/agentplaces.js +242 -0
  31. package/dist/server/agentread.js +569 -0
  32. package/dist/server/agenttalk.js +282 -0
  33. package/dist/server/agenttcb.js +378 -0
  34. package/dist/server/agentviews.js +3 -3
  35. package/dist/server/app.js +379 -0
  36. package/dist/server/appaccess.js +127 -0
  37. package/dist/server/appagent.js +110 -0
  38. package/dist/server/appgraph.js +176 -0
  39. package/dist/server/appshare.js +179 -0
  40. package/dist/server/appsite.js +120 -0
  41. package/dist/server/apptalk.js +195 -0
  42. package/dist/server/artcmd.js +1 -1
  43. package/dist/server/events.js +1 -1
  44. package/dist/server/history.js +51 -3
  45. package/dist/server/historyapi.js +34 -2
  46. package/dist/server/hover.js +11 -7
  47. package/dist/server/identity.js +1 -1
  48. package/dist/server/libraryroute.js +3 -3
  49. package/dist/server/live.js +162 -12
  50. package/dist/server/main.js +17 -1746
  51. package/dist/server/mcptools.js +1 -1
  52. package/dist/server/options.js +350 -0
  53. package/dist/server/outside.js +311 -0
  54. package/dist/server/pastdoc.js +22 -3
  55. package/dist/server/presence.js +25 -8
  56. package/dist/server/project.js +28 -4
  57. package/dist/server/readonlygate.js +4 -0
  58. package/dist/server/reviewapi.js +10 -3
  59. package/dist/server/send.js +259 -0
  60. package/dist/server/talk.js +13 -7
  61. package/dist/server/tokens.js +3 -3
  62. package/dist/server/view.js +3 -1
  63. package/dist/server/views.js +1 -1
  64. package/dist/shared/artrecipe.js +3 -3
  65. package/dist/shared/board.js +9 -8
  66. package/dist/shared/collab.js +54 -7
  67. package/dist/shared/comment.js +1 -1
  68. package/dist/shared/doc/build.js +30 -14
  69. package/dist/shared/doc/latex.js +7 -2
  70. package/dist/shared/doc/model.js +4 -2
  71. package/dist/shared/doc/sections.js +21 -4
  72. package/dist/shared/outside.js +16 -0
  73. package/dist/shared/pastgraph.js +11 -2
  74. package/dist/shared/pointer.js +152 -0
  75. package/dist/shared/query.js +36 -5
  76. package/dist/shared/review.js +34 -2
  77. package/dist/shared/scope.js +1 -1
  78. package/dist/shared/sharesnap.js +15 -0
  79. package/dist/shared/titles.js +4 -0
  80. package/dist/web/bundle/app.js +51061 -49518
  81. package/dist/web/index.html +4 -0
  82. package/dist/web/src/canvas.js +16 -14
  83. package/dist/web/src/highlight.js +8 -3
  84. package/dist/web/src/reviewqueue.js +52 -10
  85. package/dist/web/src/selection.js +1 -1
  86. package/dist/web/src/status.js +65 -1
  87. package/dist/web/src/theme.js +1 -1
  88. package/dist/web/src/visitors.js +1 -1
  89. package/dist/web/style.css +121 -7
  90. package/docs/agent-api/advice.md +4 -1
  91. package/docs/agent-api/export.md +8 -5
  92. package/docs/agent-api/following.md +9 -3
  93. package/docs/agent-api/history.md +3 -1
  94. package/docs/agent-api/reading.md +8 -2
  95. package/docs/agent-api/views.md +3 -1
  96. package/package.json +1 -1
@@ -16,7 +16,10 @@
16
16
  // read but what the view's scope reads to say what it holds, and the trusted prefixes: no status,
17
17
  // no opinion is printed. Its title is the view's, as the view is named, and its author line the
18
18
  // people who left a trace on the view (ExportSpec decisions 14 and 15), whom the server finds
19
- // (shared/doc/authors.ts) and the view brings; no setting gives either.
19
+ // (shared/doc/authors.ts) and the view brings; no setting gives either. A declaration from outside
20
+ // the project is printed where it is key for a target (ExportSpec decision 8, the owner's decision of
21
+ // 2026-10-20), as the project's are, from its package's source (or Lean's core's), its proofs found
22
+ // by reading it; the rest of the outside world is counted on the head card.
20
23
  //
21
24
  // A view of a past build makes that build's document (ExportSpec decision 16): its graph is the past
22
25
  // graph its board is of (shared/pastgraph.ts), that build's declarations alone; each declaration's
@@ -35,7 +38,7 @@ import { addedNames, clusterSubject, declSubject, fileOf, linksOf } from "../lib
35
38
  import { DOC_VERSION } from "./model.js";
36
39
  import { freshSpots, orderDoc } from "./order.js";
37
40
  import { cutByText, cutProofs, statementOnly } from "./proof.js";
38
- import { planDoc, tooMuch } from "./sections.js";
41
+ import { outsideKeys, planDoc, tooMuch } from "./sections.js";
39
42
  /** A view the builder cannot make a document of: it holds nothing of the project, or more than a
40
43
  * document holds. The server answers it 400, with its message. */
41
44
  export class DocInputError extends Error {
@@ -55,7 +58,8 @@ export function buildDoc(input) {
55
58
  const { g, review: d, settings: s, view } = input;
56
59
  const past = input.past ?? null;
57
60
  const set = evaluate(view.scope, { g, review: d });
58
- const plan = planDoc(g, set, view.clustering, view.hidden);
61
+ // what it holds from outside the project that is key is printed too (decision 8)
62
+ const plan = planDoc(g, set, view.clustering, view.hidden, outsideKeys(g, d));
59
63
  const why = tooMuch(plan.count);
60
64
  if (why)
61
65
  throw new DocInputError(why);
@@ -137,7 +141,9 @@ export function buildDoc(input) {
137
141
  // the docstring shown as prose is not repeated in the code
138
142
  const code = codeFor(i, doc !== null);
139
143
  const papers = papersOf(declSubject(v.name));
140
- return { id: v.name, name: v.name, short: g.short(i), kind: v.kind, module: v.module, file: input.fileOf(v.module), line: v.range ? v.range[0] : null, doc, code, ...(papers ? { papers } : {}) };
144
+ const out = g.isExt(i) ? input.outside?.(v.module) ?? null : null;
145
+ const file = g.isExt(i) ? out?.file ?? null : input.fileOf(v.module);
146
+ return { id: v.name, name: v.name, short: g.short(i), kind: v.kind, module: v.module, file, ...(g.isExt(i) ? { external: true, ...(out ? { package: out.package } : {}) } : {}), line: v.range && (out || !g.isExt(i)) ? v.range[0] : null, doc, code, ...(papers ? { papers } : {}) };
141
147
  };
142
148
  /** A declaration's code: its source where it can be read (a theorem's up to its statement, a
143
149
  * definition's whole with the proofs in it cut), else the statement the graph holds. `dropDoc`:
@@ -160,10 +166,13 @@ export function buildDoc(input) {
160
166
  elide(c);
161
167
  return c;
162
168
  };
163
- const src = g.isExt(i) || !v.range ? null : sourceOf(v.module);
169
+ // outside the project, its package's source where it is found (decision 8)
170
+ const ext = g.isExt(i);
171
+ const src = !v.range || (ext && !input.outside?.(v.module)) ? null : sourceOf(v.module);
164
172
  const at = src ? excerptOf(src.lines, src.edited, v.name, v.range) : null;
165
- // a past build's text that is not kept (HistorySpec decision 21): its statement then, said so
166
- if (!src && past && !g.isExt(i) && v.range)
173
+ // a past build's text that is not kept (HistorySpec decisions 21 and 24): its statement then,
174
+ // said so
175
+ if (!src && past && v.range)
167
176
  return { ...fromGraph(), notKept: true };
168
177
  if (!src || !at)
169
178
  return fromGraph();
@@ -189,10 +198,10 @@ export function buildDoc(input) {
189
198
  const cut = v.proofs?.length ? cutProofs(src.lines, start, at.end, v.proofs) : null;
190
199
  return cut?.cuts ? { lines: cut.lines, proofElided: false, from: "source", proofsCut: cut.cuts } : codeOf(text, from);
191
200
  }
192
- // the pass's places are not this text's (a past build's never are): the proofs as reading the
193
- // text finds them
201
+ // the pass's places are not this text's (a past build's never are, nor the outside world's): the
202
+ // proofs as reading the text finds them
194
203
  const cut = cutByText(text);
195
- return placed({ lines: cut.lines, proofElided: false, from, ...(cut.cuts ? { proofsCut: cut.cuts } : {}), textCut: past ? "past" : src.edited ? "edited" : "unread" });
204
+ return placed({ lines: cut.lines, proofElided: false, from, ...(cut.cuts ? { proofsCut: cut.cuts } : {}), textCut: ext ? "outside" : past ? "past" : src.edited ? "edited" : "unread" });
196
205
  };
197
206
  // a declaration, then the notes attached to it, as its explanation
198
207
  const declItem = (i) => {
@@ -312,9 +321,9 @@ export function docNotes(doc) {
312
321
  };
313
322
  const count = (n, one, many) => `${n} ${n === 1 ? one : many}`;
314
323
  const out = [];
315
- const why = { edited: "their file changed since it was compiled", unread: "the usage pass has not read them (it is off, still running, or failed on their module)" };
324
+ const why = { edited: "their file changed since it was compiled", unread: "the usage pass has not read them (it is off, still running, or failed on their module)", outside: "they are outside the project, which the usage pass reads alone" };
316
325
  const reading = "Reading the text leaves out every `by` block, one that builds data too, and keeps a proof written as a term.";
317
- for (const k of ["edited", "unread"]) {
326
+ for (const k of ["edited", "unread", "outside"]) {
318
327
  const es = all.filter((e) => e.code.textCut === k);
319
328
  if (es.length)
320
329
  out.push(`The proofs inside ${count(es.length, "definition", "definitions")} were found by reading the text rather than where the usage pass found them, since ${why[k]}: ${names(es)}. ${reading}`);
@@ -330,8 +339,15 @@ export function docNotes(doc) {
330
339
  if (gone.length)
331
340
  out.push(`The text of ${count(gone.length, "declaration", "declarations")} at this build is not kept, and ${gone.length === 1 ? "its statement is" : "their statements are"} printed instead: ${names(gone)}.`);
332
341
  const bare = all.filter((e) => e.code.from === "statement" && !e.code.notKept);
333
- if (bare.length)
334
- out.push(`${count(bare.length, "declaration of the project is", "declarations of the project are")} printed from the graph's statement rather than from the source: ${names(bare)}.`);
342
+ const own = bare.filter((e) => !e.external);
343
+ const away = bare.filter((e) => e.external);
344
+ if (own.length)
345
+ out.push(`${count(own.length, "declaration of the project is", "declarations of the project are")} printed from the graph's statement rather than from the source: ${names(own)}.`);
346
+ if (away.length)
347
+ out.push(`${count(away.length, "key declaration from outside the project is", "key declarations from outside the project are")} printed by name alone, their source not found: ${names(away)}.`);
348
+ const changed = all.filter((e) => e.package && e.code.from === "edited");
349
+ if (changed.length)
350
+ out.push(`${count(changed.length, "key declaration from outside the project is", "key declarations from outside the project are")} printed from ${changed.length === 1 ? "its package" : "their packages"} as ${changed.length === 1 ? "it is" : "they are"} now, at another revision than the graph was read at, found by name: ${names(changed)}.`);
335
351
  return out;
336
352
  }
337
353
  /** A theorem's proof left out: `:= …` after the statement's last line. */
@@ -204,6 +204,9 @@ function blocks(bs) {
204
204
  /** What is said under the code of a declaration of a past build whose text of then is not kept
205
205
  * (ExportSpec decision 16): its statement as the build recorded it is printed instead. */
206
206
  export const NOT_KEPT_NOTE = "Its source text at this build is not kept: printed is its statement, as the build recorded it.";
207
+ /** The same of a declaration outside the project (HistorySpec decision 24): outside sources are not
208
+ * kept per build, and its package is at another revision now; the build kept no statement of it. */
209
+ export const OUTSIDE_NOT_KEPT_NOTE = "Its source at this build was not kept: outside sources are not kept per build, and its package is at another revision now.";
207
210
  /** A declaration: its head, its full name and place, what it is, its code. `level`: its PDF
208
211
  * bookmark's, one below its section's. */
209
212
  function decl(d, level, refs = new Map()) {
@@ -212,12 +215,14 @@ function decl(d, level, refs = new Map()) {
212
215
  out.push(`\\vpBookmark{${id}}{${int(level)}}{${escapeLatex(bookmarkText(d.short))}}`);
213
216
  out.push(`\\begin{vpDecl}{${id}}{${escapeLatex(d.short)}}{${escapeLatex(d.kind)}}`);
214
217
  out.push(`\\vpFullName{${escapeName(d.name)}}`);
215
- out.push(`\\vpPlace{${escapeName(d.module)}}{${d.file ? escapePath(d.file) : ""}}{${d.line ? int(d.line) : ""}}`);
218
+ // outside the project, its file in its package, the package named (ExportSpec decision 8)
219
+ const file = d.file ? `${d.file}${d.package ? ` (${d.package})` : ""}` : "";
220
+ out.push(`\\vpPlace{${escapeName(d.module)}}{${file ? escapePath(file) : ""}}{${d.line ? int(d.line) : ""}}`);
216
221
  if (d.doc)
217
222
  out.push(`\\begin{vpDocstring}`, blocks(d.doc), `\\end{vpDocstring}`);
218
223
  out.push(code(d.code));
219
224
  if (d.code.notKept)
220
- out.push(`\\vpDeclNote{${escapeLatex(NOT_KEPT_NOTE)}}`);
225
+ out.push(`\\vpDeclNote{${escapeLatex(d.external ? OUTSIDE_NOT_KEPT_NOTE : NOT_KEPT_NOTE)}}`);
221
226
  if (d.papers)
222
227
  out.push(papers(d.papers, refs));
223
228
  // the notes attached to it, as its explanation
@@ -33,5 +33,7 @@
33
33
  * (2026-10-12): the board's order, a section's declarations, notes and sections in one list
34
34
  * (`items`), the document's first ones too; the notes the view shows (`NoteEntry`), a declaration's
35
35
  * own under it (`DeclEntry.notes`), their images and clips as figures; a declaration a note names
36
- * linked where the document prints it (an inline `decl`). */
37
- export const DOC_VERSION = 10;
36
+ * linked where the document prints it (an inline `decl`). 11 (2026-10-20): a declaration from outside
37
+ * the project that is key for a target printed as the project's are, from its package's source
38
+ * (`DeclEntry.package`; `textCut: "outside"`), the rest of the outside world counted as before. */
39
+ export const DOC_VERSION = 11;
@@ -1,6 +1,8 @@
1
1
  // The exported document's plan (ExportSpec decisions 12 and 13): what a view holds, as the document
2
2
  // prints it. Every declaration of the project the board holds is printed, whatever is folded; what
3
- // the view holds from outside the project is not, and is counted instead. The sections are the
3
+ // the view holds from outside the project is not, and is counted instead — but where it is key for a
4
+ // target (ExportSpec decision 8, the owner's decision of 2026-10-20: key declarations may be outside
5
+ // since 0.6.0), which is printed as the project's are, from its package's source. The sections are the
4
6
  // view's cluster structure as the board shows it — its clustering, its hidden levels taken out
5
7
  // (ViewSpec decision 24; shared/layout.ts, clusterTree) — each cluster that holds something printed
6
8
  // a section, nested by its depth.
@@ -11,6 +13,7 @@
11
13
  // in that order, and the Export window (web/src/exportmodal.ts) says from it what the document will
12
14
  // hold, so that the two agree.
13
15
  import { clusterTree } from "../layout.js";
16
+ import { evaluate } from "../query.js";
14
17
  /** Heading levels: section, subsection, subsubsection, then a paragraph-level heading, which every
15
18
  * deeper level takes too. */
16
19
  export const HEADING_LEVELS = 4;
@@ -25,13 +28,23 @@ export function tooMuch(count) {
25
28
  return `This view holds ${count.toLocaleString("en")} declarations of the project; a document prints at most ${MAX_DOC_DECLS.toLocaleString("en")}. Export a narrower view: a namespace or a folder, a target's Key view (key(T)) or the TCB of a target`;
26
29
  return null;
27
30
  }
31
+ /** The declarations outside the project a document prints (ExportSpec decision 8, the owner's
32
+ * decision of 2026-10-20): those key for a target, each target's marks that its TCB or review set
33
+ * still holds (`key(targets)`, shared/query.ts), per node of `g`. */
34
+ export function outsideKeys(g, d) {
35
+ const key = evaluate({ op: "key", of: "targets" }, { g, review: d });
36
+ for (let i = 0; i < g.projectCount; i++)
37
+ key[i] = 0;
38
+ return key;
39
+ }
28
40
  /** The plan of the document of the board that holds `set` (per node of `g`) clustered by `mode`
29
41
  * with the levels `hidden` hidden. A cluster that holds no declaration of its own and one section
30
42
  * only is merged into it, its heading `A.B`, so that the document has no heading chains with
31
43
  * nothing under them; the board merges such a chain into one circle already where it holds nothing
32
44
  * else at all. On a board of a past build, `g` is its past graph (shared/pastgraph.ts), which holds
33
- * that build's declarations alone. */
34
- export function planDoc(g, set, mode, hidden) {
45
+ * that build's declarations alone. `keyed`: the declarations outside the project that are printed,
46
+ * those key for a target (`outsideKeys`); none where it is left out. */
47
+ export function planDoc(g, set, mode, hidden, keyed = null) {
35
48
  // the board's members in the whole graph's order, as a board's graph has them (shared/board.ts)
36
49
  const members = [];
37
50
  for (let i = 0; i < g.n; i++)
@@ -42,8 +55,11 @@ export function planDoc(g, set, mode, hidden) {
42
55
  const top = [];
43
56
  const by = new Map();
44
57
  let outside = 0;
58
+ let keyOutside = 0;
45
59
  members.forEach((i, k) => {
46
- if (g.isExt(i)) {
60
+ if (g.isExt(i) && keyed?.[i])
61
+ keyOutside++;
62
+ else if (g.isExt(i)) {
47
63
  outside++;
48
64
  const lib = g.nodes[i].module.split(".")[0] || g.nodes[i].module;
49
65
  by.set(lib, (by.get(lib) ?? 0) + 1);
@@ -88,6 +104,7 @@ export function planDoc(g, set, mode, hidden) {
88
104
  sections,
89
105
  count: top.length + own.reduce((a, d) => a + d.length, 0),
90
106
  sectionCount,
107
+ keyOutside,
91
108
  outside: { count: outside, by: [...by].map(([name, count]) => ({ name, count })).sort((a, b) => b.count - a.count || (a.name < b.name ? -1 : 1)) },
92
109
  };
93
110
  }
@@ -0,0 +1,16 @@
1
+ // A declaration outside the project, where it is written (ReviewSpec, "The source window", the
2
+ // owner's decision of 2026-10-20): a package of the project's lake-manifest, or Lean's core, as the
3
+ // server finds it (server/outside.ts) and tells the page and the agents with the file's text.
4
+ import { githubBlob } from "./deploy.js";
5
+ /** The package in words, as the window's title bar and the agents say it: `mathlib at 089be84`,
6
+ * `Lean v4.35.0`. */
7
+ export function packageWords(o) {
8
+ if (!o.rev)
9
+ return o.package;
10
+ return o.core ? `${o.package} ${o.rev}` : `${o.package} at ${o.rev.slice(0, 7)}`;
11
+ }
12
+ /** "Open on GitHub" for lines `from` to `to` (from 1) of an outside file: its package's repository at
13
+ * the revision; null where there is none. */
14
+ export function outsideLink(o, from, to) {
15
+ return o.github ? githubBlob(o.github.repo, o.github.rev, o.github.path, from, to) : null;
16
+ }
@@ -22,7 +22,7 @@ export const PAST_CHANGED = 4;
22
22
  /** renamed since: shown under its name then */
23
23
  export const PAST_RENAMED = 8;
24
24
  /** The git commit of a past build; none where it is not known, or only guessed. Its source is the
25
- * project's, which the page has now (web/src/main.ts, GET /api/git). */
25
+ * project's, which the page has now (web/src/pageart.ts, GET /api/git). */
26
26
  function gitThen(commit) {
27
27
  if (!commit || commit.guessed)
28
28
  return { git: undefined };
@@ -36,7 +36,16 @@ export function pastGraph(snap, edges, now, diff) {
36
36
  const thenName = new Map(diff.renamed.map(([a, b]) => [b, a]));
37
37
  const removed = new Set(diff.removed);
38
38
  const changed = new Set(diff.changed.map((n) => thenName.get(n) ?? n));
39
- const nodes = snap.nodes;
39
+ // a snapshot read before 0.7.0 recorded no place for its outside declarations: where its package
40
+ // is at the same revision now, the place now is the place then, and only there is its source shown
41
+ // (HistorySpec decision 24; the server says which), so it takes the place now
42
+ const nodes = snap.nodes.map((v, i) => {
43
+ if (i < P || v.range)
44
+ return v;
45
+ const j = now.byName.get(v.name);
46
+ const r = j !== undefined && now.isExt(j) ? now.nodes[j].range : undefined;
47
+ return r ? { ...v, range: r } : v;
48
+ });
40
49
  const meta = {
41
50
  schema: 1,
42
51
  layoutVersion: now.meta.layoutVersion,
@@ -0,0 +1,152 @@
1
+ // Pointers in a room (CollabSpec decision 4; the owner's decisions of 2026-10-20): a reader and those
2
+ // who follow them directly see one another's pointers and text selections — the followed reader
3
+ // their followers', the followers the followed reader's and one another's. Only direct relations
4
+ // make a room: whom a page follows, who follows it, and who follows the same reader as it.
5
+ //
6
+ // A pointer is anchored to what is under it, never to the screen: a follower's page shows what the
7
+ // followed one shows, laid out for another screen, scrolled as its reader scrolls it. So a position is
8
+ // said as what it is on — the board, in its world (the camera is followed); the linear form, by its
9
+ // row; a source window's text, by its declaration, a line and a column; the reference window, by its
10
+ // page and where on it; an element of a followed surface (the panels, Activity, the review strip, the
11
+ // Export window), by the steps down to it from the surface and where in it — and each page finds it
12
+ // again on its own layout. A text selection is two such points in text.
13
+ //
14
+ // What a page sends (POST /api/pointer) and what the others in its room are told (`pointer`) are this
15
+ // module's, checked here as the server checks every field: a page sends only while it is in a room,
16
+ // at most every LEAD_MS (followed) or FOLLOW_MS (following); the server relays at most RELAY_PER_S a
17
+ // second per page, within the room alone, and keeps nothing. A private or read-only reader's pointer
18
+ // is never sent on, nor an agent's (it has none); a private or read-only follower is sent the
19
+ // others'. Each page draws at most SHOWN others' pointers, fading FADE_MS after they stop.
20
+ /** a followed reader's page sends its pointer at most this often (ms): some 16 a second */
21
+ export const LEAD_MS = 60;
22
+ /** a follower's, at most this often: some 10 a second */
23
+ export const FOLLOW_MS = 100;
24
+ /** the most a page's pointer is relayed in a second; more are dropped */
25
+ export const RELAY_PER_S = 25;
26
+ /** the most others' pointers a page shows at once: the latest to move */
27
+ export const SHOWN = 5;
28
+ /** a pointer still for this long fades */
29
+ export const FADE_MS = 2000;
30
+ /** the most bytes a pointer's request holds */
31
+ export const BODY_MAX = 4096;
32
+ /** the most steps from a surface down to an element, and the most characters of an attribute's value */
33
+ export const STEPS_MAX = 16;
34
+ const VALUE_MAX = 160;
35
+ const num = (x, lo, hi) => (typeof x === "number" && Number.isFinite(x) && x >= lo && x <= hi ? x : null);
36
+ const frac = (x) => num(x, -0.5, 1.5);
37
+ const str = (x, max) => (typeof x === "string" && x.length > 0 && x.length <= max && !/[\u0000-\u001f\u007f]/.test(x) ? x : null);
38
+ function cleanStep(x) {
39
+ if (!Array.isArray(x) || x.length !== 3)
40
+ return null;
41
+ const [a, v, n] = x;
42
+ const nth = Number.isInteger(n) && n >= 0 && n < 5000 ? n : null;
43
+ if (nth === null)
44
+ return null;
45
+ if (a === null)
46
+ return v === null ? [null, null, nth] : null;
47
+ if (typeof a !== "string" || !/^(?:id|class|data-[a-z0-9-]{1,40})$/.test(a))
48
+ return null;
49
+ if (a === "class" && !(typeof v === "string" && /^[\w-]{1,60}$/.test(v)))
50
+ return null;
51
+ if (v === null)
52
+ return [a, null, nth];
53
+ const value = typeof v === "string" && v.length <= VALUE_MAX && !/[\u0000-\u001f\u007f]/.test(v) ? v : null;
54
+ return value === null ? null : [a, value, nth];
55
+ }
56
+ function cleanSteps(x) {
57
+ if (!Array.isArray(x) || x.length > STEPS_MAX)
58
+ return null;
59
+ const out = x.map(cleanStep);
60
+ return out.every((s) => s !== null) ? out : null;
61
+ }
62
+ function cleanRoot(x) {
63
+ const o = x && typeof x === "object" ? x : null;
64
+ if (!o)
65
+ return null;
66
+ if (typeof o.id === "string")
67
+ return /^[A-Za-z][\w-]{0,60}$/.test(o.id) ? { id: o.id } : null;
68
+ if (o.sw !== undefined)
69
+ return str(o.sw, 2000) ? { sw: o.sw } : null;
70
+ return o.pw === true ? { pw: true } : null;
71
+ }
72
+ const lineCol = (x) => {
73
+ if (!Array.isArray(x) || x.length !== 2)
74
+ return null;
75
+ const [l, c] = x;
76
+ return Number.isInteger(l) && Number.isInteger(c) && l >= 0 && c >= 0 && l < 1e6 && c < 1e5 ? [l, c] : null;
77
+ };
78
+ /** A pointer's place as a page sent it, checked; null where it is none. */
79
+ export function cleanAt(x) {
80
+ const o = x && typeof x === "object" && !Array.isArray(x) ? x : null;
81
+ if (!o)
82
+ return null;
83
+ if (Array.isArray(o.b)) {
84
+ const [bx, by] = o.b;
85
+ const px = num(bx, -1e9, 1e9), py = num(by, -1e9, 1e9);
86
+ return o.b.length === 2 && px !== null && py !== null ? { b: [px, py] } : null;
87
+ }
88
+ if (Array.isArray(o.l)) {
89
+ const [k, fy, dx] = o.l;
90
+ const key = str(k, 2000), y = frac(fy), d = num(dx, -1e6, 1e6);
91
+ return o.l.length === 3 && key && y !== null && d !== null ? { l: [key, y, d] } : null;
92
+ }
93
+ if (o.sw !== undefined && o.lc !== undefined) {
94
+ const sw = str(o.sw, 2000), lc = lineCol(o.lc);
95
+ return sw && lc ? { sw, lc } : null;
96
+ }
97
+ if (Array.isArray(o.pw)) {
98
+ const [p, fx, fy] = o.pw;
99
+ const page = Number.isInteger(p) && p >= 0 && p <= 100000 ? p : null;
100
+ const x2 = frac(fx), y2 = frac(fy);
101
+ return o.pw.length === 3 && page !== null && x2 !== null && y2 !== null ? { pw: [page, x2, y2] } : null;
102
+ }
103
+ if (o.in !== undefined) {
104
+ const root = cleanRoot(o.in), p = cleanSteps(o.p);
105
+ const f = Array.isArray(o.f) && o.f.length === 2 ? [frac(o.f[0]), frac(o.f[1])] : null;
106
+ return root && p && f && f[0] !== null && f[1] !== null ? { in: root, p, f: [f[0], f[1]] } : null;
107
+ }
108
+ return null;
109
+ }
110
+ /** A point in text as a page sent it, checked; null where it is none. */
111
+ export function cleanText(x) {
112
+ const o = x && typeof x === "object" && !Array.isArray(x) ? x : null;
113
+ if (!o)
114
+ return null;
115
+ if (o.sw !== undefined && o.lc !== undefined) {
116
+ const sw = str(o.sw, 2000), lc = lineCol(o.lc);
117
+ return sw && lc ? { sw, lc } : null;
118
+ }
119
+ const root = cleanRoot(o.in), p = cleanSteps(o.p);
120
+ const at = Number.isInteger(o.o) && o.o >= 0 && o.o < 1e7 ? o.o : null;
121
+ return root && p && at !== null ? { in: root, p, o: at } : null;
122
+ }
123
+ /** A selection as a page sent it, checked; null where it is none. */
124
+ export function cleanSel(x) {
125
+ const o = x && typeof x === "object" && !Array.isArray(x) ? x : null;
126
+ const a = o ? cleanText(o.a) : null, b = o ? cleanText(o.b) : null;
127
+ return a && b ? { a, b } : null;
128
+ }
129
+ /** What a page sent, checked: what is malformed is none. */
130
+ export function cleanPointer(x) {
131
+ const o = x && typeof x === "object" ? x : {};
132
+ return { at: cleanAt(o.at), sel: cleanSel(o.sel), ...(o.click === true ? { click: true } : {}) };
133
+ }
134
+ /** Whether `other` is in `page`'s room (the owner's decision of 2026-10-20): the reader `page`
135
+ * follows, someone following `page`, or someone following the reader `page` follows — direct
136
+ * relations alone, never another page of the same person. */
137
+ export function inRoom(page, other) {
138
+ if (other.id === page.id || (page.key !== null && other.key === page.key))
139
+ return false;
140
+ if (page.follows !== null && other.key === page.follows)
141
+ return true;
142
+ if (page.key !== null && other.follows === page.key)
143
+ return true;
144
+ return page.follows !== null && other.follows === page.follows;
145
+ }
146
+ /** The pages `from`'s pointer is relayed to: those of its room. A page nobody sees has its pointer
147
+ * shown to nobody. */
148
+ export function roomOf(from, pages) {
149
+ if (from.key === null)
150
+ return [];
151
+ return pages.filter((p) => inRoom(from, p)).map((p) => p.id);
152
+ }
@@ -14,6 +14,7 @@
14
14
  // file(Mathlib.NumberTheory) declarations of the modules under the prefix
15
15
  // trusted | external | sorry | nonstandard
16
16
  // kind(theorem, def) | status(unreviewed, stale) | advice(comment)
17
+ // mine(none, stale) where the reader's own review stands (none: they gave no opinion)
17
18
  // key(fermatLastTheoremFour) the target and the declarations marked key for it
18
19
  // key(targets) the same for every target
19
20
  // X and Y | X or Y | X except Y left to right, one level; parentheses group
@@ -23,9 +24,10 @@
23
24
  // word and a parenthesis (`ns(`), or joins with and, or, except is a query; a query that is one
24
25
  // plain word is written in parentheses there (`tcb((external))`). Words are read without regard to case (`usedby`); `namespace` and
25
26
  // `module` may stand for `ns` and `file`.
26
- import { adviceOf, keyMarks, STANDARD_AXIOMS, statusOf, trusted, under } from "./review.js";
27
+ import { adviceOf, keyMarks, ownStatus, STANDARD_AXIOMS, statusOf, trusted, under } from "./review.js";
27
28
  export const KINDS = ["theorem", "def", "abbrev", "instance", "structure", "class", "inductive", "opaque", "axiom", "quot", "constructor", "recursor", "notation", "unknown"];
28
29
  export const STATUSES = ["unreviewed", "approved", "commented", "stale"];
30
+ export const MINE_STATUSES = ["approved", "commented", "stale", "none"];
29
31
  const VERDICTS = ["approve", "comment"];
30
32
  const CLOSURES = ["tcb", "uses", "usedBy", "refs"];
31
33
  const PLAIN = ["all", "selection", "trusted", "external", "sorry", "nonstandard"];
@@ -340,7 +342,9 @@ function parse(text) {
340
342
  return { op: "status", statuses: choose(args(), STATUSES, "status") };
341
343
  if (w === "advice")
342
344
  return { op: "advice", verdicts: choose(args(), VERDICTS, "advice") };
343
- throw new QueryError(`${text1(t)} is not a word of the query language (all, tcb, uses, usedBy, refs, decl, key, ns, file, trusted, external, kind, status, advice, sorry, nonstandard)`, t.at);
345
+ if (w === "mine")
346
+ return { op: "mine", statuses: choose(args(), MINE_STATUSES, "mine") };
347
+ throw new QueryError(`${text1(t)} is not a word of the query language (all, tcb, uses, usedBy, refs, decl, key, ns, file, trusted, external, kind, status, advice, mine, sorry, nonstandard)`, t.at);
344
348
  };
345
349
  const expr = () => {
346
350
  let q = atom();
@@ -395,6 +399,8 @@ export function printQuery(q) {
395
399
  return `status(${q.statuses.join(", ")})`;
396
400
  case "advice":
397
401
  return `advice(${q.verdicts.join(", ")})`;
402
+ case "mine":
403
+ return `mine(${q.statuses.join(", ")})`;
398
404
  case "and":
399
405
  case "or":
400
406
  case "except": {
@@ -485,6 +491,8 @@ function readJson(x, why = false) {
485
491
  : null;
486
492
  case "advice":
487
493
  return Array.isArray(o.verdicts) && o.verdicts.length && o.verdicts.every((s) => VERDICTS.includes(s)) ? { op: "advice", verdicts: [...o.verdicts] } : null;
494
+ case "mine":
495
+ return Array.isArray(o.statuses) && o.statuses.length && o.statuses.every((s) => MINE_STATUSES.includes(s)) ? { op: "mine", statuses: [...o.statuses] } : null;
488
496
  case "and":
489
497
  case "or":
490
498
  case "except": {
@@ -549,9 +557,10 @@ export function namesIn(q) {
549
557
  walk(q);
550
558
  return [...out];
551
559
  }
552
- /** Whether the query reads the review (trust, statuses, advice): its set changes with opinions. */
560
+ /** Whether the query reads the review (trust, statuses, advice, one's own): its set changes with
561
+ * opinions. */
553
562
  export function readsReview(q) {
554
- if (q.op === "trusted" || q.op === "status" || q.op === "advice" || q.op === "key")
563
+ if (q.op === "trusted" || q.op === "status" || q.op === "advice" || q.op === "key" || q.op === "mine")
555
564
  return true;
556
565
  if ((q.op === "tcb" || q.op === "uses" || q.op === "usedBy" || q.op === "refs") && q.of !== "selection" && !Array.isArray(q.of))
557
566
  return readsReview(q.of);
@@ -559,6 +568,16 @@ export function readsReview(q) {
559
568
  return readsReview(q.a) || readsReview(q.b);
560
569
  return false;
561
570
  }
571
+ /** Whether the query reads one's own review (`mine(…)`): its set is each reader's own. */
572
+ export function readsMine(q) {
573
+ if (q.op === "mine")
574
+ return true;
575
+ if ((q.op === "tcb" || q.op === "uses" || q.op === "usedBy" || q.op === "refs") && q.of !== "selection" && !Array.isArray(q.of))
576
+ return readsMine(q.of);
577
+ if (q.op === "and" || q.op === "or" || q.op === "except")
578
+ return readsMine(q.a) || readsMine(q.b);
579
+ return false;
580
+ }
562
581
  /** The query with the selection replaced by `names`: what is lit now, as a scope (Zoom in). */
563
582
  export function withSelection(q, names) {
564
583
  switch (q.op) {
@@ -638,6 +657,8 @@ const list = (names) => (names.length > 2 ? `${names.slice(0, 2).map(last).join(
638
657
  const roots = (of) => (of === "selection" ? "the selection" : Array.isArray(of) ? list(of) : describe(of));
639
658
  const or = (xs) => (xs.length > 1 ? `${xs.slice(0, -1).join(", ")} or ${xs[xs.length - 1]}` : xs[0]);
640
659
  // a Map, not an object: `constructor` is a kind, and an object's own property besides
660
+ /** one's own review in words (`mine(…)`): "me" is whoever reads it, the reader */
661
+ const MINE_WORDS = { approved: "approved by me", commented: "commented on by me", stale: "stale of mine", none: "not reviewed by me" };
641
662
  const PLURAL = new Map([["theorem", "theorems"], ["def", "definitions"], ["abbrev", "abbreviations"], ["instance", "instances"], ["structure", "structures"], ["class", "classes"], ["inductive", "inductive types"], ["opaque", "opaque constants"], ["axiom", "axioms"], ["notation", "notations"]]);
642
663
  /** A set in a few words, for a chip: "TCB of fermatLastTheoremFour", "everything". */
643
664
  export function describe(q) {
@@ -683,6 +704,8 @@ export function describe(q) {
683
704
  return or(q.statuses.map((s) => (s === "unreviewed" ? "not yet reviewed" : s)));
684
705
  case "advice":
685
706
  return `what an agent ${or(q.verdicts.map((v) => (v === "approve" ? "approves" : "comments on")))}`;
707
+ case "mine":
708
+ return or(q.statuses.map((s) => MINE_WORDS[s]));
686
709
  case "and":
687
710
  case "or":
688
711
  case "except":
@@ -706,7 +729,7 @@ export function describeCondition(c) {
706
729
  return `only in namespace ${q.prefix}`;
707
730
  if (q.op === "file")
708
731
  return `only in files under ${q.prefix}`;
709
- if (q.op === "kind" || q.op === "status" || q.op === "advice" || q.op === "key")
732
+ if (q.op === "kind" || q.op === "status" || q.op === "advice" || q.op === "key" || q.op === "mine")
710
733
  return `only ${describe(q)}`;
711
734
  return `and ${describe(q)}`;
712
735
  }
@@ -814,6 +837,14 @@ function evaluateIn(q, ctx, walks) {
814
837
  return a !== null && vs.has(a);
815
838
  });
816
839
  }
840
+ case "mine": {
841
+ // nobody's own review to read: nothing (an agent's advice is no one's own, AgentSpec decision 2)
842
+ const me = ctx.me;
843
+ if (!me)
844
+ return out;
845
+ const ss = new Set(q.statuses);
846
+ return each((i) => ss.has(ownStatus(d, g.nodes[i].name, me, g.nodes[i].hash)));
847
+ }
817
848
  case "and":
818
849
  case "or":
819
850
  case "except": {
@@ -355,8 +355,14 @@ export function record(d, r, toolchain, now) {
355
355
  applyEvent(d, e);
356
356
  return e;
357
357
  }
358
+ /** Whose opinion a request records or takes back: the person it is for (ReviewSpec decisions 8 and
359
+ * 9), else its writer's own — an agent's, its advice. */
360
+ function whoseOp(r) {
361
+ return r.for?.trim() ? { by: r.for.trim(), ...(r.forPerson ? { person: r.forPerson } : {}) } : { by: r.by.trim(), agent: r.agent, person: r.person };
362
+ }
358
363
  /** Whether recording `r` would change nothing: a target marked that is one, a prefix trusted that
359
- * is, a key declaration marked that is, a withdrawal with no opinion standing to take back. Such a
364
+ * is, a key declaration marked that is, a withdrawal with no opinion standing to take back, an
365
+ * approval of the present version by someone whose current opinion there is one already. Such a
360
366
  * request is answered, and nothing is appended. */
361
367
  export function noChange(d, r) {
362
368
  if (r.op === "target")
@@ -365,9 +371,14 @@ export function noChange(d, r) {
365
371
  return d.trusted.includes(r.prefix) === r.on;
366
372
  if (r.op === "key")
367
373
  return keyMarked(d, r.target, r.name) === r.on;
374
+ // nobody approves twice (ReviewSpec decision 1, the owner's decision of 2026-10-20): people,
375
+ // someone spoken for and agents' advice alike; once a change has made it stale, approving again
376
+ // is new
377
+ if (r.op === "opinion")
378
+ return r.verdict === "approve" && approval(d, r.name, whoseOp(r), r.hash) === "approved";
368
379
  // nothing standing to take back (ReviewSpec decision 9)
369
380
  if (r.op === "withdraw")
370
- return !standing(d, r.name, r.for?.trim() ? { by: r.for.trim(), ...(r.forPerson ? { person: r.forPerson } : {}) } : { by: r.by.trim(), agent: r.agent, person: r.person });
381
+ return !standing(d, r.name, whoseOp(r));
371
382
  if (r.op === "move")
372
383
  return moveIsIdle(d, { ...r, rename: r.rename || undefined });
373
384
  if (isLibraryOp(r.op))
@@ -622,6 +633,27 @@ export function standing(d, name, who) {
622
633
  const o = (Object.hasOwn(d.opinions, name) ? d.opinions[name] : []).findLast((p) => author(p) === whose);
623
634
  return o && !o.withdrawn ? o : null;
624
635
  }
636
+ /** Where one person's own review of a declaration stands (the owner's decision of 2026-10-20: the
637
+ * Mine scheme, `mine(…)`): their current opinion, on the version whose hash is `hash` — approved,
638
+ * commented — or on an earlier one, stale; none where they have none (none given, or withdrawn).
639
+ * Nobody else's opinion counts, and an agent's advice is no person's. */
640
+ export function ownStatus(d, name, who, hash) {
641
+ const o = standing(d, name, who);
642
+ if (!o)
643
+ return "none";
644
+ return !fresh(o, hash) ? "stale" : STATUS_OF[o.verdict];
645
+ }
646
+ /** Where the approval of `who` on `name` stands against the version whose hash is `hash` (ReviewSpec
647
+ * decision 1, the owner's decision of 2026-10-20): `approved` where their current opinion is an
648
+ * approval of that version — approving again records nothing —, `stale` where it is an approval of
649
+ * an earlier one, `none` where it is no approval (none, a comment, or withdrawn). What the review
650
+ * box's Approve says (Approve, Approved ✓, Approve again), and what the server takes as no change. */
651
+ export function approval(d, name, who, hash) {
652
+ const o = standing(d, name, who);
653
+ if (!o || o.verdict !== "approve")
654
+ return "none";
655
+ return fresh(o, hash) ? "approved" : "stale";
656
+ }
625
657
  /** An opinion recorded for someone else (ReviewSpec decision 8), as the review holds it: theirs —
626
658
  * under their latest name where they are invited — saying who recorded it. */
627
659
  function recordedFor(d, o, forName, forPerson) {
@@ -2,7 +2,7 @@
2
2
  // namespaces and sections around it, the `open` commands (an `open … in` right before it
3
3
  // included), the `variable`s, `universe`s, options and section-local commands. The page reads the
4
4
  // namespaces and opens to link the short names in a declaration's source (web/src/scope.ts); the
5
- // agents' API answers with all of it (server/agent.ts, `context`); shared/context.ts writes it as
5
+ // agents' API answers with all of it (server/agentread.ts, `context`); shared/context.ts writes it as
6
6
  // the block of Lean shown above a declaration's source and recorded with what an opinion judged.
7
7
  // This is the text, read without elaborating it: where Lean is running, what Lean says wins.
8
8
  /** The namespaces that exist in the graph: every proper prefix of a declaration's name. */
@@ -66,6 +66,12 @@ const same = (...fields) => ({
66
66
  write: (v) => Object.fromEntries(fields.filter((f) => v[f] !== undefined).map((f) => [f, v[f]])),
67
67
  read: (o, clean) => Object.fromEntries(fields.filter((f) => f in o && clean[f] !== undefined).map((f) => [f, clean[f]])),
68
68
  });
69
+ /** The Export window with its job only where the job has an id: one the server had not named yet,
70
+ * or refused, is nothing the opener can read. */
71
+ function namedJob(e) {
72
+ const { job, ...rest } = e;
73
+ return { ...rest, ...(job?.id ? { job } : {}) };
74
+ }
69
75
  /** to a tenth of a unit of the board's world: a tenth of a pixel at the closest zoom but one */
70
76
  const tenth = (n) => Math.round(n * 10) / 10;
71
77
  /** The form of every followed part, by its name in the registry (web/src/surfaces.ts, which holds the
@@ -106,6 +112,15 @@ export const SNAPSHOT_FORMS = {
106
112
  colouring: same("scheme"),
107
113
  edges: same("edges"),
108
114
  linear: same("linear"),
115
+ // the Export window open, with its settings and the document it shows typeset or typesetting,
116
+ // which the opener reads by its id from the export's cache (the owner's decision of 2026-10-20); a
117
+ // job the server had not named yet, or refused, is no document to show, and is left out. Closed,
118
+ // nothing: the opener's own stays as it is
119
+ export: {
120
+ fields: ["export"],
121
+ write: (v) => (v.export?.open ? { export: namedJob(v.export) } : {}),
122
+ read: (o, clean) => ("export" in o && clean.export?.open ? { export: namedJob(clean.export) } : {}),
123
+ },
109
124
  artwork: same("artwork"),
110
125
  };
111
126
  /** The snapshot of where a page is (`v`, as presence carries it: the registry's parts, read by the