@botiverse/porthole 0.9.0 → 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.
Files changed (65) hide show
  1. package/dist/annotate/types.d.ts +21 -7
  2. package/dist/annotate/validate.d.ts +18 -3
  3. package/dist/annotate/validate.js +29 -5
  4. package/dist/bridge/bridge.js +1 -51
  5. package/dist/bridge/unseen.d.ts +18 -0
  6. package/dist/bridge/unseen.js +71 -0
  7. package/dist/check/files.d.ts +2 -0
  8. package/dist/check/files.js +67 -50
  9. package/dist/check/lint.d.ts +8 -1
  10. package/dist/check/lint.js +18 -0
  11. package/dist/check/markup.d.ts +7 -0
  12. package/dist/check/markup.js +49 -0
  13. package/dist/check/page-source.js +1 -1
  14. package/dist/check/scroll.d.ts +100 -0
  15. package/dist/check/scroll.js +1429 -0
  16. package/dist/conformance/behavior.js +107 -68
  17. package/dist/conformance/clipboard.js +16 -14
  18. package/dist/conformance/harness-source.js +1 -1
  19. package/dist/conformance/limits.js +117 -64
  20. package/dist/conformance/probes.js +66 -49
  21. package/dist/conformance/runtime.js +6 -0
  22. package/dist/conformance/served.js +66 -63
  23. package/dist/guide/guide.js +1 -1
  24. package/dist/guide/runtime.js +2 -2
  25. package/dist/host/create-host.js +46 -4
  26. package/dist/index.d.ts +1 -1
  27. package/dist/platform/types.d.ts +4 -2
  28. package/dist/react/frame.d.ts +2 -1
  29. package/dist/runtime/requests.d.ts +5 -0
  30. package/dist/runtime/requests.js +16 -1
  31. package/dist/runtime/types.generated.js +1 -1
  32. package/dist/shell/annotate.d.ts +6 -3
  33. package/dist/shell/annotate.js +474 -104
  34. package/dist/shell/use.js +9 -1
  35. package/docs/ADOPTING.md +99 -1
  36. package/docs/ARCHITECTURE.md +2 -1
  37. package/docs/DECISIONS.md +764 -14
  38. package/docs/DESIGN.md +192 -42
  39. package/docs/THREAT_MODEL.md +109 -27
  40. package/package.json +1 -1
  41. package/src/annotate/types.ts +22 -7
  42. package/src/annotate/validate.ts +32 -6
  43. package/src/bridge/bridge.ts +1 -60
  44. package/src/bridge/unseen.ts +82 -0
  45. package/src/check/files.ts +68 -54
  46. package/src/check/lint.ts +24 -0
  47. package/src/check/markup.ts +53 -0
  48. package/src/check/scroll.ts +1757 -0
  49. package/src/conformance/behavior.ts +221 -69
  50. package/src/conformance/clipboard.ts +44 -14
  51. package/src/conformance/limits.ts +169 -76
  52. package/src/conformance/probes.ts +97 -49
  53. package/src/conformance/runtime.ts +9 -0
  54. package/src/conformance/served.ts +112 -63
  55. package/src/guide/guide.ts +1 -0
  56. package/src/guide/runtime.ts +2 -2
  57. package/src/host/create-host.ts +50 -4
  58. package/src/index.ts +1 -0
  59. package/src/platform/types.ts +4 -2
  60. package/src/react/frame.tsx +2 -1
  61. package/src/runtime/requests.ts +23 -1
  62. package/src/runtime/types.generated.ts +1 -1
  63. package/src/shell/annotate.ts +474 -104
  64. package/src/shell/use.ts +9 -1
  65. package/types/runtime/v1/comments.d.ts +14 -4
