@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 CHANGED
@@ -4,6 +4,42 @@
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.12
8
+
9
+ - **Annotations: the keyboard back on a marker (P134).** `annotations.focusMark(id)` (React:
10
+ `focusMark(id)` on the `ref`) moves the DOM focus to that mark's marker in the frame. It is for
11
+ one moment: after Escape closed your own view of that mark, once it is closed. It carries no
12
+ content and reports nothing; with no such marker it does nothing and throws nothing. An older
13
+ shell ignores it.
14
+ - **Annotations: a marker's name (P134).** It reads `1 comment on "Paragraph 3. Filler…"`: the words
15
+ it is on, in quotes, with no element's tag. `anchor.label` and everything you store are unchanged.
16
+ - **Key or pointer (P134).** `activated` is unchanged. Read `document.activeElement` on your own page
17
+ as it arrives: the frame there means the focus is in the frame. A hint: a page can still forge
18
+ `activated` while the person is in the frame, and a host that moves the keyboard into its view on
19
+ this gates what posts from that view itself (ADOPTING, THREAT_MODEL §7).
20
+ - **Security (P134):** the shell's move uses the platform's `focus`, kept before content runs (control
21
+ `marker-focus`). No CSP, sandbox, egress or gate changes; the focus guard is untouched.
22
+
23
+ ## 0.14.11
24
+
25
+ - **Annotations: markers are buttons (P133).** A marker is a real button in the frame's Tab order,
26
+ after the page's own stops and in reading order, named for what it is ("3 comments on …"; in
27
+ English). Enter or Space on it reports `activated` through the path a click takes, the same
28
+ gesture check included, unheard by the page's scripts, once for a key held down. The focus on a
29
+ marker lights its words and brings it into view. This reverses P104's "no tab stop": the page
30
+ shares that focus order, so a host keeps its own list of marks as the keyboard way that holds.
31
+ - **Annotations: a posted comment's marker sits at its paragraph's end (P133).** On the last line
32
+ of the block its words end in, just past the last word, or in the line's gutter where that
33
+ doesn't fit. A draft's stays beside its own words, and an element's on its corner.
34
+ - **Annotations: the last line (P133).** `selected`, each attached result of `anchored`, and
35
+ `tracked` now carry a `lastLineDocumentRect`, the last line with words on it (an element's whole
36
+ box) in the coordinates of `documentRect`, and `selected` carries the `scroll` it was read at, so
37
+ a host places its UI after the last line. Optional: an older shell sends neither (test for them),
38
+ and an older host drops them. Upgrade the content server (the shell) for all three.
39
+ - **Security (P133):** `lastLineDocumentRect` is the page's word, checked as any box and not clamped
40
+ to the frame: clip what you draw from it (THREAT_MODEL §6, ADOPTING). `rect` is clamped as before.
41
+ The keyboard on a marker is new (THREAT_MODEL §7): no CSP, sandbox, egress or gate changes.
42
+
7
43
  ## 0.14.10
8
44
 
9
45
  - **Annotations: a mark's place in the document (P132).** Each attached result of an `anchored`
@@ -46,8 +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). A result's `documentRect` (P132) is the same shape in the document's coordinates, and
50
- * isn't clamped.
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.
51
51
  */
