visualproof 0.4.4 → 0.5.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 (48) hide show
  1. package/README.md +16 -7
  2. package/dist/assets/tips/tour-agent.webp +0 -0
  3. package/dist/assets/tips/tour-arrange.webp +0 -0
  4. package/dist/assets/tips/tour-artwork.webp +0 -0
  5. package/dist/assets/tips/tour-checks.webp +0 -0
  6. package/dist/assets/tips/tour-keys.webp +0 -0
  7. package/dist/assets/tips/tour-library.webp +0 -0
  8. package/dist/assets/tips/tour-project.webp +0 -0
  9. package/dist/assets/tips/tour-review.webp +0 -0
  10. package/dist/assets/tips/tour-share.webp +0 -0
  11. package/dist/assets/tips/tour-source.webp +0 -0
  12. package/dist/assets/tips/tour-target.webp +0 -0
  13. package/dist/assets/tips/tour-view.webp +0 -0
  14. package/dist/assets/tips/tour.json +117 -112
  15. package/dist/assets/tips/tour.webp +0 -0
  16. package/dist/server/access.js +3 -1
  17. package/dist/server/accesspage.js +130 -0
  18. package/dist/server/agent.js +6 -1
  19. package/dist/server/buildwatch.js +133 -0
  20. package/dist/server/deploy.js +844 -0
  21. package/dist/server/doctor.js +15 -3
  22. package/dist/server/film.js +1 -1
  23. package/dist/server/historyapi.js +100 -50
  24. package/dist/server/historythread.js +206 -0
  25. package/dist/server/hover.js +8 -0
  26. package/dist/server/live.js +187 -36
  27. package/dist/server/main.js +256 -30
  28. package/dist/server/review.js +27 -7
  29. package/dist/server/status.js +119 -46
  30. package/dist/server/usage.js +51 -0
  31. package/dist/shared/board.js +2 -1
  32. package/dist/shared/deploy.js +35 -0
  33. package/dist/shared/layout.js +297 -70
  34. package/dist/shared/libm.js +366 -0
  35. package/dist/shared/palette.js +1 -1
  36. package/dist/shared/separate.js +556 -32
  37. package/dist/web/bundle/app.js +1972 -826
  38. package/dist/web/bundle/edges.js +2 -1
  39. package/dist/web/bundle/layout.js +1026 -80
  40. package/dist/web/src/canvas.js +47 -34
  41. package/dist/web/src/overview.js +4 -1
  42. package/dist/web/src/scene.js +13 -12
  43. package/dist/web/src/status.js +28 -0
  44. package/dist/web/src/theme.js +108 -0
  45. package/dist/web/style.css +102 -35
  46. package/docs/agent-api/history.md +3 -0
  47. package/docs/agent-api/requests.md +4 -3
  48. package/package.json +1 -1
@@ -4,7 +4,9 @@
4
4
  // Two speeds, on purpose. Build status is cheap (a few stats and hashes) and goes out every
5
5
  // second it changes, so a page shows "building 12 / 40" while Lean works. The graph is expensive
6
6
  // and only meaningful between builds, so it is re-extracted once the outputs stop moving; until
7
- // then the page keeps the last good graph and says how old it is.
7
+ // then the page keeps the last good graph and says how old it is. With nothing happening, the
8
+ // loop asks which compiles run, and looks at the files only when a watch says something moved
9
+ // (server/buildwatch.ts): a server at rest costs next to nothing.
8
10
  //
9
11
  // The extractor's graph is served as soon as it is ready; the usage pass (server/usage.ts) then
10
12
  // elaborates the modules whose result is not cached, and its findings — the notation each unit is
@@ -25,7 +27,8 @@ import { Invites } from "./invites.js";
25
27
  import { ReadOnlyLinks } from "./readonly.js";
26
28
  import { Talk } from "./talk.js";
27
29
  import { Asks } from "./askfollow.js";
28
- import { BuildTracker, importable, outputStamp, scanModules, sourceStamp } from "./status.js";
30
+ import { BuildTracker, compiling, importable, outputsOf, probeAll, scanModules, stampOf } from "./status.js";
31
+ import { BuildWatch, moduleDirs, shouldLook } from "./buildwatch.js";
29
32
  import { Views } from "./views.js";
