@botiverse/porthole 0.14.11 → 0.14.13
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 +28 -0
- package/dist/annotate/types.d.ts +7 -2
- package/dist/annotate/types.js +5 -0
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +8 -0
- package/dist/host/types.d.ts +19 -0
- package/dist/react/frame.d.ts +8 -0
- package/dist/react/frame.js +6 -0
- package/dist/react/view.js +1 -0
- package/dist/shell/annotate.d.ts +14 -3
- package/dist/shell/annotate.js +70 -10
- package/docs/ADOPTING.md +58 -4
- package/docs/DECISIONS.md +236 -1
- package/docs/DESIGN.md +17 -8
- package/docs/THREAT_MODEL.md +59 -5
- package/package.json +1 -1
- package/src/annotate/types.ts +7 -2
- package/src/host/create-host.ts +8 -0
- package/src/host/types.ts +19 -0
- package/src/react/frame.tsx +14 -0
- package/src/react/view.tsx +1 -0
- package/src/shell/annotate.ts +71 -10
package/docs/DESIGN.md
CHANGED
|
@@ -780,8 +780,8 @@ binding is mounting and lifecycle (P034).
|
|
|
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
782
|
(the mark followed, or null, P118); `onAnnotation` gets what the frame reported, `tracked`
|
|
783
|
-
boxes too. A frame that mounts again gets them all. A `ref` holds `clearSelection()`
|
|
784
|
-
(`PortholeFrameHandle`), a no-op while no display runs.
|
|
783
|
+
boxes too. A frame that mounts again gets them all. A `ref` holds `clearSelection()`, `find`,
|
|
784
|
+
`clearFind` and `focusMark(id)` (`PortholeFrameHandle`), each a no-op while no display runs.
|
|
785
785
|
- **Errors** (P055): `onContentError` gets what the content did wrong (what it
|
|
786
786
|
threw, what the sandbox blocked, a navigation the shell stopped, that it kept
|
|
787
787
|
navigating away): the agent's to hear. `onNavigationBlocked` gets a stopped
|
|
@@ -1047,6 +1047,7 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1047
1047
|
| host → frame | `porthole/annotate.focus` | `{ id }`: scrolled into view inside the frame, made the active mark, flashed |
|
|
1048
1048
|
| host → frame | `porthole/annotate.clear` | — |
|
|
1049
1049
|
| 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 }`: 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; on a nested page that had the focus the host's `display.focus()` doesn't bring it back, a known gap), one that didn't wait 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()` |
|
|
1050
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) |
|
|
1051
1052
|
| frame → host | `porthole/annotate.unselected` | — (the text selection went away) |
|
|
1052
1053
|
| frame → host | `porthole/annotate.cancelled` | — (Escape) |
|
|
@@ -1126,8 +1127,8 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1126
1127
|
while elements are picked, the keyboard's Tab too.
|
|
1127
1128
|
- **Markers from the keyboard** (P133). Each marker is a `<button>` with a tab stop,
|
|
1128
1129
|
in the page's reading order after the page's own stops (the layer is the document's
|
|
1129
|
-
last child), named for what it is (`aria-label`:
|
|
1130
|
-
…"
|
|
1130
|
+
last child), named for what it is (`aria-label`: `3 comments on "…"`, `Draft comment
|
|
1131
|
+
on "…"`, with the words it is on, an element's tag left out, P134, in English); only the markers are exposed to
|
|
1131
1132
|
assistive technology, the layer no longer `aria-hidden`, its marks and outline are.
|
|
1132
1133
|
A press of a pointer still moves no focus. Enter and Space make the button's own
|
|
1133
1134
|
trusted click, which goes the way a pointer's does, but has no count and no place, so
|
|
@@ -1172,9 +1173,9 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1172
1173
|
see or do anything. A view a report opens or moves guards its presses
|
|
1173
1174
|
(THREAT_MODEL §6).
|
|
1174
1175
|
- **Host API.** `display.annotations.start(mode?)`, `stop()`, `show(marks)`,
|
|
1175
|
-
`focus(id)`, `track(id)`, `clear()`, `clearSelection()` (P115), and the
|
|
1176
|
-
event (`AnnotationReport`); the state is given to every frame the display runs (not a
|
|
1177
|
-
`clearSelection`: a new frame has no selection). `parseAnchor` checks an anchor a host
|
|
1176
|
+
`focus(id)`, `track(id)`, `clear()`, `clearSelection()` (P115), `focusMark(id)` (P134), and the
|
|
1177
|
+
`annotation` event (`AnnotationReport`); the state is given to every frame the display runs (not a
|
|
1178
|
+
`clearSelection`: a new frame has no selection; nor a `focusMark`). `parseAnchor` checks an anchor a host
|
|
1178
1179
|
stores (its server, before saving a comment).
|
|
1179
1180
|
|
|
1180
1181
|
Tests (`leak/annotate.spec.ts`, all three engines): a pick outlines and picks
|
|
@@ -1190,7 +1191,12 @@ double, right or middle click (`marker-click` → those two cases), by the keybo
|
|
|
1190
1191
|
too (P133: a button in reading order and named for what it is, Enter and Space
|
|
1191
1192
|
reported once, a key held down once, none of it heard, nothing while elements are
|
|
1192
1193
|
picked; `marker-key`, `marker-click` too), brought into view by the focus and keeping
|
|
1193
|
-
it through redraws,
|
|
1194
|
+
it through redraws, reached by the host's `focusMark` after its card closed and left
|
|
1195
|
+
alone where there's no such marker, by the kept `focus` (P134, `marker-focus`), a call parked meanwhile
|
|
1196
|
+
dropped once the person has moved on or the focus is on the host's body, and a second after the
|
|
1197
|
+
host's `display.focus()` landing (P135, `marker-late`), by the kept
|
|
1198
|
+
`hasFocus`, which a page's patch can't answer (`marker-has-focus`); on a nested page a parked call
|
|
1199
|
+
lands while the focus is in the page, and that host's move is a known gap (`test.fail`, P135), at its paragraph's end past the last word, a nested block's
|
|
1194
1200
|
words not its own, a draft's by its words; focus and
|
|
1195
1201
|
selection kept, a drag from a marker too (`marker-prevent` → the press case), none
|
|
1196
1202
|
without a count, stepping aside while picking, drawn whole at the frame's top; a
|
|
@@ -1532,6 +1538,9 @@ control the tables above name to the registry):
|
|
|
1532
1538
|
| `marker-prevent` | `annotate.spec.ts` | `a marker's press, of any kind, moves nothing of the content's: no handler, no focus, no selection` | — | — |
|
|
1533
1539
|
| `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)` | — | — |
|
|
1534
1540
|
| `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
|
+
| `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-has-focus` | `annotate.spec.ts` | `a page that patched hasFocus to say yes gets no landing the platform's own answer refuses (P135)` | — | — |
|
|
1535
1544
|
| `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)` | — | — |
|
|
1536
1545
|
| `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` | — | — |
|
|
1537
1546
|
| `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` | — | — |
|
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.13 (2026-11-06). 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
|
|
@@ -34,7 +34,11 @@ draws from them to its own region (§6, §7); `rect` stays clamped and no wall m
|
|
|
34
34
|
makes markers buttons in the frame's Tab order, reversing P104's "no tab stop": the page shares that
|
|
35
35
|
order, so it can steer or spoil the focus, and a host keeps its own list of marks (§7). A press only
|
|
36
36
|
reports `activated`, which the page could already fake; `lastLineDocumentRect` is unclamped, for a
|
|
37
|
-
host to clip as P132's are; no wall moves.
|
|
37
|
+
host to clip as P132's are; no wall moves. 0.14.12: P134 adds `annotations.focusMark(id)`, the host's
|
|
38
|
+
word to put the keyboard back on a marker, and a second exception to "takes no focus" whose conditions
|
|
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. Known gap: a nested page that had the
|
|
41
|
+
focus doesn't get it back from `display.focus()` (§6).
|
|
38
42
|
|
|
39
43
|
## 1. Two layers
|
|
40
44
|
|
|
@@ -227,6 +231,11 @@ Whatever the use:
|
|
|
227
231
|
when `selected` comes, so what it can do with that moment is put the person's next keys into a
|
|
228
232
|
draft they see and can discard, never send one; outside such a mode, or for a composer that can
|
|
229
233
|
send, it takes no focus.
|
|
234
|
+
A second exception (P134): a host may move focus into a view a report opened if all of these hold:
|
|
235
|
+
it reads its own page's `document.activeElement` and that is this frame; the focus goes only to a
|
|
236
|
+
container that takes no input (`tabindex="-1"`), never a field or a button; and every control in
|
|
237
|
+
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. That's the host's duty: Porthole doesn't guarantee it.
|
|
230
239
|
- Know that a display can take the keyboard: a page calls `focus()` on its own input whenever it
|
|
231
240
|
likes (on Chromium and WebKit with no gesture), and what the person goes on typing goes to it.
|
|
232
241
|
`createHost` (every `PortholeView` too) gives focus back when it leaves one of the page's text
|
|
@@ -236,6 +245,14 @@ Whatever the use:
|
|
|
236
245
|
your composer with `focusField(field)`, not the field's own `focus()` (Firefox ignores that while
|
|
237
246
|
a fighting frame holds focus); and with a platform of your own, implement its focus guard
|
|
238
247
|
(`focused`, `onFocusTaken`, `focus`) or accept that a display can read what is typed beside it.
|
|
248
|
+
- 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 lands only if the
|
|
250
|
+
focus is in the frame by then, and in the normal flow it is on your `<body>`. Nothing says so. If
|
|
251
|
+
the focus is still on your body a moment later, the person hasn't moved on: `display.focus()`,
|
|
252
|
+
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. A known gap
|
|
254
|
+
(P135): on a nested page that had the focus, `display.focus()` doesn't bring it back, so a word
|
|
255
|
+
that waits is dropped even then. Nothing leaks: the keyboard stays out of the page.
|
|
239
256
|
- List every app origin in `appOrigins` (`hostOrigins` in `/server`): only those may frame content,
|
|
240
257
|
and only those are checked against the content domain for a shared site.
|
|
241
258
|
- Under the app runtime, run `defineRuntimeConformance` with `api` in CI (§7).
|
|
@@ -856,9 +873,46 @@ own frame, below the shell, P111), so:
|
|
|
856
873
|
power but `activated`, which it can fake anyway within the host's checks, keys go to a marker only
|
|
857
874
|
while the frame has the focus, so nothing typed in the host passes through it (P109 is unchanged),
|
|
858
875
|
and a page's made-up key or `click()` is no trusted click. Assistive technology now reads the
|
|
859
|
-
marker's name, the page's own words
|
|
860
|
-
|
|
861
|
-
seen: its own list of marks is the
|
|
876
|
+
marker's name, the page's own words after the shell's, in quotes that bound nothing (P134: a
|
|
877
|
+
text anchor's `label`, an element's quote, or what follows the tag in its `label`). A host can't
|
|
878
|
+
rely on a marker being reached, as it can't on one being seen: its own list of marks is the
|
|
879
|
+
keyboard way that holds.
|
|
880
|
+
- *Which input made an `activated`* (P134). The report doesn't say, and a field saying so would be
|
|
881
|
+
the page's word. A host reads its own page instead, as the report arrives: is the frame element
|
|
882
|
+
`document.activeElement`? The page can't fake that reading, and that is all it gets. It tells that
|
|
883
|
+
the focus is in the frame, not that a key was pressed: a pointer's click after the person was
|
|
884
|
+
in the frame reads the same, and the page can move the focus into its frame itself, from anywhere
|
|
885
|
+
but one of the host's text fields (the guard lets that be, P109). **The page can still forge
|
|
886
|
+
`activated` while the person really is in the frame, and this signal doesn't stop that.** A host
|
|
887
|
+
that moves the keyboard into its view on the signal takes §6's second exception, with its
|
|
888
|
+
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.
|
|
890
|
+
- *Back to a marker* (P134). `annotations.focusMark(id)` is the host's word to the frame
|
|
891
|
+
(`porthole/annotate.focusMark`, `{ id }`), for one moment only: after the keyboard closed the host's
|
|
892
|
+
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
|
|
893
|
+
shell moves the focus through the platform's `focus` as it was before content ran (control
|
|
894
|
+
`marker-focus`: a page that replaced it is handed the marker otherwise); with no such marker it does
|
|
895
|
+
nothing. The page reads the message, so it learns a card closed, and can take the focus back at once
|
|
896
|
+
or forge the message and focus a marker itself, which gives it nothing a fake `activated` doesn't:
|
|
897
|
+
a host can't rely on the focus landing. To the focus guard the move is the frame's own, so from a
|
|
898
|
+
host's text field that still has focus it is undone and counted (P109), not passed as the host's:
|
|
899
|
+
no window was opened in the guard for it.
|
|
900
|
+
A word that has to wait while the frame finds its marks is up to a second old when it could land
|
|
901
|
+
(P135), and a marker's `focus()` takes the keyboard with no gesture on Chromium and WebKit, past a
|
|
902
|
+
guard that defends only text fields: a person gone on to a host's button would be pulled back. So
|
|
903
|
+
the shell drops a parked word unless the focus is in its document as it lands, by `hasFocus` as it
|
|
904
|
+
was before content ran (control `marker-has-focus`: a page that replaced it to say yes gets the
|
|
905
|
+
landing otherwise; `marker-late` takes the test out). A word that doesn't wait isn't asked: it is
|
|
906
|
+
the host's word of this moment, and the frame has no focus then on the very path it is for. A page
|
|
907
|
+
can really take the focus and so pass the test, which gives it nothing, since it then has the
|
|
908
|
+
keyboard; and a parked word can still move the focus off the page's own field onto a marker, inside
|
|
909
|
+
the frame. §6 has the host's side: a second `focusMark` after its own `display.focus()`.
|
|
910
|
+
The word is a message, so from the host's close until the frame moves, the focus rests on the host's
|
|
911
|
+
body. A forged `activated` in that gap finds no frame focused, so a host that gates a view on "the
|
|
912
|
+
frame had the focus" doesn't gate that one. That is accepted, on the host's side of the wall: such
|
|
913
|
+
a view takes no focus and keeps keys out until the focus has reached the frame (in Raft, content
|
|
914
|
+
inert for 500 ms, and the focus handed back to the frame within 150 ms if the marker didn't take
|
|
915
|
+
it, with `focusMark` again after it, P135), so the keys go to the page and nothing is written.
|
|
862
916
|
- *What doesn't hold against content that does.* The shell shares the content's realm. It reads
|
|
863
917
|
and stops a marker's press through the platform's own functions and getters, kept before
|
|
864
918
|
content runs (P105, control `marker-originals`), so patching `Event`'s or `MouseEvent`'s
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.14.
|
|
3
|
+
"version": "0.14.13",
|
|
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
|
@@ -100,8 +100,8 @@ export interface AnnotationMark {
|
|
|
100
100
|
* draws the bubble alone) at the end of a text anchor's paragraph (P133) and the top right of an
|
|
101
101
|
* element. The person can click it, or reach it with the keyboard and press Enter or Space
|
|
102
102
|
* (P133): the frame reports `activated`. Its accessible name says what it is, with the count and
|
|
103
|
-
*
|
|
104
|
-
* draft's is dropped (P107): its marker has no number.
|
|
103
|
+
* the words it is on, quoted, an element's tag left out (P134). The content can read the number;
|
|
104
|
+
* give one only where the page may know it. A draft's is dropped (P107): its marker has no number.
|
|
105
105
|
*/
|
|
106
106
|
readonly count?: number;
|
|
107
107
|
/**
|
|
@@ -240,6 +240,11 @@ export const ANNOTATE_METHODS = {
|
|
|
240
240
|
tracked: "porthole/annotate.tracked",
|
|
241
241
|
/** Host → frame: take the page's text selection away, telling nothing back (P115). */
|
|
242
242
|
clearSelection: "porthole/annotate.clearSelection",
|
|
243
|
+
/**
|
|
244
|
+
* Host → frame: put the focus on one mark's marker (`{ id }`), telling nothing back (P134); one
|
|
245
|
+
* that waited for the marks is dropped unless the focus is in the frame's document by then (P135).
|
|
246
|
+
*/
|
|
247
|
+
focusMark: "porthole/annotate.focusMark",
|
|
243
248
|
} as const;
|
|
244
249
|
|
|
245
250
|
/** The most of each part of an anchor or report the host takes. */
|
package/src/host/create-host.ts
CHANGED
|
@@ -664,6 +664,14 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
664
664
|
needsAnnotate("clearSelection");
|
|
665
665
|
toFrame(ANNOTATE_METHODS.clearSelection, {});
|
|
666
666
|
},
|
|
667
|
+
focusMark(id) {
|
|
668
|
+
// Host → frame only, and kept for no later frame (P134). A mark that has gone, or has no
|
|
669
|
+
// marker, is nothing to ask for, and no fault: the host's card closed with the mark's.
|
|
670
|
+
needsAnnotate("focusMark");
|
|
671
|
+
if (marks.some((mark) => mark.id === id && hasMarker(mark))) {
|
|
672
|
+
toFrame(ANNOTATE_METHODS.focusMark, { id });
|
|
673
|
+
}
|
|
674
|
+
},
|
|
667
675
|
};
|
|
668
676
|
|
|
669
677
|
const hostContext = (): HostContext => {
|
package/src/host/types.ts
CHANGED
|
@@ -320,6 +320,25 @@ export interface AnnotationControls {
|
|
|
320
320
|
* a frame that runs later (it has no selection to clear).
|
|
321
321
|
*/
|
|
322
322
|
clearSelection(): void;
|
|
323
|
+
/**
|
|
324
|
+
* Puts the keyboard back on a mark's marker in the frame (P134): for after Escape closed the
|
|
325
|
+
* host's own view of that mark, and for nothing else. No content goes with it, and no report
|
|
326
|
+
* comes of it. Nothing happens, and nothing throws, for an id no mark with a marker is shown
|
|
327
|
+
* under, or if the frame has no such marker now (its words are gone, elements are being picked):
|
|
328
|
+
* the display's own `focus()` isn't used, so the frame takes no focus for a marker it hasn't got.
|
|
329
|
+
* Call it once the view is closed: from one of the page's text fields that still has focus, the
|
|
330
|
+
* move is the frame's own to the focus guard, undone and counted (P109). The page can take the
|
|
331
|
+
* focus back at once. Not kept for a frame that runs later.
|
|
332
|
+
*
|
|
333
|
+
* On a calm page it lands at once, from anywhere on the host's page. While the frame is finding
|
|
334
|
+
* its marks (a `show` just sent, the content just changed) it waits, and is then dropped unless
|
|
335
|
+
* the focus is in the frame by then (P135), so a word that comes late takes no keyboard from a
|
|
336
|
+
* person who moved on. Nothing says it was dropped: if the frame isn't your page's
|
|
337
|
+
* `document.activeElement` soon after and the person hasn't moved on, call `focus()` and then
|
|
338
|
+
* `focusMark(id)` again. Known gap: on a nested page that had the focus, `focus()` doesn't bring
|
|
339
|
+
* it back into the page, so a second call that waits is dropped too (ADOPTING).
|
|
340
|
+
*/
|
|
341
|
+
focusMark(id: string): void;
|
|
323
342
|
}
|
|
324
343
|
|
|
325
344
|
export interface DisplayControls {
|
package/src/react/frame.tsx
CHANGED
|
@@ -497,6 +497,14 @@ export interface PortholeFrameHandle {
|
|
|
497
497
|
* `"annotations"` (the core's call throws; this never does).
|
|
498
498
|
*/
|
|
499
499
|
clearSelection(): void;
|
|
500
|
+
/**
|
|
501
|
+
* Puts the keyboard back on a mark's marker in the frame (`annotations.focusMark(id)`, P134),
|
|
502
|
+
* once Escape closed your own view of that mark. Nothing happens for an id with no marker, or
|
|
503
|
+
* while no display runs. A config without `annotate`: `onHostError`, kind `"annotations"`. While
|
|
504
|
+
* the frame is finding its marks it waits, and is dropped unless the focus is in the frame by
|
|
505
|
+
* then (P135): call it again after your own move of the focus into the frame.
|
|
506
|
+
*/
|
|
507
|
+
focusMark(id: string): void;
|
|
500
508
|
/**
|
|
501
509
|
* Finds `query` in the frame and highlights it (`find.query`, P131): where the matches stand,
|
|
502
510
|
* or `"unsupported"` (a config without `find`, an older shell, no answer in time, a later
|
|
@@ -812,6 +820,12 @@ export function PortholeFrame(props: PortholeFrameProps): ReactElement {
|
|
|
812
820
|
attempt(() => now.annotations.clearSelection(), own.current);
|
|
813
821
|
}
|
|
814
822
|
},
|
|
823
|
+
focusMark(id) {
|
|
824
|
+
const now = display.current;
|
|
825
|
+
if (now !== null) {
|
|
826
|
+
attempt(() => now.annotations.focusMark(id), own.current);
|
|
827
|
+
}
|
|
828
|
+
},
|
|
815
829
|
find(query, options) {
|
|
816
830
|
try {
|
|
817
831
|
checkFindQuery(query, options);
|
package/src/react/view.tsx
CHANGED
|
@@ -253,6 +253,7 @@ function InstanceView(props: PortholeViewProps): ReactElement | null {
|
|
|
253
253
|
ref,
|
|
254
254
|
(): PortholeFrameHandle => ({
|
|
255
255
|
clearSelection: () => shown.current?.clearSelection(),
|
|
256
|
+
focusMark: (id) => shown.current?.focusMark(id),
|
|
256
257
|
find: (query, options) =>
|
|
257
258
|
shown.current?.find(query, options) ?? Promise.resolve("unsupported"),
|
|
258
259
|
clearFind: () => shown.current?.clearFind(),
|
package/src/shell/annotate.ts
CHANGED
|
@@ -34,14 +34,37 @@ export const MARKER_HIT = String.raw`(count, boxAt, x, y, touch) => {
|
|
|
34
34
|
return best;
|
|
35
35
|
}`;
|
|
36
36
|
|
|
37
|
+
/**
|
|
38
|
+
* What a marker is called (P133, P134), to whoever can't see it, spliced into the runtime: what it
|
|
39
|
+
* is, and the words it is on, in quotes. In English, whatever the page's language: the shell has no
|
|
40
|
+
* words of the host's. `anchor.label` stays as the host stores it (it is the host's to show): an
|
|
41
|
+
* element's starts with its tag (`describe`, "p#intro.lead Words"), so an element's words are its
|
|
42
|
+
* quote, cut where the label's are and marked so, or for one with no text of its own (an image's
|
|
43
|
+
* `alt`) what follows the tag in the label. An element with neither has no words.
|
|
44
|
+
*/
|
|
45
|
+
export const MARKER_NAME = String.raw`(mark) => {
|
|
46
|
+
const squash = (text) => String(text).replace(/\s+/g, " ").trim();
|
|
47
|
+
const anchor = mark.anchor;
|
|
48
|
+
const label = typeof anchor.label === "string" ? squash(anchor.label).slice(0, 120) : "";
|
|
49
|
+
let words = label;
|
|
50
|
+
if (anchor.kind === "element") {
|
|
51
|
+
const quote = anchor.selectors.filter((each) => each && each.type === "TextQuoteSelector")[0];
|
|
52
|
+
const said = quote && typeof quote.exact === "string" ? squash(quote.exact.slice(0, 300)) : "";
|
|
53
|
+
const space = label.indexOf(" ");
|
|
54
|
+
words = said.length > 40 ? said.slice(0, 40).trim() + "\u2026" : said !== "" ? said : space === -1 ? "" : label.slice(space + 1);
|
|
55
|
+
}
|
|
56
|
+
const what = mark.draft ? "Draft comment" : mark.count === 1 ? "1 comment" : mark.count > 1 ? mark.count + " comments" : "Comment";
|
|
57
|
+
return words === "" ? what : what + ' on "' + words + '"';
|
|
58
|
+
}`;
|
|
59
|
+
|
|
37
60
|
/**
|
|
38
61
|
* The shell's annotation runtime (P053), spliced into the shell's runtime (`__ANNOTATE__`) when
|
|
39
62
|
* the config declares `annotate`, so it runs before any content does, with the DOM's own
|
|
40
63
|
* functions as they were. Plain ES2020 like the rest of the shell; no template literals (it sits
|
|
41
64
|
* in one).
|
|
42
65
|
*
|
|
43
|
-
* The host drives it (`porthole/annotate.start|stop|show|focus|clear|track|clearSelection`)
|
|
44
|
-
* reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked`):
|
|
66
|
+
* The host drives it (`porthole/annotate.start|stop|show|focus|clear|track|clearSelection|focusMark`)
|
|
67
|
+
* and it reports (`porthole/annotate.selected|unselected|cancelled|anchored|activated|tracked`):
|
|
45
68
|
* - picking an element: the element under the pointer (or finger) is outlined with its name; a
|
|
46
69
|
* click or tap picks it, and the content's own handlers never see that click (unless the content
|
|
47
70
|
* patched the DOM's built-ins, P105); Escape cancels (while selecting text too, P112);
|
|
@@ -56,7 +79,9 @@ export const MARKER_HIT = String.raw`(count, boxAt, x, y, touch) => {
|
|
|
56
79
|
* in the line's gutter), an element's on its corner; a click on it, or Enter or Space with the
|
|
57
80
|
* focus on it (P133), is reported (`activated`), and the content's own handlers never see it; a
|
|
58
81
|
* draft is drawn apart, a dashed line and a hollow bubble with no number, and has a marker with
|
|
59
|
-
* or without a count;
|
|
82
|
+
* or without a count; the host's `focusMark` (P134) puts the focus on a marker that is there, and
|
|
83
|
+
* tells nothing back; one that had to wait for the marks lands only if the focus is still in this
|
|
84
|
+
* document (P135);
|
|
60
85
|
* - following: while a mark has a marker, once a scroll, a resize or a change of the content
|
|
61
86
|
* settles, the marks that moved since the host was last told are reported, at most once a
|
|
62
87
|
* second, so the host's own UI beside a mark can follow;
|
|
@@ -87,6 +112,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
87
112
|
track: "porthole/annotate.track",
|
|
88
113
|
tracked: "porthole/annotate.tracked",
|
|
89
114
|
clearSelection: "porthole/annotate.clearSelection",
|
|
115
|
+
focusMark: "porthole/annotate.focusMark",
|
|
90
116
|
};
|
|
91
117
|
// The DOM's own functions, taken before content runs.
|
|
92
118
|
const elementFromPoint = Document.prototype.elementFromPoint;
|
|
@@ -97,6 +123,8 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
97
123
|
const createElementNS = Document.prototype.createElementNS;
|
|
98
124
|
const selectionOf = Document.prototype.getSelection;
|
|
99
125
|
const removeAllRanges = Selection.prototype.removeAllRanges;
|
|
126
|
+
const focusElement = HTMLElement.prototype.focus;
|
|
127
|
+
const hasFocus = Document.prototype.hasFocus;
|
|
100
128
|
const elementRect = Element.prototype.getBoundingClientRect;
|
|
101
129
|
const rangeRect = Range.prototype.getBoundingClientRect;
|
|
102
130
|
const rangeRects = Range.prototype.getClientRects;
|
|
@@ -401,13 +429,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
401
429
|
const markerWidth = (label) => Math.max(MARKER_HEIGHT, 23 + (label === "" ? 0 : 3 + label.length * 7));
|
|
402
430
|
// Compact (P105): the number alone, or the glyph alone for none, with less padding.
|
|
403
431
|
const compactWidth = (label) => (label === "" ? 21 : Math.max(MARKER_HEIGHT, 10 + label.length * 7));
|
|
404
|
-
|
|
405
|
-
// on. In English, whatever the page's language: the shell has no words of the host's.
|
|
406
|
-
const nameOf = (mark) => {
|
|
407
|
-
const words = typeof mark.anchor.label === "string" ? squash(mark.anchor.label).slice(0, LIMIT.label) : "";
|
|
408
|
-
const what = mark.draft ? "Draft comment" : mark.count === 1 ? "1 comment" : mark.count > 1 ? mark.count + " comments" : "Comment";
|
|
409
|
-
return words === "" ? what : what + " on " + words;
|
|
410
|
-
};
|
|
432
|
+
const nameOf = ${MARKER_NAME};
|
|
411
433
|
// A rect's last line with words on it: its last box with a width, else any with a size.
|
|
412
434
|
const lastBox = (rects) => {
|
|
413
435
|
let any = null;
|
|
@@ -1054,6 +1076,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
1054
1076
|
// mark), nor before a run of changes settles; a focus asked for meanwhile waits for it.
|
|
1055
1077
|
let waitingForContent = false;
|
|
1056
1078
|
let pendingFocus = null;
|
|
1079
|
+
let pendingMarker = null;
|
|
1057
1080
|
const settling = () => anchorTimer !== 0 || waitingForContent || marks.some((mark) => mark.state === null);
|
|
1058
1081
|
const scheduleAnchor = (all) => {
|
|
1059
1082
|
if (all) {
|
|
@@ -1092,6 +1115,17 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
1092
1115
|
pendingFocus = null;
|
|
1093
1116
|
focus(id);
|
|
1094
1117
|
}
|
|
1118
|
+
if (pendingMarker !== null) {
|
|
1119
|
+
const id = pendingMarker;
|
|
1120
|
+
pendingMarker = null;
|
|
1121
|
+
// Parked, the host's word is old: the person may have moved on, and a marker's focus
|
|
1122
|
+
// takes the keyboard with no gesture. So it lands only if the focus is still in this
|
|
1123
|
+
// document, asked through the kept function: a page that says it has the focus gets
|
|
1124
|
+
// no landing the platform would refuse. Otherwise it is dropped (P135).
|
|
1125
|
+
if (callOf(hasFocus, document, []) === true) {
|
|
1126
|
+
focusMark(id);
|
|
1127
|
+
}
|
|
1128
|
+
}
|
|
1095
1129
|
}, wait);
|
|
1096
1130
|
};
|
|
1097
1131
|
new MutationObserver((records) => {
|
|
@@ -1196,6 +1230,29 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
1196
1230
|
report([{ mark, result: resultOf(mark, null, scroll) }], scroll);
|
|
1197
1231
|
};
|
|
1198
1232
|
|
|
1233
|
+
// The focus on a mark's marker, at the host's word (P134). Marks a show just replaced have no
|
|
1234
|
+
// markers yet, so it waits for them, as focus does; then a marker that isn't there, or has
|
|
1235
|
+
// stepped aside for picking, is nothing to do. The kept function, so a page that patched
|
|
1236
|
+
// focus isn't handed the marker from inside the closed root. The shell's focus listener
|
|
1237
|
+
// lights it and brings it into view; nothing is told. A call that isn't parked reads no
|
|
1238
|
+
// focus: it is the host's word just now, and after its card closed the focus is on the
|
|
1239
|
+
// host's body, so this document has none yet. Only the landing of a parked one asks (P135).
|
|
1240
|
+
const focusMark = (id) => {
|
|
1241
|
+
if (settling()) {
|
|
1242
|
+
pendingMarker = id;
|
|
1243
|
+
return;
|
|
1244
|
+
}
|
|
1245
|
+
if (mode.elements || !isShown(id)) {
|
|
1246
|
+
return;
|
|
1247
|
+
}
|
|
1248
|
+
for (let i = 0; i < markers.length; i += 1) {
|
|
1249
|
+
if (markers[i].id === id) {
|
|
1250
|
+
callOf(focusElement, markers[i].element, [{ preventScroll: true }]);
|
|
1251
|
+
return;
|
|
1252
|
+
}
|
|
1253
|
+
}
|
|
1254
|
+
};
|
|
1255
|
+
|
|
1199
1256
|
// A marker's click (P104). The layer takes no pointer but on its markers, so a press whose
|
|
1200
1257
|
// target is the layer is on a marker: the content's handlers never see it (this listener
|
|
1201
1258
|
// runs before any of theirs), nor does what lies under it, and a click is reported. A press
|
|
@@ -1630,9 +1687,13 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
1630
1687
|
}
|
|
1631
1688
|
break;
|
|
1632
1689
|
}
|
|
1690
|
+
case M.focusMark:
|
|
1691
|
+
focusMark(String(params.id));
|
|
1692
|
+
break;
|
|
1633
1693
|
case M.clear:
|
|
1634
1694
|
track(null);
|
|
1635
1695
|
pendingFocus = null;
|
|
1696
|
+
pendingMarker = null;
|
|
1636
1697
|
marks = [];
|
|
1637
1698
|
active = null;
|
|
1638
1699
|
hot = null;
|