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
@@ -13,7 +13,8 @@
13
13
  // written in, the exact contexts — come as the next version of the graph. Where every module's
14
14
  // result is cached, the merged graph is the first one served.
15
15
  import { randomBytes } from "node:crypto";
16
- import { madeBy, nameKey, sameName } from "../shared/collab.js";
16
+ import { cleanFollowing, madeBy, nameKey, personKey, sameName } from "../shared/collab.js";
17
+ import { cleanPointer, RELAY_PER_S, roomOf } from "../shared/pointer.js";
17
18
  import { prepare } from "./pipeline.js";
18
19
  import { extract, loadSaved } from "./extract.js";
19
20
  import { DEFAULT_JOBS, UsagePass, mergeUsage, saveMerged } from "./usage.js";
@@ -33,7 +34,7 @@ import { buildChanges } from "../shared/build.js";
33
34
  import { Views } from "./views.js";
34
35
  import { graphOf, memoryProblem, titleContext } from "./agentviews.js";
35
36
  import { ownName, rebinder, versionBase, versions, withVersions } from "./versions.js";
36
- import { buildTime, commitNow, History } from "./history.js";
37
+ import { backfillPackages, buildTime, commitNow, History } from "./history.js";
37
38
  import { backfillSources, keepSources } from "./sourcestore.js";
38
39
  import { findRenames, Renames } from "./renames.js";
39
40
  import { carryClusterLinks, Library } from "./library.js";
@@ -46,6 +47,7 @@ import { boardSet } from "../shared/board.js";
46
47
  import { derivesOn, existsIn } from "../shared/noteplace.js";
47
48
  import { packageVersion } from "./version.js";
48
49
  import { withoutReasons } from "../shared/timeline.js";
50
+ import { OutsideSources } from "./outside.js";
49
51
  const TICK = 1000;
50
52
  /** outputs quiet this long, and no compile running: the build is over */
51
53
  const SETTLE = 2500;
@@ -75,6 +77,9 @@ export const BUILD_DELTA_MAX = 64 << 10;
75
77
  export const BUILD_DELTA_PART = 1 / 8;
76
78
  /** The graph's modules and their files (meta.modules), per graph read (agentviews.ts, graphOf). */
77
79
  const moduleFiles = new WeakMap();
