visualproof 0.7.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 (46) hide show
  1. package/dist/assets/tips/phone-fingers.light.mp4 +0 -0
  2. package/dist/assets/tips/phone-fingers.light.webp +0 -0
  3. package/dist/assets/tips/tour-agent.webp +0 -0
  4. package/dist/assets/tips/tour-arrange.webp +0 -0
  5. package/dist/assets/tips/tour-artwork.webp +0 -0
  6. package/dist/assets/tips/tour-checks.webp +0 -0
  7. package/dist/assets/tips/tour-export.webp +0 -0
  8. package/dist/assets/tips/tour-keys.webp +0 -0
  9. package/dist/assets/tips/tour-library.webp +0 -0
  10. package/dist/assets/tips/tour-project.webp +0 -0
  11. package/dist/assets/tips/tour-review.webp +0 -0
  12. package/dist/assets/tips/tour-share.webp +0 -0
  13. package/dist/assets/tips/tour-source.webp +0 -0
  14. package/dist/assets/tips/tour-target.webp +0 -0
  15. package/dist/assets/tips/tour-view.webp +0 -0
  16. package/dist/assets/tips/tour.json +90 -90
  17. package/dist/assets/tips/tour.webp +0 -0
  18. package/dist/server/agent.js +2 -2
  19. package/dist/server/agentadvice.js +16 -3
  20. package/dist/server/agentfollow.js +32 -4
  21. package/dist/server/agentviews.js +1 -1
  22. package/dist/server/app.js +3 -1
  23. package/dist/server/apptalk.js +21 -4
  24. package/dist/server/live.js +101 -10
  25. package/dist/server/mcptools.js +1 -1
  26. package/dist/server/presence.js +25 -8
  27. package/dist/server/readonlygate.js +4 -0
  28. package/dist/server/reviewapi.js +10 -3
  29. package/dist/shared/board.js +9 -8
  30. package/dist/shared/collab.js +53 -6
  31. package/dist/shared/pointer.js +152 -0
  32. package/dist/shared/query.js +36 -5
  33. package/dist/shared/review.js +34 -2
  34. package/dist/shared/sharesnap.js +15 -0
  35. package/dist/shared/titles.js +4 -0
  36. package/dist/web/bundle/app.js +1495 -248
  37. package/dist/web/index.html +4 -0
  38. package/dist/web/src/canvas.js +16 -14
  39. package/dist/web/src/highlight.js +8 -3
  40. package/dist/web/src/reviewqueue.js +52 -10
  41. package/dist/web/src/status.js +65 -1
  42. package/dist/web/style.css +121 -7
  43. package/docs/agent-api/advice.md +4 -1
  44. package/docs/agent-api/following.md +9 -3
  45. package/docs/agent-api/views.md +3 -1
  46. 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";
@@ -314,7 +315,7 @@ export class Live {
314
315
  return;
315
316
  }
316
317
  this.send("presence", this.presence.list());
