@botiverse/porthole 0.14.14 → 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 +27 -0
- package/dist/annotate/types.d.ts +41 -1
- package/dist/annotate/types.js +7 -1
- package/dist/annotate/validate.d.ts +17 -1
- package/dist/annotate/validate.js +55 -0
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +50 -3
- package/dist/host/types.d.ts +16 -2
- package/dist/index.d.ts +1 -1
- package/dist/react/frame.d.ts +11 -0
- package/dist/react/frame.js +37 -24
- package/dist/shell/annotate.d.ts +6 -2
- package/dist/shell/annotate.js +158 -11
- package/docs/ADOPTING.md +41 -1
- package/docs/DECISIONS.md +165 -2
- package/docs/DESIGN.md +27 -5
- package/docs/THREAT_MODEL.md +14 -5
- package/package.json +1 -1
- package/src/annotate/types.ts +38 -1
- package/src/annotate/validate.ts +67 -0
- package/src/host/create-host.ts +51 -2
- package/src/host/types.ts +21 -2
- package/src/index.ts +1 -0
- package/src/react/frame.tsx +57 -30
- package/src/shell/annotate.ts +158 -11
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"`.
|
|
@@ -436,6 +437,45 @@ composer.onClose(() => display.annotations.clearSelection());
|
|
|
436
437
|
composer.openAt(frame, clipToFrame(at), report.anchor); // the frame's px: clip them, then add its position
|
|
437
438
|
});
|
|
438
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
|
+
```
|
|
439
479
|
- **The keyboard** (P133): each marker is a button in the frame's Tab order, after the page's own
|
|
440
480
|
stops, in reading order, named for what it is (`3 comments on "the words"`, from the `count` and
|
|
441
481
|
the anchor's words, without an element's tag, P134; in English, whatever your UI's language). The
|
package/docs/DECISIONS.md
CHANGED
|
@@ -5985,7 +5985,7 @@ answer needs its sandbox taken off for a worker, and none is: the narrowest fix
|
|
|
5985
5985
|
`Sec-Fetch-Dest: worker` answer) would fix nothing. The agent manual already teaches workers from
|
|
5986
5986
|
`blob:` URLs only.
|
|
5987
5987
|
|
|
5988
|
-
## P112 · 2026-10-28 · 0.14's comment UX: what annotations add for a host's comment modes · Accepted
|
|
5988
|
+
## P112 · 2026-10-28 · 0.14's comment UX: what annotations add for a host's comment modes · Accepted; amended by P138
|
|
5989
5989
|
|
|
5990
5990
|
**Context.** Raft's comment design (its modes A–C, a card that follows its mark, a list in document
|
|
5991
5991
|
order, block selection on touch) needs more from `annotate` than 0.13 has. Each addition is the
|
|
@@ -6260,7 +6260,7 @@ Tested: `test/shell.test.ts` (`<`, `</`, `</di`, inside an attribute, and whole
|
|
|
6260
6260
|
unchanged); `leak/react.spec.ts` "content streams through props…" (a draft cut after `</` and
|
|
6261
6261
|
after `<` draws neither).
|
|
6262
6262
|
|
|
6263
|
-
## P118 · 2026-10-28 · React: `trackedAnnotation` and a handle with `clearSelection` · Accepted; amended by P131
|
|
6263
|
+
## P118 · 2026-10-28 · React: `trackedAnnotation` and a handle with `clearSelection` · Accepted; amended by P131, P138
|
|
6264
6264
|
|
|
6265
6265
|
**Context.** Raft's web app (Kirby) shows displays through `PortholeFrame` and `PortholeView`,
|
|
6266
6266
|
which hold the display handle inside: it could not follow a mark (`annotations.track`, P112) or
|
|
@@ -8287,3 +8287,166 @@ of the host's, like the rest of the exception. No code changes.
|
|
|
8287
8287
|
**Revisit when** a host's calm closes are seen dropped (the word's age on a real machine); people are
|
|
8288
8288
|
seen moving on inside 100 ms; a platform gives frames a clock that is shared and monotonic; or the
|
|
8289
8289
|
parked word's own age should count.
|
|
8290
|
+
|
|
8291
|
+
## P138 · 2026-11-08 · The selection followed: a composer stays beside what it is for, and what was picked stays lit · Accepted
|
|
8292
|
+
|
|
8293
|
+
Amends P112 (`track` follows the selection too) and P118 (`trackedSelection`). From a Raft user's
|
|
8294
|
+
report, Kirby's design.
|
|
8295
|
+
|
|
8296
|
+
**Context.** A host opens its composer on `selected`, where the selection is at that moment. A pick
|
|
8297
|
+
ends with element mode, and its outline with it (`hover = null`), so after the click nothing in the
|
|
8298
|
+
page says which element the composer is for. `selected` is sent once for a pick, and for words again
|
|
8299
|
+
only once a scroll settles, at most a second apart (P105). So a composer drawn as a popover at the
|
|
8300
|
+
report's box stays where the element was as the page scrolls, resizes or lays itself out again, and
|
|
8301
|
+
covers whatever comes there. A posted comment's card has what the composer lacks: `track(id)` follows
|
|
8302
|
+
its mark at every animation frame (P112), with its place in the document (P132), and `anchored` says
|
|
8303
|
+
when it is orphaned. But it follows a mark by id, and the selection has none.
|
|
8304
|
+
|
|
8305
|
+
**Decision.**
|
|
8306
|
+
|
|
8307
|
+
1. **`annotations.track({ selection: true })`** follows the selection the frame last reported as
|
|
8308
|
+
`selected` (the element picked, by a click or a held block, or the words selected) instead of a
|
|
8309
|
+
mark. One followed thing at a time, as before: a mark's id, `null` or `clear` ends it; a `show`, a
|
|
8310
|
+
`stop` and a pick's end leave it. It is kept for a frame that runs later, as a followed mark is.
|
|
8311
|
+
On the wire it is `porthole/annotate.track` with `{ id: null, selection: true }`.
|
|
8312
|
+
2. **The shell keeps what each `selected` reported**: the element, or a copy of the range (the DOM's
|
|
8313
|
+
own `cloneRange`, taken before content runs), which the page's changes keep up to date and which
|
|
8314
|
+
outlives the page's own selection (a click elsewhere, the host's `clearSelection`, P115). A newer
|
|
8315
|
+
`selected` replaces it, and a followed selection follows the new one from the next frame. Taken
|
|
8316
|
+
out of the page (a re-render), it is found again by its anchor, as a mark is, at most twice a
|
|
8317
|
+
second while it is gone.
|
|
8318
|
+
3. **`porthole/annotate.selectionTracked`** reports it as `tracked` reports a mark, on the same clock
|
|
8319
|
+
(an animation frame where it moved, at most one every 16 ms), and also when the frame's viewport
|
|
8320
|
+
changed size: `{ state: "attached", rect, documentRect, lastLineDocumentRect?, scroll, inView }`,
|
|
8321
|
+
or `{ state: "orphaned" }` once while it isn't in the page (or the frame has nothing to follow, a
|
|
8322
|
+
new frame after a reload). The first comes at the frame after the host asks. `inView` is whether
|
|
8323
|
+
any of its box is inside the viewport. It is a new method, not `tracked` with another shape, so
|
|
8324
|
+
that `tracked`'s `id: string` stays as hosts read it and an older host drops it unread (an unknown
|
|
8325
|
+
method is no report, and not a malformed one).
|
|
8326
|
+
4. **`createHost` takes it only while it follows the selection**, at most 60 a second together with
|
|
8327
|
+
`tracked` (one array: one followed thing, one rate), outside the bridge's rate as `tracked` is
|
|
8328
|
+
(P112). Its `rect` is clamped (P104); `documentRect` and `lastLineDocumentRect` are checked and
|
|
8329
|
+
left unclamped (P132, P133); `inView` is the page's word and the host's together: false unless
|
|
8330
|
+
its box as reported reaches the viewport as the host reads it (`inViewport`), so a page can't say
|
|
8331
|
+
"in view" of a box the clamp puts on an edge. Every field but the last line is required: the
|
|
8332
|
+
method is new with its shell, which always has them.
|
|
8333
|
+
5. **The followed selection is drawn** in the shell's layer while it is followed: an element in the
|
|
8334
|
+
picking outline (blue, lighter, without the tag that names it), words with a light blue fill and
|
|
8335
|
+
a line under them, apart from the marks' yellow, since no comment is there yet. In the layer's
|
|
8336
|
+
`aria-hidden` outlines, under the layer's `pointer-events: none`: no pointer, no Tab stop, no
|
|
8337
|
+
name. It goes when the following ends.
|
|
8338
|
+
6. **React**: `trackedSelection?: boolean`. While true the selection is followed in
|
|
8339
|
+
`trackedAnnotation`'s place; false gives that mark back. A separate prop, not a wider
|
|
8340
|
+
`trackedAnnotation`, so the composer's state and the open card's are each a host's own value and
|
|
8341
|
+
the precedence is Porthole's, once.
|
|
8342
|
+
|
|
8343
|
+
**How a host tells, and what an older shell does.** A shell that follows a selection answers at its
|
|
8344
|
+
next animation frame, `attached` or `orphaned`. An older shell reads `{ id: null, selection: true }`
|
|
8345
|
+
as `track(null)`: it follows nothing, sends nothing, and draws nothing, which is today's behaviour,
|
|
8346
|
+
and a host that places by `selected`'s boxes until a `selectionTracked` comes keeps it there. An
|
|
8347
|
+
older host never asks, so a newer shell never sends it; a page that sends it anyway to an older host
|
|
8348
|
+
sends a method that host doesn't know.
|
|
8349
|
+
|
|
8350
|
+
**Not a loosening.** No CSP, sandbox flag, egress, gate or allowlist changes, and no new budget:
|
|
8351
|
+
- *Frame to host.* The same boxes the frame already sends in `selected` and `tracked` (`rect`,
|
|
8352
|
+
`documentRect`, `lastLineDocumentRect`, `scroll`) and a boolean, through the same checks, the same
|
|
8353
|
+
clamp and the same 60 a second as `tracked`, which it shares, since one thing is followed at a
|
|
8354
|
+
time: a host that followed a card and now follows a composer takes what it took. No anchor, label
|
|
8355
|
+
or words go with it: those went with `selected`. The host takes it only after it asked.
|
|
8356
|
+
- *Host to frame.* The page reads the host's messages (it shares the shell's realm, P053). It learns
|
|
8357
|
+
that the host follows its selection, and when that ends: that a composer is open on it, and closed.
|
|
8358
|
+
That is P112's `track(id)` (which card is open) and P121's `clearSelection` (when the person was done)
|
|
8359
|
+
for the composer: end it on every close, posted or dismissed, so the end says nothing of what came
|
|
8360
|
+
of it, as P121 asks of the clear.
|
|
8361
|
+
- *What the page can do with it.* It moves the host's composer, within its frame, as often as 60
|
|
8362
|
+
times a second, and can say it is out of view or gone. P112 accepted that for a card that follows
|
|
8363
|
+
its mark, under THREAT_MODEL §6's guard of a view a report moves (no press for 500 ms after it
|
|
8364
|
+
appears or moves, beside the frame where it can, no focus but by §6's exceptions); a composer that
|
|
8365
|
+
follows is such a view, and a composer hidden for `inView: false` and shown again appears again.
|
|
8366
|
+
`selectionTracked` joins §6's list. A forged `orphaned` or `inView: false` is no more than a page
|
|
8367
|
+
that never reports a selection, which it can already do; a host keeps the person's words in the
|
|
8368
|
+
composer either way.
|
|
8369
|
+
- *The layer.* A closed shadow root the page can't read, as for marks; the highlight takes no
|
|
8370
|
+
pointer, so the page's clicks and selections reach it as before.
|
|
8371
|
+
|
|
8372
|
+
**Focus and keys.** Following reads boxes and draws; it calls no `focus()`, changes no selection,
|
|
8373
|
+
adds no listener, and prevents and stops no event. Markers' tab stops, `focusMark` and its tests
|
|
8374
|
+
(P134, P135, P137), `display.focus()` on a nested page (P136), the hold gesture (P112) and Escape (a
|
|
8375
|
+
pick's, and text mode's `cancelled`) are as they were. Escape in the frame doesn't end the following:
|
|
8376
|
+
the host ends it from its composer's own Escape, and a frame's Escape while text is selected is
|
|
8377
|
+
`cancelled` as before (P112).
|
|
8378
|
+
|
|
8379
|
+
**Rejected.**
|
|
8380
|
+
- *A draft mark for the composer* (`show` with `kind: "draft"` and `track` its id), which works today:
|
|
8381
|
+
a draft is a comment the author kept, drawn with a marker, a button in the page's Tab order and
|
|
8382
|
+
named "Draft comment" (P107, P133), anchored again from its selectors (best-effort, 150 ms after a
|
|
8383
|
+
change), and it reaches the page as a draft; the composer is none of those until the person keeps
|
|
8384
|
+
it.
|
|
8385
|
+
- *`selected` re-sent at every frame*: it carries the anchor and its words, which the bridge's rate
|
|
8386
|
+
is for, and an older host would open its composer again at each one.
|
|
8387
|
+
- *`tracked` with `selection: true` and no `id`*: `tracked`'s `id` is a string hosts read, and an
|
|
8388
|
+
older host would count each as a malformed report against the page.
|
|
8389
|
+
- *`inView` computed by the host alone*: the shell can say more (a box its page clips), and the
|
|
8390
|
+
host's test still bounds it.
|
|
8391
|
+
|
|
8392
|
+
**Tested.** `test/annotate.test.ts` "the followed selection (P138)": `parseReport` rebuilds it from
|
|
8393
|
+
known fields (an anchor, a label or an id a page adds are dropped), drops a malformed or incomplete
|
|
8394
|
+
one; `inViewport` and `followsSelection`; through `createHost`, the wire message, an older shell's
|
|
8395
|
+
reading of it, reports taken only while followed, a show leaving it, a mark's id, `null` and `clear`
|
|
8396
|
+
ending it, the clamp and `inView`, 60 a second, and the following kept for a new frame; the shell's
|
|
8397
|
+
runtime: only `selection === true` follows it, a mark's id wins, its tells carry no words and it
|
|
8398
|
+
calls no focus, selection or listener, the kept `cloneRange`, every `selected` kept, the highlight in
|
|
8399
|
+
the aria-hidden outlines. `leak/annotate.spec.ts` "a followed selection's place comes as it moves…"
|
|
8400
|
+
(three engines): a picked element followed and lit, out of view and back as the document scrolls,
|
|
8401
|
+
orphaned when the page takes it out and found again when it puts it back, a page's own word taken
|
|
8402
|
+
neither unasked nor after `track(null)` nor past 60 a second, the highlight gone with the following;
|
|
8403
|
+
"following the selection moves no focus…": with the page's field focused, nothing moves the focus,
|
|
8404
|
+
the page hears every key, Escape is `cancelled` as before, and the words stay followed after the
|
|
8405
|
+
host's `clearSelection`, where the layout moves them. `leak/react.spec.ts` "trackedSelection follows
|
|
8406
|
+
the picked element…": in `trackedAnnotation`'s place, and false gives the mark back;
|
|
8407
|
+
`test/react-ssr.test.ts` its type. Negative control `track-selection-checks` (taken unasked, at any
|
|
8408
|
+
rate).
|
|
8409
|
+
|
|
8410
|
+
*After Tenny's review (porthole#116), two changes, decided by the reviewer:*
|
|
8411
|
+
|
|
8412
|
+
- **No gap at pick time.** A pick's outline went with the pick, and the follow's highlight came only
|
|
8413
|
+
once the host's `track` arrived: a frame or two with nothing drawn. Now the element just picked (a
|
|
8414
|
+
click's, or a held block's) keeps an outline after `selected`, drawn as the follow's highlight is,
|
|
8415
|
+
until the host follows it (the follow takes it over in the same draw, so nothing changes on
|
|
8416
|
+
screen) or the pick ends as a selection does: the next pick, or a selection reported after it;
|
|
8417
|
+
the host's `clearSelection`; a mode started or stopped (`start`, `stop`); `clear`; Escape in the
|
|
8418
|
+
frame (the key is left as it was: nothing prevents or stops it); or the element leaving the page.
|
|
8419
|
+
There is no timer. Not `unselected`: a selection made after the pick already ended it as it was
|
|
8420
|
+
reported, so the only selection `unselected` can be about is one from before the pick, which the
|
|
8421
|
+
pick's own click takes away where text is selected too, and ending on it would take the outline
|
|
8422
|
+
away a moment after the pick. An older host never follows, so its people now see the picked
|
|
8423
|
+
element outlined until one of those, where before the outline went at once: the shell's change
|
|
8424
|
+
alone, bounded by the events that end a selection today.
|
|
8425
|
+
So the follow comes before a mode change that a host makes in the same moment (it ends picking
|
|
8426
|
+
as its composer opens), the React binding sends the following before the mode (the mode's effect
|
|
8427
|
+
now runs after the following's); a host on the core calls `track({ selection: true })` before
|
|
8428
|
+
`start` or `stop`. The other way round, the stop ends the outline and the follow draws it again a
|
|
8429
|
+
task later, which is the gap this removes.
|
|
8430
|
+
- **No re-sent `selected` while followed.** While the selection is followed, a scroll sets no
|
|
8431
|
+
follow-up for it (P105's re-send once a scroll settles): the follow's reports already say where it
|
|
8432
|
+
is, and the re-send spent the bridge's 120 reports a minute, which the person's clicks need. A new
|
|
8433
|
+
selection is still reported, as ever. Once the following ends, a scroll re-sends it as before (its
|
|
8434
|
+
box is compared with the one last told, so one that moved meanwhile is told then).
|
|
8435
|
+
|
|
8436
|
+
*Tested.* `test/annotate.test.ts` "a pick keeps its outline until the host follows it…", "without a
|
|
8437
|
+
follow, a pick's outline ends as a selection does…", "while the selection is followed, a scroll
|
|
8438
|
+
re-sends no selected…" (the shell's runtime, as its other tests read it), and the highlight test
|
|
8439
|
+
reads the outline drawn for either. `leak/annotate.spec.ts` "a pick keeps its outline until the host
|
|
8440
|
+
follows it, and without a follow it ends as a selection does…" (three engines: outlined after the
|
|
8441
|
+
pick and 1.5 s on, then gone at Escape, which the page still hears, at a mode started, at stop, at
|
|
8442
|
+
`clearSelection`, at the next pick, at a selection after a pick, at `clear`; lit as the follow takes
|
|
8443
|
+
over and gone at its end); "while the selection is followed a scroll re-sends no selected…" (no
|
|
8444
|
+
`selected` past the settle and the follow-ups' clock while `selectionTracked` comes, then a re-send
|
|
8445
|
+
once the following ends); the follow's test now finds the picked element outlined before the host
|
|
8446
|
+
follows it. No new negative control: neither is a defense.
|
|
8447
|
+
|
|
8448
|
+
**Revisit when** a host needs two things followed at once (a composer beside an open card); the
|
|
8449
|
+
selection inside a page's own scrolling box (its `inView` there is the viewport's, not the box's);
|
|
8450
|
+
Escape in the frame should end a composer by itself; `inView` on a followed mark's `tracked` too; or
|
|
8451
|
+
an older host's people are seen confused by a pick's outline that stays.
|
|
8452
|
+
|
package/docs/DESIGN.md
CHANGED
|
@@ -743,7 +743,7 @@ binding is mounting and lifecycle (P034).
|
|
|
743
743
|
onContentError onHostError onResize onNavigated onNavigationBlocked onRefused onMuted
|
|
744
744
|
onInitialized onOutcome
|
|
745
745
|
fill? // fill the box and scroll inside, not grow with the content
|
|
746
|
-
annotating? annotations? focusedAnnotation? trackedAnnotation? onAnnotation? // where annotate is declared
|
|
746
|
+
annotating? annotations? focusedAnnotation? trackedAnnotation? trackedSelection? onAnnotation? // where annotate is declared
|
|
747
747
|
ref? // a PortholeFrameHandle: clearSelection() (P118)
|
|
748
748
|
aliases? themeKey? renderPlaceholder? eager? confirm? document? instance?
|
|
749
749
|
className? style? />
|
|
@@ -779,8 +779,9 @@ binding is mounting and lifecycle (P034).
|
|
|
779
779
|
- **Annotations** follow props: `annotating` (what the person may point at now, or
|
|
780
780
|
null), `annotations` (the marks), `focusedAnnotation` (each new id is brought into
|
|
781
781
|
view; `{ id, key }` with a new key focuses the same one again), `trackedAnnotation`
|
|
782
|
-
(the mark followed, or null, P118)
|
|
783
|
-
|
|
782
|
+
(the mark followed, or null, P118), `trackedSelection` (true: the selection followed in
|
|
783
|
+
its place, and highlighted, P138); `onAnnotation` gets what the frame reported, `tracked`
|
|
784
|
+
and `selectionTracked` boxes too. A frame that mounts again gets them all. A `ref` holds `clearSelection()`, `find`,
|
|
784
785
|
`clearFind` and `focusMark(id)` (`PortholeFrameHandle`), each a no-op while no display runs.
|
|
785
786
|
- **Errors** (P055): `onContentError` gets what the content did wrong (what it
|
|
786
787
|
threw, what the sandbox blocked, a navigation the shell stopped, that it kept
|
|
@@ -1049,12 +1050,13 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1049
1050
|
| host → frame | `porthole/annotate.clear` | — |
|
|
1050
1051
|
| host → frame | `porthole/annotate.clearSelection` | —: the page's text selection is taken away (the DOM's own `removeAllRanges`, taken before content runs) with what the shell held of it, and nothing is reported back; marks, drafts and the mode stay (P115) |
|
|
1051
1052
|
| host → frame | `porthole/annotate.focusMark` | `{ id, at }`, `at` the host's `Date.now()` as it sent it (P137): the DOM focus goes to that mark's marker (the DOM's own `focus`, taken before content runs), once the marks of a `show` are found; a call that had to wait for them is dropped unless the focus is in the frame's document as it lands (the DOM's own `hasFocus`, taken before content runs; P135), and so is one the frame takes 100 ms or more after `at` by its own clock (the DOM's own `Date.now`, taken before content runs) or with no `at` (P137); a fresh one isn't asked; nothing is reported back, and with no such marker, or while elements are picked, nothing happens. For after the keyboard closed the host's view: Escape, or a Tab past its ends (P134); a host calls it again after its own `display.focus()` |
|
|
1052
|
-
| frame → host | `porthole/annotate.selected` | `{ anchor, rect, lastLineDocumentRect?, scroll? }` (a newer shell's last two, only as a pair: P133, below, P137); after a scroll, the same selection again only if its box moved more than 0.5 px, on the follow-ups' clock (P105) |
|
|
1053
|
+
| frame → host | `porthole/annotate.selected` | `{ anchor, rect, lastLineDocumentRect?, scroll? }` (a newer shell's last two, only as a pair: P133, below, P137); after a scroll, the same selection again only if its box moved more than 0.5 px, on the follow-ups' clock (P105), and not while the host follows the selection (P138) |
|
|
1053
1054
|
| frame → host | `porthole/annotate.unselected` | — (the text selection went away) |
|
|
1054
1055
|
| frame → host | `porthole/annotate.cancelled` | — (Escape) |
|
|
1055
1056
|
| frame → host | `porthole/annotate.anchored` | `{ results: [{ id, state: "attached" \| "orphaned", rect?, documentRect?, lastLineDocumentRect?, order? }], scroll? }` (a newer shell's `documentRect` and `scroll`: P132, below; `lastLineDocumentRect`: P133, never without `scroll`, P137): every mark after `show`, the one after `focus`, every mark when the content changed a state, and, while any mark has a marker (a `count` or a draft, P107), once a scroll, a resize or a run of content changes has settled (150 ms quiet), only the marks that moved more than 0.5 px since the host was last told, at most one a second together with the selection's (P104, P105) |
|
|
1056
|
-
| host → frame | `porthole/annotate.track` | `{ id }` or `{ id: null }`: follow one shown mark, or none (P112) |
|
|
1057
|
+
| host → frame | `porthole/annotate.track` | `{ id }` or `{ id: null }`: follow one shown mark, or none (P112); `{ id: null, selection: true }`: follow the selection last reported as `selected` instead, and highlight it while followed (P138; an older shell reads it as none) |
|
|
1057
1058
|
| frame → host | `porthole/annotate.tracked` | `{ id, rect, documentRect?, lastLineDocumentRect?, scroll? }`: the followed mark's box at an animation frame where it moved, at most one every 16 ms; the host takes 60 a second, for that mark only (P112); a newer shell adds its place in the document and the document's scroll (P132), and its last line's (P133, never without the scroll, P137) |
|
|
1059
|
+
| frame → host | `porthole/annotate.selectionTracked` | `{ state: "attached", rect, documentRect, lastLineDocumentRect?, scroll, inView }` or `{ state: "orphaned" }`: the followed selection's boxes, as `tracked`'s, at an animation frame where it moved or the viewport changed size, at most one every 16 ms, the first at the frame after the host asks; `orphaned` once while it isn't in the page (or the frame has no selection), found again by its anchor at most twice a second; the host takes it only while it follows the selection, 60 a second with `tracked`, its `rect` clamped, `inView` false unless its box as read reaches the viewport (P138) |
|
|
1058
1060
|
| frame → host | `porthole/annotate.activated` | `{ id, rect }`: the person clicked a mark's marker, or pressed Enter or Space on it (P133); `rect` is the marker's (P104); taken only while the host's page has transient activation (P105) |
|
|
1059
1061
|
|
|
1060
1062
|
- **Anchors** are W3C Web Annotation selectors, at most one of each:
|
|
@@ -1092,6 +1094,25 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1092
1094
|
of the words' client rects, the box a text marker's place starts from; an element,
|
|
1093
1095
|
which has no lines of its own, gives its whole box. Its place in the frame's viewport
|
|
1094
1096
|
is it less `scroll`. Absent from an older shell, and where nothing of it is drawn.
|
|
1097
|
+
- **The selection followed** (P138). The shell keeps what each `selected` reported: the
|
|
1098
|
+
element picked (a click, or a block held), or a copy of the selection's range (the
|
|
1099
|
+
DOM's own `cloneRange`, taken before content runs), which the page's changes keep up to
|
|
1100
|
+
date and which stays when the page's own selection goes (the host's `clearSelection`
|
|
1101
|
+
too). While the host follows it (`track` with `selection`; one followed thing at a time,
|
|
1102
|
+
so a mark's id or `null` ends it, as `clear` does; `show`, `stop` and a pick's end leave
|
|
1103
|
+
it), it is drawn in the layer as a pick is (an element in the picking outline, lighter
|
|
1104
|
+
and without its name; words with a light fill and a line under them, in the picking
|
|
1105
|
+
blue) and its boxes are told as a followed mark's are, with `inView` (any of its box in
|
|
1106
|
+
the viewport). Taken out of the page, it is `orphaned` once, and found again by its
|
|
1107
|
+
anchor as a mark is. It reads boxes only: no focus moves, no selection changes, no
|
|
1108
|
+
listener is added, and nothing about the words goes with it (they went with
|
|
1109
|
+
`selected`). A newer `selected` replaces it, followed from the next frame. Before the host
|
|
1110
|
+
follows it, the element just picked keeps an outline drawn the same way, so nothing changes on
|
|
1111
|
+
screen when the follow takes over; without a follow it ends as a selection does (the next pick or
|
|
1112
|
+
selection, `clearSelection`, `start`, `stop`, `clear`, Escape, the element leaving the page), on
|
|
1113
|
+
no timer (Tenny's review). While followed, a scroll re-sends no `selected` (P105's follow-up):
|
|
1114
|
+
once the following ends, it does again. The React binding sends the following before a mode
|
|
1115
|
+
change made in the same render.
|
|
1095
1116
|
- **Markers** (P104). A mark with a `count` gets a bubble glyph and its number ("99+"
|
|
1096
1117
|
above 99; 0 the bubble alone), a real button (P133, below), on an element's top right
|
|
1097
1118
|
corner, inside the frame's width, and at the end of a text anchor's paragraph (P133):
|
|
@@ -1585,6 +1606,7 @@ control the tables above name to the registry):
|
|
|
1585
1606
|
| `comments-in-frame` | `served/runtime.spec.ts` | `comments.open while the person types in the host's composer reaches no handler, by the page's own call or the shell's; from a press in the frame it does` | — | — |
|
|
1586
1607
|
| `cancel-any-mode` | `annotate.spec.ts` | `Escape while selecting text is cancelled, and stays the page's key; with no mode on, a page's own cancel isn't heard (P112)`, `a hostile page fakes reports: the host takes none it didn't ask for, nothing malformed, and not a flood` | — | — |
|
|
1587
1608
|
| `track-checks` | `annotate.spec.ts` | `a followed mark's box comes as it moves, for that mark only, at most 60 a second, clamped to the frame, until the host stops (P112)` | — | — |
|
|
1609
|
+
| `track-selection-checks` | `annotate.spec.ts` | `a followed selection's place comes as it moves, highlighted, out of view and back, gone and found again, only while the host follows it, at most 60 a second (P138)` | — | — |
|
|
1588
1610
|
| `order-check` | `annotate.spec.ts` | `every found mark's place in the document comes with its box, offscreen ones too; a place that isn't one is no report (P112)` | — | — |
|
|
1589
1611
|
| `hold-click` | `annotate.spec.ts` | `holding a block 500 ms selects it and its release's click never reaches the page; a tap, a moving finger and a mouse are the page's (P112)` | — | — |
|
|
1590
1612
|
| `clear-selection` | `annotate.spec.ts` | `clearSelection takes the page's selection away and tells nothing back; marks and drafts stay, the next selection is told (P115)` | — | — |
|
package/docs/THREAT_MODEL.md
CHANGED
|
@@ -5,7 +5,7 @@ What Porthole protects, from whom, and where that protection ends. For each way
|
|
|
5
5
|
guaranteed. [ADOPTING.md](ADOPTING.md) says how to set each one up, and
|
|
6
6
|
[DESIGN.md](DESIGN.md) lists every defense with the test that proves it.
|
|
7
7
|
|
|
8
|
-
**Status.** This describes Porthole 0.14.
|
|
8
|
+
**Status.** This describes Porthole 0.14.15 (2026-11-08). A review on 2026-10-19 found gaps, and every decision it led to
|
|
9
9
|
has merged ([§8](#8-fixes-in-flight) lists them). P096 changed the negative-control runner and CI,
|
|
10
10
|
and the shipped conformance probes' messages and timing, not what they check. P104 (0.9.0's
|
|
11
11
|
annotation markers) had a review of its own, and P105, in 0.10.0, is what it led to. 0.11.0 was
|
|
@@ -39,7 +39,9 @@ word to put the keyboard back on a marker, and a second exception to "takes no f
|
|
|
39
39
|
are the host's own (§6, §7); no wall moves. 0.14.13: P135 drops a `focusMark` that had to wait unless the focus is
|
|
40
40
|
in the frame's document by then; a call on a calm page is unchanged. 0.14.14: P136 brings `display.focus()`
|
|
41
41
|
through a nested page's shell with a new host-to-shell word no page can say; P137 applies P135's check to a
|
|
42
|
-
word 100 ms old or more; no wall moves.
|
|
42
|
+
word 100 ms old or more; no wall moves. 0.14.15: P138 lets the host follow the current selection
|
|
43
|
+
(`selectionTracked`, the same boxes as `tracked`, on its budget, only while asked) and keeps what was
|
|
44
|
+
picked lit; no wall moves.
|
|
43
45
|
|
|
44
46
|
## 1. Two layers
|
|
45
47
|
|
|
@@ -213,8 +215,9 @@ Whatever the use:
|
|
|
213
215
|
app with egress, S5, unless you accept it). Take its counts as the bar's numbers, and open your
|
|
214
216
|
bar on `findRequested`, nothing more (§7 "Find in page").
|
|
215
217
|
- Guard a view that a frame's report opens or moves (`activated`, `anchored`, `selected`,
|
|
216
|
-
`tracked`: a comment's bubble, a composer, a card that follows its mark,
|
|
217
|
-
|
|
218
|
+
`tracked`, `selectionTracked`: a comment's bubble, a composer, a card that follows its mark, a
|
|
219
|
+
composer that follows the selection (P138), which the page moves at will, up to 60 times a
|
|
220
|
+
second, and hides and shows again with `inView`). The content chooses when it appears and where, so it can bring it
|
|
218
221
|
under a press the person meant for the content (a double click on the content's own button whose
|
|
219
222
|
second click lands on the bubble's). Such a view takes no press of any kind for 500 ms after it
|
|
220
223
|
appears or moves (not a `click` only: menu triggers act on `pointerdown`, and menu items click
|
|
@@ -856,7 +859,13 @@ own frame, below the shell, P111), so:
|
|
|
856
859
|
where its words are anyway. Where a selection or a mark's words end (`lastLineDocumentRect` in
|
|
857
860
|
`selected`, `anchored` and `tracked`, P133) is one more such box, read, checked and left unclamped
|
|
858
861
|
the same way, with the same duty; `selected` also carries `scroll` now. A report with a last line
|
|
859
|
-
and no `scroll` is dropped (P137), as a malformed part drops one.
|
|
862
|
+
and no `scroll` is dropped (P137), as a malformed part drops one. A followed selection's reports
|
|
863
|
+
(`selectionTracked`, P138) are the same boxes, checked and clamped the same way, taken only while
|
|
864
|
+
the host follows the selection and within `tracked`'s 60 a second (control
|
|
865
|
+
`track-selection-checks`); their `inView` is false unless the box reaches the frame's viewport as
|
|
866
|
+
the host reads it. They carry nothing of the page's words. The page reads the host's word that
|
|
867
|
+
starts and ends the following, so it learns when a composer is open on its selection, as it
|
|
868
|
+
learns which card is open from `track` (P112): end it on every close, kept or dismissed.
|
|
860
869
|
- *What holds, against content that patches none of the DOM's or JavaScript's built-ins.* A real
|
|
861
870
|
press or click on a marker reaches none of the content's handlers (the shell's first listener
|
|
862
871
|
stops it; control `marker-click`) and moves neither focus nor a selection (control
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.14.
|
|
3
|
+
"version": "0.14.15",
|
|
4
4
|
"description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
|
|
5
5
|
"homepage": "https://github.com/botiverse/porthole#readme",
|
|
6
6
|
"bugs": {
|
package/src/annotate/types.ts
CHANGED
|
@@ -86,6 +86,13 @@ export interface AnnotateMode {
|
|
|
86
86
|
readonly text?: boolean;
|
|
87
87
|
}
|
|
88
88
|
|
|
89
|
+
/**
|
|
90
|
+
* What `annotations.track` follows (P112, P138): a shown mark, by its id; the selection the frame
|
|
91
|
+
* last reported as `selected` (the element picked, or the words selected), highlighted in the
|
|
92
|
+
* frame while followed; or nothing (`null`). One at a time: each replaces the last.
|
|
93
|
+
*/
|
|
94
|
+
export type AnnotationTrackTarget = string | { readonly selection: true } | null;
|
|
95
|
+
|
|
89
96
|
/**
|
|
90
97
|
* An anchor the host marks in the frame, under its own id. Everything here is sent into the
|
|
91
98
|
* frame, so the content can read it: give ids that say nothing (never a person's name or the
|
|
@@ -209,6 +216,30 @@ export type AnnotationReport =
|
|
|
209
216
|
readonly lastLineDocumentRect?: AnnotationRect;
|
|
210
217
|
readonly scroll?: AnnotationScroll;
|
|
211
218
|
}
|
|
219
|
+
/**
|
|
220
|
+
* Where the selection the host follows is (`annotations.track({ selection: true })`, P138): the
|
|
221
|
+
* element picked or the words selected, as the last `selected` reported them, at an animation
|
|
222
|
+
* frame where it moved or the frame's viewport changed size; at most 60 a second, together with
|
|
223
|
+
* `tracked` (one followed thing at a time). The same boxes as `tracked`'s: `rect` clamped to the
|
|
224
|
+
* frame, `documentRect` and `lastLineDocumentRect` in the document and unclamped, the `scroll`
|
|
225
|
+
* they were read at, always there. `inView`: whether any of it is inside the frame's viewport
|
|
226
|
+
* (false where the shell says so, or where `rect` lies wholly outside the viewport as the host
|
|
227
|
+
* reads it); hide UI attached to it while false. `orphaned`: it isn't in the page now (taken out,
|
|
228
|
+
* its words gone; or the frame has no selection, a new frame after a reload); `attached` again if
|
|
229
|
+
* it is found again by its anchor. The first report comes at the frame's next animation frame
|
|
230
|
+
* after the host asks, which is how a host tells a shell that follows a selection (an older one
|
|
231
|
+
* sends none). Geometry only, as `tracked`: no anchor, no words. The content's word.
|
|
232
|
+
*/
|
|
233
|
+
| {
|
|
234
|
+
readonly type: "selectionTracked";
|
|
235
|
+
readonly state: "attached";
|
|
236
|
+
readonly rect: AnnotationRect;
|
|
237
|
+
readonly documentRect: AnnotationRect;
|
|
238
|
+
readonly lastLineDocumentRect?: AnnotationRect;
|
|
239
|
+
readonly scroll: AnnotationScroll;
|
|
240
|
+
readonly inView: boolean;
|
|
241
|
+
}
|
|
242
|
+
| { readonly type: "selectionTracked"; readonly state: "orphaned" }
|
|
212
243
|
/**
|
|
213
244
|
* The person clicked the marker of a mark the host shows with a `count` (P104), or of a draft
|
|
214
245
|
* (P107), or pressed Enter or Space on it (P133); `rect` is the marker's box, to open the host's
|
|
@@ -237,10 +268,16 @@ export const ANNOTATE_METHODS = {
|
|
|
237
268
|
anchored: "porthole/annotate.anchored",
|
|
238
269
|
/** Frame → host: a mark's marker was clicked, or pressed from the keyboard (P104, P133). */
|
|
239
270
|
activated: "porthole/annotate.activated",
|
|
240
|
-
/**
|
|
271
|
+
/**
|
|
272
|
+
* Host → frame: follow one mark's box (`{ id }`), or none (`{ id: null }`) (P112), or the
|
|
273
|
+
* selection last reported, highlighted while followed (`{ id: null, selection: true }`, P138: an
|
|
274
|
+
* older shell reads it as none).
|
|
275
|
+
*/
|
|
241
276
|
track: "porthole/annotate.track",
|
|
242
277
|
/** Frame → host: the followed mark's box, as it moves (P112). */
|
|
243
278
|
tracked: "porthole/annotate.tracked",
|
|
279
|
+
/** Frame → host: where the followed selection is, as it moves (P138). */
|
|
280
|
+
selectionTracked: "porthole/annotate.selectionTracked",
|
|
244
281
|
/** Host → frame: take the page's text selection away, telling nothing back (P115). */
|
|
245
282
|
clearSelection: "porthole/annotate.clearSelection",
|
|
246
283
|
/**
|
package/src/annotate/validate.ts
CHANGED
|
@@ -8,6 +8,7 @@ import {
|
|
|
8
8
|
type AnnotationReport,
|
|
9
9
|
type AnnotationScroll,
|
|
10
10
|
type AnnotationSelector,
|
|
11
|
+
type AnnotationTrackTarget,
|
|
11
12
|
} from "./types.ts";
|
|
12
13
|
import { withoutUnseen } from "../bridge/unseen.ts";
|
|
13
14
|
|
|
@@ -145,6 +146,25 @@ export function clampRect(
|
|
|
145
146
|
return { x: left, y: top, width: right - left, height: bottom - top };
|
|
146
147
|
}
|
|
147
148
|
|
|
149
|
+
/**
|
|
150
|
+
* Whether a box the frame reported overlaps the frame's viewport (P138), before it is clamped: a
|
|
151
|
+
* box of no width or height counts where it lies strictly inside. Where the viewport isn't known,
|
|
152
|
+
* nothing is in it, as `clampRect` puts every box at the corner then.
|
|
153
|
+
*/
|
|
154
|
+
export function inViewport(
|
|
155
|
+
rect: AnnotationRect,
|
|
156
|
+
viewport: { readonly width: number; readonly height: number } | null | undefined,
|
|
157
|
+
): boolean {
|
|
158
|
+
if (viewport === null || typeof viewport !== "object") {
|
|
159
|
+
return false;
|
|
160
|
+
}
|
|
161
|
+
const { width, height } = viewport;
|
|
162
|
+
if (!Number.isFinite(width) || !Number.isFinite(height)) {
|
|
163
|
+
return false;
|
|
164
|
+
}
|
|
165
|
+
return rect.x < width && rect.x + rect.width > 0 && rect.y < height && rect.y + rect.height > 0;
|
|
166
|
+
}
|
|
167
|
+
|
|
148
168
|
const markId = (value: unknown): value is string => text(value, LIMITS.id, 1);
|
|
149
169
|
|
|
150
170
|
function results(value: unknown): AnchorResult[] | null {
|
|
@@ -280,6 +300,40 @@ export function parseReport(value: unknown): AnnotationReport | null {
|
|
|
280
300
|
...(scroll === undefined ? {} : { scroll }),
|
|
281
301
|
};
|
|
282
302
|
}
|
|
303
|
+
case "selectionTracked": {
|
|
304
|
+
// The followed selection (P138): gone, or where it is. New with its shell, so every box but
|
|
305
|
+
// the last line, and the scroll, are there; nothing about the page's words is.
|
|
306
|
+
if (value.state === "orphaned") {
|
|
307
|
+
return { type: "selectionTracked", state: "orphaned" };
|
|
308
|
+
}
|
|
309
|
+
if (value.state !== "attached" || typeof value.inView !== "boolean") {
|
|
310
|
+
return null;
|
|
311
|
+
}
|
|
312
|
+
const rect = parseRect(value.rect);
|
|
313
|
+
const documentRect = parseRect(value.documentRect);
|
|
314
|
+
const scroll = parseScroll(value.scroll);
|
|
315
|
+
const lastLineDocumentRect =
|
|
316
|
+
value.lastLineDocumentRect === undefined
|
|
317
|
+
? undefined
|
|
318
|
+
: parseRect(value.lastLineDocumentRect);
|
|
319
|
+
if (
|
|
320
|
+
rect === null ||
|
|
321
|
+
documentRect === null ||
|
|
322
|
+
scroll === null ||
|
|
323
|
+
lastLineDocumentRect === null
|
|
324
|
+
) {
|
|
325
|
+
return null;
|
|
326
|
+
}
|
|
327
|
+
return {
|
|
328
|
+
type: "selectionTracked",
|
|
329
|
+
state: "attached",
|
|
330
|
+
rect,
|
|
331
|
+
documentRect,
|
|
332
|
+
...(lastLineDocumentRect === undefined ? {} : { lastLineDocumentRect }),
|
|
333
|
+
scroll,
|
|
334
|
+
inView: value.inView,
|
|
335
|
+
};
|
|
336
|
+
}
|
|
283
337
|
default:
|
|
284
338
|
return null;
|
|
285
339
|
}
|
|
@@ -345,3 +399,16 @@ export function checkMarks(marks: readonly AnnotationMark[]): AnnotationMark[] {
|
|
|
345
399
|
};
|
|
346
400
|
});
|
|
347
401
|
}
|
|
402
|
+
|
|
403
|
+
/**
|
|
404
|
+
* Whether what `annotations.track` is given names the selection (P138): an object whose own
|
|
405
|
+
* `selection` is `true`, and nothing else does (a mark's id is a string).
|
|
406
|
+
*/
|
|
407
|
+
export const followsSelection = (
|
|
408
|
+
target: AnnotationTrackTarget | undefined,
|
|
409
|
+
): target is { readonly selection: true } =>
|
|
410
|
+
typeof target === "object" &&
|
|
411
|
+
target !== null &&
|
|
412
|
+
Object.hasOwn(target, "selection") &&
|
|
413
|
+
// A caller's word, untyped as JavaScript passes it: `true` and nothing else.
|
|
414
|
+
(target as { readonly selection?: unknown }).selection === true;
|