@botiverse/porthole 0.14.9 → 0.14.11

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 CHANGED
@@ -4,6 +4,45 @@
4
4
  section); the reasons for every change are in [docs/DECISIONS.md](docs/DECISIONS.md), by the
5
5
  P-numbers below.
6
6
 
7
+ ## 0.14.11
8
+
9
+ - **Annotations: markers are buttons (P133).** A marker is a real button in the frame's Tab order,
10
+ after the page's own stops and in reading order, named for what it is ("3 comments on …"; in
11
+ English). Enter or Space on it reports `activated` through the path a click takes, the same
12
+ gesture check included, unheard by the page's scripts, once for a key held down. The focus on a
13
+ marker lights its words and brings it into view. This reverses P104's "no tab stop": the page
14
+ shares that focus order, so a host keeps its own list of marks as the keyboard way that holds.
15
+ - **Annotations: a posted comment's marker sits at its paragraph's end (P133).** On the last line
16
+ of the block its words end in, just past the last word, or in the line's gutter where that
17
+ doesn't fit. A draft's stays beside its own words, and an element's on its corner.
18
+ - **Annotations: the last line (P133).** `selected`, each attached result of `anchored`, and
19
+ `tracked` now carry a `lastLineDocumentRect`, the last line with words on it (an element's whole
20
+ box) in the coordinates of `documentRect`, and `selected` carries the `scroll` it was read at, so
21
+ a host places its UI after the last line. Optional: an older shell sends neither (test for them),
22
+ and an older host drops them. Upgrade the content server (the shell) for all three.
23
+ - **Security (P133):** `lastLineDocumentRect` is the page's word, checked as any box and not clamped
24
+ to the frame: clip what you draw from it (THREAT_MODEL §6, ADOPTING). `rect` is clamped as before.
25
+ The keyboard on a marker is new (THREAT_MODEL §7): no CSP, sandbox, egress or gate changes.
26
+
27
+ ## 0.14.10
28
+
29
+ - **Annotations: a mark's place in the document (P132).** Each attached result of an `anchored`
30
+ report now has a `documentRect` (its box in the document: it stays put as the page scrolls, and
31
+ says where a mark scrolled out of the frame is), and the report a `scroll` (`{ x, y }`, how far
32
+ the document was scrolled as the boxes were read); `rect` is `documentRect` less `scroll`, then
33
+ clamped as before. `tracked` (P112) carries both too, so following one mark tells the document's
34
+ scroll at every animation frame where it changed, whether that mark is in view or not: a host
35
+ places every mark from one report and keeps them placed as the page scrolls, without asking
36
+ again. New exports: `AnnotationScroll`, `parseScroll`. Both fields are optional: an older shell
37
+ sends neither (test for `scroll`), and an older host drops them. Upgrade the content server (the
38
+ shell) for them.
39
+ - **Security (P132):** `documentRect` is the page's word and isn't clamped to the frame (a clamp
40
+ would erase the offscreen places it is for); Porthole checks it as any box (finite, within
41
+ `ANNOTATION_LIMITS.coordinate`, sizes not negative; a malformed one, or a malformed `scroll`,
42
+ drops the report). Clip what you draw from it to the frame's box, or to your own region beside
43
+ it (THREAT_MODEL §6, ADOPTING). `rect` is clamped as before. No CSP, sandbox, egress or gate
44
+ changes.
45
+
7
46
  ## 0.14.9
8
47
 
9
48
  - **Find in page (P131):** a host's own find bar over a display. Declare `find`
