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
@@ -0,0 +1,259 @@
1
+ // How the server sends what it answers (server/app.ts): JSON, the page's files, the graph's parts,
2
+ // the whole of a revision, texts and downloads; and a body refused as too large while it comes.
3
+ //
4
+ // Pages are often far from the server (CollabSpec, "Far pages"): every byte counts, and what a
5
+ // browser has it should not fetch again. The page's files and the graph are sent compressed, with
6
+ // a tag naming their content; a browser that has that content already is told so (304) and sends
7
+ // nothing more. Everything else in JSON is compressed when it is large.
8
+ import { createHash } from "node:crypto";
9
+ import { existsSync, readFileSync, statSync } from "node:fs";
10
+ import { extname } from "node:path";
11
+ import { gunzip, gunzipSync, gzip, gzipSync } from "node:zlib";
12
+ import { packEdges } from "../shared/edgecodec.js";
13
+ const TYPES = {
14
+ ".woff2": "font/woff2",
15
+ ".html": "text/html; charset=utf-8",
16
+ ".css": "text/css; charset=utf-8",
17
+ ".js": "text/javascript; charset=utf-8",
18
+ ".map": "application/json",
19
+ };
20
+ /** The tag naming a content. */
21
+ function tagOf(body) {
22
+ return `"${createHash("sha256").update(body).digest("base64url").slice(0, 27)}"`;
23
+ }
24
+ /** Whether the request already has the content `etag` names. */
25
+ function fresh(req, etag) {
26
+ const have = req.headers["if-none-match"];
27
+ return !!have && have.split(",").some((t) => t.trim().replace(/^W\//, "") === etag);
28
+ }
29
+ function acceptsGzip(req) {
30
+ return /\bgzip\b/.test(String(req?.headers["accept-encoding"] ?? ""));
31
+ }
32
+ /** the page's files as last read: compressed and tagged once per change on disk */
33
+ const files = new Map();
34
+ export function sendFile(req, res, file) {
35
+ if (refused.has(res))
36
+ return;
37
+ if (!existsSync(file))
38
+ return sendJson(res, { error: "not found" }, 404);
39
+ const st = statSync(file);
40
+ let f = files.get(file);
41
+ if (!f || f.mtime !== st.mtimeMs || f.size !== st.size) {
42
+ const body = readFileSync(file);
43
+ f = { mtime: st.mtimeMs, size: st.size, body, gz: null, etag: tagOf(body) };
44
+ files.set(file, f);
45
+ }
46
+ const head = { "content-type": TYPES[extname(file)] ?? "application/octet-stream", "cache-control": "no-cache", etag: f.etag, vary: "accept-encoding" };
47
+ if (fresh(req, f.etag)) {
48
+ res.writeHead(304, head);
49
+ return void res.end();
50
+ }
51
+ if (!acceptsGzip(req)) {
52
+ res.writeHead(200, head);
53
+ return void res.end(f.body);
54
+ }
55
+ f.gz ??= gzipSync(f.body, { level: 9 });
56
+ res.writeHead(200, { ...head, "content-encoding": "gzip" });
57
+ res.end(f.gz);
58
+ }
59
+ /** how long the rest of a body refused as too large is read before it is answered all the same,
60
+ * and the connection cut: long enough for a client to finish sending what it began, not for an
61
+ * endless body */
62
+ const TOO_LARGE_GRACE_MS = 2000;
63
+ export class TooLarge extends Error {
64
+ }
65
+ /** A request's body, refused (TooLarge) once it passes `limit` bytes: what comes after is not kept. */
66
+ export function readBody(req, limit) {
67
+ return new Promise((ok, fail) => {
68
+ const parts = [];
69
+ let size = 0;
70
+ if (Number(req.headers["content-length"]) > limit)
71
+ return fail(new TooLarge());
72
+ req.on("data", (b) => {
73
+ if (size > limit)
74
+ return;
75
+ size += b.length;
76
+ if (size > limit) {
77
+ parts.length = 0;
78
+ fail(new TooLarge());
79
+ }
80
+ else
81
+ parts.push(b);
82
+ });
83
+ req.on("end", () => ok(Buffer.concat(parts).toString("utf8")));
84
+ req.on("error", fail);
85
+ });
86
+ }
87
+ /** Responses refused as too large and not answered yet (tooLarge): what the handler that asked for
88
+ * the body answers meanwhile is not sent. */
89
+ export const refused = new WeakSet();
90
+ /** Answer 413 to a body too large and close the connection. The rest of the body is read and thrown
91
+ * away first, and the answer goes once it has all come: a connection closed while the client is
92
+ * still sending is reset on some systems (macOS), and the client never reads the answer. A client
93
+ * still sending after a short grace is answered all the same, and cut off. */
94
+ export function tooLarge(req, res, body) {
95
+ refused.add(res);
96
+ let done = false;
97
+ const answer = () => {
98
+ if (done)
99
+ return;
100
+ done = true;
101
+ refused.delete(res);
102
+ sendJson(res, body, 413, { connection: "close" });
103
+ };
104
+ req.on("data", () => { });
105
+ req.on("end", answer);
106
+ req.resume();
107
+ if (req.readableEnded)
108
+ answer();
109
+ setTimeout(() => {
110
+ answer();
111
+ setTimeout(() => req.socket.destroy(), 500).unref();
112
+ }, TOO_LARGE_GRACE_MS).unref();
113
+ }
114
+ /** Send a JSON answer, once: a handler that answers after something else already did (a body too
115
+ * large, answered as it was read) is not heard. */
116
+ export function sendJson(res, body, code = 200, headers = {}) {
117
+ if (res.headersSent || res.writableEnded || refused.has(res))
118
+ return;
119
+ sendJsonText(res, JSON.stringify(body), code, headers);
120
+ }
121
+ /** The same, of an answer written as JSON already. */
122
+ function sendJsonText(res, text, code = 200, headers = {}) {
123
+ if (res.headersSent || res.writableEnded || refused.has(res))
124
+ return;
125
+ // a small answer is not worth compressing; a status with its build log, a source file, are; a
126
+ // large one is compressed off the server's thread, which meanwhile answers others
127
+ if (text.length > JSON_GZIP_FROM && acceptsGzip(res.req)) {
128
+ res.writeHead(code, { "content-type": "application/json", "cache-control": "no-store", "content-encoding": "gzip", vary: "accept-encoding", ...headers });
129
+ if (text.length < JSON_GZIP_AWAY_FROM)
130
+ return void res.end(gzipSync(text));
131
+ return void gzip(text, (e, gz) => (e ? res.destroy(e) : res.end(gz)));
132
+ }
133
+ res.writeHead(code, { "content-type": "application/json", "cache-control": "no-store", ...headers });
134
+ res.end(text);
135
+ }
136
+ /** what is sent whole under the tag of its revision, compressed, per what it is of (the review, the
137
+ * build status) */
138
+ const revisionGz = new WeakMap();
139
+ /** A whole sent under the tag of its revision: the review (GET /api/review), tagged with its run and
140
+ * its revision (server/review.ts), and the build status (GET /api/build, server/live.ts). A page that
141
+ * has it is answered 304, which a reload is, and one that fell behind is sent it compressed — once a
142
+ * revision, off the server's thread when it is large, the same bytes for every page (a review of
143
+ * 5,000 opinions on Sphere-Packing-Lean: 8.5 MB of JSON, 1.1 MB sent; the build status of
144
+ * NavierStokesAndEuler's 2,657 files: 362 KB, 42 KB sent). `of` is what it is of; `whole` writes it,
145
+ * asked only where it is sent. */
146
+ export function sendRevision(req, res, of, tag, whole) {
147
+ if (res.headersSent || res.writableEnded || refused.has(res))
148
+ return;
149
+ const head = { "content-type": "application/json", "cache-control": "private, no-cache", etag: tag, vary: "accept-encoding" };
150
+ if (fresh(req, tag)) {
151
+ res.writeHead(304, head);
152
+ return void res.end();
153
+ }
154
+ const text = whole();
155
+ if (text.length <= JSON_GZIP_FROM || !acceptsGzip(req)) {
156
+ res.writeHead(200, head);
157
+ return void res.end(text);
158
+ }
159
+ let c = revisionGz.get(of);
160
+ if (c?.tag !== tag) {
161
+ const gz = text.length < JSON_GZIP_AWAY_FROM ? Promise.resolve(gzipSync(text)) : new Promise((ok, fail) => gzip(text, (e, b) => (e ? fail(e) : ok(b))));
162
+ revisionGz.set(of, (c = { tag, gz }));
163
+ // a compression that failed is tried again by the next page that asks
164
+ gz.catch(() => revisionGz.get(of)?.gz === gz && revisionGz.delete(of));
165
+ }
166
+ c.gz.then((gz) => {
167
+ if (res.headersSent || res.destroyed)
168
+ return;
169
+ res.writeHead(200, { ...head, "content-encoding": "gzip" });
170
+ res.end(gz);
171
+ }, (e) => res.destroy(e));
172
+ }
173
+ /** Send a text that is not JSON (the agents' documentation, the MCP server's file), compressed
174
+ * where the client takes it. */
175
+ export function sendText(req, res, text, type, code = 200) {
176
+ if (res.headersSent || res.writableEnded || refused.has(res))
177
+ return;
178
+ const head = { "content-type": type, "cache-control": "no-store", vary: "accept-encoding" };
179
+ if (text.length > JSON_GZIP_FROM && acceptsGzip(req)) {
180
+ res.writeHead(code, { ...head, "content-encoding": "gzip" });
181
+ return void res.end(gzipSync(text));
182
+ }
183
+ res.writeHead(code, head);
184
+ res.end(text);
185
+ }
186
+ /** Send a file to download (a typeset document): as it is, never cached, named for the disk. */
187
+ export function sendDownload(res, f) {
188
+ if (res.headersSent || res.writableEnded || refused.has(res))
189
+ return;
190
+ res.writeHead(200, { "content-type": f.type, "content-length": String(f.body.length), "content-disposition": `attachment; filename="${f.name.replace(/[^A-Za-z0-9._-]/g, "_")}"`, "cache-control": "no-store" });
191
+ res.end(f.body);
192
+ }
193
+ /** The Host a request was sent to, when it looks like one. */
194
+ export function hostOf(req) {
195
+ return /^[A-Za-z0-9.:[\]-]{1,300}$/.test(req.headers.host ?? "") ? req.headers.host : "127.0.0.1";
196
+ }
197
+ /** The server's address as the request's browser reached it: its Origin where it names the host
198
+ * the request was sent to (a page's POST carries it, with the scheme), else http:// and the Host. */
199
+ export function reachedAt(req) {
200
+ const host = hostOf(req);
201
+ try {
202
+ const o = new URL(String(req.headers.origin ?? ""));
203
+ if (o.host === host && (o.protocol === "http:" || o.protocol === "https:"))
204
+ return o.origin;
205
+ }
206
+ catch {
207
+ // no Origin, or not an address: the Host
208
+ }
209
+ return `http://${host}`;
210
+ }
211
+ /** characters from which a JSON answer is sent compressed */
212
+ const JSON_GZIP_FROM = 2048;
213
+ /** characters from which a JSON answer is compressed off the server's thread: a snapshot's whole
214
+ * graph on NavierStokesAndEuler (GET /api/agent/history/graph, 105 MB of JSON) was 2 to 3 s of
215
+ * compressing, every page and agent waiting meanwhile */
216
+ export const JSON_GZIP_AWAY_FROM = 1 << 20;
217
+ /** the graph's parts as sent, each tagged once (a graph's buffers live as long as it does) */
218
+ const gzTags = new WeakMap();
219
+ /** A part of the graph, gzipped already: tagged, so that a page that has it gets 304; a client that
220
+ * does not take gzip (an agent's) is sent it as it is, made so off the server's thread. */
221
+ export function sendGz(req, res, gz, type) {
222
+ if (refused.has(res))
223
+ return;
224
+ let etag = gzTags.get(gz);
225
+ if (!etag)
226
+ gzTags.set(gz, (etag = tagOf(gz)));
227
+ const head = { "content-type": type, "cache-control": "private, no-cache", etag, vary: "accept-encoding" };
228
+ if (fresh(req, etag)) {
229
+ res.writeHead(304, head);
230
+ return void res.end();
231
+ }
232
+ if (!acceptsGzip(req))
233
+ return void gunzip(gz, (e, plain) => {
234
+ if (e)
235
+ return res.destroy(e);
236
+ res.writeHead(200, head);
237
+ res.end(plain);
238
+ });
239
+ res.writeHead(200, { ...head, "content-encoding": "gzip" });
240
+ res.end(gz);
241
+ }
242
+ /** the edges packed for pages (shared/edgecodec.ts), once per graph and format */
243
+ const packedEdges = new WeakMap();
244
+ export function packedGz(edgesGz, format) {
245
+ let byFormat = packedEdges.get(edgesGz);
246
+ if (!byFormat)
247
+ packedEdges.set(edgesGz, (byFormat = new Map()));
248
+ let p = byFormat.get(format);
249
+ if (!p) {
250
+ const raw = gunzipSync(edgesGz);
251
+ const edges = new Int32Array(raw.buffer, raw.byteOffset, raw.byteLength / 4);
252
+ let n = 0;
253
+ for (let k = 0; k < edges.length; k += 3)
254
+ n = Math.max(n, edges[k] + 1, edges[k + 1] + 1);
255
+ p = gzipSync(packEdges(edges, n, format), { level: 9 });
256
+ byFormat.set(format, p);
257
+ }
258
+ return p;
259
+ }
@@ -15,7 +15,7 @@
15
15
  //
16
16
  // The state each agent is shown in comes from what it does, not from what it says: *listening*
17
17
  // while a wait is open; *thinking* from the moment messages were handed to it until it replies, with
18
- // what its requests show it doing (server/agent.ts, doingOf) and the line it may set itself;
18
+ // what its requests show it doing (server/agenttalk.ts, doingOf) and the line it may set itself;
19
19
  // *working* when it makes requests with nothing to answer; *offline* once it has had no wait open
20
20
  // and made no request for its longest wait plus a minute — the time an agent that listens takes at
21
21
  // most to come back. An offline agent's private channel cannot be written to (409); a mention of it
@@ -27,7 +27,7 @@
27
27
  // many a minute. A person's message in the public channel keeps the tokens of the agents it is handed
28
28
  // to (`to`, the agents it mentions that were listed as it was written), which is told to nobody.
29
29
  // Revoking a token, or its expiry, ends its wait at once. Who may read and write which channel is
30
- // server/main.ts's to check (shared/collab.ts, madeBy), and which page is sent which message
30
+ // server/apptalk.ts's to check (shared/collab.ts, madeBy), and which page is sent which message
31
31
  // server/live.ts's.
32
32
  //
33
33
  // A session that replaces another knows nothing of what the page still shows (the owner's decisions
@@ -71,6 +71,10 @@ export class Talk {
71
71
  /** each channel's last id in this server's life: a channel whose messages all expired goes on
72
72
  * counting from there, so that no agent's place in it (`read`) passes what comes next */
73
73
  lastIds = new Map();
74
+ /** the order messages were written in here, which their times (to the millisecond) may not tell:
75
+ * what is handed to an agent from both channels at once is in that order (`inOrder`) */
76
+ written = new WeakMap();
77
+ writes = 0;
74
78
  agents = new Map();
75
79
  buckets = new Map();
76
80
  ticks = 0;
@@ -290,7 +294,7 @@ export class Talk {
290
294
  const a = this.agent(token);
291
295
  const mine = this.load(token).filter((m) => m.kind !== "agent" && m.id > a.read);
292
296
  const named = this.load(PUBLIC).filter((m) => m.id > a.readPublic && m.kind === "person" && !!m.to?.includes(token));
293
- return inOrder(mine, named);
297
+ return inOrder(mine, named, (m) => this.written.get(m) ?? 0);
294
298
  }
295
299
  /** What `queued` holds is the agent's from now on: what comes after it is handed next. */
296
300
  mark(a, queued) {
@@ -312,7 +316,7 @@ export class Talk {
312
316
  const news = since.filter((m) => fresh.has(m.id));
313
317
  const told = since.filter((m) => !fresh.has(m.id));
314
318
  const missed = queued.filter((m) => m.channel === "public");
315
- const earlier = earlierOf(inOrder(told, missed), news.length > 0, now);
319
+ const earlier = earlierOf(inOrder(told, missed, (m) => this.written.get(m) ?? 0), news.length > 0, now);
316
320
  return earlier ? [earlier, ...news.map(outward)] : news.map(outward);
317
321
  }
318
322
  /** Hand over what a wait answers with: what is queued is the agent's from now on; people's
@@ -428,6 +432,7 @@ export class Talk {
428
432
  this.lastIds.set(channel, id);
429
433
  const msg = { id, at: new Date(now).toISOString(), ...rest, channel: channel === PUBLIC ? "public" : "private", ...(to?.length ? { to } : {}) };
430
434
  thread.push(msg);
435
+ this.written.set(msg, ++this.writes);
431
436
  if (thread.length > 2 * HELD)
432
437
  thread.splice(0, thread.length - HELD);
433
438
  mkdirSync(this.dir, { recursive: true });
@@ -534,13 +539,14 @@ export function forPages(m) {
534
539
  const { where: _where, ...rest } = m;
535
540
  return rest;
536
541
  }
537
- /** Two channels' messages as one list, in the order they were written. */
538
- function inOrder(a, b) {
542
+ /** Two channels' messages as one list, in the order they were written: by their times, and those of
543
+ * one millisecond by `written` (what was read from disk, 0, keeps the order it is given in). */
544
+ function inOrder(a, b, written) {
539
545
  if (!b.length)
540
546
  return a;
541
547
  if (!a.length)
542
548
  return b;
543
- return [...a, ...b].sort((x, y) => (x.at < y.at ? -1 : x.at > y.at ? 1 : 0));
549
+ return [...a, ...b].sort((x, y) => (x.at < y.at ? -1 : x.at > y.at ? 1 : written(x) - written(y)));
544
550
  }
545
551
  /** What came before as the entry a returning agent is handed first, or null where there is none: the
546
552
  * newest of `told`, at most EARLIER_MESSAGES and EARLIER_CHARS characters of text, each with who
@@ -1,6 +1,6 @@
1
1
  // Agent tokens (AgentSpec decision 7): sharing with an AI agent hands it a credential of its own,
2
2
  // never the server's key. A person makes one from Share for one agent; the token fixes the agent's
3
- // name and what it may do, lasts a few days, reaches the agents' API only (server/main.ts), and can
3
+ // name and what it may do, lasts a few days, reaches the agents' API only (server/app.ts), and can
4
4
  // be revoked from Share by anyone with a name.
5
5
  //
6
6
  // A token is `vpa_<id>_<secret>`: the prefix makes one recognisable wherever it is pasted or leaks
@@ -91,7 +91,7 @@ export class AgentTokens {
91
91
  }
92
92
  }
93
93
  /** Make a token for an agent: the token (for its prompt) and its record. The name and level are
94
- * checked by the caller (server/main.ts); the name is used as given, numbered when an agent in
94
+ * checked by the caller (server/appshare.ts); the name is used as given, numbered when an agent in
95
95
  * force has it already; `by` is a person's name, and `person` their personal link's id where an
96
96
  * invited person makes it (`makerPerson`: who its maker is, AgentSpec decision 7). */
97
97
  create(o) {
@@ -119,7 +119,7 @@ export class AgentTokens {
119
119
  this.onChanged();
120
120
  return { token: tokenOf(record), record };
121
121
  }
122
- /** A token in force, whole, for its prompt to be shown again (server/main.ts); null when there is
122
+ /** A token in force, whole, for its prompt to be shown again (server/appshare.ts); null when there is
123
123
  * no such token in force — an ended one is never shown. */
124
124
  token(id, now = Date.now()) {
125
125
  const r = this.inForce(now).find((x) => x.id === id);
@@ -63,8 +63,10 @@ function viewParts(p, ex) {
63
63
  v.proofs = n.proofs;
64
64
  return v;
65
65
  });
66
+ // an outside declaration's doc and place in its package's source, which the source window shows
67
+ // (ReviewSpec, "The source window", the owner's decision of 2026-10-20)
66
68
  for (const e of g.externals)
67
- nodes.push({ name: e.name, kind: e.kind, module: e.module, ax: e.ax, ext: true });
69
+ nodes.push({ name: e.name, kind: e.kind, module: e.module, ax: e.ax, ext: true, ...(e.doc ? { doc: e.doc } : {}), ...(e.range ? { range: e.range } : {}) });
68
70
  notationStatements(p, nodes);
69
71
  const edges = new Int32Array(g.edges.length * 3);
70
72
  g.edges.forEach(([s, d, m], i) => {
@@ -935,7 +935,7 @@ export class Views {
935
935
  return null;
936
936
  }
937
937
  // ---------------------------------------------------------------- the page's endpoints
938
- /** A request under /api/views, read by main.ts: what the page asks, under the name it gives. An
938
+ /** A request under /api/views, read by appsite.ts: what the page asks, under the name it gives. An
939
939
  * agent may use them too, within what `--agents` allows (AgentSpec decision 9): opening a view
940
940
  * is reading; everything else, deleting a view and laying one out afresh included, is level
941
941
  * full, recorded as the agent's. A private reader's changes are recorded without a name, and
@@ -2,9 +2,9 @@
2
2
  // picture of the board is, in words that hold on any project — a size by its name, names by a rule
3
3
  // ("the clusters to depth 1, and the targets"), targets and the selection by full name — so that
4
4
  // one recipe makes the same kind of picture of every codebase. An agent sends one
5
- // (POST /api/agent/artwork, server/agent.ts); the link it gets back carries it after `#`, and the
6
- // page that opens it resolves it against the board it opens on (web/src/main.ts, openRecipe) and
7
- // opens the artwork mode with what it says, saving the files where the link asks.
5
+ // (POST /api/agent/artwork, server/agentexport.ts); the link it gets back carries it after `#`, and
6
+ // the page that opens it resolves it against the board it opens on (web/src/pageart.ts, openRecipe)
7
+ // and opens the artwork mode with what it says, saving the files where the link asks.
8
8
  import { ART_MAX_SIDE, ART_NAMES_BYTES, ART_RULED_BYTES, ART_STYLES, ART_TARGETS_BYTES, artNameId, cleanNames, FOOT_SIZE, SCHEMES, TITLE_CHARS, TITLE_SIZE } from "./collab.js";
9
9
  /** The sizes offered (web/src/artwork.ts, PRESETS), each in either orientation: given landscape;
10
10
  * `key`, a recipe's name for it. */
@@ -101,11 +101,11 @@ export function setKey(g, set) {
101
101
  }
102
102
  return `${count}.${sum.toString(36)}.${mix.toString(36)}`;
103
103
  }
104
- /** The board a scope makes of a graph and a review. A scope holding the whole project and either
105
- * all of the outside world or none of it is the server's layout; anything else is laid out on its
106
- * own. */
107
- export function boardSet(g, review, scope) {
108
- const set = evaluate(scope, { g, review });
104
+ /** The board a scope makes of a graph and a review (`me`: whose own review `mine(…)` reads, the
105
+ * page's reader). A scope holding the whole project and either all of the outside world or none of
106
+ * it is the server's layout; anything else is laid out on its own. */
107
+ export function boardSet(g, review, scope, me = null) {
108
+ const set = evaluate(scope, { g, review, me });
109
109
  let own = 0, ext = 0;
110
110
  for (let i = 0; i < g.n; i++)
111
111
  if (set[i])
@@ -114,11 +114,12 @@ export function boardSet(g, review, scope) {
114
114
  const whole = own === g.projectCount && g.projectCount > 0 && (ext === 0 || outsideAll);
115
115
  return { set, key: setKey(g, set), count: own + ext, whole, outside: whole && ext > 0, sub: whole ? null : subgraph(g, set) };
116
116
  }
117
- /** What query `q` lights up on board `bs` of graph `g` (the graph the board was taken from): the
117
+ /** What query `q` lights up on board `bs` of graph `g` (the graph the board was taken from; `me` as
118
+ * boardSet's): the
118
119
  * query's set in the whole graph, then what of it the board holds — never the outside world on a
119
120
  * board without it. */
120
- export function lightUp(g, review, bs, q) {
121
- const full = evaluate(q, { g, review });
121
+ export function lightUp(g, review, bs, q, me = null) {
122
+ const full = evaluate(q, { g, review, me });
122
123
  let total = 0, count = 0;
123
124
  if (!bs.sub) {
124
125
  // the whole graph is the board's: cut in place what its scope leaves out
@@ -1,5 +1,6 @@
1
1
  // What the server and the page share about the people on a server (CollabSpec.md): names, the
2
2
  // colour each name has, and what a reader tells the others about where they are.
3
+ import { readSettings } from "./doc/settings.js";
3
4
  /** the most characters a name may have */
4
5
  export const MAX_NAME = 60;
5
6
  /** A name someone can be known by: 1–60 characters, no line breaks or other control characters. */
@@ -66,9 +67,47 @@ export function colorOf(name) {
66
67
  const hue = ((h >>> 0) % 360 + 360) % 360;
67
68
  return `hsl(${hue} 62% 46%)`;
68
69
  }
70
+ /** Who a page or an agent is among the people: one person per name — an agent and a person of the
71
+ * same name are two, and so are a guest and someone invited by a personal link — and a page without
72
+ * a name on its own. An agent is its presence entry, which the server keeps one per token, or one
73
+ * per name for an agent without a token (server/presence.ts): an agent that gives the name of one
74
+ * with a token is another, so that nobody can speak for an agent with a token by giving its name
75
+ * (AgentSpec, "Presence") — lead the people following it, or speak in its channels. What
76
+ * following follows, what a page says it follows (PresenceView `following`), and a request to
77
+ * follow asks to follow (web/src/askfollow.ts). */
78
+ export function personKey(p) {
79
+ return p.agent ? `a:${p.id}` : p.name ? `${p.verified ? "v" : "n"}:${p.name}` : `s:${p.id}`;
80
+ }
81
+ /** Whom a page says it follows, as personKey names them, checked; null where it is none. */
82
+ export function cleanFollowing(x) {
83
+ return typeof x === "string" && x.length <= 200 && /^[avns]:[^\u0000-\u001f\u007f]+$/.test(x) ? x : null;
84
+ }
69
85
  /** the most source windows a reader pins at once (web/src/sources.ts): a few declarations side by
70
86
  * side, not a wall of them */
71
87
  export const MAX_PINNED = 6;
88
+ export const EXPORT_SETTINGS = ["paper", "fontSize", "codeSize", "contents"];
89
+ /** the most characters of a job's failure presence carries: the rest is its job's to tell */
90
+ const EXPORT_ERROR_MAX = 500;
91
+ /** The Export window as a page sent it, checked; null where it is not one. Settings out of range
92
+ * are not carried (readSettings, as POST /api/export reads them), nor a job that is none. */
93
+ export function cleanExport(v) {
94
+ if (!v || typeof v !== "object" || typeof v.open !== "boolean")
95
+ return null;
96
+ const o = v;
97
+ if (!o.open)
98
+ return { open: false };
99
+ const raw = o.settings && typeof o.settings === "object" && !Array.isArray(o.settings) ? o.settings : null;
100
+ const read = raw ? readSettings(Object.fromEntries(EXPORT_SETTINGS.filter((k) => k in raw).map((k) => [k, raw[k]]))) : null;
101
+ const settings = read && "settings" in read ? Object.fromEntries(EXPORT_SETTINGS.map((k) => [k, read.settings[k]])) : null;
102
+ const j = o.job && typeof o.job === "object" ? o.job : null;
103
+ const state = j && ["running", "done", "failed"].includes(j.state) ? j.state : null;
104
+ const id = j && typeof j.id === "string" && /^(?:[0-9a-f]{32})?$/.test(j.id) ? j.id : null;
105
+ // a job is known by its id, but one refused before it was one, or not yet answered
106
+ const job = state && id !== null && (id || state !== "done")
107
+ ? { id, state, ...(state === "failed" && typeof j.error === "string" ? { error: cutShort(j.error.replace(/[\u0000-\u001f\u007f]+/g, " "), EXPORT_ERROR_MAX) } : {}) }
108
+ : null;
109
+ return { open: true, ...(settings ? { settings } : {}), ...(job ? { job } : {}) };
110
+ }
72
111
  /** An artwork's ways of being drawn (ArtworkLook `style`). */
73
112
  export const ART_STYLES = ["board", "cells", "stars"];
74
113
  /** the title's size, in hundredths of the picture's height: the least, the most, the first */
@@ -96,7 +135,7 @@ export function artNameId(kind, s) {
96
135
  return `${kind === "cluster" ? "c" : "d"}:${s}`;
97
136
  }
98
137
  /** The most an artwork's names hidden, its names shown, and its targets chosen each take in what
99
- * presence carries, in bytes of their JSON: a heartbeat is at most 16 KB (server/main.ts), and the
138
+ * presence carries, in bytes of their JSON: a heartbeat is at most 16 KB (server/apptalk.ts), and the
100
139
  * rest of where a reader is has room beside them. Names by selection are kept as what differs from
101
140
  * As shown, so that a few names hidden or added are a few names carried. */
102
141
  export const ART_NAMES_BYTES = 4000;
@@ -129,11 +168,13 @@ export function cleanNames(v, budget, ok = () => true) {
129
168
  export const isArtNameId = (s) => /^[cd]:./.test(s);
130
169
  /** the most pixels a side of an artwork has */
131
170
  export const ART_MAX_SIDE = 16384;
132
- /** A place with no artwork in it: an agent's (ExportSpec decision 19, agents have no artwork). */
133
- export function withoutArtwork(v) {
134
- if (!v || !("artwork" in v))
171
+ /** A place as an agent's is: no artwork (ExportSpec decision 19, agents have none), no Export window
172
+ * (an agent exports through its API), and nobody followed (agents follow nobody; both the owner's
173
+ * decisions of 2026-10-20). */
174
+ export function agentPlace(v) {
175
+ if (!v || !("artwork" in v || "export" in v || "following" in v))
135
176
  return v;
136
- const { artwork: _artwork, ...rest } = v;
177
+ const { artwork: _artwork, export: _export, following: _following, ...rest } = v;
137
178
  return rest;
138
179
  }
139
180
  /** An artwork's settings as given, checked; null where they are not. */
@@ -166,8 +207,12 @@ export function cleanArtwork(v) {
166
207
  const style = one(ART_STYLES, o.style) ?? "board";
167
208
  return { w, h, scheme, theme, background, labels, namesFrom, hiddenNames, shownNames, ruledNames, edges, notes: o.notes, targets, shownTargets, keys, selection: o.selection, source: o.source === true, style, title: cleanTitle(o.title), subtitle: cleanTitle(o.subtitle), titleSize: cleanTitleSize(o.titleSize), footSize: cleanFootSize(o.footSize), border: o.border === true, region: [...r] };
168
209
  }
169
- /** The legend's schemes (CanvasSpec, "Colour schemes"). */
210
+ /** The schemes a picture is drawn in (CanvasSpec, "Colour schemes"; an artwork, ExportSpec decision
211
+ * 19): by kind or by status. */
170
212
  export const SCHEMES = ["kind", "status"];
213
+ /** The legend's schemes, the board's: those, and Mine — the reader's own review (the owner's
214
+ * decision of 2026-10-20), which a picture drawn by the server has nobody to draw for. */
215
+ export const BOARD_SCHEMES = ["kind", "status", "mine"];
171
216
  /** Activity's filters: the kind of event, and whose (web/src/activity.ts). */
172
217
  export const ACTIVITY_KINDS = ["all", "review", "build", "change"];
173
218
  export const ACTIVITY_WHO = ["all", "agents", "people"];
@@ -224,7 +269,7 @@ export function cleanView(v) {
224
269
  const kind = one(ACTIVITY_KINDS, av?.kind), who = one(ACTIVITY_WHO, av?.who);
225
270
  const activity = av && typeof av.open === "boolean" && kind && who ? { open: av.open, kind, who, ...(typeof av.mine === "string" && validName(av.mine) ? { mine: av.mine } : {}) } : null;
226
271
  const lost = o.lostFound && typeof o.lostFound === "object" ? o.lostFound.open : undefined;
227
- const scheme = one(SCHEMES, o.scheme);
272
+ const scheme = one(BOARD_SCHEMES, o.scheme);
228
273
  const pinned = Array.isArray(o.pinned)
229
274
  ? o.pinned
230
275
  .slice(0, MAX_PINNED)
@@ -246,6 +291,7 @@ export function cleanView(v) {
246
291
  view: str(o.view, 300),
247
292
  scope: str(o.scope, 4000),
248
293
  tabs: Array.isArray(o.tabs) ? o.tabs.slice(0, 50).map((t) => str(t, 300)).filter((t) => t !== null) : [],
294
+ ...(cleanFollowing(o.following) ? { following: cleanFollowing(o.following) } : {}),
249
295
  ...(snapshot !== null ? { history: { snapshot } } : {}),
250
296
  ...(o.focus === null || str(o.focus) ? { focus: o.focus } : {}),
251
297
  ...(visitors.length ? { visitors } : {}),
@@ -256,5 +302,6 @@ export function cleanView(v) {
256
302
  ...(typeof o.edges === "boolean" ? { edges: o.edges } : {}),
257
303
  ...(typeof o.linear === "boolean" ? { linear: o.linear } : {}),
258
304
  ...(o.artwork === null ? { artwork: null } : cleanArtwork(o.artwork) ? { artwork: cleanArtwork(o.artwork) } : {}),
305
+ ...(cleanExport(o.export) ? { export: cleanExport(o.export) } : {}),
259
306
  };
260
307
  }
@@ -16,7 +16,7 @@
16
16
  // made of, what a quote of an opinion keeps, a quote of source lines, and where either goes in the
17
17
  // text being written; tested in test/comment.test.ts.
18
18
  /** the longest comment, in UTF-16 units, as the server takes it (server/reviewapi.ts,
19
- * server/agent.ts, `invalid` in shared/review.ts) */
19
+ * server/agentadvice.ts, `invalid` in shared/review.ts) */
20
20
  export const MAX_COMMENT = 10000;
21
21
  /** a quote of an opinion keeps at most this many lines of its comment, and this many characters */
22
22
  export const QUOTE_LINES = 4;