@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/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
|
|
@@ -1003,6 +1004,7 @@ for that to lapse and click with raw input.
|
|
|
1003
1004
|
| The keyboard: the focus guard (P109) | a move of the keyboard from one of the host page's text fields into a display's frame that the person didn't make (no press on the frame, `:active` on Chromium and WebKit, the pointer coming over it on Firefox; no Tab; no gesture the page's own events don't explain) is undone once the move is over; three while typing within 10 s, or five within 2 s, stop the display | `test/focus-guard.test.ts`; `leak/served/runtime.spec.ts`: "a page that takes the keyboard while the person types in the host's composer…", "a page that takes the keyboard back on its own blur keeps none of it…" (GK-1), "a composer the host focuses with focusField…", "the person's own moves into the frame keep the keyboard…" | `focus-guard` → the first (all three) and the next two (Firefox); `focus-guard-watch` (the watch after a take-back, the look at every frame) → those two (Firefox) |
|
|
1004
1005
|
| The runtime: `comments.open` from the frame the person is in (P109) | its `user-activation` gate also needs the host page's focus in the calling frame (`CapabilitySpec.inFrame`, `Surface.focused`), after the focus guard | `leak/served/runtime.spec.ts`: "comments.open while the person types in the host's composer reaches no handler…" | `comments-in-frame` → that case (all three) |
|
|
1005
1006
|
| A nested page: Porthole's shell above an opaque page (P111) | the framed address answers the shell alone (its own script by hash, framing and fetching only the sealed prefix); the page is its child, `sandbox="allow-scripts"` in the attribute and its CSP (never `allow-same-origin`: a static check over every sandbox Porthole writes), loaded without a cookie; the shell passes messages by `event.source`, never in its own namespace; the host takes a move into the frame, or a `comments.open`, for the person's only if the shell's activation turned on within the last second with no trusted press or key on the host's page since (or a Tab, the host's move, a press the engine shows), asking the shell to look as it hears the move; where the host's page sees the pointer over its frames, not with the pointer elsewhere within a second of typing; in a fight over a text field, a frame that takes focus again is judged without the shell and taken back at once, counted (P120); no press within 250 ms of the person's key on the host's page (P122) | `test/nested.test.ts`; `leak/served/nested.spec.ts` on full Chromium, the headless shell, WebKit and Firefox | `shell-namespace` → "the shell's words are the shell's alone…" (all three); `shell-host-input` → "a page's focus() just after the person pressed it and went back…" (all three); `pointer-rule` (P120's pointer rule out) → "an activation that came as the person typed…" (all three); `key-press` (P122's 250 ms out) → "an activation that turned on within 250 ms of the person's key…" (all three); `nested-fight` (a frame that takes focus back in a fight let be) → "a page that holds the keyboard from its load…" (Firefox); `leak/served/nested-keyboard.spec.ts` (a page that takes the keyboard as the person types: a race, no control's probe) |
|
|
1007
|
+
| A nested page's shell passes the focus on at the host's word (P136) | `display.focus()` sends `porthole/shell/focus`, only a move that landed; the shell acts only while the focus is on its own document, blurring its frame first, and a page's message in its namespace never reaches that code | `test/nested.test.ts` "the host's word that it moved the focus into a nested page's frame"; `leak/served/nested.spec.ts`: "a page that had the focus gets it back by the host's own move…", "a page that never had the focus…", "a second host's move into a page it just handed the focus to…", "the host's move into a page that holds the focus…", "the host's move from its own text field…", "the host's move takes no keyboard…", "the host's move from inside a key's own handler…" (`test.fail` on Firefox) | `shell-focus-held` |
|
|
1006
1008
|
| A nested page's shell on a label of its own (P114, porthole#56) | the shell, its page and that page's files are served on `nestedLabelOf(<scope's label>)` (`porthole-<24 base32>`, one per scope), never on the scope's label, where the scope's other displays run content with `allow-same-origin`; that label answers only frame addresses of nested pages, their sealed prefix and status pages (no clean address, entry, asset, library, app, nor another instance's ticket, cookie or sealed address), the scope's label no nested page (a clean address goes on with a one-time ticket); no host's naming makes a `porthole-` label; an entry code is no document's ticket; outside `/server` too (P121), `createHost` refuses a nested page located on any other label, the shell runs on no other origin, and `nestedShellResponse` and `frameShellScript` refuse one; `nestedFileCsp` is the page's and its files' CSP for `/server` and a Worker of a host's own | `test/nested.test.ts`, `test/entry.test.ts` ("… (P114)"; `test/nested.test.ts` "… (P121)"); `leak/served/nested-siblings.spec.ts` (`[nested-siblings]`: a same-scope inline widget and artifact read each other, not the shell; `[nested-label]`: a nested page located on its scope's label is refused, no frame made) on full Chromium, the headless shell, WebKit and Firefox; `leak/kit.spec.ts` and the prod-shape profile (the label through `nodeHost`, and through a TLS edge and DNS) | `shell-label,nested-host-label,nested-shell-origin` (the shell on the scope's label, the host's and the shell's checks out) → `[nested-siblings]`, `[nested-label]` (all three); `nested-host-label` (the host's check out) → `[nested-label]` (all three) |
|
|
1007
1009
|
| The asset library (P089, P091) | `/_blob/<id>` (or the frame's `<sealed base>__porthole/blob/<id>`) for an access to its artifact (a cookie, a sealed `Referer`, the sealed path), then the host's check, the store asked with it; typed by name, never a page, code only where trusted and uploaded code may run (asked at each load; by id alone, every artifact config must, P103), inert CSP, CORP, revalidated; the page's CSP opens `<origin>/_blob/` for images, media, fonts and data, for scripts and styles only where uploads are the admins' | `test/assets.test.ts` (a forged same-origin claim: 401; another artifact's session: 404; revoked: 403; bearer mode; a stricter config turns trusted code into a download, bearer mode too); `leak/served/runtime.spec.ts`: an upload loads in its frame; a set's page loads it; static `/_blob/` in a frame by `Referer` (Chromium, Firefox; WebKit sends only the origin: measured); "a script asset runs as code only if an admin uploaded it"; "scripts load from /_blob/ only where uploads are the admins'"; "an asset reaches only its own artifact's pages"; "an asset opened on its own runs nothing" | `blob-trusted` → the trusted-code case; `blob-script,blob-trusted` (two walls) → that case and the tab's CSP case; `blob-inert` → the opened-on-its-own case (all three; `scripts/controls.ts`) |
|
|
1008
1010
|
| Workers (P044, P045) | no Node module in `/server`; D1 tickets taken by one `DELETE … RETURNING` | `test/workers.test.ts` (workerd, no `nodejs_compat`, real D1: once per ticket, a race, anonymous, a revocation, flat names, reserved namespaces) | — |
|
|
@@ -1047,13 +1049,14 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1047
1049
|
| host → frame | `porthole/annotate.focus` | `{ id }`: scrolled into view inside the frame, made the active mark, flashed |
|
|
1048
1050
|
| host → frame | `porthole/annotate.clear` | — |
|
|
1049
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) |
|
|
1050
|
-
| host → frame | `porthole/annotate.focusMark` | `{ id }
|
|
1051
|
-
| frame → host | `porthole/annotate.selected` | `{ anchor, rect, lastLineDocumentRect?, scroll? }` (a newer shell's last two: P133, below); after a scroll, the same selection again only if its box moved more than 0.5 px, on the follow-ups' clock (P105) |
|
|
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()` |
|
|
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) |
|
|
1052
1054
|
| frame → host | `porthole/annotate.unselected` | — (the text selection went away) |
|
|
1053
1055
|
| frame → host | `porthole/annotate.cancelled` | — (Escape) |
|
|
1054
|
-
| 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): 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) |
|
|
1055
|
-
| host → frame | `porthole/annotate.track` | `{ id }` or `{ id: null }`: follow one shown mark, or none (P112) |
|
|
1056
|
-
| 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) |
|
|
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) |
|
|
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) |
|
|
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) |
|
|
1057
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) |
|
|
1058
1061
|
|
|
1059
1062
|
- **Anchors** are W3C Web Annotation selectors, at most one of each:
|
|
@@ -1091,6 +1094,25 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1091
1094
|
of the words' client rects, the box a text marker's place starts from; an element,
|
|
1092
1095
|
which has no lines of its own, gives its whole box. Its place in the frame's viewport
|
|
1093
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.
|
|
1094
1116
|
- **Markers** (P104). A mark with a `count` gets a bubble glyph and its number ("99+"
|
|
1095
1117
|
above 99; 0 the bubble alone), a real button (P133, below), on an element's top right
|
|
1096
1118
|
corner, inside the frame's width, and at the end of a text anchor's paragraph (P133):
|
|
@@ -1195,8 +1217,14 @@ it through redraws, reached by the host's `focusMark` after its card closed and
|
|
|
1195
1217
|
alone where there's no such marker, by the kept `focus` (P134, `marker-focus`), a call parked meanwhile
|
|
1196
1218
|
dropped once the person has moved on or the focus is on the host's body, and a second after the
|
|
1197
1219
|
host's `display.focus()` landing (P135, `marker-late`), by the kept
|
|
1198
|
-
`hasFocus`, which a page's patch can't answer (`marker-has-focus`)
|
|
1199
|
-
|
|
1220
|
+
`hasFocus`, which a page's patch can't answer (`marker-has-focus`), a word a busy page takes late
|
|
1221
|
+
held to the same test, by the host's stamp and the kept clock, a calm close landing, and a second
|
|
1222
|
+
word after the host's move landing (P137, `marker-busy`, `marker-clock`, in
|
|
1223
|
+
`nested-late-word.spec.ts` so that full Chromium runs it, where a person's click comes before the
|
|
1224
|
+
word); on a nested page a parked call lands while the focus is in the page, not once the person has
|
|
1225
|
+
moved on (`marker-late`), a late word not either (`marker-busy`), and after
|
|
1226
|
+
the host's move, which the shell passes on (P136, `shell-focus-held`; on Firefox not from inside a
|
|
1227
|
+
key's own handler, `test.fail`), at its paragraph's end past the last word, a nested block's
|
|
1200
1228
|
words not its own, a draft's by its words; focus and
|
|
1201
1229
|
selection kept, a drag from a marker too (`marker-prevent` → the press case), none
|
|
1202
1230
|
without a count, stepping aside while picking, drawn whole at the frame's top; a
|
|
@@ -1539,8 +1567,10 @@ control the tables above name to the registry):
|
|
|
1539
1567
|
| `marker-place` | `annotate.spec.ts` | `text markers cover no word: on a column page, and on a phone's lines with one marker each (P105, #36)` | — | — |
|
|
1540
1568
|
| `marker-key` | `annotate.spec.ts` | `a marker is a button the keyboard reaches: Tab in reading order, Enter and Space report it once, the content hears neither, and it steps aside while elements are picked (P133)` | — | — |
|
|
1541
1569
|
| `marker-focus` | `annotate.spec.ts` | `a page that patched focus isn't handed the marker the host's focusMark moves to (P134)` | — | — |
|
|
1542
|
-
| `marker-late` | `annotate.spec.ts` | `a parked focusMark doesn't land once the person has moved on to the host's button (P135)`, `a focusMark parked with the focus in the frame doesn't land once the person moves on while it waits (P135)`, `a parked focusMark with the focus on the host's body is dropped; after the host's own move into the frame a second one, parked too, lands on the marker (P135)`, `a page that patched hasFocus to say yes gets no landing the platform's own answer refuses (P135)` | — | — |
|
|
1543
|
-
| `marker-
|
|
1570
|
+
| `marker-late` | `annotate.spec.ts`, `served/nested.spec.ts` | `a parked focusMark doesn't land once the person has moved on to the host's button (P135)`, `a focusMark parked with the focus in the frame doesn't land once the person moves on while it waits (P135)`, `a parked focusMark with the focus on the host's body is dropped; after the host's own move into the frame a second one, parked too, lands on the marker (P135)`, `a page that patched hasFocus to say yes gets no landing the platform's own answer refuses (P135)`, `a parked focusMark doesn't land on a nested page once the person has moved on to the host's button (P135)` | — | — |
|
|
1571
|
+
| `marker-busy` | `nested-late-word.spec.ts`, `served/nested.spec.ts` | `a focusMark a busy page takes late doesn't land once the host's page has moved on (P137)`, `a page that stopped Date.now gets no landing for a word it took late (P137)`, `a page that patched hasFocus to say yes gets no landing for a word it took late (P137)`, `a focusMark a busy nested page takes late doesn't land once the host's page has moved on (P137)` | — | — |
|
|
1572
|
+
| `marker-clock` | `nested-late-word.spec.ts` | `a page that stopped Date.now gets no landing for a word it took late (P137)` | — | — |
|
|
1573
|
+
| `marker-has-focus` | `annotate.spec.ts`, `nested-late-word.spec.ts` | `a page that patched hasFocus to say yes gets no landing the platform's own answer refuses (P135)`, `a page that patched hasFocus to say yes gets no landing for a word it took late (P137)` | — | — |
|
|
1544
1574
|
| `marker-originals` | `annotate.spec.ts` | `a page that patches the event's built-ins neither hears a marker's press nor stops its report (P105)` | — | — |
|
|
1545
1575
|
| `follow-throttle` | `annotate.spec.ts` | `an honest scroll session, long, in comment mode, leaves room for a marker's click: follow-ups, the selection's too, at most one a second` | — | — |
|
|
1546
1576
|
| `selection-follow` | `annotate.spec.ts` | `an honest scroll session, long, in comment mode, leaves room for a marker's click: follow-ups, the selection's too, at most one a second` | — | — |
|
|
@@ -1576,6 +1606,7 @@ control the tables above name to the registry):
|
|
|
1576
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` | — | — |
|
|
1577
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` | — | — |
|
|
1578
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)` | — | — |
|
|
1579
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)` | — | — |
|
|
1580
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)` | — | — |
|
|
1581
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)` | — | — |
|
|
@@ -1585,6 +1616,7 @@ control the tables above name to the registry):
|
|
|
1585
1616
|
| `door-opaque` | `served/siblings-status.spec.ts` | `[door-reach]` | — | — |
|
|
1586
1617
|
| `frame-status-order` | `served/outcome.spec.ts` | `a nested page that says it is blocked, through its shell or past it, is told nothing and shown nothing (P124)` | — | — |
|
|
1587
1618
|
| `shell-namespace` | `served/nested.spec.ts` | `the shell's words are the shell's alone: a page that says them, to its parent or to the host's window, moves nothing` | — | — |
|
|
1619
|
+
| `shell-focus-held` | `served/nested.spec.ts` | `the host's move takes no keyboard from where the host's page went on to in the same task (P136)`, `a second host's move into a page it just handed the focus to leaves it there: no blur, and its field keeps the keyboard (P136)` | — | — |
|
|
1588
1620
|
| `shell-label,nested-host-label,nested-shell-origin` | `served/nested-siblings.spec.ts` | `[nested-siblings]`, `[nested-label]` | — | — |
|
|
1589
1621
|
| `nested-host-label` | `served/nested-siblings.spec.ts` | `[nested-label]` | — | — |
|
|
1590
1622
|
| `nested-shell-origin` | `served/nested-siblings.spec.ts` | nothing | — | the host's mount refuses a shell located on any other label first, and /server serves none there (`shell-label,nested-host-label,nested-shell-origin`) |
|
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
|
|
@@ -37,8 +37,11 @@ reports `activated`, which the page could already fake; `lastLineDocumentRect` i
|
|
|
37
37
|
host to clip as P132's are; no wall moves. 0.14.12: P134 adds `annotations.focusMark(id)`, the host's
|
|
38
38
|
word to put the keyboard back on a marker, and a second exception to "takes no focus" whose conditions
|
|
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
|
-
in the frame's document by then; a call on a calm page is unchanged.
|
|
41
|
-
|
|
40
|
+
in the frame's document by then; a call on a calm page is unchanged. 0.14.14: P136 brings `display.focus()`
|
|
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. 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.
|
|
42
45
|
|
|
43
46
|
## 1. Two layers
|
|
44
47
|
|
|
@@ -212,8 +215,9 @@ Whatever the use:
|
|
|
212
215
|
app with egress, S5, unless you accept it). Take its counts as the bar's numbers, and open your
|
|
213
216
|
bar on `findRequested`, nothing more (§7 "Find in page").
|
|
214
217
|
- Guard a view that a frame's report opens or moves (`activated`, `anchored`, `selected`,
|
|
215
|
-
`tracked`: a comment's bubble, a composer, a card that follows its mark,
|
|
216
|
-
|
|
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
|
|
217
221
|
under a press the person meant for the content (a double click on the content's own button whose
|
|
218
222
|
second click lands on the bubble's). Such a view takes no press of any kind for 500 ms after it
|
|
219
223
|
appears or moves (not a `click` only: menu triggers act on `pointerdown`, and menu items click
|
|
@@ -235,7 +239,10 @@ Whatever the use:
|
|
|
235
239
|
it reads its own page's `document.activeElement` and that is this frame; the focus goes only to a
|
|
236
240
|
container that takes no input (`tabindex="-1"`), never a field or a button; and every control in
|
|
237
241
|
that view that can write has the host's own gate, so that a forged opening and the keys right after
|
|
238
|
-
it can't submit.
|
|
242
|
+
it can't submit. The gate covers keys as well as controls: with the focus in that view the person's
|
|
243
|
+
next keys reach the host's document, so the view's own key handlers and the host's page-wide
|
|
244
|
+
shortcuts that write (an `r` that resolves, Cmd+Enter that posts) need it too (P137). That's the
|
|
245
|
+
host's duty: Porthole doesn't guarantee it.
|
|
239
246
|
- Know that a display can take the keyboard: a page calls `focus()` on its own input whenever it
|
|
240
247
|
likes (on Chromium and WebKit with no gesture), and what the person goes on typing goes to it.
|
|
241
248
|
`createHost` (every `PortholeView` too) gives focus back when it leaves one of the page's text
|
|
@@ -246,13 +253,16 @@ Whatever the use:
|
|
|
246
253
|
a fighting frame holds focus); and with a platform of your own, implement its focus guard
|
|
247
254
|
(`focused`, `onFocusTaken`, `focus`) or accept that a display can read what is typed beside it.
|
|
248
255
|
- Call `annotations.focusMark(id)` only as the person's key closes your view of that mark, and know
|
|
249
|
-
it can be dropped (P135): one that has to wait while the frame finds its marks
|
|
250
|
-
|
|
256
|
+
it can be dropped (P135, P137): one that has to wait while the frame finds its marks, or that the
|
|
257
|
+
frame takes more than 100 ms after you sent it because its page is busy, lands only if the focus
|
|
258
|
+
is in the frame by then, and in the normal flow it is on your `<body>`. Nothing says so. If
|
|
251
259
|
the focus is still on your body a moment later, the person hasn't moved on: `display.focus()`,
|
|
252
260
|
then `focusMark(id)` again. Look first: that move is yours, the focus guard doesn't judge it, and
|
|
253
|
-
a move after the person went on to a button of yours takes the keyboard from them.
|
|
254
|
-
(
|
|
255
|
-
|
|
261
|
+
a move after the person went on to a button of yours takes the keyboard from them. On a nested
|
|
262
|
+
page, use `display.focus()`: it tells the page's shell to pass the focus on (P136), and the frame's
|
|
263
|
+
own `focus()` stops at the shell, so a word that waits is dropped even after it. On Firefox,
|
|
264
|
+
`display.focus()` inside a key's own handler moves nothing: call it from a task (measured on a
|
|
265
|
+
nested page). Nothing leaks either way: the keyboard stays out of the page.
|
|
256
266
|
- List every app origin in `appOrigins` (`hostOrigins` in `/server`): only those may frame content,
|
|
257
267
|
and only those are checked against the content domain for a shared site.
|
|
258
268
|
- Under the app runtime, run `defineRuntimeConformance` with `api` in CI (§7).
|
|
@@ -848,7 +858,14 @@ own frame, below the shell, P111), so:
|
|
|
848
858
|
the frame as well (accepted, P132; the host's duty in §6). They say nothing else: the page knows
|
|
849
859
|
where its words are anyway. Where a selection or a mark's words end (`lastLineDocumentRect` in
|
|
850
860
|
`selected`, `anchored` and `tracked`, P133) is one more such box, read, checked and left unclamped
|
|
851
|
-
the same way, with the same duty; `selected` also carries `scroll` now.
|
|
861
|
+
the same way, with the same duty; `selected` also carries `scroll` now. A report with a last line
|
|
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.
|
|
852
869
|
- *What holds, against content that patches none of the DOM's or JavaScript's built-ins.* A real
|
|
853
870
|
press or click on a marker reaches none of the content's handlers (the shell's first listener
|
|
854
871
|
stops it; control `marker-click`) and moves neither focus nor a selection (control
|
|
@@ -886,7 +903,7 @@ own frame, below the shell, P111), so:
|
|
|
886
903
|
`activated` while the person really is in the frame, and this signal doesn't stop that.** A host
|
|
887
904
|
that moves the keyboard into its view on the signal takes §6's second exception, with its
|
|
888
905
|
conditions: a page can put the person's next keys in that view, and keeping those keys from posting
|
|
889
|
-
is the host's own gate on that view's controls, not Porthole's.
|
|
906
|
+
is the host's own gate on that view's controls and on its shortcuts, not Porthole's.
|
|
890
907
|
- *Back to a marker* (P134). `annotations.focusMark(id)` is the host's word to the frame
|
|
891
908
|
(`porthole/annotate.focusMark`, `{ id }`), for one moment only: after the keyboard closed the host's
|
|
892
909
|
own view of that mark, by Escape or by a Tab past its first or last control. No content goes with it, beyond an id the frame has, and nothing comes back. The
|
|
@@ -898,15 +915,23 @@ own frame, below the shell, P111), so:
|
|
|
898
915
|
host's text field that still has focus it is undone and counted (P109), not passed as the host's:
|
|
899
916
|
no window was opened in the guard for it.
|
|
900
917
|
A word that has to wait while the frame finds its marks is up to a second old when it could land
|
|
901
|
-
(P135)
|
|
902
|
-
|
|
903
|
-
|
|
904
|
-
|
|
905
|
-
|
|
906
|
-
|
|
918
|
+
(P135). A word the shell doesn't park can be as old: the frame takes it when its thread is free, a
|
|
919
|
+
busy page changes nothing the shell can see, and a frame out of process doesn't stop the host's
|
|
920
|
+
page meanwhile (P137). A marker's `focus()` takes the keyboard with no gesture on Chromium and
|
|
921
|
+
WebKit, past a guard that defends only text fields: a person gone on to a host's button would be
|
|
922
|
+
pulled back. So the shell drops a parked word unless the focus is in its document as it lands, and
|
|
923
|
+
a word older than 100 ms unless the focus is there as it comes, by `hasFocus` as it was before
|
|
924
|
+
content ran (control `marker-has-focus`: a page that replaced it to say yes gets the landing
|
|
925
|
+
otherwise; `marker-late` takes the first test out, `marker-busy` the second). A word's age is the
|
|
926
|
+
shell's `Date.now` as it was before content ran, less the stamp `createHost` put on it as it was
|
|
927
|
+
sent (`at`): one machine's wall clock (control `marker-clock`: a page that stopped its own clock
|
|
928
|
+
makes a late word look fresh otherwise). A word with no stamp, from an older host, is old. A fresh
|
|
929
|
+
word isn't asked: the frame has no focus then on the very path it is for. That leaves a person who
|
|
930
|
+
moves on within those 100 ms, faster than a person does, and a page that forges the whole word with
|
|
931
|
+
a fresh stamp, or rewrites a real word as it arrives, as it can forge the word at all, which gives it nothing (P134). A page
|
|
907
932
|
can really take the focus and so pass the test, which gives it nothing, since it then has the
|
|
908
|
-
keyboard; and a
|
|
909
|
-
the frame. §6 has the host's side: a second `focusMark` after its own `display.focus()`.
|
|
933
|
+
keyboard; and a word that passes it can still move the focus off the page's own field onto a marker,
|
|
934
|
+
inside the frame. §6 has the host's side: a second `focusMark` after its own `display.focus()`.
|
|
910
935
|
The word is a message, so from the host's close until the frame moves, the focus rests on the host's
|
|
911
936
|
body. A forged `activated` in that gap finds no frame focused, so a host that gates a view on "the
|
|
912
937
|
frame had the focus" doesn't gate that one. That is accepted, on the host's side of the wall: such
|
|
@@ -1043,7 +1068,8 @@ unposted words beside the frame and tell the page when.
|
|
|
1043
1068
|
since; or a Tab, the host's own move, or a press the engine shows on the frame element. Nothing
|
|
1044
1069
|
else counts as a press: no pointer over the frame, no host-wide activation. A move the shell
|
|
1045
1070
|
hasn't spoken of yet waits for its word at most 500 ms (the host asks it to look at once,
|
|
1046
|
-
`porthole/shell/look`), then is taken back.
|
|
1071
|
+
`porthole/shell/look`), then is taken back. The shell passes a focus on to the page by the host's
|
|
1072
|
+
word (`porthole/shell/focus`, P136), which only `display.focus()` sends and no page can say. A key the person types into the page turns its
|
|
1047
1073
|
activation on as a press does, so (P120, after the audit of P111's guard, NG-1): where the
|
|
1048
1074
|
host's page sees the pointer over its frames (Firefox; Chromium and WebKit where the frame is in
|
|
1049
1075
|
their process, once the pointer has been over one), an activation while the pointer isn't over
|
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
|
|
@@ -137,7 +144,8 @@ export interface AnchorResult {
|
|
|
137
144
|
* Where its last line is in the document (P133), in the coordinates of `documentRect` and as
|
|
138
145
|
* unclamped: its last line with words on it for text, its whole box for an element, which has no
|
|
139
146
|
* lines of its own. For a host's UI after the last line (its right, or its bottom). Absent from
|
|
140
|
-
* an older shell, and where nothing of the mark is drawn.
|
|
147
|
+
* an older shell, and where nothing of the mark is drawn. Never without its report's `scroll`
|
|
148
|
+
* (a report that tries is dropped, P137). The page's word.
|
|
141
149
|
*/
|
|
142
150
|
readonly lastLineDocumentRect?: AnnotationRect;
|
|
143
151
|
/**
|
|
@@ -154,7 +162,8 @@ export type AnnotationReport =
|
|
|
154
162
|
* The person pointed at an element or settled a text selection. A newer shell (P133) adds where
|
|
155
163
|
* it ends, for a host's UI after its last line: `lastLineDocumentRect` as a result's is, with
|
|
156
164
|
* how far the document was scrolled as it was read (so its place in the frame's viewport is the
|
|
157
|
-
* one less the other, unclamped). Both absent from an older shell
|
|
165
|
+
* one less the other, unclamped). Both absent from an older shell, and never one alone (a report
|
|
166
|
+
* that tries is dropped, P137).
|
|
158
167
|
*/
|
|
159
168
|
| {
|
|
160
169
|
readonly type: "selected";
|
|
@@ -196,7 +205,8 @@ export type AnnotationReport =
|
|
|
196
205
|
* document scrolls, so a host following one mark hears the scroll at every animation frame where
|
|
197
206
|
* it changed, whether that mark is in the frame or not, and places every mark it holds a
|
|
198
207
|
* `documentRect` for (an `anchored` report's) without asking again. A newer one still (P133) adds
|
|
199
|
-
* its `lastLineDocumentRect
|
|
208
|
+
* its `lastLineDocumentRect`, never without `scroll` (a report that tries is dropped, P137), though
|
|
209
|
+
* `scroll` comes without it.
|
|
200
210
|
*/
|
|
201
211
|
| {
|
|
202
212
|
readonly type: "tracked";
|
|
@@ -206,6 +216,30 @@ export type AnnotationReport =
|
|
|
206
216
|
readonly lastLineDocumentRect?: AnnotationRect;
|
|
207
217
|
readonly scroll?: AnnotationScroll;
|
|
208
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" }
|
|
209
243
|
/**
|
|
210
244
|
* The person clicked the marker of a mark the host shows with a `count` (P104), or of a draft
|
|
211
245
|
* (P107), or pressed Enter or Space on it (P133); `rect` is the marker's box, to open the host's
|
|
@@ -234,10 +268,16 @@ export const ANNOTATE_METHODS = {
|
|
|
234
268
|
anchored: "porthole/annotate.anchored",
|
|
235
269
|
/** Frame → host: a mark's marker was clicked, or pressed from the keyboard (P104, P133). */
|
|
236
270
|
activated: "porthole/annotate.activated",
|
|
237
|
-
/**
|
|
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
|
+
*/
|
|
238
276
|
track: "porthole/annotate.track",
|
|
239
277
|
/** Frame → host: the followed mark's box, as it moves (P112). */
|
|
240
278
|
tracked: "porthole/annotate.tracked",
|
|
279
|
+
/** Frame → host: where the followed selection is, as it moves (P138). */
|
|
280
|
+
selectionTracked: "porthole/annotate.selectionTracked",
|
|
241
281
|
/** Host → frame: take the page's text selection away, telling nothing back (P115). */
|
|
242
282
|
clearSelection: "porthole/annotate.clearSelection",
|
|
243
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 {
|
|
@@ -192,6 +212,15 @@ function results(value: unknown): AnchorResult[] | null {
|
|
|
192
212
|
return out;
|
|
193
213
|
}
|
|
194
214
|
|
|
215
|
+
/**
|
|
216
|
+
* A last line with nothing to read it by (P137): its place in the frame's viewport is its own less
|
|
217
|
+
* the scroll it was read at, so a shell sends no last line without one, and a host needn't test for
|
|
218
|
+
* both. The scroll alone is a shell's own: 0.14.10's `tracked` and `anchored` (P132, no last line yet),
|
|
219
|
+
* and a newer one's where nothing of the mark is drawn.
|
|
220
|
+
*/
|
|
221
|
+
const lineWithoutScroll = (line: AnnotationRect | undefined, scroll: unknown): boolean =>
|
|
222
|
+
line !== undefined && scroll === undefined;
|
|
223
|
+
|
|
195
224
|
/** A report from the frame, checked; null if malformed (it is then dropped). */
|
|
196
225
|
export function parseReport(value: unknown): AnnotationReport | null {
|
|
197
226
|
if (!isRecord(value)) {
|
|
@@ -210,6 +239,10 @@ export function parseReport(value: unknown): AnnotationReport | null {
|
|
|
210
239
|
if (anchor === null || rect === null || lastLineDocumentRect === null || scroll === null) {
|
|
211
240
|
return null;
|
|
212
241
|
}
|
|
242
|
+
// A pair, here (P137): a selection has never had one without the other.
|
|
243
|
+
if ((lastLineDocumentRect === undefined) !== (scroll === undefined)) {
|
|
244
|
+
return null;
|
|
245
|
+
}
|
|
213
246
|
return {
|
|
214
247
|
type: "selected",
|
|
215
248
|
anchor,
|
|
@@ -225,9 +258,14 @@ export function parseReport(value: unknown): AnnotationReport | null {
|
|
|
225
258
|
case "anchored": {
|
|
226
259
|
const checked = results(value.results);
|
|
227
260
|
const scroll = value.scroll === undefined ? undefined : parseScroll(value.scroll);
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
261
|
+
if (
|
|
262
|
+
checked === null ||
|
|
263
|
+
scroll === null ||
|
|
264
|
+
checked.some((each) => lineWithoutScroll(each.lastLineDocumentRect, scroll))
|
|
265
|
+
) {
|
|
266
|
+
return null;
|
|
267
|
+
}
|
|
268
|
+
return { type: "anchored", results: checked, ...(scroll === undefined ? {} : { scroll }) };
|
|
231
269
|
}
|
|
232
270
|
case "activated": {
|
|
233
271
|
const rect = parseRect(value.rect);
|
|
@@ -248,7 +286,8 @@ export function parseReport(value: unknown): AnnotationReport | null {
|
|
|
248
286
|
rect === null ||
|
|
249
287
|
documentRect === null ||
|
|
250
288
|
lastLineDocumentRect === null ||
|
|
251
|
-
scroll === null
|
|
289
|
+
scroll === null ||
|
|
290
|
+
lineWithoutScroll(lastLineDocumentRect, scroll)
|
|
252
291
|
) {
|
|
253
292
|
return null;
|
|
254
293
|
}
|
|
@@ -261,6 +300,40 @@ export function parseReport(value: unknown): AnnotationReport | null {
|
|
|
261
300
|
...(scroll === undefined ? {} : { scroll }),
|
|
262
301
|
};
|
|
263
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
|
+
}
|
|
264
337
|
default:
|
|
265
338
|
return null;
|
|
266
339
|
}
|
|
@@ -326,3 +399,16 @@ export function checkMarks(marks: readonly AnnotationMark[]): AnnotationMark[] {
|
|
|
326
399
|
};
|
|
327
400
|
});
|
|
328
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;
|