30
33
  import { graphOf, memoryProblem, titleContext } from "./agentviews.js";
31
34
  import { ownName, rebinder, versionBase, versions, withVersions } from "./versions.js";
@@ -45,6 +48,9 @@ import { withoutReasons } from "../shared/timeline.js";
45
48
  const TICK = 1000;
46
49
  /** outputs quiet this long, and no compile running: the build is over */
47
50
  const SETTLE = 2500;
51
+ /** how long a watch's news of a change a look found may take before the look counts as one it
52
+ * missed (server/buildwatch.ts) */
53
+ const MISS_GRACE_MS = 500;
48
54
  const PING = 15000;
49
55
  /** Event streams, which every change goes to: at most this many open at once, and this many per
50
56
  * page (`session`: a reload, a lost connection coming back), its oldest closed for a new one. */
@@ -70,7 +76,15 @@ export class Live {
70
76
  mods = new Map();
71
77
  lastStamp = "";
72
78
  extractedStamp = "";
79
+ /** what the last look would read: the stamp, or a followed branch's outputs alone */
80
+ lastRead = "";
73
81
  quietSince = 0;
82
+ /** what tells the loop to look at the files (server/buildwatch.ts) */
83
+ buildWatch = new BuildWatch((l) => this.say(l));
84
+ /** when the files were last looked at, the compiles that ran then, and the status as last sent */
85
+ lastLook = 0;
86
+ lastRunning = "";
87
+ buildText = "";
74
88
  build = null;
75
89
  graph = null;
76
90
  extracting = false;
@@ -86,6 +100,11 @@ export class Live {
86
100
  /** review changes not yet sent: those made in one turn of the event loop go out as one */
87
101
  reviewPending = [];
88
102
  version = 0;
103
+ /** the branch followed (DeploySpec), where the server builds what it shows; null for a workspace,
104
+ * whose builds are its owner's */
105
+ deploy = null;
106
+ /** graphs being made ready to serve (install): the tree is read meanwhile */
107
+ installing = 0;
89
108
  /** this server's process, as its pages know it (UpdateSpec decision 8): the graph's versions are
90
109
  * counted again by another */
91
110
  instance = randomBytes(6).toString("base64url");
@@ -344,7 +363,11 @@ export class Live {
344
363
  }
345
364
  /** The review changed (server/review.ts tells it): every open page gets what changed — the new
346
365
  * events, which it applies to the review it holds (`review-delta`), or, where events came in
347
- * between, the whole review (`review`). Changes made in one turn (an agent's batch of advice)
366
+ * between, the revision alone (`review-rev`), at which the page reads the whole review (GET
367
+ * /api/review, compressed and tagged). The stream never carries the whole review: with thousands
368
+ * of opinions it is megabytes, and it went uncompressed to every page, which read it again from
369
+ * GET /api/review besides (5.4 MB to each page of a review of 5,000 opinions on
370
+ * NavierStokesAndEuler, 0.7 MB compressed). Changes made in one turn (an agent's batch of advice)
348
371
  * go out as one. A new target's TCB is where its timeline starts; it has no view until a click
349
372
  * gives it one (ViewSpec decision 29). */
350
373
  reviewChanged(c) {
@@ -362,7 +385,7 @@ export class Live {
362
385
  if (deltas)
363
386
  this.send("review-delta", { epoch: last.epoch, base: cs[0].base, rev: last.rev, events: cs.flatMap((c) => c.events), problems: last.problems, error: this.review.error });
364
387
  else
365
- this.send("review", this.review.whole());
388
+ this.send("review-rev", this.reviewRev());
366
389
  this.timeline.reviewChanged(this.review.data);
367
390
  // a target a move brought from another name takes that name's view over; a target unmarked is
368
391
  // unlinked from its view
@@ -397,27 +420,43 @@ export class Live {
397
420
  if (this.history)
398
421
  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)}`));
399
422
  // the review's logs are watched whatever the graph comes from: they may change on disk any time
400
- setInterval(() => this.checkReview(), TICK);
401
- setInterval(() => {
423
+ this.timers.push(setInterval(() => this.checkReview(), TICK));
424
+ this.timers.push(setInterval(() => {
402
425
  for (const st of [...this.streams.values()])
403
426
  this.push(st, ": ping\n\n");
404
- }, PING);
427
+ }, PING));
405
428
  if (this.saved) {
406
429
  // a saved extraction does not change: no watching of the build
407
430
  void this.extract(null);
408
431
  return;
409
432
  }
410
433
  const loop = async () => {
434
+ if (this.stopped)
435
+ return;
411
436
  try {
412
437
  await this.tick();
413
438
  }
414
439
  catch (e) {
415
440
  this.say(`watch: ${e instanceof Error ? e.message : String(e)}`);
416
441
  }
417
- setTimeout(loop, TICK);
442
+ if (!this.stopped)
443
+ this.next = setTimeout(loop, TICK);
418
444
  };
419
445
  void loop();
420
446
  }
447
+ /** the loop's timers, which `stop` clears */
448
+ timers = [];
449
+ next = null;
450
+ stopped = false;
451
+ /** Nothing more is watched (a test that ran the loop, at its end). */
452
+ stop() {
453
+ this.stopped = true;
454
+ for (const t of this.timers)
455
+ clearInterval(t);
456
+ if (this.next)
457
+ clearTimeout(this.next);
458
+ this.timers = [];
459
+ }
421
460
  /** The review's logs changed on disk (by hand, a backup restored): what changed is read, and the
422
461
  * store tells the pages. */
423
462
  checkReview() {
@@ -429,30 +468,76 @@ export class Live {
429
468
  }
430
469
  }
431
470
  async tick() {
471
+ const running = await compiling(this.project);
432
472
  const now = Date.now();
433
- const stampOf = () => `${outputStamp(this.project, this.mods)}#${sourceStamp(this.project, this.mods)}`;
434
- let st = stampOf();
473
+ const runs = [...running].sort().join(" ");
474
+ // the files are looked at only when something says to (server/buildwatch.ts)
475
+ const heard = this.buildWatch.dirty;
476
+ const look = shouldLook({
477
+ heard,
478
+ polling: this.buildWatch.polling !== null,
479
+ running: running.size,
480
+ runsChanged: runs !== this.lastRunning,
481
+ active: !!this.build?.active,
482
+ sinceMove: now - this.quietSince,
483
+ sinceLook: now - this.lastLook,
484
+ unread: this.lastRead !== this.extractedStamp,
485
+ settle: SETTLE,
486
+ tick: TICK,
487
+ });
488
+ if (!look)
489
+ return;
490
+ this.buildWatch.dirty = false;
491
+ this.lastLook = now;
492
+ this.lastRunning = runs;
493
+ let probes = probeAll(this.project, this.mods);
494
+ let st = stampOf(probes);
495
+ // the first look is not a change: a project at rest is read at once
496
+ const moved = st !== this.lastStamp && this.lastStamp !== "";
497
+ // a change no watch told of, unless its news is on its way still (through the event loop; after
498
+ // a moment, on macOS): one more and the watches are given up
499
+ if (moved && !heard && this.buildWatch.polling === null)
500
+ setTimeout(() => this.buildWatch.dirty || this.buildWatch.missed(), MISS_GRACE_MS).unref();
435
501
  if (st !== this.lastStamp || this.mods.size === 0) {
436
502
  // sources or outputs moved: files may have appeared, and the import graph changed
437
503
  this.project.files = indexSources(this.project.root);
438
504
  this.mods = scanModules(this.project);
439
- st = stampOf();
505
+ probes = probeAll(this.project, this.mods);
506
+ st = stampOf(probes);
440
507
  }
441
- // the first look is not a change: a project at rest is read at once
442
- const moved = st !== this.lastStamp && this.lastStamp !== "";
508
+ this.buildWatch.watch(moduleDirs(this.project, this.mods), this.project.root);
443
509
  this.lastStamp = st;
444
510
  if (moved)
445
511
  this.quietSince = now;
446
- const build = await this.tracker.status(this.mods);
447
- const before = this.build && JSON.stringify(this.build);
512
+ // the status as JSON once a look, compared with what went out last
513
+ let build = await this.tracker.status(this.mods, probes, running);
514
+ // following a branch, the build going on is the server's own: active from its fetch to its end
515
+ // (DeploySpec decision 6)
516
+ const d = this.deploy;
517
+ if (d && d.busy && !build.active)
518
+ build = { ...build, active: true };
519
+ const text = JSON.stringify(build);
448
520
  this.build = build;
449
- if (JSON.stringify(build) !== before) {
521
+ if (text !== this.buildText) {
522
+ this.buildText = text;
450
523
  this.send("build", build);
451
524
  this.timeline.buildStatus(build);
452
525
  }
526
+ // and its builds, beside the files: the one going on, the newest commit waiting, the last
527
+ if (d) {
528
+ const now = JSON.stringify(d.status(true));
529
+ if (now !== this.deploySent) {
530
+ this.deploySent = now;
531
+ this.sendDeploy();
532
+ }
533
+ }
534
+ // a branch's tree is read only between its builds, and only where a build wrote something:
535
+ // its sources change only with a checkout, which a build follows (DeploySpec decision 5)
536
+ const read = d ? outputsOf(probes) : st;
537
+ this.lastRead = read;
453
538
  const settled = !build.active && now - this.quietSince >= SETTLE;
454
- if (settled && !this.extracting && st !== this.extractedStamp) {
455
- this.extractedStamp = st;
539
+ if (settled && !this.extracting && read !== this.extractedStamp && !d?.holds()) {
540
+ this.extractedStamp = read;
456
541
  const ok = importable(this.project, this.mods);
457
542
  const okSet = new Set(ok);
458
543
  const missing = [...this.mods.keys()].filter((m) => !okSet.has(m)).sort();
@@ -517,6 +602,17 @@ export class Live {
517
602
  * provisional: the usage pass's graph, which `completes` that build's extraction, is laid out as
518
603
  * the build's own (server/pipeline.ts, prepare). */
519
604
  async install(ex, missing, usage, completes) {
605
+ // the tree is read until it is served (the source texts the snapshot keeps): a branch's build
606
+ // waits (DeploySpec decision 5)
607
+ this.installing++;
608
+ try {
609
+ await this.installNow(ex, missing, usage, completes);
610
+ }
611
+ finally {
612
+ this.installing--;
613
+ }
614
+ }
615
+ async installNow(ex, missing, usage, completes) {
520
616
  const laid = await prepare(this.project, this.dirs, null, (l) => this.say(l), { extraction: ex, provisional: usage === "pending", completes });
521
617
  if (this.graph && this.graph.fingerprint === laid.fingerprint)
522
618
  return;
@@ -528,7 +624,8 @@ export class Live {
528
624
  // versions served are made under them (HistorySpec.md)
529
625
  const renamed = this.snapshot(ex, missing);
530
626
  const prep = this.versioned(laid);
531
- this.graph = { version: ++this.version, fingerprint: prep.fingerprint, at: new Date().toISOString(), missing, usage: { state: usage, failed }, prep };
627
+ const commit = this.deploy?.commit()?.hash;
628
+ this.graph = { version: ++this.version, fingerprint: prep.fingerprint, at: new Date().toISOString(), missing, usage: { state: usage, failed }, ...(commit ? { commit } : {}), prep };
532
629
  this.send("graph", this.graphInfo());
533
630
  this.lostChanged();
534
631
  // opinions recorded under the kernel's hash are bound to the versions of this graph
@@ -615,7 +712,8 @@ export class Live {
615
712
  // a re-layout going on is let finish; a newer build supersedes the pass
616
713
  while (this.extracting && this.passFor === ex.fingerprint)
617
714
  await new Promise((ok) => setTimeout(ok, 200));
618
- if (!merged || this.passFor !== ex.fingerprint)
715
+ // a branch's build that started meanwhile changes the tree: its graph is read once it ends
716
+ if (!merged || this.passFor !== ex.fingerprint || this.deploy?.holds())
619
717
  return;
620
718
  this.passFor = null;
621
719
  await this.install(merged, missing, "done", ex.fingerprint);
@@ -651,6 +749,12 @@ export class Live {
651
749
  const renamed = this.review.data.renamed;
652
750
  return renamed ? (u) => identityIn(renamed, u) : ownName;
653
751
  }
752
+ /** The renames in force (to → from), which `identity` follows: what the history's worker makes it
753
+ * again from (server/historythread.ts). */
754
+ renamed() {
755
+ const renamed = this.review.data.renamed;
756
+ return renamed ? Object.entries(renamed) : null;
757
+ }
654
758
  /** Keep a snapshot of the graph just read (server/history.ts): a new build's, or its own again;
655
759
  * then pair what vanished since the build before with what appeared (server/renames.ts), and
656
760
  * migrate the renames of high confidence. The pages are told of a snapshot made or changed
@@ -661,7 +765,10 @@ export class Live {
661
765
  return renamed;
662
766
  try {
663
767
  const t0 = Date.now();
664
- const commit = commitNow(this.project.root);
768
+ // a branch's build is of the commit its build checked out, on the branch followed; a
769
+ // workspace's, of the commit checked out as it is read
770
+ const d = this.deploy?.commit();
771
+ const commit = this.deploy ? (d ? { hash: d.hash, branch: d.branch } : null) : commitNow(this.project.root);
665
772
  // the texts the build was compiled from, while its files are most likely still those
666
773
  // (HistorySpec decision 21): only the files that changed since any build are written
667
774
  let written = 0;
@@ -986,7 +1093,51 @@ export class Live {
986
1093
  /** Whether the server is working on the build (an extraction, a re-layout, the usage pass):
987
1094
  * no moment to restart in (UpdateSpec decision 6). */
988
1095
  get busy() {
989
- return this.extracting || this.usage.status.state === "running";
1096
+ return this.extracting || this.usage.status.state === "running" || !!this.deploy?.busy;
1097
+ }
1098
+ /** Whether the tree is being read: an extraction, a re-layout, a graph made ready to serve. A
1099
+ * branch's build changes the tree only after (DeploySpec decision 5). */
1100
+ get reading() {
1101
+ return this.extracting || this.installing > 0;
1102
+ }
1103
+ /** Following a branch, the commit of the graph on show and the branch (an exported document's
1104
+ * build, GET /api/git): null before a build was read; undefined for a workspace, whose commit git
1105
+ * says as it is now. */
1106
+ shownCommit() {
1107
+ const d = this.deploy;
1108
+ if (!d)
1109
+ return undefined;
1110
+ const c = this.graph?.commit ?? d.commit()?.hash;
1111
+ return c ? { hash: c, branch: d.status(false).branch } : null;
1112
+ }
1113
+ /** The branch followed and its builds, as agents are told them (GET /api/agent/history); null
1114
+ * for a workspace. */
1115
+ following() {
1116
+ return this.deploy?.status(true) ?? null;
1117
+ }
1118
+ /** A branch's build ended (DeploySpec decision 5): the tree is read again once it settles,
1119
+ * whatever the build wrote — a usage pass it cut short is done then, from what it finished. */
1120
+ reread() {
1121
+ this.extractedStamp = "";
1122
+ }
1123
+ /** A branch's builds changed (one started, a step, a newer commit waiting): the loop looks at its
1124
+ * next turn, as it does when a watch tells of a change (server/buildwatch.ts), and the pages are
1125
+ * told then. */
1126
+ lookSoon() {
1127
+ this.buildWatch.dirty = true;
1128
+ }
1129
+ /** The branch's builds as the pages were last told them (`deploy`). */
1130
+ deploySent = "";
1131
+ /** The branch's builds, to every page (`deploy`): a read-only reader's without the build's log
1132
+ * (DeploySpec decision 11). */
1133
+ sendDeploy() {
1134
+ const d = this.deploy;
1135
+ if (!d || !this.streams.size)
1136
+ return;
1137
+ const full = `event: deploy\ndata: ${JSON.stringify(d.status(true))}\n\n`;
1138
+ const slim = `event: deploy\ndata: ${JSON.stringify(d.status(false))}\n\n`;
1139
+ for (const st of [...this.streams.values()])
1140
+ this.push(st, st.readOnly === null ? full : slim);
990
1141
  }
991
1142
  /** What happened, to every page: a version set aside, without why, to those not told all
992
1143
  * (UpdateSpec decision 11). */
@@ -1032,6 +1183,8 @@ export class Live {
1032
1183
  // the usage pass: how far it is, and the modules it could not elaborate
1033
1184
  usage: this.usage.status,
1034
1185
  build: this.build,
1186
+ // the branch followed, where the server builds what it shows (DeploySpec)
1187
+ ...(this.deploy ? { deploy: this.deploy.status(true) } : {}),
1035
1188
  live: !this.saved,
1036
1189
  editor: this.editor,
1037
1190
  streams: { open: this.streams.size, max: MAX_STREAMS, readOnly: this.readOnlyStreams(), maxReadOnly: MAX_READONLY_STREAMS, closedForNotReading: this.dropped, agentsListening: this.talk.count },
@@ -1079,8 +1232,11 @@ export class Live {
1079
1232
  this.write(res, "views", { views: this.views.list(), changes: [], all: true });
1080
1233
  if (this.build)
1081
1234
  this.write(res, "build", this.build);
1082
- // the whole review once; what changes after comes as deltas
1083
- this.push(st, this.reviewHello());
1235
+ if (this.deploy)
1236
+ this.write(res, "deploy", this.deploy.status(readOnly === null));
1237
+ // the review's revision: a page that holds another reads the whole review (GET /api/review);
1238
+ // what changes after comes as deltas
1239
+ this.write(res, "review-rev", this.reviewRev());
1084
1240
  const g = this.graphInfo();
1085
1241
  if (g)
1086
1242
  this.write(res, "graph", g);
@@ -1095,15 +1251,9 @@ export class Live {
1095
1251
  st.room = MAX_BUFFERED + res.writableLength;
1096
1252
  st.after = 0;
1097
1253
  }
1098
- /** the whole review as a stream's hello says it, in bytes, and the text it was made from */
1099
- reviewBytes = null;
1100
- /** The whole review as every stream's hello says it: made into bytes once a revision, not once a
1101
- * stream (a hundred pages opening at once, a review of 7.6 MB, had the server 5 s encoding it). */
1102
- reviewHello() {
1103
- const text = this.review.wholeText();
1104
- if (this.reviewBytes?.text !== text)
1105
- this.reviewBytes = { text, bytes: Buffer.from(`event: review\ndata: ${text}\n\n`) };
1106
- return this.reviewBytes.bytes;
1254
+ /** Which review the server holds (`review-rev`): its run and its revision. */
1255
+ reviewRev() {
1256
+ return { epoch: this.review.epoch, rev: this.review.rev };
1107
1257
  }
1108
1258
  write(res, event, data) {
1109
1259
  const st = this.streams.get(res);
@@ -1120,9 +1270,10 @@ export class Live {
1120
1270
  this.push(st, text);
1121
1271
  }
1122
1272
  /** Write to a stream, unless what it has not read yet passed MAX_BUFFERED beyond its hello (`room`):
1123
- * then it is closed instead, and its page reconnects to the present state. A review of 5,000
1124
- * opinions on Sphere-Packing-Lean is 7 MB: counted against MAX_BUFFERED, it closed every page's
1125
- * stream as it opened, and the pages reconnected every two seconds, never live. */
1273
+ * then it is closed instead, and its page reconnects to the present state. A hello counted against
1274
+ * MAX_BUFFERED (in 0.4.3 it carried the whole review, 7 MB for 5,000 opinions on
1275
+ * Sphere-Packing-Lean) closed every page's stream as it opened, and the pages reconnected every two
1276
+ * seconds, never live. */
1126
1277
  push(st, text) {
1127
1278
  const waiting = st.res.writableLength;
1128
1279
  // all that waits was written since the hello: the hello is read