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.
- package/dist/assets/tips/phone-fingers.light.mp4 +0 -0
- package/dist/assets/tips/phone-fingers.light.webp +0 -0
- package/dist/assets/tips/tour-agent.webp +0 -0
- package/dist/assets/tips/tour-arrange.webp +0 -0
- package/dist/assets/tips/tour-artwork.webp +0 -0
- package/dist/assets/tips/tour-checks.webp +0 -0
- package/dist/assets/tips/tour-export.webp +0 -0
- package/dist/assets/tips/tour-keys.webp +0 -0
- package/dist/assets/tips/tour-library.webp +0 -0
- package/dist/assets/tips/tour-project.webp +0 -0
- package/dist/assets/tips/tour-review.webp +0 -0
- package/dist/assets/tips/tour-share.webp +0 -0
- package/dist/assets/tips/tour-source.webp +0 -0
- package/dist/assets/tips/tour-target.webp +0 -0
- package/dist/assets/tips/tour-view.webp +0 -0
- package/dist/assets/tips/tour.json +90 -90
- package/dist/assets/tips/tour.webp +0 -0
- package/dist/server/agent.js +2 -2
- package/dist/server/agentadvice.js +16 -3
- package/dist/server/agentfollow.js +32 -4
- package/dist/server/agentviews.js +1 -1
- package/dist/server/app.js +3 -1
- package/dist/server/apptalk.js +21 -4
- package/dist/server/live.js +101 -10
- package/dist/server/mcptools.js +1 -1
- package/dist/server/presence.js +25 -8
- package/dist/server/readonlygate.js +4 -0
- package/dist/server/reviewapi.js +10 -3
- package/dist/shared/board.js +9 -8
- package/dist/shared/collab.js +53 -6
- package/dist/shared/pointer.js +152 -0
- package/dist/shared/query.js +36 -5
- package/dist/shared/review.js +34 -2
- package/dist/shared/sharesnap.js +15 -0
- package/dist/shared/titles.js +4 -0
- package/dist/web/bundle/app.js +1495 -248
- package/dist/web/index.html +4 -0
- package/dist/web/src/canvas.js +16 -14
- package/dist/web/src/highlight.js +8 -3
- package/dist/web/src/reviewqueue.js +52 -10
- package/dist/web/src/status.js +65 -1
- package/dist/web/style.css +121 -7
- package/docs/agent-api/advice.md +4 -1
- package/docs/agent-api/following.md +9 -3
- package/docs/agent-api/views.md +3 -1
- package/package.json +1 -1
package/dist/server/live.js
CHANGED
|
@@ -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.
|
|
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
|
|
330
|
-
* `verified`: the page of someone invited by a personal link (decision
|
|
331
|
-
|
|
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
|
-
|
|
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",
|
|
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",
|
|
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. */
|
package/dist/server/mcptools.js
CHANGED
|
@@ -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
|
},
|
package/dist/server/presence.js
CHANGED
|
@@ -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
|
|
70
|
-
//
|
|
71
|
-
|
|
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
|
|
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
|
package/dist/server/reviewapi.js
CHANGED
|
@@ -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
|
|
251
|
-
* a target marked that is one
|
|
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
|
}
|
package/dist/shared/board.js
CHANGED
|
@@ -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
|
|
105
|
-
*
|
|
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
|
|
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
|
package/dist/shared/collab.js
CHANGED
|
@@ -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
|
|
133
|
-
|
|
134
|
-
|
|
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
|
|
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(
|
|
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
|
+
}
|