52
52
  export interface AnnotationRect {
53
53
  readonly x: number;
@@ -86,20 +86,21 @@ export interface AnnotationMark {
86
86
  readonly id: string;
87
87
  readonly anchor: AnnotationAnchor;
88
88
  /**
89
- * A marker (P104): with a count, the shell also draws a small bubble with this number (0 to
90
- * `ANNOTATION_LIMITS.count`, a larger one clamped to it (P116); above 99 it reads "99+", 0 draws
91
- * the bubble alone) at the end of a
92
- * text anchor and the top right of an element. The person can click it: the frame reports
93
- * `activated`. The content can read the number; give one only where the page may know it. A
94
- * draft's is dropped (P107): its marker has no number.
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
+ * the words it is on, quoted, an element's tag left out (P134). The content can read the number;
95
+ * give one only where the page may know it. A draft's is dropped (P107): its marker has no number.
95
96
  */
96
97
  readonly count?: number;
97
98
  /**
98
99
  * What the mark is (P107): `"posted"` (the default, as absent) or `"draft"`, a comment its
99
100
  * author hasn't submitted yet. A draft is drawn apart (a dashed line and a hollow marker with no
100
- * number) and has a marker whether or not it has a count; its count is dropped before the mark
101
- * goes to the frame. The content can read that a mark is a draft: send drafts only to their
102
- * 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.
103
104
  */
104
105
  readonly kind?: AnnotationMarkKind;
105
106
  }
@@ -120,6 +121,13 @@ export interface AnchorResult {
120
121
  * box, or to its own region beside the frame. Absent from an older shell. The page's word.
121
122
  */
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;
123
131
  /**
124
132
  * Its place in the document among the found marks, from 0 (P112): where it starts, offscreen
125
133
  * marks included, for a host that lists marks in reading order. The content's word: an order to
@@ -129,11 +137,18 @@ export interface AnchorResult {
129
137
  }
130
138
  /** What the frame reports, once the host has checked it. */
131
139
  export type AnnotationReport =
132
- /** 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
+ */
133
146
  {
134
147
  readonly type: "selected";
135
148
  readonly anchor: AnnotationAnchor;
136
149
  readonly rect: AnnotationRect;
150
+ readonly lastLineDocumentRect?: AnnotationRect;
151
+ readonly scroll?: AnnotationScroll;
137
152
  }
138
153
  /** The text selection went away. */
139
154
  | {
@@ -171,18 +186,21 @@ export type AnnotationReport =
171
186
  * adds the mark's `documentRect` and the document's `scroll`: the mark's box moves as the
172
187
  * document scrolls, so a host following one mark hears the scroll at every animation frame where
173
188
  * it changed, whether that mark is in the frame or not, and places every mark it holds a
174
- * `documentRect` for (an `anchored` report's) without asking again.
189
+ * `documentRect` for (an `anchored` report's) without asking again. A newer one still (P133) adds
190
+ * its `lastLineDocumentRect`.
175
191
  */
176
192
  | {
177
193
  readonly type: "tracked";
178
194
  readonly id: string;
179
195
  readonly rect: AnnotationRect;
180
196
  readonly documentRect?: AnnotationRect;
197
+ readonly lastLineDocumentRect?: AnnotationRect;
181
198
  readonly scroll?: AnnotationScroll;
182
199
  }
183
200
  /**
184
201
  * The person clicked the marker of a mark the host shows with a `count` (P104), or of a draft
185
- * (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
186
204
  * it for any mark the host shows with a marker, and can tell a real one happened: open the
187
205
  * host's own view of that mark, never act on it.
188
206
  */
@@ -208,7 +226,7 @@ export declare const ANNOTATE_METHODS: {
208
226
  readonly unselected: "porthole/annotate.unselected";
209
227
  readonly cancelled: "porthole/annotate.cancelled";
210
228
  readonly anchored: "porthole/annotate.anchored";
211
- /** 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). */
212
230
  readonly activated: "porthole/annotate.activated";
213
231
  /** Host → frame: follow one mark's box (`{ id }`), or none (`{ id: null }`) (P112). */
214
232
  readonly track: "porthole/annotate.track";
@@ -216,6 +234,8 @@ export declare const ANNOTATE_METHODS: {
216
234
  readonly tracked: "porthole/annotate.tracked";
217
235
  /** Host → frame: take the page's text selection away, telling nothing back (P115). */
218
236
  readonly clearSelection: "porthole/annotate.clearSelection";
237
+ /** Host → frame: put the focus on one mark's marker (`{ id }`), telling nothing back (P134). */
238
+ readonly focusMark: "porthole/annotate.focusMark";
219
239
  };
220
240
  /** The most of each part of an anchor or report the host takes. */
221
241
  export declare const ANNOTATION_LIMITS: {
@@ -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",
@@ -36,6 +36,8 @@ export const ANNOTATE_METHODS = {
36
36
  tracked: "porthole/annotate.tracked",
37
37
  /** Host → frame: take the page's text selection away, telling nothing back (P115). */
38
38
  clearSelection: "porthole/annotate.clearSelection",
39
+ /** Host → frame: put the focus on one mark's marker (`{ id }`), telling nothing back (P134). */
40
+ focusMark: "porthole/annotate.focusMark",
39
41
  };
40
42
  /** The most of each part of an anchor or report the host takes. */
41
43
  export const ANNOTATION_LIMITS = {
@@ -135,7 +135,9 @@ function results(value) {
135
135
  const rect = each.rect === undefined ? undefined : parseRect(each.rect);
136
136
  // Where it is in the document (P132): a box as `rect` is, never clamped.
137
137
  const documentRect = each.documentRect === undefined ? undefined : parseRect(each.documentRect);
138
- if (rect === null || documentRect === null) {
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) {
139
141
  return null;
140
142
  }
141
143
  // A place among the marks (P112): a whole number below the most marks a show carries.
@@ -149,6 +151,7 @@ function results(value) {
149
151
  state: "attached",
150
152
  ...(rect === undefined ? {} : { rect }),
151
153
  ...(documentRect === undefined ? {} : { documentRect }),
154
+ ...(lastLineDocumentRect === undefined ? {} : { lastLineDocumentRect }),
152
155
  ...(order === undefined ? {} : { order }),
153
156
  });
154
157
  }
@@ -163,7 +166,21 @@ export function parseReport(value) {
163
166
  case "selected": {
164
167
  const anchor = parseAnchor(value.anchor);
165
168
  const rect = parseRect(value.rect);
166
- 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
+ };
167
184
  }
168
185
  case "unselected":
169
186
  return { type: "unselected" };
@@ -184,8 +201,15 @@ export function parseReport(value) {
184
201
  const rect = parseRect(value.rect);
185
202
  // A newer shell's (P132): where the mark is in the document, and how far it is scrolled.
186
203
  const documentRect = value.documentRect === undefined ? undefined : parseRect(value.documentRect);
204
+ const lastLineDocumentRect = value.lastLineDocumentRect === undefined
205
+ ? undefined
206
+ : parseRect(value.lastLineDocumentRect);
187
207
  const scroll = value.scroll === undefined ? undefined : parseScroll(value.scroll);
188
- if (!markId(value.id) || rect === null || documentRect === null || scroll === null) {
208
+ if (!markId(value.id) ||
209
+ rect === null ||
210
+ documentRect === null ||
211
+ lastLineDocumentRect === null ||
212
+ scroll === null) {
189
213
  return null;
190
214
  }
191
215
  return {
@@ -193,6 +217,7 @@ export function parseReport(value) {
193
217
  id: value.id,
194
218
  rect,
195
219
  ...(documentRect === undefined ? {} : { documentRect }),
220
+ ...(lastLineDocumentRect === undefined ? {} : { lastLineDocumentRect }),
196
221
  ...(scroll === undefined ? {} : { scroll }),
197
222
  };
198
223
  }