@botiverse/porthole 0.14.13 → 0.14.15
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/CHANGELOG.md +63 -2
- package/dist/annotate/types.d.ts +47 -4
- package/dist/annotate/types.js +7 -1
- package/dist/annotate/validate.d.ts +17 -1
- package/dist/annotate/validate.js +74 -4
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +52 -4
- package/dist/host/types.d.ts +21 -6
- package/dist/index.d.ts +1 -1
- package/dist/isolation/types.d.ts +6 -0
- package/dist/isolation/types.js +6 -0
- package/dist/platform/web.js +6 -1
- package/dist/react/frame.d.ts +13 -1
- package/dist/react/frame.js +37 -24
- package/dist/shell/annotate.d.ts +18 -4
- package/dist/shell/annotate.js +193 -22
- package/dist/shell/frame.d.ts +6 -1
- package/dist/shell/frame.js +45 -5
- package/docs/ADOPTING.md +69 -15
- package/docs/ARCHITECTURE.md +1 -0
- package/docs/DECISIONS.md +500 -18
- package/docs/DESIGN.md +44 -12
- package/docs/THREAT_MODEL.md +48 -22
- package/package.json +1 -1
- package/src/annotate/types.ts +44 -4
- package/src/annotate/validate.ts +90 -4
- package/src/host/create-host.ts +53 -3
- package/src/host/types.ts +26 -6
- package/src/index.ts +1 -0
- package/src/isolation/types.ts +7 -0
- package/src/platform/web.ts +6 -0
- package/src/react/frame.tsx +59 -31
- package/src/shell/annotate.ts +194 -22
- package/src/shell/frame.ts +45 -5
package/docs/ADOPTING.md
CHANGED
|
@@ -289,7 +289,8 @@ composer.onClose(() => display.annotations.clearSelection());
|
|
|
289
289
|
|
|
290
290
|
- **React** (P118): `PortholeFrame` and `PortholeView` take the same as props: `annotating`,
|
|
291
291
|
`annotations`, `focusedAnnotation` and `trackedAnnotation` (the mark to follow, by value; `null`
|
|
292
|
-
stops),
|
|
292
|
+
stops), `trackedSelection` (true while your composer is open: the selection is followed in the
|
|
293
|
+
mark's place, P138), every report through `onAnnotation` (`tracked` and `selectionTracked` too). The selection is cleared through a
|
|
293
294
|
ref, which holds `clearSelection()` only (a `PortholeFrameHandle`; never the display, whose life
|
|
294
295
|
is the binding's); with no display running it does nothing. Errors the core's calls throw (an id
|
|
295
296
|
no shown mark has, a config without `annotate`) reach `onHostError`, kind `"annotations"`.
|
|
@@ -420,9 +421,11 @@ composer.onClose(() => display.annotations.clearSelection());
|
|
|
420
421
|
their whole box (a composer's button, a card), a newer shell gives `selected`, each attached
|
|
421
422
|
result and `tracked` a `lastLineDocumentRect`: the last line with words on it, in the document's
|
|
422
423
|
coordinates (an element's whole box: it has no lines), unclamped as `documentRect` is. `selected`
|
|
423
|
-
carries the `scroll` it was read at too; an `anchored` report and `tracked` already do
|
|
424
|
-
|
|
425
|
-
|
|
424
|
+
carries the `scroll` it was read at too; an `anchored` report and `tracked` already do, and
|
|
425
|
+
`createHost` drops a report with a last line and no `scroll`, so where you have the line you have
|
|
426
|
+
the scroll (P137). A line's end in the frame's viewport is `x + width - scroll.x`, its bottom
|
|
427
|
+
`y + height - scroll.y`. Clip what you draw from it, as above, and keep `rect` where it is absent
|
|
428
|
+
(an older shell):
|
|
426
429
|
|
|
427
430
|
```js
|
|
428
431
|
display.on("annotation", (report) => {
|
|
@@ -434,6 +437,45 @@ composer.onClose(() => display.annotations.clearSelection());
|
|
|
434
437
|
composer.openAt(frame, clipToFrame(at), report.anchor); // the frame's px: clip them, then add its position
|
|
435
438
|
});
|
|
436
439
|
```
|
|
440
|
+
- **A composer that stays beside what it is for** (P138): `selected` comes once for a pick (and
|
|
441
|
+
for words again only once a scroll settles), and a pick's outline goes with it. Follow the
|
|
442
|
+
selection while your composer is open, `annotations.track({ selection: true })` (React:
|
|
443
|
+
`trackedSelection`), and the frame highlights it (a picked element in the picking outline) and
|
|
444
|
+
reports `selectionTracked` as `tracked` reports a mark: at most 60 a second, its `rect` clamped,
|
|
445
|
+
`documentRect`, `lastLineDocumentRect` and `scroll` as above, and `inView`, so you hide the
|
|
446
|
+
composer (and show your own marker at the frame's edge, from `documentRect` and `scroll`, clipped)
|
|
447
|
+
while it is out of view. `state: "orphaned"`: it isn't in the page now (a re-render took it out;
|
|
448
|
+
a reload); keep the person's words, it may be found again. It follows the latest `selected`, so a
|
|
449
|
+
new pick or selection moves it. One thing is followed at a time: it takes a followed mark's
|
|
450
|
+
place, and `track(null)`, a mark's id or `clear` ends it, the highlight with it. End it on every
|
|
451
|
+
close (posted, dismissed, Escape in your composer: the frame's own Escape doesn't end it), as you
|
|
452
|
+
clear the selection: the page reads when it starts and ends, so an end on every close says nothing
|
|
453
|
+
of what came of it. The composer moves at the page's word: guard it as below, armed again each
|
|
454
|
+
time it moves or shows again. An older shell sends nothing (and draws nothing): place by
|
|
455
|
+
`selected` until the first `selectionTracked`, which a newer one sends at its next animation
|
|
456
|
+
frame. A newer shell keeps the picked element outlined from the pick on, so there is no gap
|
|
457
|
+
before the follow's highlight; ask for the follow before a `start` or `stop` you send as the
|
|
458
|
+
composer opens (React orders them so), or the stop ends that outline a moment before the follow
|
|
459
|
+
draws it again. Without a follow the outline ends as a selection does (the next pick, Escape,
|
|
460
|
+
`clearSelection`, `start`, `stop`, `clear`). While you follow the selection, `selected` isn't
|
|
461
|
+
re-sent after a scroll: read where it is from `selectionTracked`.
|
|
462
|
+
|
|
463
|
+
```js
|
|
464
|
+
display.on("annotation", (report) => {
|
|
465
|
+
if (report.type === "selected") {
|
|
466
|
+
composer.openBeside(frame, report.rect, report.anchor); // as before: an older shell stops here
|
|
467
|
+
display.annotations.track({ selection: true });
|
|
468
|
+
}
|
|
469
|
+
if (report.type !== "selectionTracked") return;
|
|
470
|
+
if (report.state === "orphaned") return composer.detach(); // keep its words
|
|
471
|
+
if (!report.inView) return composer.collapseToMarker(report.documentRect, report.scroll);
|
|
472
|
+
if (composer.moveBeside(frame, report.rect) > 4) composerGuard.placed();
|
|
473
|
+
});
|
|
474
|
+
composer.onClose(() => {
|
|
475
|
+
display.annotations.track(null); // or the open card's mark: track(cardId)
|
|
476
|
+
display.annotations.clearSelection();
|
|
477
|
+
});
|
|
478
|
+
```
|
|
437
479
|
- **The keyboard** (P133): each marker is a button in the frame's Tab order, after the page's own
|
|
438
480
|
stops, in reading order, named for what it is (`3 comments on "the words"`, from the `count` and
|
|
439
481
|
the anchor's words, without an element's tag, P134; in English, whatever your UI's language). The
|
|
@@ -453,7 +495,10 @@ composer.onClose(() => display.annotations.clearSelection());
|
|
|
453
495
|
can forge `activated` while the person really is there, which this doesn't stop. So moving the
|
|
454
496
|
keyboard into your view on it is your own step outside "takes no focus" above, and a page can
|
|
455
497
|
bring it about: gate whatever posts from that view (a Reply in a frame-opened card) yourself;
|
|
456
|
-
Porthole can't.
|
|
498
|
+
Porthole can't. That goes for keys too: with the focus in your view the person's next keys reach
|
|
499
|
+
your document, so the view's own key handlers and your page-wide shortcuts that write (an `r` that
|
|
500
|
+
resolves, Cmd+Enter that posts) need the same gate (P137). When the person's key closes your view
|
|
501
|
+
of that mark from inside it (Escape, or a
|
|
457
502
|
Tab past its first or last control), whether or not the keyboard got there through `activated`,
|
|
458
503
|
and only then, close it and call
|
|
459
504
|
`display.annotations.focusMark(id)` (React: `focusMark(id)` on the `ref`) to put the keyboard back
|
|
@@ -464,10 +509,14 @@ composer.onClose(() => display.annotations.clearSelection());
|
|
|
464
509
|
the way that holds.
|
|
465
510
|
On a calm page that lands at once, from your `<body>`. While the frame is finding its marks (a
|
|
466
511
|
`show` just sent, which many hosts send as a card closes, or content that just changed) the word
|
|
467
|
-
waits, up to a second, and is then dropped unless the focus is in the frame by then
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
512
|
+
waits, up to a second, and is then dropped unless the focus is in the frame by then. A word the
|
|
513
|
+
frame takes more than 100 ms after you sent it, because its page is busy, is held to the same
|
|
514
|
+
test. So a late word takes no keyboard from a person who moved on ([P135](DECISIONS.md),
|
|
515
|
+
[P137](DECISIONS.md)). As your card has just closed, the focus is on your `<body>`, so a word that
|
|
516
|
+
waited or came late is dropped, and nothing tells you: **call `focusMark` again after your own
|
|
517
|
+
move of the focus into the frame.** Call it as your close runs, not after other work: its age
|
|
518
|
+
starts when you call it, and where the browser runs the frame on your thread, what your task does
|
|
519
|
+
next counts too.
|
|
471
520
|
|
|
472
521
|
```js
|
|
473
522
|
closeCard();
|
|
@@ -486,15 +535,20 @@ composer.onClose(() => display.annotations.clearSelection());
|
|
|
486
535
|
that step: it is only ever taken for the page's from a text field, and this one starts on `<body>`.
|
|
487
536
|
An id with no marker then leaves the focus in the frame, with the keys going to the page.
|
|
488
537
|
|
|
489
|
-
**
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
538
|
+
**Nested pages (P136).** `display.focus()` reaches a nested page on every engine, whether or not
|
|
539
|
+
it had the focus. Two ways don't:
|
|
540
|
+
- The frame's own `focus()`, which the React step above is: it stops at the page's shell (Chromium
|
|
541
|
+
and WebKit from anywhere, Firefox from a focused element of yours), so a `focusMark` that waits
|
|
542
|
+
is dropped even after it, and nothing tells you. On a calm page the second call doesn't wait and
|
|
543
|
+
lands. On a page that is changing, keep your own list of marks as the way back.
|
|
544
|
+
- `display.focus()` inside a key's own handler, on Firefox (measured on a nested page): it moves
|
|
545
|
+
nothing. Call it from a task, as the timer above does.
|
|
494
546
|
|
|
495
547
|
Without the second call, nothing changes on a calm page. On a busy one, a word that the frame
|
|
496
548
|
finishes with before your own move is lost where it used to land, so the person gets the frame and
|
|
497
|
-
not the marker. That is the cost of never pulling the keyboard into the page.
|
|
549
|
+
not the marker. That is the cost of never pulling the keyboard into the page. Upgrade the host and
|
|
550
|
+
the content server together: a newer shell takes a word from an older `createHost`, which has no
|
|
551
|
+
stamp, as a late one (the second call still lands), and an older shell ignores the stamp.
|
|
498
552
|
- **Labels and quotes are the page's text**: shown only as text. Porthole takes out of a label what
|
|
499
553
|
the person can't see; a quote (`exact`) keeps it, to be found again. Hand either to a model only
|
|
500
554
|
as the page's words.
|
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -215,6 +215,7 @@ Host app Shell (its own origin) Page (opaque child)
|
|
|
215
215
|
│── the host's messages ──────►│── postMessage ───────────────►│
|
|
216
216
|
│◄── porthole/shell/state ─────│ its own activation, its focus │
|
|
217
217
|
│── porthole/shell/look ──────►│ look now (as a move is heard) │
|
|
218
|
+
│── porthole/shell/focus ─────►│ display.focus(): on to the ──►│ the page's window
|
|
218
219
|
```
|
|
219
220
|
|
|
220
221
|
### URL frame
|