317
- this.send("private", { count: this.presence.privateCount() });
318
+ this.sendPrivate();
318
319
  this.presenceTimer = setTimeout(() => {
319
320
  this.presenceTimer = null;
320
321
  if (this.presenceDirty) {
@@ -324,11 +325,54 @@ export class Live {
324
325
  }, PRESENCE_EVERY);
325
326
  this.presenceTimer.unref?.();
326
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
+ }
327
370
  /** A page's heartbeat, by the secret its stream was given: false when no open stream has it (a
328
371
  * stream that closed, a guess), and nothing changes. A private page's (`priv`, CollabSpec
329
- * decision 8) is counted and nothing more is kept of it: not its name, not where it is.
330
- * `verified`: the page of someone invited by a personal link (decision 9). */
331
- 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) {
332
376
  const s = typeof token === "string" ? this.byToken.get(token) : undefined;
333
377
  if (!s)
334
378
  return false;
@@ -336,14 +380,58 @@ export class Live {
336
380
  // of the channels its stream is sent (CollabSpec decision 13)
337
381
  if (s.readOnly === null)
338
382
  s.name = who;
339
- 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) {
340
386
  this.rename(s, priv, name, view, idle, verified);
387
+ if (priv && following)
388
+ this.presence.beatPrivate(s.id, following);
389
+ }
341
390
  else if (priv)
342
- this.presence.beatPrivate(s.id);
391
+ this.presence.beatPrivate(s.id, following);
343
392
  else
344
393
  this.presence.beat(s.id, name, view, idle, false, verified);
345
394
  return true;
346
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
+ }
347
435
  /** A page went private, or showed itself again (CollabSpec decision 8): its stream gets a new
348
436
  * public id, so that nothing the others were told under one id — where the page was, under its
349
437
  * name; the `from` of what it arranged — ties it to what they are told under the other. The page
@@ -368,7 +456,7 @@ export class Live {
368
456
  }
369
457
  this.presence.renamed(old, s.id, priv, name, view, idle, verified);
370
458
  this.write(s.res, "presence", this.presence.list());
371
- this.write(s.res, "private", { count: this.presence.privateCount() });
459
+ this.write(s.res, "private", this.privateNow(s));
372
460
  }
373
461
  /** The file of a module of the graph on show, relative to the project (meta.modules): the only
374
462
  * modules whose source is served or handed to Lean. Undefined when the graph has no such module
@@ -1323,7 +1411,7 @@ export class Live {
1323
1411
  connection: "keep-alive",
1324
1412
  });
1325
1413
  res.write("retry: 2000\n\n");
1326
- 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 };
1327
1415
  this.streams.set(res, st);
1328
1416
  this.byToken.set(st.token, st);
1329
1417
  this.presence.open(st.id);
@@ -1332,7 +1420,7 @@ export class Live {
1332
1420
  if (this.updateStatus)
1333
1421
  this.write(res, "updates", this.updateStatus(st.toldAll));
1334
1422
  this.write(res, "presence", this.presence.list());
1335
- this.write(res, "private", { count: this.presence.privateCount() });
1423
+ this.write(res, "private", this.privateNow(st));
1336
1424
  this.write(res, "people", this.invites.people());
1337
1425
  // the views as they are: a page that was away (a restart, a lost connection) catches up, and
1338
1426
  // reads again the boards it has open
@@ -1452,6 +1540,9 @@ export class Live {
1452
1540
  // what its page was asked goes unanswered, and what it asked is withdrawn
1453
1541
  this.asks.closed(st.token);
1454
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();
1455
1546
  }
1456
1547
  }
1457
1548
  /** The importable modules nothing else importable imports: importing them imports the rest. */
@@ -58,7 +58,7 @@ export const TOOLS = [
58
58
  },
59
59
  {
60
60
  name: "companion",
61
- about: "Who is on the page now and where each one looks (view, selection, the declaration in their panel, source windows); with wait, the answer comes when someone comes, goes or moves.",
61
+ about: "Who is on the page now and where each one looks (view, selection, the declaration in their panel, source windows), and who follows you; with wait, the answer comes when someone comes, goes or moves.",
62
62
  call: { method: "GET", path: "/api/agent/companion" },
63
63
  args: { wait: int("seconds to wait for a change (at most 60)"), since: int("the rev of an earlier answer") },
64
64
  },
@@ -22,6 +22,12 @@
22
22
  // afresh when it goes private and when it shows itself again (server/live.ts), so its entries under
23
23
  // either id say nothing of the other.
24
24
  //
25
+ // Who follows whom (the owner's decision of 2026-10-20): a listed page says it in its place
26
+ // (`following`, as shared/collab.ts personKey names the person followed), which every page reads; a
27
+ // private page says it alone, and is counted for the person it follows (`privateFollowers`), which
28
+ // only that person's pages are told (server/live.ts). A read-only page says nothing, and is seen by
29
+ // nobody (CollabSpec decision 11); an agent follows nobody.
30
+ //
25
31
  // What an agent asks to follow the people it helps (GET /api/agent/companion) waits for the list to
26
32
  // change: `rev` counts the changes that matter to it — someone came, went, moved, went idle, an
27
33
  // agent went offline or came back — and leaves out a camera that moved, which a page reports
