@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.
@@ -52,7 +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).
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.
56
57
  */
57
58
  export interface AnnotationRect {
58
59
  readonly x: number;
@@ -61,6 +62,17 @@ export interface AnnotationRect {
61
62
  readonly height: number;
62
63
  }
63
64
 
65
+ /**
66
+ * How far the frame's document is scrolled when the boxes beside it were read (P132), CSS px: the
67
+ * top left of the document's root element (`<html>`), from the viewport's, negated (`window.scrollX`
68
+ * and `window.scrollY` on a page whose root has no margin). A box in the viewport is its
69
+ * `documentRect` less this. The page's word, as every box is.
70
+ */
71
+ export interface AnnotationScroll {
72
+ readonly x: number;
73
+ readonly y: number;
74
+ }
75
+
64
76
  /** What the person may point at while the host is asking. */
65
77
  export interface AnnotateMode {
66
78
  /**
@@ -83,20 +95,21 @@ export interface AnnotationMark {
83
95
  readonly id: string;
84
96
  readonly anchor: AnnotationAnchor;
85
97
  /**
86
- * A marker (P104): with a count, the shell also draws a small bubble with this number (0 to
87
- * `ANNOTATION_LIMITS.count`, a larger one clamped to it (P116); above 99 it reads "99+", 0 draws
88
- * the bubble alone) at the end of a
89
- * text anchor and the top right of an element. The person can click it: the frame reports
90
- * `activated`. The content can read the number; give one only where the page may know it. A
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
+ * `anchor.label`. The content can read the number; give one only where the page may know it. A
91
104
  * draft's is dropped (P107): its marker has no number.
92
105
  */
93
106
  readonly count?: number;
94
107
  /**
95
108
  * What the mark is (P107): `"posted"` (the default, as absent) or `"draft"`, a comment its
96
109
  * author hasn't submitted yet. A draft is drawn apart (a dashed line and a hollow marker with no
97
- * number) and has a marker whether or not it has a count; its count is dropped before the mark
98
- * goes to the frame. The content can read that a mark is a draft: send drafts only to their
99
- * 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.
100
113
  */
101
114
  readonly kind?: AnnotationMarkKind;
102
115
  }
@@ -112,6 +125,21 @@ export interface AnchorResult {
112
125
  readonly state: AnchorState;
113
126
  /** Where it is now, when attached. */
114
127
  readonly rect?: AnnotationRect;
128
+ /**
129
+ * Where it is in the document (P132): `rect` as the shell read it, before the host clamped it,
130
+ * plus the report's `scroll`; so it stays where it is as the document scrolls, and says where a
131
+ * mark scrolled out of the frame is. Not clamped to the frame's viewport (an offscreen mark's is
132
+ * outside it: that is its point): a host places its own UI from it only clipped to the frame's
133
+ * box, or to its own region beside the frame. Absent from an older shell. The page's word.
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;
115
143
  /**
116
144
  * Its place in the document among the found marks, from 0 (P112): where it starts, offscreen
117
145
  * marks included, for a host that lists marks in reading order. The content's word: an order to
@@ -122,11 +150,18 @@ export interface AnchorResult {
122
150
 
123
151
  /** What the frame reports, once the host has checked it. */
124
152
  export type AnnotationReport =
125
- /** 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
+ */
126
159
  | {
127
160
  readonly type: "selected";
128
161
  readonly anchor: AnnotationAnchor;
129
162
  readonly rect: AnnotationRect;
163
+ readonly lastLineDocumentRect?: AnnotationRect;
164
+ readonly scroll?: AnnotationScroll;
130
165
  }
131
166
  /** The text selection went away. */
132
167
  | { readonly type: "unselected" }
@@ -143,16 +178,38 @@ export type AnnotationReport =
143
178
  * scroll, a resize or a change of the content has settled, only the marks that moved since the
144
179
  * host was last told, at most once a second (P104).
145
180
  */
146
- | { readonly type: "anchored"; readonly results: readonly AnchorResult[] }
181
+ | {
182
+ readonly type: "anchored";
183
+ readonly results: readonly AnchorResult[];
184
+ /**
185
+ * How far the document was scrolled as the boxes were read (P132); with it, each attached
186
+ * result has its `documentRect`. Absent from an older shell: its results have no
187
+ * `documentRect` either, and only `rect` says where marks are.
188
+ */
189
+ readonly scroll?: AnnotationScroll;
190
+ }
147
191
  /**
148
192
  * The box of the mark the host follows (`annotations.track`, P112), in the frame's viewport, at
149
193
  * an animation frame where it moved: at most 60 a second, for that mark only, clamped to the
150
- * frame. The content's word: where to put a card beside it, nothing more.
194
+ * frame. The content's word: where to put a card beside it, nothing more. A newer shell (P132)
195
+ * adds the mark's `documentRect` and the document's `scroll`: the mark's box moves as the
196
+ * document scrolls, so a host following one mark hears the scroll at every animation frame where
197
+ * it changed, whether that mark is in the frame or not, and places every mark it holds a
198
+ * `documentRect` for (an `anchored` report's) without asking again. A newer one still (P133) adds
199
+ * its `lastLineDocumentRect`.
151
200
  */
152
- | { readonly type: "tracked"; readonly id: string; readonly rect: AnnotationRect }
201
+ | {
202
+ readonly type: "tracked";
203
+ readonly id: string;
204
+ readonly rect: AnnotationRect;
205
+ readonly documentRect?: AnnotationRect;
206
+ readonly lastLineDocumentRect?: AnnotationRect;
207
+ readonly scroll?: AnnotationScroll;
208
+ }
153
209
  /**
154
210
  * The person clicked the marker of a mark the host shows with a `count` (P104), or of a draft
155
- * (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
156
213
  * it for any mark the host shows with a marker, and can tell a real one happened: open the
157
214
  * host's own view of that mark, never act on it.
158
215
  */
@@ -175,7 +232,7 @@ export const ANNOTATE_METHODS = {
175
232
  unselected: "porthole/annotate.unselected",
176
233
  cancelled: "porthole/annotate.cancelled",
177
234
  anchored: "porthole/annotate.anchored",
178
- /** 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). */
179
236
  activated: "porthole/annotate.activated",
180
237
  /** Host → frame: follow one mark's box (`{ id }`), or none (`{ id: null }`) (P112). */
181
238
  track: "porthole/annotate.track",
@@ -6,6 +6,7 @@ import {
6
6
  type AnnotationMark,
7
7
  type AnnotationRect,
8
8
  type AnnotationReport,
9
+ type AnnotationScroll,
9
10
  type AnnotationSelector,
10
11
  } from "./types.ts";
11
12
  import { withoutUnseen } from "../bridge/unseen.ts";
@@ -112,6 +113,17 @@ export function parseRect(value: unknown): AnnotationRect | null {
112
113
  return { x, y, width, height };
113
114
  }
114
115
 
116
+ /**
117
+ * How far the document is scrolled (P132): two finite numbers within the coordinate limit (either
118
+ * may be negative: an engine's overscroll); null for anything else.
119
+ */
120
+ export function parseScroll(value: unknown): AnnotationScroll | null {
121
+ if (!isRecord(value) || !coordinate(value.x) || !coordinate(value.y)) {
122
+ return null;
123
+ }
124
+ return { x: value.x, y: value.y };
125
+ }
126
+
115
127
  /**
116
128
  * A box the frame reported, clamped to the frame's viewport (`width` by `height`, CSS px, P104):
117
129
  * each side is held within it, so what overlaps the viewport keeps the part inside, and what lies
@@ -152,7 +164,12 @@ function results(value: unknown): AnchorResult[] | null {
152
164
  return null;
153
165
  }
154
166
  const rect = each.rect === undefined ? undefined : parseRect(each.rect);
155
- if (rect === null) {
167
+ // Where it is in the document (P132): a box as `rect` is, never clamped.
168
+ const documentRect = each.documentRect === undefined ? undefined : parseRect(each.documentRect);
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) {
156
173
  return null;
157
174
  }
158
175
  // A place among the marks (P112): a whole number below the most marks a show carries.
@@ -167,6 +184,8 @@ function results(value: unknown): AnchorResult[] | null {
167
184
  id: each.id,
168
185
  state: "attached",
169
186
  ...(rect === undefined ? {} : { rect }),
187
+ ...(documentRect === undefined ? {} : { documentRect }),
188
+ ...(lastLineDocumentRect === undefined ? {} : { lastLineDocumentRect }),
170
189
  ...(order === undefined ? {} : { order }),
171
190
  });
172
191
  }
@@ -182,7 +201,22 @@ export function parseReport(value: unknown): AnnotationReport | null {
182
201
  case "selected": {
183
202
  const anchor = parseAnchor(value.anchor);
184
203
  const rect = parseRect(value.rect);
185
- 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
+ };
186
220
  }
187
221
  case "unselected":
188
222
  return { type: "unselected" };
@@ -190,7 +224,10 @@ export function parseReport(value: unknown): AnnotationReport | null {
190
224
  return { type: "cancelled" };
191
225
  case "anchored": {
192
226
  const checked = results(value.results);
193
- return checked === null ? null : { type: "anchored", results: checked };
227
+ const scroll = value.scroll === undefined ? undefined : parseScroll(value.scroll);
228
+ return checked === null || scroll === null
229
+ ? null
230
+ : { type: "anchored", results: checked, ...(scroll === undefined ? {} : { scroll }) };
194
231
  }
195
232
  case "activated": {
196
233
  const rect = parseRect(value.rect);
@@ -198,7 +235,31 @@ export function parseReport(value: unknown): AnnotationReport | null {
198
235
  }
199
236
  case "tracked": {
200
237
  const rect = parseRect(value.rect);
201
- return !markId(value.id) || rect === null ? null : { type: "tracked", id: value.id, rect };
238
+ // A newer shell's (P132): where the mark is in the document, and how far it is scrolled.
239
+ const documentRect =
240
+ value.documentRect === undefined ? undefined : parseRect(value.documentRect);
241
+ const lastLineDocumentRect =
242
+ value.lastLineDocumentRect === undefined
243
+ ? undefined
244
+ : parseRect(value.lastLineDocumentRect);
245
+ const scroll = value.scroll === undefined ? undefined : parseScroll(value.scroll);
246
+ if (
247
+ !markId(value.id) ||
248
+ rect === null ||
249
+ documentRect === null ||
250
+ lastLineDocumentRect === null ||
251
+ scroll === null
252
+ ) {
253
+ return null;
254
+ }
255
+ return {
256
+ type: "tracked",
257
+ id: value.id,
258
+ rect,
259
+ ...(documentRect === undefined ? {} : { documentRect }),
260
+ ...(lastLineDocumentRect === undefined ? {} : { lastLineDocumentRect }),
261
+ ...(scroll === undefined ? {} : { scroll }),
262
+ };
202
263
  }
203
264
  default:
204
265
  return null;
@@ -389,7 +389,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
389
389
  };
390
390
  /**
391
391
  * Every box a report carries, clamped to the frame's viewport as it is now (P104): the page
392
- * places the host's own UI nowhere outside its frame.
392
+ * places the host's own UI nowhere outside its frame. A mark's `documentRect` and the
393
+ * document's `scroll` (P132) pass as they were checked: where a mark is in the document,
394
+ * offscreen too, which a clamp would erase; the host clips what it draws from them.
393
395
  */
394
396
  const withinFrame = (report: AnnotationReport): AnnotationReport => {
395
397
  const viewport = frameViewport();
@@ -400,7 +402,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
400
402
  return { ...report, rect: clampRect(report.rect, viewport) };
401
403
  case "anchored":
402
404
  return {
403
- type: "anchored",
405
+ ...report,
404
406
  results: report.results.map((result) =>
405
407
  result.rect === undefined
406
408
  ? result
@@ -490,7 +492,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
490
492
  if (results.length === 0) {
491
493
  return;
492
494
  }
493
- report = { type: "anchored", results };
495
+ report = { ...report, results };
494
496
  break;
495
497
  }
496
498
  case "activated": {
package/src/host/types.ts CHANGED
@@ -306,7 +306,9 @@ export interface AnnotationControls {
306
306
  * Follows one shown mark (P112): while it moves (a scroll, a layout change) the display reports
307
307
  * `{ type: "tracked", id, rect }` at most once per animation frame (60 a second), its box clamped
308
308
  * to the frame, for that mark only; `null` stops. One at a time: a new id replaces the last.
309
- * Throws for an id no shown mark has; a `show` without it, or `clear`, stops it.
309
+ * Throws for an id no shown mark has; a `show` without it, or `clear`, stops it. From a newer
310
+ * shell (P132) each also carries the mark's `documentRect` and the document's `scroll`, so
311
+ * following one mark tells how far the document scrolled, for every mark placed by `documentRect`.
310
312
  */
311
313
  track(id: string | null): void;
312
314
  /** Removes every mark. */
package/src/index.ts CHANGED
@@ -342,12 +342,13 @@ export {
342
342
  type AnnotationMarkKind,
343
343
  type AnnotationRect,
344
344
  type AnnotationReport,
345
+ type AnnotationScroll,
345
346
  type AnnotationSelector,
346
347
  type CssSelector,
347
348
  type TextPositionSelector,
348
349
  type TextQuoteSelector,
349
350
  } from "./annotate/types.ts";
350
- export { parseAnchor, parseRect, parseReport } from "./annotate/validate.ts";
351
+ export { parseAnchor, parseRect, parseReport, parseScroll } from "./annotate/validate.ts";
351
352
 
352
353
  // Find in page (P131): the host's find bar, the frame's matches, and the host's checks on both.
353
354
  export {
@@ -690,7 +690,8 @@ export interface PortholeFrameProps {
690
690
  | null;
691
691
  /**
692
692
  * The mark to follow (`annotations.track`, P112, P118): while it moves, `onAnnotation` gets
693
- * `{ type: "tracked", id, rect }` at most once per animation frame, for it alone. `null` (or
693
+ * `{ type: "tracked", id, rect }` at most once per animation frame, for it alone (from a newer
694
+ * shell with its `documentRect` and the document's `scroll`, P132). `null` (or
694
695
  * leaving it out once set) stops. By value: given when it changes, and when the display is made.
695
696
  * Only a shown mark (`annotations`) is followed: another id, or a config without `annotate`, is
696
697
  * `onHostError` (kind `"annotations"`), as the core's call throws. `annotations` without it