@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.
@@ -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.10 (2026-11-05). A review on 2026-10-19 found gaps, and every decision it led to
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) isn't clamped to the frame: clip
200
- whatever you draw from it to the frame's box, or to your own region beside the frame.
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.10",
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": {
@@ -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) is the same shape in the document's coordinates, and
56
- * isn't clamped.
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 (0 to
99
- * `ANNOTATION_LIMITS.count`, a larger one clamped to it (P116); above 99 it reads "99+", 0 draws
100
- * the bubble alone) at the end of a
101
- * text anchor and the top right of an element. The person can click it: the frame reports
102
- * `activated`. The content can read the number; give one only where the page may know it. A
103
- * draft's is dropped (P107): its marker has no number.
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) and has a marker whether or not it has a count; its count is dropped before the mark
110
- * goes to the frame. The content can read that a mark is a draft: send drafts only to their
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
- /** The person pointed at an element or settled a text selection. */
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 own UI beside it. The content can fake
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. */
@@ -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
- if (rect === null || documentRect === null) {
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
- return anchor === null || rect === null ? null : { type: "selected", anchor, rect };
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 (!markId(value.id) || rect === null || documentRect === null || scroll === null) {
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
  }
@@ -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 {
@@ -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);
@@ -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(),