@parcha/pi-browser 0.1.0-beta.18 → 0.1.0-beta.20

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 (87) hide show
  1. package/CHANGELOG.md +5 -0
  2. package/README.md +177 -39
  3. package/dist/coding-agent-local.js +2 -1
  4. package/dist/coding-agent.d.ts +42 -2
  5. package/dist/coding-agent.js +159 -21
  6. package/dist/core/clip.d.ts +31 -0
  7. package/dist/core/clip.js +49 -0
  8. package/dist/core/contract.d.ts +4 -1
  9. package/dist/core/contract.js +40 -7
  10. package/dist/core/custody.d.ts +79 -5
  11. package/dist/core/custody.js +66 -5
  12. package/dist/core/decisions.d.ts +4 -0
  13. package/dist/core/dial.d.ts +7 -0
  14. package/dist/core/dial.js +41 -0
  15. package/dist/core/downloads.d.ts +1 -0
  16. package/dist/core/downloads.js +17 -5
  17. package/dist/core/driving-guard.d.ts +13 -0
  18. package/dist/core/driving-guard.js +61 -0
  19. package/dist/core/driving.d.ts +61 -0
  20. package/dist/core/driving.js +156 -0
  21. package/dist/core/effects.js +33 -13
  22. package/dist/core/evidence.d.ts +3 -1
  23. package/dist/core/failures.d.ts +5 -1
  24. package/dist/core/failures.js +20 -4
  25. package/dist/core/files.d.ts +8 -0
  26. package/dist/core/files.js +74 -0
  27. package/dist/core/find.d.ts +3 -1
  28. package/dist/core/find.js +2 -1
  29. package/dist/core/guard.d.ts +9 -1
  30. package/dist/core/guard.js +7 -2
  31. package/dist/core/host.d.ts +49 -1
  32. package/dist/core/images.d.ts +10 -2
  33. package/dist/core/images.js +4 -4
  34. package/dist/core/lease.d.ts +1 -1
  35. package/dist/core/lease.js +2 -1
  36. package/dist/core/session-control.d.ts +2 -0
  37. package/dist/core/session-control.js +5 -0
  38. package/dist/core/tools.d.ts +70 -4
  39. package/dist/core/tools.js +288 -45
  40. package/dist/core/unanswered.d.ts +3 -0
  41. package/dist/core/unanswered.js +17 -0
  42. package/dist/core/usage.d.ts +2 -0
  43. package/dist/core/usage.js +6 -0
  44. package/dist/core/web.d.ts +1 -1
  45. package/dist/core/web.js +9 -7
  46. package/dist/driver/extension-worker.d.ts +4 -2
  47. package/dist/driver/extension-worker.js +16 -10
  48. package/dist/driver/page-driver.d.ts +8 -0
  49. package/dist/driver/page-driver.js +128 -0
  50. package/dist/driver/stagehand.d.ts +3 -1
  51. package/dist/driver/stagehand.js +40 -66
  52. package/dist/durable.d.ts +16 -4
  53. package/dist/durable.js +415 -82
  54. package/dist/index.d.ts +2 -0
  55. package/dist/index.js +2 -0
  56. package/dist/live-view/index.d.ts +4 -0
  57. package/dist/live-view/index.js +4 -0
  58. package/dist/live-view/protocol.d.ts +152 -0
  59. package/dist/live-view/protocol.js +84 -0
  60. package/dist/live-view/provider.d.ts +6 -0
  61. package/dist/live-view/provider.js +23 -0
  62. package/dist/live-view/server.d.ts +50 -0
  63. package/dist/live-view/server.js +342 -0
  64. package/dist/live-view/stream.d.ts +7 -0
  65. package/dist/live-view/stream.js +388 -0
  66. package/dist/live-view/token.d.ts +6 -0
  67. package/dist/live-view/token.js +13 -0
  68. package/dist/live-view/viewer.d.ts +6 -0
  69. package/dist/live-view/viewer.js +350 -0
  70. package/dist/live-view/ws.d.ts +19 -0
  71. package/dist/live-view/ws.js +176 -0
  72. package/dist/providers/assigned.d.ts +18 -0
  73. package/dist/providers/assigned.js +76 -0
  74. package/dist/providers/cdp-call.js +12 -2
  75. package/dist/providers/cdp.js +37 -11
  76. package/dist/recorder/follow.d.ts +10 -0
  77. package/dist/recorder/follow.js +27 -2
  78. package/dist/recorder/frames.d.ts +7 -0
  79. package/dist/recorder/frames.js +73 -5
  80. package/dist/store.d.ts +22 -3
  81. package/dist/store.js +75 -4
  82. package/dist/testing/backend.d.ts +26 -0
  83. package/dist/testing/backend.js +21 -3
  84. package/dist/testing/driver.d.ts +18 -1
  85. package/dist/testing/driver.js +4 -0
  86. package/dist/web.js +2 -2
  87. package/package.json +10 -2
