@botiverse/porthole 0.14.10 → 0.14.12
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 +36 -0
- package/dist/annotate/types.d.ts +35 -15
- package/dist/annotate/types.js +3 -1
- package/dist/annotate/validate.js +28 -3
- 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 +11 -0
- package/dist/react/frame.d.ts +6 -0
- package/dist/react/frame.js +6 -0
- package/dist/react/view.js +1 -0
- package/dist/shell/annotate.d.ts +21 -7
- package/dist/shell/annotate.js +277 -43
- package/dist/shell/find.d.ts +1 -1
- package/dist/shell/find.js +1 -1
- package/docs/ADOPTING.md +52 -5
- package/docs/ARCHITECTURE.md +4 -3
- package/docs/DECISIONS.md +243 -2
- package/docs/DESIGN.md +57 -23
- package/docs/THREAT_MODEL.md +55 -5
- package/package.json +1 -1
- package/src/annotate/types.ts +35 -15
- package/src/annotate/validate.ts +33 -3
- package/src/host/create-host.ts +8 -0
- package/src/host/types.ts +11 -0
- package/src/react/frame.tsx +12 -0
- package/src/react/view.tsx +1 -0
- package/src/shell/annotate.ts +278 -43
- package/src/shell/find.ts +1 -1
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.12 (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
|
|
@@ -30,7 +30,13 @@ in page (`find`, off unless a config declares it): the host's find bar sends the
|
|
|
30
30
|
into the frame, where the content can read it, and takes counts, a box and the find shortcut back
|
|
31
31
|
as the content's word (§6, §7 "Find in page"); no wall moves. 0.14.10: P132 adds a mark's place in
|
|
32
32
|
the document and the document's scroll to annotation reports, unclamped, so a host must clip what it
|
|
33
|
-
draws from them to its own region (§6, §7); `rect` stays clamped and no wall moves.
|
|
33
|
+
draws from them to its own region (§6, §7); `rect` stays clamped and no wall moves. 0.14.11: P133
|
|
34
|
+
makes markers buttons in the frame's Tab order, reversing P104's "no tab stop": the page shares that
|
|
35
|
+
order, so it can steer or spoil the focus, and a host keeps its own list of marks (§7). A press only
|
|
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. 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.
|
|
34
40
|
|
|
35
41
|
## 1. Two layers
|
|
36
42
|
|
|
@@ -196,8 +202,9 @@ Whatever the use:
|
|
|
196
202
|
log them, show nothing for them. A url-mode app can still say any outcome (S6).
|
|
197
203
|
- Take what the frame reports about annotations as UI hints (where to draw, what to open), never
|
|
198
204
|
as permissions, and put nothing in a mark the page may not know (§7). A mark's place in the
|
|
199
|
-
document (`documentRect`, with the report's `scroll`, P132)
|
|
200
|
-
|
|
205
|
+
document (`documentRect`, with the report's `scroll`, P132) and its last line's
|
|
206
|
+
(`lastLineDocumentRect`, P133) aren't clamped to the frame: clip whatever you draw from them to
|
|
207
|
+
the frame's box, or to your own region beside the frame.
|
|
201
208
|
- Under `find` (P131), know that the page reads every query your find bar sends it, and declare
|
|
202
209
|
`find` only for displays whose pages may learn what the person searches for (not a third-party
|
|
203
210
|
app with egress, S5, unless you accept it). Take its counts as the bar's numbers, and open your
|
|
@@ -222,6 +229,11 @@ Whatever the use:
|
|
|
222
229
|
when `selected` comes, so what it can do with that moment is put the person's next keys into a
|
|
223
230
|
draft they see and can discard, never send one; outside such a mode, or for a composer that can
|
|
224
231
|
send, it takes no focus.
|
|
232
|
+
A second exception (P134): a host may move focus into a view a report opened if all of these hold:
|
|
233
|
+
it reads its own page's `document.activeElement` and that is this frame; the focus goes only to a
|
|
234
|
+
container that takes no input (`tabindex="-1"`), never a field or a button; and every control in
|
|
235
|
+
that view that can write has the host's own gate, so that a forged opening and the keys right after
|
|
236
|
+
it can't submit. That's the host's duty: Porthole doesn't guarantee it.
|
|
225
237
|
- Know that a display can take the keyboard: a page calls `focus()` on its own input whenever it
|
|
226
238
|
likes (on Chromium and WebKit with no gesture), and what the person goes on typing goes to it.
|
|
227
239
|
`createHost` (every `PortholeView` too) gives focus back when it leaves one of the page's text
|
|
@@ -824,7 +836,9 @@ own frame, below the shell, P111), so:
|
|
|
824
836
|
what they are for: a host that maps a `documentRect` onto its own page without clipping to the
|
|
825
837
|
frame's box (or to its own region beside it) lets the page choose where that UI goes, outside
|
|
826
838
|
the frame as well (accepted, P132; the host's duty in §6). They say nothing else: the page knows
|
|
827
|
-
where its words are anyway.
|
|
839
|
+
where its words are anyway. Where a selection or a mark's words end (`lastLineDocumentRect` in
|
|
840
|
+
`selected`, `anchored` and `tracked`, P133) is one more such box, read, checked and left unclamped
|
|
841
|
+
the same way, with the same duty; `selected` also carries `scroll` now.
|
|
828
842
|
- *What holds, against content that patches none of the DOM's or JavaScript's built-ins.* A real
|
|
829
843
|
press or click on a marker reaches none of the content's handlers (the shell's first listener
|
|
830
844
|
stops it; control `marker-click`) and moves neither focus nor a selection (control
|
|
@@ -837,6 +851,42 @@ own frame, below the shell, P111), so:
|
|
|
837
851
|
loses a tap within 13 px of a bubble (a few px of its words above and below it), as it loses
|
|
838
852
|
one on the bubble. Which pointer is used is read from trusted pointer events only; a page that
|
|
839
853
|
makes its own up changes nothing, and a real `activated` still needs a real click.
|
|
854
|
+
- *The keyboard on a marker* (P133, reversing P104's point 6). A marker is a button with a tab
|
|
855
|
+
stop. Enter and Space on it are stopped in the shell's first listener, as a press is (control
|
|
856
|
+
`marker-key`), and the click they make is a trusted one the content doesn't get (`marker-click`):
|
|
857
|
+
it can neither hear nor cancel them. Every other key on a marker is the page's, as on a button of
|
|
858
|
+
its own, Tab too. So what P104 feared stands, and is accepted: the markers join a focus order the
|
|
859
|
+
content controls. It can take the focus from a marker (`focus()` from any handler or timer), keep
|
|
860
|
+
the person from reaching one (a trap on Tab in its own elements), draw its own look-alike with
|
|
861
|
+
its own tab stop, and tell that the person is on one (`document.activeElement` is the layer, its
|
|
862
|
+
own element's `focusout` names it). None of that gives it what it lacks: a marker's press has no
|
|
863
|
+
power but `activated`, which it can fake anyway within the host's checks, keys go to a marker only
|
|
864
|
+
while the frame has the focus, so nothing typed in the host passes through it (P109 is unchanged),
|
|
865
|
+
and a page's made-up key or `click()` is no trusted click. Assistive technology now reads the
|
|
866
|
+
marker's name, the page's own words after the shell's, in quotes that bound nothing (P134: a
|
|
867
|
+
text anchor's `label`, an element's quote, or what follows the tag in its `label`). A host can't
|
|
868
|
+
rely on a marker being reached, as it can't on one being seen: its own list of marks is the
|
|
869
|
+
keyboard way that holds.
|
|
870
|
+
- *Which input made an `activated`* (P134). The report doesn't say, and a field saying so would be
|
|
871
|
+
the page's word. A host reads its own page instead, as the report arrives: is the frame element
|
|
872
|
+
`document.activeElement`? The page can't fake that reading, and that is all it gets. It tells that
|
|
873
|
+
the focus is in the frame, not that a key was pressed: a pointer's click after the person was
|
|
874
|
+
in the frame reads the same, and the page can move the focus into its frame itself, from anywhere
|
|
875
|
+
but one of the host's text fields (the guard lets that be, P109). **The page can still forge
|
|
876
|
+
`activated` while the person really is in the frame, and this signal doesn't stop that.** A host
|
|
877
|
+
that moves the keyboard into its view on the signal takes §6's second exception, with its
|
|
878
|
+
conditions: a page can put the person's next keys in that view, and keeping those keys from posting
|
|
879
|
+
is the host's own gate on that view's controls, not Porthole's.
|
|
880
|
+
- *Back to a marker* (P134). `annotations.focusMark(id)` is the host's word to the frame
|
|
881
|
+
(`porthole/annotate.focusMark`, `{ id }`), for one moment only: after Escape closed the host's own
|
|
882
|
+
view of that mark. No content goes with it, beyond an id the frame has, and nothing comes back. The
|
|
883
|
+
shell moves the focus through the platform's `focus` as it was before content ran (control
|
|
884
|
+
`marker-focus`: a page that replaced it is handed the marker otherwise); with no such marker it does
|
|
885
|
+
nothing. The page reads the message, so it learns a card closed, and can take the focus back at once
|
|
886
|
+
or forge the message and focus a marker itself, which gives it nothing a fake `activated` doesn't:
|
|
887
|
+
a host can't rely on the focus landing. To the focus guard the move is the frame's own, so from a
|
|
888
|
+
host's text field that still has focus it is undone and counted (P109), not passed as the host's:
|
|
889
|
+
no window was opened in the guard for it.
|
|
840
890
|
- *What doesn't hold against content that does.* The shell shares the content's realm. It reads
|
|
841
891
|
and stops a marker's press through the platform's own functions and getters, kept before
|
|
842
892
|
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.12",
|
|
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
|
@@ -52,8 +52,8 @@ export interface AnnotationAnchor {
|
|
|
52
52
|
* The page's word: the host clamps each it reports to the frame's viewport (P104), so one wholly
|
|
53
53
|
* outside is a box of no size on the nearest edge. A positioning hint only. It is in the frame's
|
|
54
54
|
* own layout px: a host that scales or transforms the frame maps it through that transform too
|
|
55
|
-
* (P105). A result's `documentRect` (P132)
|
|
56
|
-
*
|
|
55
|
+
* (P105). A result's `documentRect` (P132) and a report's `lastLineDocumentRect` (P133) are the
|
|
56
|
+
* same shape in the document's coordinates, and aren't clamped.
|
|
57
57
|
*/
|
|
58
58
|
export interface AnnotationRect {
|
|
59
59
|
readonly x: number;
|
|
@@ -95,20 +95,21 @@ export interface AnnotationMark {
|
|
|
95
95
|
readonly id: string;
|
|
96
96
|
readonly anchor: AnnotationAnchor;
|
|
97
97
|
/**
|
|
98
|
-
* A marker (P104): with a count, the shell also draws a small bubble with this number
|
|
99
|
-
* `ANNOTATION_LIMITS.count`, a larger one clamped to it (P116); above 99 it reads "99+", 0
|
|
100
|
-
* the bubble alone) at the end of a
|
|
101
|
-
*
|
|
102
|
-
* `activated`.
|
|
103
|
-
*
|
|
98
|
+
* A marker (P104): with a count, the shell also draws a small button, a bubble with this number
|
|
99
|
+
* (0 to `ANNOTATION_LIMITS.count`, a larger one clamped to it (P116); above 99 it reads "99+", 0
|
|
100
|
+
* draws the bubble alone) at the end of a text anchor's paragraph (P133) and the top right of an
|
|
101
|
+
* element. The person can click it, or reach it with the keyboard and press Enter or Space
|
|
102
|
+
* (P133): the frame reports `activated`. Its accessible name says what it is, with the count and
|
|
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.
|
|
104
105
|
*/
|
|
105
106
|
readonly count?: number;
|
|
106
107
|
/**
|
|
107
108
|
* What the mark is (P107): `"posted"` (the default, as absent) or `"draft"`, a comment its
|
|
108
109
|
* author hasn't submitted yet. A draft is drawn apart (a dashed line and a hollow marker with no
|
|
109
|
-
* number
|
|
110
|
-
*
|
|
111
|
-
* author's own frame.
|
|
110
|
+
* number, beside its anchor's own last line, not at its paragraph's end: P133) and has a marker
|
|
111
|
+
* whether or not it has a count; its count is dropped before the mark goes to the frame. The
|
|
112
|
+
* content can read that a mark is a draft: send drafts only to their author's own frame.
|
|
112
113
|
*/
|
|
113
114
|
readonly kind?: AnnotationMarkKind;
|
|
114
115
|
}
|
|
@@ -132,6 +133,13 @@ export interface AnchorResult {
|
|
|
132
133
|
* box, or to its own region beside the frame. Absent from an older shell. The page's word.
|
|
133
134
|
*/
|
|
134
135
|
readonly documentRect?: AnnotationRect;
|
|
136
|
+
/**
|
|
137
|
+
* Where its last line is in the document (P133), in the coordinates of `documentRect` and as
|
|
138
|
+
* unclamped: its last line with words on it for text, its whole box for an element, which has no
|
|
139
|
+
* 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. The page's word.
|
|
141
|
+
*/
|
|
142
|
+
readonly lastLineDocumentRect?: AnnotationRect;
|
|
135
143
|
/**
|
|
136
144
|
* Its place in the document among the found marks, from 0 (P112): where it starts, offscreen
|
|
137
145
|
* marks included, for a host that lists marks in reading order. The content's word: an order to
|
|
@@ -142,11 +150,18 @@ export interface AnchorResult {
|
|
|
142
150
|
|
|
143
151
|
/** What the frame reports, once the host has checked it. */
|
|
144
152
|
export type AnnotationReport =
|
|
145
|
-
/**
|
|
153
|
+
/**
|
|
154
|
+
* The person pointed at an element or settled a text selection. A newer shell (P133) adds where
|
|
155
|
+
* it ends, for a host's UI after its last line: `lastLineDocumentRect` as a result's is, with
|
|
156
|
+
* 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.
|
|
158
|
+
*/
|
|
146
159
|
| {
|
|
147
160
|
readonly type: "selected";
|
|
148
161
|
readonly anchor: AnnotationAnchor;
|
|
149
162
|
readonly rect: AnnotationRect;
|
|
163
|
+
readonly lastLineDocumentRect?: AnnotationRect;
|
|
164
|
+
readonly scroll?: AnnotationScroll;
|
|
150
165
|
}
|
|
151
166
|
/** The text selection went away. */
|
|
152
167
|
| { readonly type: "unselected" }
|
|
@@ -180,18 +195,21 @@ export type AnnotationReport =
|
|
|
180
195
|
* adds the mark's `documentRect` and the document's `scroll`: the mark's box moves as the
|
|
181
196
|
* document scrolls, so a host following one mark hears the scroll at every animation frame where
|
|
182
197
|
* it changed, whether that mark is in the frame or not, and places every mark it holds a
|
|
183
|
-
* `documentRect` for (an `anchored` report's) without asking again.
|
|
198
|
+
* `documentRect` for (an `anchored` report's) without asking again. A newer one still (P133) adds
|
|
199
|
+
* its `lastLineDocumentRect`.
|
|
184
200
|
*/
|
|
185
201
|
| {
|
|
186
202
|
readonly type: "tracked";
|
|
187
203
|
readonly id: string;
|
|
188
204
|
readonly rect: AnnotationRect;
|
|
189
205
|
readonly documentRect?: AnnotationRect;
|
|
206
|
+
readonly lastLineDocumentRect?: AnnotationRect;
|
|
190
207
|
readonly scroll?: AnnotationScroll;
|
|
191
208
|
}
|
|
192
209
|
/**
|
|
193
210
|
* The person clicked the marker of a mark the host shows with a `count` (P104), or of a draft
|
|
194
|
-
* (P107); `rect` is the marker's box, to open the host's
|
|
211
|
+
* (P107), or pressed Enter or Space on it (P133); `rect` is the marker's box, to open the host's
|
|
212
|
+
* own UI beside it. The content can fake
|
|
195
213
|
* it for any mark the host shows with a marker, and can tell a real one happened: open the
|
|
196
214
|
* host's own view of that mark, never act on it.
|
|
197
215
|
*/
|
|
@@ -214,7 +232,7 @@ export const ANNOTATE_METHODS = {
|
|
|
214
232
|
unselected: "porthole/annotate.unselected",
|
|
215
233
|
cancelled: "porthole/annotate.cancelled",
|
|
216
234
|
anchored: "porthole/annotate.anchored",
|
|
217
|
-
/** Frame → host: a mark's marker was clicked (P104). */
|
|
235
|
+
/** Frame → host: a mark's marker was clicked, or pressed from the keyboard (P104, P133). */
|
|
218
236
|
activated: "porthole/annotate.activated",
|
|
219
237
|
/** Host → frame: follow one mark's box (`{ id }`), or none (`{ id: null }`) (P112). */
|
|
220
238
|
track: "porthole/annotate.track",
|
|
@@ -222,6 +240,8 @@ export const ANNOTATE_METHODS = {
|
|
|
222
240
|
tracked: "porthole/annotate.tracked",
|
|
223
241
|
/** Host → frame: take the page's text selection away, telling nothing back (P115). */
|
|
224
242
|
clearSelection: "porthole/annotate.clearSelection",
|
|
243
|
+
/** Host → frame: put the focus on one mark's marker (`{ id }`), telling nothing back (P134). */
|
|
244
|
+
focusMark: "porthole/annotate.focusMark",
|
|
225
245
|
} as const;
|
|
226
246
|
|
|
227
247
|
/** The most of each part of an anchor or report the host takes. */
|
package/src/annotate/validate.ts
CHANGED
|
@@ -166,7 +166,10 @@ function results(value: unknown): AnchorResult[] | null {
|
|
|
166
166
|
const rect = each.rect === undefined ? undefined : parseRect(each.rect);
|
|
167
167
|
// Where it is in the document (P132): a box as `rect` is, never clamped.
|
|
168
168
|
const documentRect = each.documentRect === undefined ? undefined : parseRect(each.documentRect);
|
|
169
|
-
|
|
169
|
+
// Where its last line is in the document (P133), as `documentRect` is.
|
|
170
|
+
const lastLineDocumentRect =
|
|
171
|
+
each.lastLineDocumentRect === undefined ? undefined : parseRect(each.lastLineDocumentRect);
|
|
172
|
+
if (rect === null || documentRect === null || lastLineDocumentRect === null) {
|
|
170
173
|
return null;
|
|
171
174
|
}
|
|
172
175
|
// A place among the marks (P112): a whole number below the most marks a show carries.
|
|
@@ -182,6 +185,7 @@ function results(value: unknown): AnchorResult[] | null {
|
|
|
182
185
|
state: "attached",
|
|
183
186
|
...(rect === undefined ? {} : { rect }),
|
|
184
187
|
...(documentRect === undefined ? {} : { documentRect }),
|
|
188
|
+
...(lastLineDocumentRect === undefined ? {} : { lastLineDocumentRect }),
|
|
185
189
|
...(order === undefined ? {} : { order }),
|
|
186
190
|
});
|
|
187
191
|
}
|
|
@@ -197,7 +201,22 @@ export function parseReport(value: unknown): AnnotationReport | null {
|
|
|
197
201
|
case "selected": {
|
|
198
202
|
const anchor = parseAnchor(value.anchor);
|
|
199
203
|
const rect = parseRect(value.rect);
|
|
200
|
-
|
|
204
|
+
// A newer shell's (P133): where its last line is in the document, and how far it is scrolled.
|
|
205
|
+
const lastLineDocumentRect =
|
|
206
|
+
value.lastLineDocumentRect === undefined
|
|
207
|
+
? undefined
|
|
208
|
+
: parseRect(value.lastLineDocumentRect);
|
|
209
|
+
const scroll = value.scroll === undefined ? undefined : parseScroll(value.scroll);
|
|
210
|
+
if (anchor === null || rect === null || lastLineDocumentRect === null || scroll === null) {
|
|
211
|
+
return null;
|
|
212
|
+
}
|
|
213
|
+
return {
|
|
214
|
+
type: "selected",
|
|
215
|
+
anchor,
|
|
216
|
+
rect,
|
|
217
|
+
...(lastLineDocumentRect === undefined ? {} : { lastLineDocumentRect }),
|
|
218
|
+
...(scroll === undefined ? {} : { scroll }),
|
|
219
|
+
};
|
|
201
220
|
}
|
|
202
221
|
case "unselected":
|
|
203
222
|
return { type: "unselected" };
|
|
@@ -219,8 +238,18 @@ export function parseReport(value: unknown): AnnotationReport | null {
|
|
|
219
238
|
// A newer shell's (P132): where the mark is in the document, and how far it is scrolled.
|
|
220
239
|
const documentRect =
|
|
221
240
|
value.documentRect === undefined ? undefined : parseRect(value.documentRect);
|
|
241
|
+
const lastLineDocumentRect =
|
|
242
|
+
value.lastLineDocumentRect === undefined
|
|
243
|
+
? undefined
|
|
244
|
+
: parseRect(value.lastLineDocumentRect);
|
|
222
245
|
const scroll = value.scroll === undefined ? undefined : parseScroll(value.scroll);
|
|
223
|
-
if (
|
|
246
|
+
if (
|
|
247
|
+
!markId(value.id) ||
|
|
248
|
+
rect === null ||
|
|
249
|
+
documentRect === null ||
|
|
250
|
+
lastLineDocumentRect === null ||
|
|
251
|
+
scroll === null
|
|
252
|
+
) {
|
|
224
253
|
return null;
|
|
225
254
|
}
|
|
226
255
|
return {
|
|
@@ -228,6 +257,7 @@ export function parseReport(value: unknown): AnnotationReport | null {
|
|
|
228
257
|
id: value.id,
|
|
229
258
|
rect,
|
|
230
259
|
...(documentRect === undefined ? {} : { documentRect }),
|
|
260
|
+
...(lastLineDocumentRect === undefined ? {} : { lastLineDocumentRect }),
|
|
231
261
|
...(scroll === undefined ? {} : { scroll }),
|
|
232
262
|
};
|
|
233
263
|
}
|
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,17 @@ 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
|
+
focusMark(id: string): void;
|
|
323
334
|
}
|
|
324
335
|
|
|
325
336
|
export interface DisplayControls {
|
package/src/react/frame.tsx
CHANGED
|
@@ -497,6 +497,12 @@ 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"`.
|
|
504
|
+
*/
|
|
505
|
+
focusMark(id: string): void;
|
|
500
506
|
/**
|
|
501
507
|
* Finds `query` in the frame and highlights it (`find.query`, P131): where the matches stand,
|
|
502
508
|
* or `"unsupported"` (a config without `find`, an older shell, no answer in time, a later
|
|
@@ -812,6 +818,12 @@ export function PortholeFrame(props: PortholeFrameProps): ReactElement {
|
|
|
812
818
|
attempt(() => now.annotations.clearSelection(), own.current);
|
|
813
819
|
}
|
|
814
820
|
},
|
|
821
|
+
focusMark(id) {
|
|
822
|
+
const now = display.current;
|
|
823
|
+
if (now !== null) {
|
|
824
|
+
attempt(() => now.annotations.focusMark(id), own.current);
|
|
825
|
+
}
|
|
826
|
+
},
|
|
815
827
|
find(query, options) {
|
|
816
828
|
try {
|
|
817
829
|
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(),
|