package/dist/shell/use.js CHANGED
@@ -131,7 +131,15 @@ export const USE_RUNTIME = String.raw `
131
131
  const METHODS = {
132
132
  user: { get: () => call("user", "get", {}) },
133
133
  comments: {
134
- open: (anchor) => clicked("comments", "comments.open") || call("comments", "open", { anchor: typeof anchor === "string" ? { name: anchor } : record(anchor) }),
134
+ // The draft goes as the page gave it, for the host to refuse what isn't text (P108): read
135
+ // after the click's check, so a getter that throws is a rejection; options that aren't an
136
+ // object send a null draft, refused.
137
+ open: (anchor, options) =>
138
+ clicked("comments", "comments.open") ||
139
+ Promise.resolve().then(() => {
140
+ const draft = options === undefined || options === null ? undefined : typeof options === "object" ? options.draft : null;
141
+ return call("comments", "open", { anchor: typeof anchor === "string" ? { name: anchor } : record(anchor), ...(draft === undefined ? {} : { draft }) });
142
+ }),
135
143
  },
136
144
  clipboard: { copy: (text) => clicked("copyText", "clipboard.copy") || call("clipboard", "copy", { text: String(text) }) },
137
145
  links: { open: (url) => clicked("openLink", "links.open") || call("links", "open", { url: String(url) }) },
package/docs/ADOPTING.md CHANGED
@@ -246,6 +246,102 @@ createHost(config, {
246
246
  Myanmar (Persian's می‌خواهم). Subdivision flags (tag characters) don't. Your own `show` resolves only once that very update is visible: if a later update of
247
247
  the display replaces it before it is drawn, reject, and it doesn't go.
248
248
 
249
+ ### Annotations: comments on a display
250
+
251
+ With `annotate` declared (`capabilities: { annotate: {} }`), a host lets people point at a
252
+ display and keeps its comments beside it ([P053](DECISIONS.md), P104). Everything the frame
253
+ reports is the page's word: a hint where to draw, never a permission. A mark's `count` puts a
254
+ numbered marker beside its words; a click on one is `activated`. A draft, a comment its author
255
+ hasn't posted yet (`kind: "draft"`, P107), is drawn apart: a dashed line and a hollow marker with no
256
+ number, which is clicked and followed as a posted one is.
257
+
258
+ ```js
259
+ display.annotations.show([
260
+ ...comments.map((c) => ({ id: c.markId, anchor: c.anchor, count: c.replies })),
261
+ // Only in the author's own frame: the page can read that these are drafts.
262
+ ...myDrafts.map((d) => ({ id: d.markId, anchor: d.anchor, kind: "draft" })),
263
+ ]);
264
+ display.annotations.start({ elements: false, text: true }); // comment mode: the person selects words
265
+ display.on("annotation", (report) => {
266
+ if (report.type === "selected") composer.openBeside(frame, report.rect, report.anchor);
267
+ if (report.type === "activated") bubble.openBeside(frame, report.rect, report.id);
268
+ if (report.type === "anchored") bubble.follow(report.results);
269
+ });
270
+ ```
271
+
272
+ - **Ids say nothing, and a count only where the page may know it**: the content reads every
273
+ `show`. Who wrote what stays in your view, outside the frame.
274
+ - **Drafts only to their author's frame**: the page reads which marks are drafts (that its viewer
275
+ is writing a comment there), so send a person's drafts only to the frame that person is viewing,
276
+ never one shared with others. A draft's `count` is dropped before the frame (no number is
277
+ drawn), so give a draft's id at random like any other; a `kind` other than `"posted"` or
278
+ `"draft"` throws, as a bad anchor does (React: `onHostError`, kind `"annotations"`). The shell
279
+ is your content server's: upgrade its Porthole first, or an older shell draws a draft as a
280
+ posted mark without a marker.
281
+ - **No drafts to a page that can pass them on**, or accept that it does: a page with the runtime's
282
+ `db` writes and `user` can store who is drafting where (`user.get()` and the marks it is shown)
283
+ for its author and other viewers to read before the draft is posted, and tie the posted comment
284
+ to its author after; origins its config declares for egress (an MCP App's `connectDomains`, an
285
+ `egress` you opened) can carry the same out. Send
286
+ drafts only to pages without such a channel (annotations, `copyText`, `openLink` and the like),
287
+ or accept that the page's author and other viewers can learn of them (THREAT_MODEL §7).
288
+ - **The content chooses when your view opens and where** (it can post `activated` for a mark you
289
+ show on the person's own press in the content, under their pointer, P105), so a view that a
290
+ report opens or moves takes no press of any kind for 500 ms after it appears or moves (no
291
+ `pointerdown`, `pointerup`, `click` or key: menu triggers act on a press, and menu items click
292
+ themselves on a release), ignores a press that began before that, opens beside the frame rather
293
+ than over `rect` where the layout allows, takes no focus, and has no destructive action (resolve,
294
+ delete) one click away. Making it `inert` while it arms does all of the first:
295
+
296
+ ```js
297
+ // Call placed() each time the view appears or moves. For 500 ms it takes nothing (inert: no
298
+ // press, no click, no focus; the pointer reaches what is under it), then only a press or a key
299
+ // that began on it after that.
300
+ function guardPresses(...parts) {
301
+ let timer = 0;
302
+ let fresh = false;
303
+ for (const part of parts) {
304
+ part.addEventListener("pointerdown", () => (fresh = true), true);
305
+ part.addEventListener("keydown", () => (fresh = true), true);
306
+ for (const type of ["pointerup", "mouseup", "touchend", "click"]) {
307
+ part.addEventListener(type, (event) => {
308
+ if (!fresh) {
309
+ event.preventDefault();
310
+ event.stopPropagation();
311
+ }
312
+ }, true);
313
+ }
314
+ }
315
+ const arm = (on) => {
316
+ for (const part of parts) {
317
+ part.inert = on;
318
+ part.style.pointerEvents = on ? "none" : "";
319
+ }
320
+ };
321
+ return {
322
+ placed() {
323
+ fresh = false;
324
+ arm(true);
325
+ clearTimeout(timer);
326
+ timer = setTimeout(() => arm(false), 500);
327
+ },
328
+ };
329
+ }
330
+ ```
331
+
332
+ Menus and popovers the view opens are part of it, but a portaled one (Base UI's, Radix's) is
333
+ drawn outside it, where this guard doesn't reach: give it a container inside the view (both take
334
+ one, `container`), or pass that container to `guardPresses` too, and close it each time the view
335
+ appears or moves.
336
+
337
+ - **Boxes are in the frame's CSS px**, clamped to its viewport (P104): add the frame element's
338
+ position. A frame you scale or transform (a thumbnail, a zoomed preview) needs the box mapped
339
+ through that transform too (`frame.getBoundingClientRect().width / frame.clientWidth` for a
340
+ plain scale), or your view lands off by the difference.
341
+ - **Labels and quotes are the page's text**: shown only as text. Porthole takes out of a label what
342
+ the person can't see; a quote (`exact`) keeps it, to be found again. Hand either to a model only
343
+ as the page's words.
344
+
249
345
  ## 4. Served pages: the host kit
250
346
 
251
347
  ### Local development
@@ -429,7 +525,9 @@ handlers: {
429
525
  db: (args, { viewer, declared, instance, changed, signal }) => myApi.db(instance, viewer, args, declared?.rules, { changed, signal }),
430
526
  artifact: (args, { viewer, instance }) => myApi.artifact(instance, viewer, args), // Refused("conflict") when base moved
431
527
  assets: (args, { viewer, instance }) => myApi.assets(instance, viewer, args),
432
- comments: ({ anchor }) => composer.open(anchor), // true if it opened
528
+ // true if it opened; a draft (P108) is shown whole and editable, posted only on the person's Send,
529
+ // the composer armed for 500 ms (THREAT_MODEL §6)
530
+ comments: ({ anchor, draft }) => composer.open(anchor, { draft }),
433
531
  },
434
532
  // 5. The mount: what this version declared, within what the artifact declares now; null for a
435
533
  // page published before 0.7 (required under a runtime). Before rendering: a stored
@@ -294,7 +294,8 @@ several displays on one page are in [THREAT_MODEL.md](THREAT_MODEL.md).
294
294
  - **Annotations** (`annotate`): the host drives a select mode and marks anchors in
295
295
  the shell; anchors are W3C Web Annotation selectors a host stores with its own
296
296
  comments (P053). A mark may carry a count, drawn as a clickable marker whose click
297
- the host hears and answers with its own UI outside the frame (P104).
297
+ the host hears and answers with its own UI outside the frame (P104), and may be a
298
+ draft, its author's unposted comment, drawn apart with a hollow marker (P107).
298
299
  - **Served content.** A host plugs its own policy and infrastructure into `/server`:
299
300
  who may see what (`authorize`), where tickets live (`TicketStore`: memory, D1),
300
301
  how origins are named (`content.name`, other servers' `reserved` namespaces),