@@ -46,7 +46,8 @@ export interface AnnotationAnchor {
46
46
  * The page's word: the host clamps each it reports to the frame's viewport (P104), so one wholly
47
47
  * outside is a box of no size on the nearest edge. A positioning hint only. It is in the frame's
48
48
  * own layout px: a host that scales or transforms the frame maps it through that transform too
49
- * (P105).
49
+ * (P105). A result's `documentRect` (P132) and a report's `lastLineDocumentRect` (P133) are the
50
+ * same shape in the document's coordinates, and aren't clamped.
50
51
  */
51
52
  export interface AnnotationRect {
52
53
  readonly x: number;
@@ -54,6 +55,16 @@ export interface AnnotationRect {
54
55
  readonly width: number;
55
56
  readonly height: number;
56
57
  }
58
+ /**
59
+ * How far the frame's document is scrolled when the boxes beside it were read (P132), CSS px: the
60
+ * top left of the document's root element (`<html>`), from the viewport's, negated (`window.scrollX`
61
+ * and `window.scrollY` on a page whose root has no margin). A box in the viewport is its
62
+ * `documentRect` less this. The page's word, as every box is.
63
+ */
64
+ export interface AnnotationScroll {
65
+ readonly x: number;
66
+ readonly y: number;
67
+ }
57
68
  /** What the person may point at while the host is asking. */
58
69
  export interface AnnotateMode {
59
70
  /**
@@ -75,20 +86,21 @@ export interface AnnotationMark {
75
86
  readonly id: string;
76
87
  readonly anchor: AnnotationAnchor;
77
88
  /**
78
- * A marker (P104): with a count, the shell also draws a small bubble with this number (0 to
79
- * `ANNOTATION_LIMITS.count`, a larger one clamped to it (P116); above 99 it reads "99+", 0 draws
80
- * the bubble alone) at the end of a
81
- * text anchor and the top right of an element. The person can click it: the frame reports
82
- * `activated`. The content can read the number; give one only where the page may know it. A
89
+ * A marker (P104): with a count, the shell also draws a small button, a bubble with this number
90
+ * (0 to `ANNOTATION_LIMITS.count`, a larger one clamped to it (P116); above 99 it reads "99+", 0
91
+ * draws the bubble alone) at the end of a text anchor's paragraph (P133) and the top right of an
92
+ * element. The person can click it, or reach it with the keyboard and press Enter or Space
93
+ * (P133): the frame reports `activated`. Its accessible name says what it is, with the count and
94
+ * `anchor.label`. The content can read the number; give one only where the page may know it. A
83
95
  * draft's is dropped (P107): its marker has no number.
84
96
  */
85
97
  readonly count?: number;
86
98
  /**
87
99
  * What the mark is (P107): `"posted"` (the default, as absent) or `"draft"`, a comment its
88
100
  * author hasn't submitted yet. A draft is drawn apart (a dashed line and a hollow marker with no
89
- * number) and has a marker whether or not it has a count; its count is dropped before the mark
90
- * goes to the frame. The content can read that a mark is a draft: send drafts only to their
91
- * author's own frame.
101
+ * number, beside its anchor's own last line, not at its paragraph's end: P133) and has a marker
102
+ * whether or not it has a count; its count is dropped before the mark goes to the frame. The
103
+ * content can read that a mark is a draft: send drafts only to their author's own frame.
92
104
  */
93
105
  readonly kind?: AnnotationMarkKind;
94
106
  }
@@ -101,6 +113,21 @@ export interface AnchorResult {
101
113
  readonly state: AnchorState;
102
114
  /** Where it is now, when attached. */
103
115
  readonly rect?: AnnotationRect;
116
+ /**
117
+ * Where it is in the document (P132): `rect` as the shell read it, before the host clamped it,
118
+ * plus the report's `scroll`; so it stays where it is as the document scrolls, and says where a
119
+ * mark scrolled out of the frame is. Not clamped to the frame's viewport (an offscreen mark's is
120
+ * outside it: that is its point): a host places its own UI from it only clipped to the frame's
121
+ * box, or to its own region beside the frame. Absent from an older shell. The page's word.
122
+ */
123
+ readonly documentRect?: AnnotationRect;
124
+ /**
125
+ * Where its last line is in the document (P133), in the coordinates of `documentRect` and as
126
+ * unclamped: its last line with words on it for text, its whole box for an element, which has no
127
+ * lines of its own. For a host's UI after the last line (its right, or its bottom). Absent from
128
+ * an older shell, and where nothing of the mark is drawn. The page's word.
129
+ */
130
+ readonly lastLineDocumentRect?: AnnotationRect;
104
131
  /**
105
132
  * Its place in the document among the found marks, from 0 (P112): where it starts, offscreen
106
133
  * marks included, for a host that lists marks in reading order. The content's word: an order to
@@ -110,11 +137,18 @@ export interface AnchorResult {
110
137
  }
111
138
  /** What the frame reports, once the host has checked it. */
112
139
  export type AnnotationReport =
113
- /** The person pointed at an element or settled a text selection. */
140
+ /**
141
+ * The person pointed at an element or settled a text selection. A newer shell (P133) adds where
142
+ * it ends, for a host's UI after its last line: `lastLineDocumentRect` as a result's is, with
143
+ * how far the document was scrolled as it was read (so its place in the frame's viewport is the
144
+ * one less the other, unclamped). Both absent from an older shell.
145
+ */
114
146
  {
115
147
  readonly type: "selected";
116
148
  readonly anchor: AnnotationAnchor;
117
149
  readonly rect: AnnotationRect;
150
+ readonly lastLineDocumentRect?: AnnotationRect;
151
+ readonly scroll?: AnnotationScroll;
118
152
  }
119
153
  /** The text selection went away. */
120
154
  | {
@@ -138,20 +172,35 @@ export type AnnotationReport =
138
172
  | {
139
173
  readonly type: "anchored";
140
174
  readonly results: readonly AnchorResult[];
175
+ /**
176
+ * How far the document was scrolled as the boxes were read (P132); with it, each attached
177
+ * result has its `documentRect`. Absent from an older shell: its results have no
178
+ * `documentRect` either, and only `rect` says where marks are.
179
+ */
180
+ readonly scroll?: AnnotationScroll;
141
181
  }
142
182
  /**
143
183
  * The box of the mark the host follows (`annotations.track`, P112), in the frame's viewport, at
144
184
  * an animation frame where it moved: at most 60 a second, for that mark only, clamped to the
145
- * frame. The content's word: where to put a card beside it, nothing more.
185
+ * frame. The content's word: where to put a card beside it, nothing more. A newer shell (P132)
186
+ * adds the mark's `documentRect` and the document's `scroll`: the mark's box moves as the
187
+ * document scrolls, so a host following one mark hears the scroll at every animation frame where
188
+ * it changed, whether that mark is in the frame or not, and places every mark it holds a
189
+ * `documentRect` for (an `anchored` report's) without asking again. A newer one still (P133) adds
190
+ * its `lastLineDocumentRect`.
146
191
  */
147
192
  | {
148
193
  readonly type: "tracked";
149
194
  readonly id: string;
150
195
  readonly rect: AnnotationRect;
196
+ readonly documentRect?: AnnotationRect;
197
+ readonly lastLineDocumentRect?: AnnotationRect;
198
+ readonly scroll?: AnnotationScroll;
151
199
  }
152
200
  /**
153
201
  * The person clicked the marker of a mark the host shows with a `count` (P104), or of a draft
154
- * (P107); `rect` is the marker's box, to open the host's own UI beside it. The content can fake
202
+ * (P107), or pressed Enter or Space on it (P133); `rect` is the marker's box, to open the host's
203
+ * own UI beside it. The content can fake
155
204
  * it for any mark the host shows with a marker, and can tell a real one happened: open the
156
205
  * host's own view of that mark, never act on it.
157
206
  */
@@ -177,7 +226,7 @@ export declare const ANNOTATE_METHODS: {
177
226
  readonly unselected: "porthole/annotate.unselected";
178
227
  readonly cancelled: "porthole/annotate.cancelled";
179
228
  readonly anchored: "porthole/annotate.anchored";
180
- /** Frame → host: a mark's marker was clicked (P104). */
229
+ /** Frame → host: a mark's marker was clicked, or pressed from the keyboard (P104, P133). */
181
230
  readonly activated: "porthole/annotate.activated";
182
231
  /** Host → frame: follow one mark's box (`{ id }`), or none (`{ id: null }`) (P112). */
183
232
  readonly track: "porthole/annotate.track";
@@ -28,7 +28,7 @@ export const ANNOTATE_METHODS = {
28
28
  unselected: "porthole/annotate.unselected",
29
29
  cancelled: "porthole/annotate.cancelled",
30
30
  anchored: "porthole/annotate.anchored",
31
- /** Frame → host: a mark's marker was clicked (P104). */
31
+ /** Frame → host: a mark's marker was clicked, or pressed from the keyboard (P104, P133). */
32
32
  activated: "porthole/annotate.activated",
33
33
  /** Host → frame: follow one mark's box (`{ id }`), or none (`{ id: null }`) (P112). */
34
34
  track: "porthole/annotate.track",
@@ -1,4 +1,4 @@
1
- import { type AnnotateMode, type AnnotationAnchor, type AnnotationMark, type AnnotationRect, type AnnotationReport } from "./types.ts";
1
+ import { type AnnotateMode, type AnnotationAnchor, type AnnotationMark, type AnnotationRect, type AnnotationReport, type AnnotationScroll } from "./types.ts";
2
2
  /**
3
3
  * An anchor, rebuilt from its known fields; null if any part is malformed or too large. Its label
4
4
  * is text for the person, so what they couldn't see is taken out of it (P105: a wordless element's
@@ -8,6 +8,11 @@ import { type AnnotateMode, type AnnotationAnchor, type AnnotationMark, type Ann
8
8
  export declare function parseAnchor(value: unknown): AnnotationAnchor | null;
9
9
  /** A box in the frame's viewport; null unless every number is finite and sizes aren't negative. */
10
10
  export declare function parseRect(value: unknown): AnnotationRect | null;
11
+ /**
12
+ * How far the document is scrolled (P132): two finite numbers within the coordinate limit (either
13
+ * may be negative: an engine's overscroll); null for anything else.
14
+ */
15
+ export declare function parseScroll(value: unknown): AnnotationScroll | null;
11
16
  /**
12
17
  * A box the frame reported, clamped to the frame's viewport (`width` by `height`, CSS px, P104):
13
18
  * each side is held within it, so what overlaps the viewport keeps the part inside, and what lies
@@ -88,6 +88,16 @@ export function parseRect(value) {
88
88
  }
89
89
  return { x, y, width, height };
90
90
  }
91
+ /**
92
+ * How far the document is scrolled (P132): two finite numbers within the coordinate limit (either
93
+ * may be negative: an engine's overscroll); null for anything else.
94
+ */
95
+ export function parseScroll(value) {
96
+ if (!isRecord(value) || !coordinate(value.x) || !coordinate(value.y)) {
97
+ return null;
98
+ }
99
+ return { x: value.x, y: value.y };
100
+ }
91
101
  /**
92
102
  * A box the frame reported, clamped to the frame's viewport (`width` by `height`, CSS px, P104):
93
103
  * each side is held within it, so what overlaps the viewport keeps the part inside, and what lies
@@ -123,7 +133,11 @@ function results(value) {
123
133
  return null;
124
134
  }
125
135
  const rect = each.rect === undefined ? undefined : parseRect(each.rect);
126
- if (rect === null) {
136
+ // Where it is in the document (P132): a box as `rect` is, never clamped.
137
+ const documentRect = each.documentRect === undefined ? undefined : parseRect(each.documentRect);
138
+ // Where its last line is in the document (P133), as `documentRect` is.
139
+ const lastLineDocumentRect = each.lastLineDocumentRect === undefined ? undefined : parseRect(each.lastLineDocumentRect);
140
+ if (rect === null || documentRect === null || lastLineDocumentRect === null) {
127
141
  return null;
128
142
  }
129
143
  // A place among the marks (P112): a whole number below the most marks a show carries.
@@ -136,6 +150,8 @@ function results(value) {
136
150
  id: each.id,
137
151
  state: "attached",
138
152
  ...(rect === undefined ? {} : { rect }),
153
+ ...(documentRect === undefined ? {} : { documentRect }),
154
+ ...(lastLineDocumentRect === undefined ? {} : { lastLineDocumentRect }),
139
155
  ...(order === undefined ? {} : { order }),
140
156
  });
141
157
  }
@@ -150,7 +166,21 @@ export function parseReport(value) {
150
166
  case "selected": {
151
167
  const anchor = parseAnchor(value.anchor);
152
168
  const rect = parseRect(value.rect);
153
- return anchor === null || rect === null ? null : { type: "selected", anchor, rect };
169
+ // A newer shell's (P133): where its last line is in the document, and how far it is scrolled.
170
+ const lastLineDocumentRect = value.lastLineDocumentRect === undefined
171
+ ? undefined
172
+ : parseRect(value.lastLineDocumentRect);
173
+ const scroll = value.scroll === undefined ? undefined : parseScroll(value.scroll);
174
+ if (anchor === null || rect === null || lastLineDocumentRect === null || scroll === null) {
175
+ return null;
176
+ }
177
+ return {
178
+ type: "selected",
179
+ anchor,
180
+ rect,
181
+ ...(lastLineDocumentRect === undefined ? {} : { lastLineDocumentRect }),
182
+ ...(scroll === undefined ? {} : { scroll }),
183
+ };
154
184
  }
155
185
  case "unselected":
156
186
  return { type: "unselected" };
@@ -158,7 +188,10 @@ export function parseReport(value) {
158
188
  return { type: "cancelled" };
159
189
  case "anchored": {
160
190
  const checked = results(value.results);
161
- return checked === null ? null : { type: "anchored", results: checked };
191
+ const scroll = value.scroll === undefined ? undefined : parseScroll(value.scroll);
192
+ return checked === null || scroll === null
193
+ ? null
194
+ : { type: "anchored", results: checked, ...(scroll === undefined ? {} : { scroll }) };
162
195
  }
163
196
  case "activated": {
164
197
  const rect = parseRect(value.rect);
@@ -166,7 +199,27 @@ export function parseReport(value) {
166
199
  }
167
200
  case "tracked": {
168
201
  const rect = parseRect(value.rect);
169
- return !markId(value.id) || rect === null ? null : { type: "tracked", id: value.id, rect };
202
+ // A newer shell's (P132): where the mark is in the document, and how far it is scrolled.
203
+ const documentRect = value.documentRect === undefined ? undefined : parseRect(value.documentRect);
204
+ const lastLineDocumentRect = value.lastLineDocumentRect === undefined
205
+ ? undefined
206
+ : parseRect(value.lastLineDocumentRect);
207
+ const scroll = value.scroll === undefined ? undefined : parseScroll(value.scroll);
208
+ if (!markId(value.id) ||
209
+ rect === null ||
210
+ documentRect === null ||
211
+ lastLineDocumentRect === null ||
212
+ scroll === null) {
213
+ return null;
214
+ }
215
+ return {
216
+ type: "tracked",
217
+ id: value.id,
218
+ rect,
219
+ ...(documentRect === undefined ? {} : { documentRect }),
220
+ ...(lastLineDocumentRect === undefined ? {} : { lastLineDocumentRect }),
221
+ ...(scroll === undefined ? {} : { scroll }),
222
+ };
170
223
  }
171
224
  default:
172
225
  return null;