80
+ /** The modules the graph's outside declarations are in, per graph read: the only outside modules
81
+ * whose source is served or handed to Lean (server/outside.ts). */
82
+ const outsideModules = new WeakMap();
78
83
  export class Live {
79
84
  project;
80
85
  /** the site directory and the project's caches (server/dirs.ts) */
@@ -175,6 +180,10 @@ export class Live {
175
180
  nodeIndex = new Map();
176
181
  /** the declarations outside the project the graph on show refers to: in it too */
177
182
  outside = new Set();
183
+ /** where the outside declarations' sources are (server/outside.ts), and the packages' revisions
184
+ * as the graph on show was read: a package at another one now is not the text it was read from */
185
+ outsideSources;
186
+ outsideRead = null;
178
187
  constructor(project, dirs, saved, review, editor = null, jobs = DEFAULT_JOBS) {
179
188
  this.project = project;
180
189
  this.dirs = dirs;
@@ -182,6 +191,8 @@ export class Live {
182
191
  this.review = review;
183
192
  this.editor = editor;
184
193
  this.usage = new UsagePass(project, dirs, saved ? 0 : jobs, (l) => this.say(l));
194
+ // the toolchain is the project's as it is now: a branch followed may change it (server/deploy.ts)
195
+ this.outsideSources = new OutsideSources(project.root, () => this.project.toolchain);
185
196
  this.tracker = new BuildTracker(project);
186
197
  this.timeline = new Timeline(dirs.site, (e) => this.sendActivity(e));
187
198
  this.tokens = new AgentTokens(dirs.site);
@@ -304,7 +315,7 @@ export class Live {
304
315
  return;
305
316
  }
306
317
  this.send("presence", this.presence.list());
307
- this.send("private", { count: this.presence.privateCount() });
318
+ this.sendPrivate();
308
319
  this.presenceTimer = setTimeout(() => {
309
320
  this.presenceTimer = null;
310
321
  if (this.presenceDirty) {
@@ -314,11 +325,54 @@ export class Live {
314
325
  }, PRESENCE_EVERY);
315
326
  this.presenceTimer.unref?.();
316
327
  }
328
+ /** How many private readers there are, as each page is told it (`private`): with how many of them
329
+ * follow its reader, which that reader's pages alone are told (the owner's decision of
330
+ * 2026-10-20), and whether someone unseen does — a read-only reader, never who nor how many, so
331
+ * that the page sends its pointer to them (the owner's decision of 2026-10-21). A private page,
332
+ * or a read-only one, is followed by nobody. */
333
+ privateOf(st, listed, followers, count, unseen) {
334
+ const me = st.private || st.readOnly !== null ? undefined : listed.get(st.id);
335
+ const key = me ? personKey(me) : null;
336
+ const n = key ? (followers.get(key) ?? 0) : 0;
337
+ return { count, ...(n ? { followers: n } : {}), ...(key && unseen.has(key) ? { unseen: true } : {}) };
338
+ }
339
+ /** The people read-only pages follow, as they said it (pointer). */
340
+ unseenFollowed() {
341
+ const out = new Set();
342
+ for (const st of this.streams.values())
343
+ if (st.readOnly !== null && st.follows)
344
+ out.add(st.follows);
345
+ return out;
346
+ }
347
+ /** Every page is told how many private readers there are, and how many of them follow its reader:
348
+ * one text for all the pages nobody private follows, one per count for the others. */
349
+ sendPrivate() {
350
+ if (!this.streams.size)
351
+ return;
352
+ const listed = new Map(this.presence.list().map((p) => [p.id, p]));
353
+ const followers = this.presence.privateFollowers();
354
+ const count = this.presence.privateCount();
355
+ const unseen = this.unseenFollowed();
356
+ const texts = new Map();
357
+ for (const st of [...this.streams.values()]) {
358
+ const p = this.privateOf(st, listed, followers, count, unseen);
359
+ const n = `${p.followers ?? 0}${p.unseen ? "+" : ""}`;
360
+ let text = texts.get(n);
361
+ if (text === undefined)
362
+ texts.set(n, (text = `event: private\ndata: ${JSON.stringify(p)}\n\n`));
363
+ this.push(st, text);
364
+ }
365
+ }
366
+ /** What one page is told of the private readers now. */
367
+ privateNow(st) {
368
+ return this.privateOf(st, new Map(this.presence.list().map((p) => [p.id, p])), this.presence.privateFollowers(), this.presence.privateCount(), this.unseenFollowed());
369
+ }
317
370
  /** A page's heartbeat, by the secret its stream was given: false when no open stream has it (a
318
371
  * stream that closed, a guess), and nothing changes. A private page's (`priv`, CollabSpec
319
- * decision 8) is counted and nothing more is kept of it: not its name, not where it is.
320
- * `verified`: the page of someone invited by a personal link (decision 9). */
321
- beat(token, name, view, idle, priv = false, verified = false, who = name) {
372
+ * decision 8) is counted, with whom it follows (`following`), and nothing more is kept of it: not
373
+ * its name, not where it is. `verified`: the page of someone invited by a personal link (decision
374
+ * 9). */
375
+ beat(token, name, view, idle, priv = false, verified = false, who = name, following = null) {
322
376
  const s = typeof token === "string" ? this.byToken.get(token) : undefined;
323
377
  if (!s)
324
378
  return false;
@@ -326,14 +380,58 @@ export class Live {
326
380
  // of the channels its stream is sent (CollabSpec decision 13)
327
381
  if (s.readOnly === null)
328
382
  s.name = who;
329
- if (s.private !== priv)
383
+ // whom it follows: its room's pointers are relayed to it (pointer)
384
+ s.follows = priv ? following : (view?.following ?? null);
385
+ if (s.private !== priv) {
330
386
  this.rename(s, priv, name, view, idle, verified);
387
+ if (priv && following)
388
+ this.presence.beatPrivate(s.id, following);
389
+ }
331
390
  else if (priv)
332
- this.presence.beatPrivate(s.id);
391
+ this.presence.beatPrivate(s.id, following);
333
392
  else
334
393
  this.presence.beat(s.id, name, view, idle, false, verified);
335
394
  return true;
336
395
  }
396
+ /** A page's pointer, by its stream's secret (POST /api/pointer; shared/pointer.ts): relayed at once
397
+ * to the pages of its room — whom it follows, who follows it, who follows the one it follows —
398
+ * and kept nowhere. A private or read-only page's is relayed to nobody, but a read-only page says
399
+ * whom it follows here, as it sends no heartbeat (CollabSpec decision 11), so as to be sent its
400
+ * room's; it is counted nowhere. Beyond RELAY_PER_S a second a page's are dropped. Answers the
401
+ * pages it went to, or null where no open stream has the secret. */
402
+ pointer(token, body, now = Date.now()) {
403
+ const s = typeof token === "string" ? this.byToken.get(token) : undefined;
404
+ if (!s)
405
+ return null;
406
+ if (s.readOnly !== null) {
407
+ const was = s.follows;
408
+ if ("following" in body)
409
+ s.follows = cleanFollowing(body.following);
410
+ // the reader it follows, or followed, is told whether someone unseen follows them
411
+ if (s.follows !== was)
412
+ this.sendPrivate();
413
+ return 0;
414
+ }
415
+ if (s.private)
416
+ return 0;
417
+ s.relayed = s.relayed.filter((t) => now - t < 1000);
418
+ if (s.relayed.length >= RELAY_PER_S)
419
+ return 0;
420
+ s.relayed.push(now);
421
+ const listed = new Map(this.presence.list().map((p) => [p.id, p]));
422
+ const page = (st) => {
423
+ const p = st.private || st.readOnly !== null ? undefined : listed.get(st.id);
424
+ return { id: st.id, key: p ? personKey(p) : null, follows: st.follows };
425
+ };
426
+ const to = new Set(roomOf(page(s), [...this.streams.values()].map(page)));
427
+ if (!to.size)
428
+ return 0;
429
+ const text = `event: pointer\ndata: ${JSON.stringify({ from: s.id, ...cleanPointer(body) })}\n\n`;
430
+ for (const st of [...this.streams.values()])
431
+ if (to.has(st.id))
432
+ this.push(st, text);
433
+ return to.size;
434
+ }
337
435
  /** A page went private, or showed itself again (CollabSpec decision 8): its stream gets a new
338
436
  * public id, so that nothing the others were told under one id — where the page was, under its
339
437
  * name; the `from` of what it arranged — ties it to what they are told under the other. The page
@@ -358,7 +456,7 @@ export class Live {
358
456
  }
359
457
  this.presence.renamed(old, s.id, priv, name, view, idle, verified);
360
458
  this.write(s.res, "presence", this.presence.list());
361
- this.write(s.res, "private", { count: this.presence.privateCount() });
459
+ this.write(s.res, "private", this.privateNow(s));
362
460
  }
363
461
  /** The file of a module of the graph on show, relative to the project (meta.modules): the only
364
462
  * modules whose source is served or handed to Lean. Undefined when the graph has no such module
@@ -372,6 +470,39 @@ export class Live {
372
470
  moduleFiles.set(G.meta, (files = new Map(G.meta.modules.map((m) => [m.name, m.file]))));
373
471
  return files.get(module);
374
472
  }
473
+ /** The file of a module outside the project, where an outside declaration of the graph on show
474
+ * is in it (ReviewSpec, "The source window", the owner's decision of 2026-10-20): its package's or
475
+ * Lean's core's (server/outside.ts), and whether that package is at another revision now than
476
+ * when the graph was read (`changed`). Undefined where the graph has no outside declaration in
477
+ * that module (or there is no graph yet, or it is a saved graph's, whose project is not here),
478
+ * null where its file is not found. */
479
+ outsideFile(module) {
480
+ const G = graphOf(this);
481
+ if (!G || this.saved)
482
+ return undefined;
483
+ let mods = outsideModules.get(G.meta);
484
+ if (!mods)
485
+ outsideModules.set(G.meta, (mods = new Set(G.meta.nodes.slice(G.meta.projectCount).map((v) => v.module))));
486
+ if (!mods.has(module))
487
+ return undefined;
488
+ const file = this.outsideSources.find(module);
489
+ if (!file)
490
+ return null;
491
+ const read = this.outsideRead;
492
+ const p = file.package;
493
+ const changed = !!read && (p.core ? read.toolchain !== this.project.toolchain : (read.packages[p.name] ?? null) !== p.rev);
494
+ return { file, changed };
495
+ }
496
+ /** A module outside the project as it is now, whatever the graph on show holds (server/outside.ts),
497
+ * and the toolchain now: what a past build's outside source is compared with (HistorySpec
498
+ * decision 24; server/historyapi.ts, `pastOutside`). Null for a saved graph, whose project is not
499
+ * here. */
500
+ outsideNow(module) {
501
+ if (this.saved)
502
+ return null;
503
+ const file = this.outsideSources.find(module);
504
+ return file && { file, toolchain: this.project.toolchain };
505
+ }
375
506
  /** The Project view's pins changed (the agents' API): every page gets the operations, and who
376
507
  * made them. */
377
508
  placesChanged(ops, from, by) {
@@ -470,6 +601,18 @@ export class Live {
470
601
  // background (HistorySpec decision 22): a snapshot backfilled is not looked at again
471
602
  if (this.history)
472
603
  void backfillSources(this.history, this.project, this.dirs.cache, (l) => this.say(l)).catch((e) => this.say(`history: the source texts could not be backfilled: ${e instanceof Error ? e.message : String(e)}`));
604
+ // the packages' revisions of the snapshots read before they were recorded, from their commits
605
+ // (HistorySpec decision 24)
606
+ if (this.history && !this.saved) {
607
+ try {
608
+ const n = backfillPackages(this.history, this.project.root);
609
+ if (n)
610
+ this.say(`history: ${n} snapshot(s) given their packages' revisions, from their commits' lake-manifest.json`);
611
+ }
612
+ catch (e) {
613
+ this.say(`history: the packages' revisions could not be backfilled: ${e instanceof Error ? e.message : String(e)}`);
614
+ }
615
+ }
473
616
  // the review's logs are watched whatever the graph comes from: they may change on disk any time
474
617
  this.timers.push(setInterval(() => this.checkReview(), TICK));
475
618
  this.timers.push(setInterval(() => {
@@ -665,6 +808,10 @@ export class Live {
665
808
  this.base = versionBase(ex.graph);
666
809
  this.nodeIndex = new Map(this.base.names.map((n, i) => [n, i]));
667
810
  this.outside = new Set(ex.graph.externals.map((e) => e.name));
811
+ // the revisions its outside declarations were read at: those of the manifest it was extracted
812
+ // with (server/extract.ts, fingerprint), as it is now; the packages and the toolchain as they are
813
+ this.outsideSources.forget();
814
+ this.outsideRead = this.saved ? null : { packages: this.outsideSources.revisions(), toolchain: this.project.toolchain };
668
815
  // the history first: the renames found against the build before are migrated, so that the
669
816
  // versions served are made under them (HistorySpec.md)
670
817
  const renamed = this.snapshot(ex, missing);
@@ -822,7 +969,7 @@ export class Live {
822
969
  written = found.written;
823
970
  return found;
824
971
  };
825
- const r = this.history.record(ex.graph, { at: buildTime(this.project), fingerprint: ex.fingerprint, commit, toolchain: this.project.toolchain, missing, sources, tool: this.toolVersion });
972
+ const r = this.history.record(ex.graph, { at: buildTime(this.project), fingerprint: ex.fingerprint, commit, toolchain: this.project.toolchain, missing, sources, tool: this.toolVersion, packages: this.outsideSources.revisions() });
826
973
  if (!r.written)
827
974
  return renamed;
828
975
  const s = r.info;
@@ -1264,7 +1411,7 @@ export class Live {
1264
1411
  connection: "keep-alive",
1265
1412
  });
1266
1413
  res.write("retry: 2000\n\n");
1267
- const st = { res, id: randomBytes(9).toString("base64url"), token: randomBytes(24).toString("base64url"), session, private: false, person, readOnly, name: readOnly === null ? name : null, toldAll, room: Infinity, after: 0, buildDeltas };
1414
+ const st = { res, id: randomBytes(9).toString("base64url"), token: randomBytes(24).toString("base64url"), session, private: false, person, readOnly, follows: null, relayed: [], name: readOnly === null ? name : null, toldAll, room: Infinity, after: 0, buildDeltas };
1268
1415
  this.streams.set(res, st);
1269
1416
  this.byToken.set(st.token, st);
1270
1417
  this.presence.open(st.id);
@@ -1273,7 +1420,7 @@ export class Live {
1273
1420
  if (this.updateStatus)
1274
1421
  this.write(res, "updates", this.updateStatus(st.toldAll));
1275
1422
  this.write(res, "presence", this.presence.list());
1276
- this.write(res, "private", { count: this.presence.privateCount() });
1423
+ this.write(res, "private", this.privateNow(st));
1277
1424
  this.write(res, "people", this.invites.people());
1278
1425
  // the views as they are: a page that was away (a restart, a lost connection) catches up, and
1279
1426
  // reads again the boards it has open
@@ -1393,6 +1540,9 @@ export class Live {
1393
1540
  // what its page was asked goes unanswered, and what it asked is withdrawn
1394
1541
  this.asks.closed(st.token);
1395
1542
  st.res.destroy();
1543
+ // a read-only page that followed someone: they are told whether someone unseen still does
1544
+ if (st.readOnly !== null && st.follows)
1545
+ this.sendPrivate();
1396
1546
  }
1397
1547
  }
1398
1548
  /** The importable modules nothing else importable imports: importing them imports the rest. */