visualproof 0.11.1 → 0.12.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/README.md CHANGED
@@ -46,7 +46,8 @@ It follows the repository's default branch and builds each new commit itself ([F
46
46
  branch](docs/MANUAL.md#following-a-branch)). Or, for the code you are editing:
47
47
  `cd my-lean-project && lake build && visualproof serve .`
48
48
  Add `--claude-oauth <file>`, the file holding the token `claude setup-token` prints, for its own AI
49
- agent on your Claude Code ([how](docs/MANUAL.md#run)).
49
+ agent on your Claude Code ([how](docs/MANUAL.md#run)); `--livekit-url wss://… --livekit-keys <file>`
50
+ for a video call on a [LiveKit](https://docs.livekit.io) server of yours ([how](docs/MANUAL.md#run)).
50
51
 
51
52
  It needs Node, elan and Poppler, and git to follow a branch ([Requirements](#requirements)). On the
52
53
  first visit the page offers a short tour of your own project; `?` holds the tips — a film of a
@@ -85,6 +86,9 @@ project's edge.
85
86
  - **A review together**: approve or comment on each declaration, mark targets and their key
86
87
  declarations, leave notes, link papers to declarations, and see what changed since an opinion was
87
88
  given. Everyone on the page sees it live.
89
+ - **A video call** beside the board (with `--livekit-url`): in a window you move, resize, collapse
90
+ and maximize; a link that brings whoever opens it one press from the call; and *Follow me*, which
91
+ shows everyone the board itself rather than a shared screen.
88
92
  - **AI agents as reviewers**, through a JSON API and an MCP server. They read, advise and annotate
89
93
  under their own names, and their opinions stay advice. Experimentally (`--claude-oauth`), the
90
94
  server runs one of its own on your Claude Code, which everyone on the page talks with, each
@@ -5,7 +5,8 @@
5
5
  // answers each request is by area: who comes in and who they are (server/appaccess.ts), Share
6
6
  // (server/appshare.ts), people on the page with one another (server/apptalk.ts), what pages record
7
7
  // in the site (server/appsite.ts), the agents' API and the exported document (server/appagent.ts),
8
- // the project as pages read it (server/appgraph.ts); server/send.ts sends the answers.
8
+ // the project as pages read it (server/appgraph.ts), the call (server/appcall.ts); server/send.ts
9
+ // sends the answers.
9
10
  import { join } from "node:path";
10
11
  import { WEB, WEBFONTS, bundleDir } from "./pipeline.js";
11
12
  import { Live } from "./live.js";
@@ -33,6 +34,7 @@ import { ask, chat, chatNew, chatStop, pointer, presence } from "./apptalk.js";
33
34
  import { history, layoutUndo, libraryRequest, reviewPost, views } from "./appsite.js";
34
35
  import { agentRoute, exportRoute } from "./appagent.js";
35
36
  import { git, graphParts, hover, source, status } from "./appgraph.js";
37
+ import { callRoute } from "./appcall.js";
36
38
  /** The server's answers to requests: exported so that the tests serve them as the server does. */
37
39
  export class App {
38
40
  live;
@@ -177,11 +179,11 @@ export class App {
177
179
  // it says, and its cookie does from then on; a revoked one's cookie is forgotten, and lets
178
180
  // nobody in
179
181
  if (path.startsWith(INVITE_PATH))
180
- return enter(this, req, res, path.slice(INVITE_PATH.length), path);
182
+ return enter(this, req, res, path.slice(INVITE_PATH.length), path, landing(url));
181
183
  // a read-only link (CollabSpec decision 11, server/readonly.ts): its cookie lets its holder
182
184
  // read, where nothing else lets them in
183
185
  if (path.startsWith(READONLY_PATH))
184
- return enterReadOnly(this, req, res, path.slice(READONLY_PATH.length), path);
186
+ return enterReadOnly(this, req, res, path.slice(READONLY_PATH.length), path, landing(url));
185
187
  const link = this.ids.link(req);
186
188
  // a link that ended: its cookie is forgotten as a page loads, once the page has said so. Not
187
189
  // before: the page's requests meanwhile are told (a browser the key lets in too, as a guest,
@@ -246,8 +248,9 @@ export class App {
246
248
  }
247
249
  else if (a !== "in") {
248
250
  // the link: the browser keeps the cookie, and the key leaves the address (a fragment
249
- // after the key, a place in the page, comes along to "/")
250
- res.writeHead(303, { location: "/", "set-cookie": [a.enter, ...cookies], "cache-control": "no-store", "referrer-policy": "no-referrer" });
251
+ // after the key, a place in the page, comes along to "/"); a call link's `?call` too
252
+ // (CallSpec decision 6)
253
+ res.writeHead(303, { location: landing(url), "set-cookie": [a.enter, ...cookies], "cache-control": "no-store", "referrer-policy": "no-referrer" });
251
254
  return void res.end();
252
255
  }
253
256
  else {
@@ -289,7 +292,8 @@ export class App {
289
292
  // the page, and its workers: the one that lays out the Time Machine's past graphs
290
293
  // (web/src/layoutworker.ts), the one that chooses the overview's edges (web/src/edgeworker.ts),
291
294
  // and pdf.js's, which reads the library's PDFs for the reference window (AttachmentSpec decision 11)
292
- if (/^\/(app|layout|edges|pdfworker)\.js(\.map)?$/.test(path))
295
+ // and the call's own bundle (CallSpec, "As built"), loaded when the call window first opens
296
+ if (/^\/(app|layout|edges|pdfworker|call)\.js(\.map)?$/.test(path))
293
297
  return sendFile(req, res, join(bundleDir(), path.slice(1)));
294
298
  if (path.startsWith("/pdfjs/"))
295
299
  return pdfjsAsset(res, path);
@@ -322,6 +326,9 @@ export class App {
322
326
  return chatStop(this, req, res);
323
327
  if (path === "/api/ask" || path === "/api/ask/answer")
324
328
  return ask(this, req, res, url);
329
+ // the call (CallSpec): a page's token, leaving, ending, removing, inviting
330
+ if (path.startsWith("/api/call/"))
331
+ return callRoute(this, req, res, url);
325
332
  if (path === "/api/agent" || path.startsWith("/api/agent/"))
326
333
  return agentRoute(this, req, res, url);
327
334
  // the views, each a shared board (ViewSpec.md)
@@ -380,5 +387,10 @@ export class App {
380
387
  }
381
388
  }
382
389
  }
390
+ /** Where a link that lets someone in goes on to: the page, with `?call` where the link had it — a
391
+ * call link opens the call's pre-join (CallSpec decision 6). */
392
+ export function landing(url) {
393
+ return url.searchParams.has("call") ? "/?call" : "/";
394
+ }
383
395
  /** an artwork's font file (assets/webfonts/) */
384
396
  const FONT_PATH = /^\/fonts\/(source-sans-3|source-serif-4|jost)-[a-z-]+\.woff2$/;
@@ -12,10 +12,10 @@ import { sendJson, sendText } from "./send.js";
12
12
  * any address nobody was given. On a server with a key, a browser is shown the page of a link
13
13
  * that does not open the site instead (CollabSpec decision 7), which says neither which it was
14
14
  * nor who revoked it — unless the key or a link of its own lets it in, and it may be told. */
15
- export function enter(app, req, res, token, path) {
15
+ export function enter(app, req, res, token, path, to = "/") {
16
16
  const c = app.ids.header ? null : app.live.invites.check(token);
17
17
  if (c && "ok" in c) {
18
- res.writeHead(303, { location: "/", "set-cookie": app.live.invites.cookie(c.ok), "cache-control": "no-store", "referrer-policy": "no-referrer" });
18
+ res.writeHead(303, { location: to, "set-cookie": app.live.invites.cookie(c.ok), "cache-control": "no-store", "referrer-policy": "no-referrer" });
19
19
  return void res.end();
20
20
  }
21
21
  if (app.access && asksForPage(req, path) && (!c || !letIn(app, req)))
@@ -29,10 +29,10 @@ export function enter(app, req, res, token, path) {
29
29
  * (a fragment) comes along. A revoked link says so; anything else, and any link on a server
30
30
  * open to all or behind a sign-in, which have none, is answered as an address nobody was given;
31
31
  * to a browser, on a server with a key, as a personal link's (enter). */
32
- export function enterReadOnly(app, req, res, token, path) {
32
+ export function enterReadOnly(app, req, res, token, path, to = "/") {
33
33
  const c = app.access && !app.ids.header ? app.live.readOnly.check(token) : null;
34
34
  if (c && "ok" in c) {
35
- res.writeHead(303, { location: "/", "set-cookie": app.live.readOnly.cookie(c.ok.id), "cache-control": "no-store", "referrer-policy": "no-referrer" });
35
+ res.writeHead(303, { location: to, "set-cookie": app.live.readOnly.cookie(c.ok.id), "cache-control": "no-store", "referrer-policy": "no-referrer" });
36
36
  return void res.end();
37
37
  }
38
38
  if (app.access && asksForPage(req, path) && (!c || !letIn(app, req)))
@@ -53,8 +53,10 @@ export function identityGet(app, req, res, link, reader) {
53
53
  const person = app.ids.person(req);
54
54
  const holder = app.ids.taken(req);
55
55
  const ended = link && "ended" in link ? link : null;
56
+ // a read-only reader is told whether their link joins the call (CallSpec decision 4)
57
+ const call = reader !== undefined && reader !== "public" && app.live.call !== null && !!app.live.readOnly.get(reader)?.call;
56
58
  if (reader !== undefined)
57
- return sendJson(res, { mode: app.ids.mode, name: null, readOnly: { by: reader === "public" ? "public" : "link" } });
59
+ return sendJson(res, { mode: app.ids.mode, name: null, readOnly: { by: reader === "public" ? "public" : "link", ...(call ? { call: true } : {}) } });
58
60
  return sendJson(res, {
59
61
  mode: app.ids.mode,
60
62
  name: app.ids.who(req),
@@ -0,0 +1,118 @@
1
+ // The call (the routes of server/app.ts; CallSpec, server/call.ts): a page's token for the call, and
2
+ // what someone in it does — leave, end it for everyone, remove a participant, invite someone here.
3
+ // Each request names the page's event stream by its secret (`hello`), as a heartbeat does: the call
4
+ // is the page's, not the browser's. Everyone let in fully joins and acts as an equal (CallSpec
5
+ // decision 3); a read-only reader joins only by a read-only link that joins the call, and does
6
+ // nothing to anyone else (decision 4); agents have no place in a call.
7
+ import { CALL_TAB } from "../shared/call.js";
8
+ import { invalidPersonName, taken } from "./invites.js";
9
+ import { sendJson } from "./send.js";
10
+ /** What a page is told where the call's server does not answer: nothing of where it is. */
11
+ const UNAVAILABLE = "The call's server does not answer now: try again in a moment. Whoever runs this server finds why in its log.";
12
+ export async function callRoute(app, req, res, url) {
13
+ const call = app.live.call;
14
+ // without --livekit-url there is no call (CallSpec decision 1)
15
+ if (!call)
16
+ return sendJson(res, { error: "not found" }, 404);
17
+ if (req.method !== "POST")
18
+ return sendJson(res, { error: `${url.pathname} answers POST.` }, 405);
19
+ if (app.ids.kind(req) === "agent")
20
+ return sendJson(res, { error: "Agents have no place in a call." }, 403);
21
+ const r = await app.json(req, 4096);
22
+ if (r.error !== undefined)
23
+ return sendJson(res, { error: `The body is ${r.error}.` }, 400);
24
+ const b = (r.body && typeof r.body === "object" ? r.body : {});
25
+ const page = typeof b.token === "string" ? app.live.callPage(b.token) : null;
26
+ if (!page)
27
+ return sendJson(res, { error: "This request is not from an open event stream of this page's: it is sent with the token the stream says hello with.", stream: false }, 403);
28
+ const reader = app.readOnlyOf.get(req);
29
+ // the request and the stream it names are one reader's, read-only or not: a browser that holds
30
+ // both kinds of cookie speaks for each of its pages as that page was let in
31
+ if ((reader !== undefined) !== (page.readOnly !== null))
32
+ return sendJson(res, { error: "This request is not from that page's way in: reload the page.", stream: false }, 403);
33
+ // what a page that leaves sends as it goes: nothing kept out
34
+ if (url.pathname === "/api/call/leave") {
35
+ await call.leave(page.token);
36
+ return sendJson(res, { ok: true });
37
+ }
38
+ if (url.pathname === "/api/call/token") {
39
+ // in a call one is seen (CallSpec decision 3)
40
+ if (page.private || app.ids.privateOf(req) !== null)
41
+ return sendJson(res, { error: "You are private: in a call everyone sees you. Go visible (the menu under your name) to join.", private: true }, 409);
42
+ let name;
43
+ let link = null;
44
+ if (reader !== undefined) {
45
+ // a read-only reader joins by a read-only link that joins the call, under a name they give
46
+ // (CallSpec decision 4); --public's readers have none
47
+ const by = page.readOnly;
48
+ const l = by === "public" ? null : app.live.readOnly.get(by);
49
+ if (!l?.call || l.revoked)
50
+ return sendJson(res, { error: by === "public" ? "Whoever reads by the address alone has no call: a read-only link made to join the call has." : "This read-only link does not join the call: whoever made it can switch that, in Share.", readOnly: true }, 403);
51
+ const bad = invalidPersonName(b.name);
52
+ if (bad)
53
+ return sendJson(res, { error: bad, who: true }, 400);
54
+ name = b.name.trim();
55
+ const holder = app.live.invites.holder(name);
56
+ if (holder)
57
+ return sendJson(res, { error: taken(holder), who: true, taken: true }, 409);
58
+ link = by;
59
+ }
60
+ else {
61
+ const me = app.ids.who(req);
62
+ if (!me)
63
+ return sendJson(res, app.nameless(req, "a call shows everyone in it by name"), 401);
64
+ name = me;
65
+ }
66
+ if (typeof b.tab !== "string" || !CALL_TAB.test(b.tab))
67
+ return sendJson(res, { error: "tab is what this page's tab calls itself in the call: 16 to 64 letters, digits, _ and -." }, 400);
68
+ const wait = call.allow(`t:${page.token}`);
69
+ if (wait)
70
+ return sendJson(res, { error: `Too many at once: wait ${wait} s.`, retryAfter: wait }, 429, { "retry-after": String(wait) });
71
+ // LiveKit did not answer the last time it was asked: asked again, and a token only where it does
72
+ if (call.unavailable !== null)
73
+ await call.look();
74
+ if (call.unavailable !== null)
75
+ return sendJson(res, { error: UNAVAILABLE, unavailable: true }, 503);
76
+ return sendJson(res, call.give(page, b.tab, name, link));
77
+ }
78
+ // the rest is for someone in the call, let in fully: a read-only reader does nothing to anyone
79
+ // else (CallSpec decision 4)
80
+ if (reader !== undefined)
81
+ return sendJson(res, { error: "This page is read-only: in the call it joins and leaves, and nothing else.", readOnly: true }, 403);
82
+ const mine = call.inCall(page.token);
83
+ if (!mine)
84
+ return sendJson(res, { error: "Only someone in the call does that.", inCall: false }, 403);
85
+ const me = app.ids.who(req) ?? page.name;
86
+ try {
87
+ if (url.pathname === "/api/call/end") {
88
+ await call.end(me);
89
+ return sendJson(res, { ok: true });
90
+ }
91
+ if (url.pathname === "/api/call/remove") {
92
+ if (typeof b.identity !== "string")
93
+ return sendJson(res, { error: "identity is a participant's, as the call lists them." }, 400);
94
+ if (!(await call.remove(b.identity, me)))
95
+ return sendJson(res, { error: "There is no such participant in the call." }, 404);
96
+ return sendJson(res, { ok: true });
97
+ }
98
+ }
99
+ catch (e) {
100
+ // what LiveKit answered, and where it is, are the server's log's, not the page's
101
+ console.error(`call: ${url.pathname}: ${e instanceof Error ? e.message : String(e)}`);
102
+ return sendJson(res, { error: UNAVAILABLE, unavailable: true }, 503);
103
+ }
104
+ if (url.pathname === "/api/call/invite") {
105
+ if (typeof b.to !== "string")
106
+ return sendJson(res, { error: "to is a reader's id, as presence lists them." }, 400);
107
+ const wait = call.allow(`i:${page.token}`);
108
+ if (wait)
109
+ return sendJson(res, { error: `Too many at once: wait ${wait} s.`, retryAfter: wait }, 429, { "retry-after": String(wait) });
110
+ const done = call.invite(b.to, me ?? "Someone");
111
+ if (done === "none")
112
+ return sendJson(res, { error: "There is nobody here by that id: they left, or went private." }, 404);
113
+ if (done === "in")
114
+ return sendJson(res, { error: "They are in the call already." }, 409);
115
+ return sendJson(res, { ok: true });
116
+ }
117
+ return sendJson(res, { error: "not found" }, 404);
118
+ }
@@ -167,9 +167,11 @@ async function myLink(app, req, res, path) {
167
167
  res.setHeader("set-cookie", [...(Array.isArray(set) ? set : set === undefined ? [] : [String(set)]), invites.cookie(made.record)]);
168
168
  return sendJson(res, { invite: Invites.info(made.record), link: `${address}${INVITE_PATH}${made.token}` });
169
169
  }
170
- /** Read-only links (CollabSpec decision 11), for people: every link (GET), a new one (POST), and
171
- * revoking one (POST …/revoke). Anyone let in may make one; revoking needs a name, which Share
172
- * says beside the link. A server open to all, or behind a sign-in, has none. */
170
+ /** Read-only links (CollabSpec decision 11), for people: every link (GET), a new one (POST
171
+ * {call?}), revoking one (POST …/revoke), and whether one joins the call (POST …/call {id, call};
172
+ * CallSpec decision 4: a link that stops joining it takes its holders out of the call). Anyone let
173
+ * in may make one; revoking needs a name, which Share says beside the link. A server open to all,
174
+ * or behind a sign-in, has none. */
173
175
  export async function shareReadOnly(app, req, res, url) {
174
176
  if (app.ids.kind(req) === "agent")
175
177
  return sendJson(res, { error: "Read-only links are for people: an agent cannot make, list or revoke them." }, 403);
@@ -195,8 +197,29 @@ export async function shareReadOnly(app, req, res, url) {
195
197
  return sendJson(res, { error: "There is no such read-only link in force." }, 404);
196
198
  return sendJson(res, { ok: true, links: list() });
197
199
  }
200
+ if (path === "/api/share/readonly/call") {
201
+ const call = app.live.call;
202
+ if (!call)
203
+ return sendJson(res, { error: "This server has no call." }, 404);
204
+ const r = await app.json(req, 4096);
205
+ if (r.error !== undefined)
206
+ return sendJson(res, { error: `The body is ${r.error}.` }, 400);
207
+ const b = (r.body ?? {});
208
+ if (typeof b.id !== "string" || typeof b.call !== "boolean")
209
+ return sendJson(res, { error: "Say which link (id) and whether it joins the call (call: true or false)." }, 400);
210
+ if (!links.setCall(b.id, b.call))
211
+ return sendJson(res, { error: "There is no such read-only link in force." }, 404);
212
+ if (!b.call)
213
+ call.cutLink(b.id);
214
+ return sendJson(res, { ok: true, links: list() });
215
+ }
198
216
  if (path !== "/api/share/readonly")
199
217
  return sendJson(res, { error: "not found" }, 404);
200
- const made = links.create(me);
218
+ const r = await app.json(req, 4096);
219
+ if (r.error !== undefined)
220
+ return sendJson(res, { error: `The body is ${r.error}.` }, 400);
221
+ // a link made to join the call, where the server has one (CallSpec decision 4)
222
+ const joins = r.body?.call === true && app.live.call !== null;
223
+ const made = links.create(me, Date.now(), joins);
201
224
  return sendJson(res, { made: { ...made, link: `${address}${made.path}` }, links: list() });
202
225
  }