@@ -66,9 +72,11 @@ export class Presence {
66
72
  notify() {
67
73
  const list = this.list();
68
74
  this.send(list);
69
- // neither a camera that pans nor what an agent does while online is a move; an agent going
70
- // offline or coming back is, and so is a private reader coming or going
71
- const sig = JSON.stringify([this.privateCount(), list.map((p) => ({ ...p, view: p.view ? { ...p.view, cam: null } : null, talk: p.talk ? p.talk.state === "offline" : undefined }))]);
75
+ // neither a camera that pans nor what an agent does while online is a move, nor whom a page
76
+ // follows but where it is an agent, which that agent is told (its companion's `followedBy`); an
77
+ // agent going offline or coming back is, and so is a private reader coming or going
78
+ const agents = (f) => (f?.startsWith("a:") ? f : undefined);
79
+ const sig = JSON.stringify([this.privateCount(), [...this.privateFollowers()].filter(([k]) => k.startsWith("a:")), list.map((p) => ({ ...p, view: p.view ? { ...p.view, cam: null, following: agents(p.view.following) } : null, talk: p.talk ? p.talk.state === "offline" : undefined }))]);
72
80
  if (sig === this.lastSig)
73
81
  return;
74
82
  this.lastSig = sig;
@@ -105,16 +113,25 @@ export class Presence {
105
113
  if (!same)
106
114
  this.notify();
107
115
  }
108
- /** A private page's heartbeat (CollabSpec decision 8): it is here, and that is all that is kept
109
- * of it — no name, no place, never idle. */
110
- beatPrivate(id) {
116
+ /** A private page's heartbeat (CollabSpec decision 8): it is here, and whom it follows, and that
117
+ * is all that is kept of it — no name, no place, never idle. */
118
+ beatPrivate(id, following = null) {
111
119
  if (this.closed.has(id))
112
120
  return;
113
121
  const was = this.sessions.get(id);
114
- this.sessions.set(id, { name: null, view: null, idle: false, seen: Date.now(), agent: false, private: true });
115
- if (!was?.private)
122
+ this.sessions.set(id, { name: null, view: null, idle: false, seen: Date.now(), agent: false, private: true, ...(following ? { following } : {}) });
123
+ if (!was?.private || was.following !== (following ?? undefined))
116
124
  this.notify();
117
125
  }
126
+ /** How many private pages follow each person, by personKey: what that person's pages alone are
127
+ * told (server/live.ts), never who. */
128
+ privateFollowers() {
129
+ const out = new Map();
130
+ for (const e of this.sessions.values())
131
+ if (e.private && e.following)
132
+ out.set(e.following, (out.get(e.following) ?? 0) + 1);
133
+ return out;
134
+ }
118
135
  /** A page named afresh as it went private or showed itself again (server/live.ts): its entry under
119
136
  * `old` goes, and comes back under `id` — counted, or listed with its name and place — as one
120
137
  * change, so that no list goes out with the page under both ids, or under neither. */
@@ -30,6 +30,10 @@ export function readOnlyAllows(method, path) {
30
30
  // the printed document of a view as it is shared (bounded below)
31
31
  if (method === "POST" && path === "/api/export")
32
32
  return true;
33
+ // whom the page follows, so as to be sent the pointers of its room (the owner's decisions of
34
+ // 2026-10-20): its own pointer is relayed to nobody, and it is counted nowhere
35
+ if (method === "POST" && path === "/api/pointer")
36
+ return true;
33
37
  return false;
34
38
  }
35
39
  /** Whether Lean's answer is what it says in the end, to be kept for the build: not a failure, nor
@@ -20,6 +20,12 @@
20
20
  // nothing: a declaration gone from the graph, or a file changed since compiled, keeps what was said
21
21
  // of it withdrawable.
22
22
  //
23
+ // Nobody approves twice (ReviewSpec decision 1, the owner's decision of 2026-10-20): an approval of
24
+ // the present version by someone whose current opinion there is an approval of it already — their
25
+ // own, the person's they speak for, an agent's advice — writes nothing, and is answered
26
+ // `{ok, unchanged: true}` (shared/review.ts, noChange); once a change has made it stale, approving
27
+ // again is recorded.
28
+ //
23
29
  // Every refusal is an answer: a status, and words that say what to do instead.
24
30
  import { readFileSync } from "node:fs";
25
31
  import { join } from "node:path";
@@ -247,10 +253,11 @@ export class ReviewApi {
247
253
  return appended(this.world.review.append(who, op, this.world.project.toolchain));
248
254
  }
249
255
  }
250
- /** An append's result as an answer: the change and the event written (none where nothing changed:
251
- * a target marked that is one), or why nothing was written. */
256
+ /** An append's result as an answer: the change and the event written, or `unchanged` where nothing
257
+ * changed (a target marked that is one, an approval of the version one approved already: ReviewSpec
258
+ * decision 1), or why nothing was written. */
252
259
  export function appended(r) {
253
260
  if ("status" in r)
254
261
  return { status: r.status, body: { error: r.error, hint: r.status === 409 ? "Mend that line of the log by hand (or ask its writer to); VisualProof never rewrites a log." : "Send {op, …}." } };
255
- return { status: 200, body: { ok: true, change: r.change, ...(r.change ? { event: r.event } : {}) } };
262
+ return { status: 200, body: { ok: true, change: r.change, ...(r.change ? { event: r.event } : { unchanged: true }) } };
256
263
  }
@@ -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 */
@@ -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
  }
@@ -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
+ }