@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.
- package/dist/annotate/types.d.ts +21 -7
- package/dist/annotate/validate.d.ts +18 -3
- package/dist/annotate/validate.js +29 -5
- package/dist/bridge/bridge.js +1 -51
- package/dist/bridge/unseen.d.ts +18 -0
- package/dist/bridge/unseen.js +71 -0
- package/dist/check/files.d.ts +2 -0
- package/dist/check/files.js +67 -50
- package/dist/check/lint.d.ts +8 -1
- package/dist/check/lint.js +18 -0
- package/dist/check/markup.d.ts +7 -0
- package/dist/check/markup.js +49 -0
- package/dist/check/page-source.js +1 -1
- package/dist/check/scroll.d.ts +100 -0
- package/dist/check/scroll.js +1429 -0
- package/dist/conformance/behavior.js +107 -68
- package/dist/conformance/clipboard.js +16 -14
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/limits.js +117 -64
- package/dist/conformance/probes.js +66 -49
- package/dist/conformance/runtime.js +6 -0
- package/dist/conformance/served.js +66 -63
- package/dist/guide/guide.js +1 -1
- package/dist/guide/runtime.js +2 -2
- package/dist/host/create-host.js +46 -4
- package/dist/index.d.ts +1 -1
- package/dist/platform/types.d.ts +4 -2
- package/dist/react/frame.d.ts +2 -1
- package/dist/runtime/requests.d.ts +5 -0
- package/dist/runtime/requests.js +16 -1
- package/dist/runtime/types.generated.js +1 -1
- package/dist/shell/annotate.d.ts +6 -3
- package/dist/shell/annotate.js +474 -104
- package/dist/shell/use.js +9 -1
- package/docs/ADOPTING.md +99 -1
- package/docs/ARCHITECTURE.md +2 -1
- package/docs/DECISIONS.md +764 -14
- package/docs/DESIGN.md +192 -42
- package/docs/THREAT_MODEL.md +109 -27
- package/package.json +1 -1
- package/src/annotate/types.ts +22 -7
- package/src/annotate/validate.ts +32 -6
- package/src/bridge/bridge.ts +1 -60
- package/src/bridge/unseen.ts +82 -0
- package/src/check/files.ts +68 -54
- package/src/check/lint.ts +24 -0
- package/src/check/markup.ts +53 -0
- package/src/check/scroll.ts +1757 -0
- package/src/conformance/behavior.ts +221 -69
- package/src/conformance/clipboard.ts +44 -14
- package/src/conformance/limits.ts +169 -76
- package/src/conformance/probes.ts +97 -49
- package/src/conformance/runtime.ts +9 -0
- package/src/conformance/served.ts +112 -63
- package/src/guide/guide.ts +1 -0
- package/src/guide/runtime.ts +2 -2
- package/src/host/create-host.ts +50 -4
- package/src/index.ts +1 -0
- package/src/platform/types.ts +4 -2
- package/src/react/frame.tsx +2 -1
- package/src/runtime/requests.ts +23 -1
- package/src/runtime/types.generated.ts +1 -1
- package/src/shell/annotate.ts +474 -104
- package/src/shell/use.ts +9 -1
- 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
|
-
|
|
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
|
-
|
|
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
|
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -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),
|