@@ -0,0 +1,388 @@
1
+ const QUALITY = 60;
2
+ const MAX_WIDTH = 1280;
3
+ const MAX_HEIGHT = 800;
4
+ const COMMAND_MS = 5_000;
5
+ /** A page that has sent no screencast frame this long after it was followed gets one screenshot as its first frame. The stream never activates a tab or touches any page but the one it follows: switching tabs would hide the page the model may be driving. */
6
+ const FIRST_FRAME_MS = 400;
7
+ /** A stand-in that failed (the screenshot errored, timed out or the page had no size yet) is tried again this often, up to STAND_IN_TRIES times in all. */
8
+ const STAND_IN_RETRY_MS = 1_000;
9
+ const STAND_IN_TRIES = 6;
10
+ /** Chrome sends a page's address when it moves but not its title when the document sets it, so the title is asked for at the end of a load and now and then. */
11
+ const TITLE_POLL_MS = 1_500;
12
+ /** A text message is one paste or one typed run: bound it so a viewer cannot make the browser take an unbounded insert. */
13
+ const MAX_TEXT = 100_000;
14
+ const BUTTON_BITS = { left: 1, right: 2, middle: 4 };
15
+ const DIALOG_KINDS = new Set(["alert", "confirm", "prompt", "beforeunload"]);
16
+ /** Why one input or nav message was not delivered: the server tells the viewer (`held`). */
17
+ export class StreamRefusal extends Error {
18
+ reason;
19
+ constructor(reason) {
20
+ super(reason);
21
+ this.reason = reason;
22
+ this.name = "StreamRefusal";
23
+ }
24
+ }
25
+ const finite = (value, limit = 1e6) => typeof value === "number" && Number.isFinite(value) && Math.abs(value) <= limit;
26
+ const modifiers = (value) => (typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 15 ? value : 0);
27
+ const bad = () => { throw new StreamRefusal("bad_message"); };
28
+ export const openStream = (cdpUrl, handlers) => {
29
+ const socket = new WebSocket(cdpUrl);
30
+ let seq = 0;
31
+ let closing = false;
32
+ let current = null;
33
+ /** Every page the browser has: its address and title, and when it was last opened or moved (an arrival counter, not a clock). */
34
+ const pages = new Map();
35
+ let moves = 0;
36
+ const waiting = new Map();
37
+ let announced = "";
38
+ /** The frames each session has sent (screencast frames and stand-ins): Chrome sends a screencast frame only when the page changes, so a still page followed later, or a document navigated to, may stay silent. */
39
+ const framesFrom = new Map();
40
+ const seenFrom = (sessionId) => framesFrom.get(sessionId) ?? 0;
41
+ const post = (method, params = {}, sessionId) => {
42
+ const id = ++seq;
43
+ if (socket.readyState === 1)
44
+ socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
45
+ return id;
46
+ };
47
+ /** The ids of input commands the browser has not answered: a click that opens an alert is not answered until the alert is, so they end when a dialog opens (see below). */
48
+ const inputs = new Set();
49
+ const request = (method, params = {}, sessionId) => new Promise((resolve, reject) => {
50
+ if (socket.readyState !== 1)
51
+ return reject(new Error("the browser's socket is closed"));
52
+ const id = post(method, params, sessionId);
53
+ const isInput = method.startsWith("Input.");
54
+ const timer = setTimeout(() => { waiting.delete(id); inputs.delete(id); reject(new Error(`the browser did not answer ${method}`)); }, COMMAND_MS);
55
+ timer.unref?.();
56
+ waiting.set(id, { resolve: (value) => { inputs.delete(id); resolve(value); }, reject: (error) => { inputs.delete(id); reject(error); }, timer });
57
+ if (isInput)
58
+ inputs.add(id);
59
+ });
60
+ /** Chrome holds the answer to an input command that opened a JS dialog until the dialog is answered, and the dialog's answer comes from the same viewer: the command ends when the dialog opens, or the viewer's next message would wait behind it. */
61
+ const releaseInputs = () => {
62
+ for (const id of [...inputs]) {
63
+ const entry = waiting.get(id);
64
+ if (!entry)
65
+ continue;
66
+ waiting.delete(id);
67
+ clearTimeout(entry.timer);
68
+ entry.resolve(undefined);
69
+ }
70
+ inputs.clear();
71
+ };
72
+ const page = () => {
73
+ const sessionId = current?.sessionId;
74
+ if (!sessionId)
75
+ throw new StreamRefusal("no_page");
76
+ return sessionId;
77
+ };
78
+ /** The viewer is told of the page shown when its address or title changes, and at every change of page. */
79
+ const announce = () => {
80
+ const shown = current ? pages.get(current.targetId) : undefined;
81
+ if (!shown)
82
+ return;
83
+ const key = JSON.stringify([current.targetId, shown.url, shown.title]);
84
+ if (key === announced)
85
+ return;
86
+ announced = key;
87
+ handlers.page({ url: shown.url, title: shown.title });
88
+ };
89
+ /** One screenshot of the page stands in for a frame the screencast has not sent. It is delivered only for a page that has a size (a page not laid out yet answers 0x0) and only while no frame has come from the session since
90
+ * `base`; it answers true when nothing more is to be done (delivered, or a real frame came meanwhile) and false when it should be tried again. */
91
+ const firstFrame = async (sessionId, base) => {
92
+ try {
93
+ const metrics = await request("Page.getLayoutMetrics", {}, sessionId);
94
+ const w = Math.round(Number(metrics?.cssVisualViewport?.clientWidth)) || 0;
95
+ const h = Math.round(Number(metrics?.cssVisualViewport?.clientHeight)) || 0;
96
+ if (!(w > 0 && h > 0))
97
+ return false;
98
+ const shot = await request("Page.captureScreenshot", { format: "jpeg", quality: QUALITY }, sessionId);
99
+ if (closing || current?.sessionId !== sessionId || seenFrom(sessionId) !== base)
100
+ return true;
101
+ if (typeof shot?.data !== "string" || shot.data.length === 0)
102
+ return false;
103
+ framesFrom.set(sessionId, base + 1);
104
+ handlers.frame(Buffer.from(shot.data, "base64"), { w, h }, () => { });
105
+ return true;
106
+ }
107
+ catch {
108
+ return false; /* the page could not be captured this time */
109
+ }
110
+ };
111
+ /** Arms the stand-in for a session: when it has sent no frame FIRST_FRAME_MS from now, one screenshot is delivered, and a failed one is tried again. It is armed when a page is followed and at every main-frame navigation of
112
+ * it, since a new document may be as still as the old. The stream never activates a tab or touches any page but the one it follows. */
113
+ const standIn = (sessionId, tries = 0) => {
114
+ const base = seenFrom(sessionId);
115
+ const timer = setTimeout(() => {
116
+ if (closing || current?.sessionId !== sessionId || seenFrom(sessionId) !== base)
117
+ return;
118
+ void firstFrame(sessionId, base).then((done) => { if (!done && tries + 1 < STAND_IN_TRIES)
119
+ standIn(sessionId, tries + 1); });
120
+ }, tries === 0 ? FIRST_FRAME_MS : STAND_IN_RETRY_MS);
121
+ timer.unref?.();
122
+ };
123
+ const follow = (targetId) => {
124
+ if (current?.targetId === targetId)
125
+ return;
126
+ if (current?.sessionId) {
127
+ post("Page.stopScreencast", {}, current.sessionId);
128
+ post("Target.detachFromTarget", { sessionId: current.sessionId });
129
+ }
130
+ // A dialog of the page left is not the new page's.
131
+ if (current)
132
+ handlers.dialog(null);
133
+ current = { targetId, sessionId: null };
134
+ post("Target.attachToTarget", { targetId, flatten: true });
135
+ announce();
136
+ };
137
+ /** The page's title as the browser holds it now (`Target.getTargetInfo`: no script runs in the page). */
138
+ let asking = false;
139
+ const refreshTitle = () => {
140
+ const shown = current;
141
+ if (!shown || asking || socket.readyState !== 1)
142
+ return;
143
+ asking = true;
144
+ request("Target.getTargetInfo", { targetId: shown.targetId }).then((result) => {
145
+ const info = result?.targetInfo;
146
+ const known = pages.get(shown.targetId);
147
+ if (!info || !known || current?.targetId !== shown.targetId)
148
+ return;
149
+ if (typeof info.title === "string")
150
+ known.title = info.title;
151
+ announce();
152
+ }).catch(() => { }).finally(() => { asking = false; });
153
+ };
154
+ const poll = setInterval(refreshTitle, TITLE_POLL_MS);
155
+ poll.unref?.();
156
+ const choose = () => {
157
+ let best = null;
158
+ for (const [id, shown] of pages) {
159
+ const blank = shown.url === "about:blank" || shown.url === "";
160
+ if (best === null || (best.blank && !blank) || (best.blank === blank && shown.moved > best.moved))
161
+ best = { id, moved: shown.moved, blank };
162
+ }
163
+ if (best)
164
+ follow(best.id);
165
+ };
166
+ socket.onopen = () => { post("Target.setDiscoverTargets", { discover: true }); };
167
+ socket.onmessage = (event) => {
168
+ let message;
169
+ try {
170
+ message = JSON.parse(String(event.data));
171
+ }
172
+ catch {
173
+ return;
174
+ }
175
+ if (message.id !== undefined && waiting.has(message.id)) {
176
+ const entry = waiting.get(message.id);
177
+ waiting.delete(message.id);
178
+ clearTimeout(entry.timer);
179
+ if (message.error)
180
+ entry.reject(new Error(message.error.message ?? "the browser refused"));
181
+ else
182
+ entry.resolve(message.result);
183
+ return;
184
+ }
185
+ const { method, params, sessionId } = message;
186
+ if (!method)
187
+ return;
188
+ try {
189
+ if (method === "Target.targetCreated" && params.targetInfo?.type === "page") {
190
+ pages.set(params.targetInfo.targetId, { url: String(params.targetInfo.url ?? ""), title: String(params.targetInfo.title ?? ""), moved: (moves += 1) });
191
+ choose();
192
+ }
193
+ else if (method === "Target.targetInfoChanged" && params.targetInfo?.type === "page") {
194
+ const info = params.targetInfo;
195
+ const known = pages.get(info.targetId);
196
+ // A page that moved to a new address is the one in use; a new title on the same address is not a move.
197
+ if (!known)
198
+ pages.set(info.targetId, { url: String(info.url ?? ""), title: String(info.title ?? ""), moved: (moves += 1) });
199
+ else {
200
+ if (known.url !== info.url)
201
+ known.moved = (moves += 1);
202
+ known.url = String(info.url ?? "");
203
+ known.title = String(info.title ?? "");
204
+ }
205
+ choose();
206
+ announce();
207
+ }
208
+ else if (method === "Target.attachedToTarget") {
209
+ const shown = current;
210
+ if (!shown || params.targetInfo?.targetId !== shown.targetId) {
211
+ post("Target.detachFromTarget", { sessionId: params.sessionId });
212
+ return;
213
+ }
214
+ shown.sessionId = params.sessionId;
215
+ post("Page.enable", {}, params.sessionId);
216
+ post("Page.startScreencast", { format: "jpeg", quality: QUALITY, maxWidth: MAX_WIDTH, maxHeight: MAX_HEIGHT, everyNthFrame: 1 }, params.sessionId);
217
+ const attached = String(params.sessionId);
218
+ standIn(attached);
219
+ }
220
+ else if (method === "Page.screencastFrame") {
221
+ const ackId = params.sessionId;
222
+ const frameSession = sessionId;
223
+ if (frameSession)
224
+ framesFrom.set(frameSession, seenFrom(frameSession) + 1);
225
+ let acked = false;
226
+ // Called once, by the server after the frame went out or at once to drop it; the browser then sends the next.
227
+ const ack = () => { if (acked)
228
+ return; acked = true; if (frameSession)
229
+ post("Page.screencastFrameAck", { sessionId: ackId }, frameSession); };
230
+ if (!current || frameSession !== current.sessionId || closing) {
231
+ ack();
232
+ return;
233
+ }
234
+ const w = Math.round(Number(params.metadata?.deviceWidth)) || 0;
235
+ const h = Math.round(Number(params.metadata?.deviceHeight)) || 0;
236
+ handlers.frame(Buffer.from(String(params.data), "base64"), { w, h }, ack);
237
+ }
238
+ else if ((method === "Page.loadEventFired" || method === "Page.domContentEventFired") && sessionId === current?.sessionId) {
239
+ refreshTitle();
240
+ }
241
+ else if (method === "Page.frameNavigated" && sessionId === current?.sessionId && !params.frame?.parentId) {
242
+ standIn(sessionId);
243
+ }
244
+ else if (method === "Page.javascriptDialogOpening" && sessionId === current?.sessionId) {
245
+ const kind = String(params.type);
246
+ releaseInputs();
247
+ handlers.dialog({ kind: (DIALOG_KINDS.has(kind) ? kind : "alert"), message: String(params.message ?? ""), ...(typeof params.defaultPrompt === "string" && params.defaultPrompt ? { defaultPrompt: params.defaultPrompt } : {}) });
248
+ }
249
+ else if (method === "Page.javascriptDialogClosed" && sessionId === current?.sessionId) {
250
+ handlers.dialog(null);
251
+ }
252
+ else if (method === "Target.targetDestroyed") {
253
+ pages.delete(params.targetId);
254
+ if (params.targetId === current?.targetId) {
255
+ current = null;
256
+ handlers.dialog(null);
257
+ }
258
+ choose();
259
+ }
260
+ }
261
+ catch { /* a handler that throws must not end the browser's socket */ }
262
+ };
263
+ socket.onerror = () => { };
264
+ socket.onclose = () => {
265
+ clearInterval(poll);
266
+ for (const entry of waiting.values()) {
267
+ clearTimeout(entry.timer);
268
+ entry.reject(new Error("the browser's socket closed"));
269
+ }
270
+ waiting.clear();
271
+ if (!closing)
272
+ handlers.closed();
273
+ };
274
+ const stream = {
275
+ async input(message) {
276
+ const sessionId = page();
277
+ if (message === null || typeof message !== "object")
278
+ return bad();
279
+ if (message.type === "mouse") {
280
+ if (!finite(message.x) || !finite(message.y))
281
+ return bad();
282
+ const button = message.button ?? "left";
283
+ if (!(button in BUTTON_BITS))
284
+ return bad();
285
+ const type = message.action === "down" ? "mousePressed" : message.action === "up" ? "mouseReleased" : message.action === "move" ? "mouseMoved" : bad();
286
+ const clickCount = type === "mouseMoved" ? 0 : Number.isInteger(message.clickCount) && message.clickCount >= 1 && message.clickCount <= 3 ? message.clickCount : 1;
287
+ // The buttons held are the viewer's to say (MouseEvent.buttons, the same bitmask CDP takes): a hover holds none, a drag holds the buttons of the drag. A viewer that does not say gets the old reading
288
+ // for a press (its own button) and none for a move and a release; never "the left button" for a hover.
289
+ if (message.buttons !== undefined && !(Number.isInteger(message.buttons) && message.buttons >= 0 && message.buttons <= 31))
290
+ return bad();
291
+ const held = message.buttons ?? (type === "mousePressed" ? BUTTON_BITS[button] : 0);
292
+ const moveButton = held & BUTTON_BITS.left ? "left" : held & BUTTON_BITS.right ? "right" : held & BUTTON_BITS.middle ? "middle" : "none";
293
+ await request("Input.dispatchMouseEvent", { type, x: message.x, y: message.y, button: type === "mouseMoved" ? moveButton : button, buttons: held, clickCount, modifiers: modifiers(message.modifiers) }, sessionId);
294
+ }
295
+ else if (message.type === "wheel") {
296
+ if (!finite(message.x) || !finite(message.y) || !finite(message.deltaX, 1e5) || !finite(message.deltaY, 1e5))
297
+ return bad();
298
+ await request("Input.dispatchMouseEvent", { type: "mouseWheel", x: message.x, y: message.y, deltaX: message.deltaX, deltaY: message.deltaY, modifiers: modifiers(message.modifiers) }, sessionId);
299
+ }
300
+ else if (message.type === "key") {
301
+ if (typeof message.key !== "string" || message.key.length === 0 || message.key.length > 32 || typeof message.code !== "string" || message.code.length > 32)
302
+ return bad();
303
+ if (message.action !== "down" && message.action !== "up")
304
+ return bad();
305
+ const text = typeof message.text === "string" && message.text.length > 0 && message.text.length <= 8 ? message.text : undefined;
306
+ // A key that makes text is a "keyDown" with that text; one that does not (an arrow, Enter without text, a shortcut) is a "rawKeyDown".
307
+ const type = message.action === "up" ? "keyUp" : text !== undefined ? "keyDown" : "rawKeyDown";
308
+ await request("Input.dispatchKeyEvent", {
309
+ type, key: message.key, code: message.code, modifiers: modifiers(message.modifiers),
310
+ ...(Number.isInteger(message.windowsVirtualKeyCode) && message.windowsVirtualKeyCode >= 0 && message.windowsVirtualKeyCode <= 255 ? { windowsVirtualKeyCode: message.windowsVirtualKeyCode, nativeVirtualKeyCode: message.windowsVirtualKeyCode } : {}),
311
+ ...(type === "keyDown" ? { text, unmodifiedText: text } : {}),
312
+ }, sessionId);
313
+ }
314
+ else if (message.type === "text") {
315
+ if (typeof message.text !== "string" || message.text.length === 0 || message.text.length > MAX_TEXT)
316
+ return bad();
317
+ await request("Input.insertText", { text: message.text }, sessionId);
318
+ }
319
+ else
320
+ return bad();
321
+ },
322
+ async nav(message) {
323
+ const sessionId = page();
324
+ if (message === null || typeof message !== "object" || message.type !== "nav")
325
+ return bad();
326
+ if (message.action === "reload") {
327
+ await request("Page.reload", {}, sessionId);
328
+ return;
329
+ }
330
+ if (message.action === "back") {
331
+ const history = await request("Page.getNavigationHistory", {}, sessionId);
332
+ const entry = history?.entries?.[Number(history?.currentIndex) - 1];
333
+ if (!entry || !Number.isInteger(entry.id))
334
+ return;
335
+ await request("Page.navigateToHistoryEntry", { entryId: entry.id }, sessionId);
336
+ return;
337
+ }
338
+ if (message.action === "url") {
339
+ // The address bar and the host's parser both take about:blank, exactly: the one non-http address a person has a use for, and it runs no script.
340
+ if (message.url === "about:blank") {
341
+ await request("Page.navigate", { url: "about:blank" }, sessionId);
342
+ return;
343
+ }
344
+ // A person types an address: http and https only. A javascript: or data: address runs script in the page while looking like a navigation.
345
+ let url;
346
+ try {
347
+ url = new URL(String(message.url));
348
+ }
349
+ catch {
350
+ return bad();
351
+ }
352
+ if (url.protocol !== "http:" && url.protocol !== "https:")
353
+ return bad();
354
+ await request("Page.navigate", { url: url.href }, sessionId);
355
+ return;
356
+ }
357
+ return bad();
358
+ },
359
+ async dialog(answer) {
360
+ const sessionId = page();
361
+ if (answer === null || typeof answer !== "object" || answer.type !== "dialog" || typeof answer.accept !== "boolean")
362
+ return bad();
363
+ if (answer.promptText !== undefined && (typeof answer.promptText !== "string" || answer.promptText.length > MAX_TEXT))
364
+ return bad();
365
+ await request("Page.handleJavaScriptDialog", { accept: answer.accept, ...(answer.promptText !== undefined ? { promptText: answer.promptText } : {}) }, sessionId);
366
+ },
367
+ close() {
368
+ if (closing)
369
+ return;
370
+ closing = true;
371
+ clearInterval(poll);
372
+ if (current?.sessionId) {
373
+ post("Page.stopScreencast", {}, current.sessionId);
374
+ post("Target.detachFromTarget", { sessionId: current.sessionId });
375
+ }
376
+ for (const entry of waiting.values()) {
377
+ clearTimeout(entry.timer);
378
+ entry.reject(new Error("closed"));
379
+ }
380
+ waiting.clear();
381
+ try {
382
+ socket.close();
383
+ }
384
+ catch { /* already closed */ }
385
+ },
386
+ };
387
+ return stream;
388
+ };
@@ -0,0 +1,6 @@
1
+ /** 256 random bits, base64url. It is a full-control credential for one browser: it lives in memory, in the URL's fragment, and nowhere else. */
2
+ export declare const newToken: () => string;
3
+ /** The path id of a viewer's URL: 128 random bits. It names the session without being able to open it. */
4
+ export declare const newViewerId: () => string;
5
+ /** Constant time whatever the lengths: both sides are hashed first, so neither a wrong token's length nor its prefix shows in the time taken. */
6
+ export declare function tokenMatches(expected: string, given: unknown): boolean;
@@ -0,0 +1,13 @@
1
+ import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
2
+ /** 256 random bits, base64url. It is a full-control credential for one browser: it lives in memory, in the URL's fragment, and nowhere else. */
3
+ export const newToken = () => randomBytes(32).toString("base64url");
4
+ /** The path id of a viewer's URL: 128 random bits. It names the session without being able to open it. */
5
+ export const newViewerId = () => randomBytes(16).toString("base64url");
6
+ /** Constant time whatever the lengths: both sides are hashed first, so neither a wrong token's length nor its prefix shows in the time taken. */
7
+ export function tokenMatches(expected, given) {
8
+ if (typeof given !== "string")
9
+ return false;
10
+ const a = createHash("sha256").update(expected).digest();
11
+ const b = createHash("sha256").update(given).digest();
12
+ return timingSafeEqual(a, b);
13
+ }
@@ -0,0 +1,6 @@
1
+ /** The viewer page and its two static files, served by the live view's server (never an inline script or style: the page's policy is `default-src 'self'`). */
2
+ export declare const viewerAssets: {
3
+ readonly html: string;
4
+ readonly js: string;
5
+ readonly css: string;
6
+ };