@botiverse/porthole 0.14.14 → 0.14.15

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,33 @@
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.15
8
+
9
+ - **Annotations: the selection followed (P138).** `annotations.track({ selection: true })` (React:
10
+ `trackedSelection`) follows what the last `selected` reported, the element picked or the words
11
+ selected, so your composer can stay beside it: `selectionTracked` reports come as `tracked` ones
12
+ do (at most 60 a second, the same boxes), with `inView` to hide the composer while it is out of
13
+ view, and `state: "orphaned"` while it isn't in the page. While it is followed the frame
14
+ highlights it, a picked element in the picking outline, so the page shows what the comment is
15
+ for. `track(null)`, a mark's id or `clear` ends it and the highlight (React: `trackedSelection`
16
+ false gives `trackedAnnotation` back). An older shell sends nothing and draws nothing: place by
17
+ `selected` until a `selectionTracked` comes. Upgrade the content server for the shell's part.
18
+ - **Annotations: a pick keeps its outline (P138, Tenny's review).** The element just picked stays
19
+ outlined after `selected`, so nothing flickers before you follow it, and the follow's highlight
20
+ takes over. Without a follow it ends as a selection does: the next pick or selection,
21
+ `clearSelection`, `start` or `stop`, `clear`, Escape in the frame, or the element leaving the
22
+ page. With an older host, this is the one change people see from a newer content server: the
23
+ outline no longer goes the moment they pick. Call `track({ selection: true })` before a `start` or
24
+ `stop` you send at the same time (React does).
25
+ - **Annotations: no re-sent `selected` while the selection is followed (P138, Tenny's review).** A
26
+ scroll no longer re-sends it once it settles (P105) while you follow it: `selectionTracked` says
27
+ where it is. New selections are reported as before, and once the following ends a scroll re-sends
28
+ it again.
29
+ - **Security (P138):** no CSP, sandbox, egress or gate changes. The host takes `selectionTracked`
30
+ only while it follows the selection, on `tracked`'s 60 a second (control
31
+ `track-selection-checks`). It carries boxes only. A composer that follows is a view a report
32
+ moves: guard it as THREAT_MODEL §6 says, and end the following on every close.
33
+
7
34
  ## 0.14.14
8
35
 
9
36
  - **Nested pages: `display.focus()` reaches the page (P136).** It stopped at the page's shell on every
@@ -77,6 +77,14 @@ export interface AnnotateMode {
77
77
  /** Text, by selecting it: each settled selection is reported, and its clearing. */
78
78
  readonly text?: boolean;
79
79
  }
80
+ /**
81
+ * What `annotations.track` follows (P112, P138): a shown mark, by its id; the selection the frame
82
+ * last reported as `selected` (the element picked, or the words selected), highlighted in the
83
+ * frame while followed; or nothing (`null`). One at a time: each replaces the last.
84
+ */
85
+ export type AnnotationTrackTarget = string | {
86
+ readonly selection: true;
87
+ } | null;
80
88
  /**
81
89
  * An anchor the host marks in the frame, under its own id. Everything here is sent into the
82
90
  * frame, so the content can read it: give ids that say nothing (never a person's name or the
@@ -200,6 +208,32 @@ export type AnnotationReport =
200
208
  readonly lastLineDocumentRect?: AnnotationRect;
201
209
  readonly scroll?: AnnotationScroll;
202
210
  }
211
+ /**
212
+ * Where the selection the host follows is (`annotations.track({ selection: true })`, P138): the
213
+ * element picked or the words selected, as the last `selected` reported them, at an animation
214
+ * frame where it moved or the frame's viewport changed size; at most 60 a second, together with
215
+ * `tracked` (one followed thing at a time). The same boxes as `tracked`'s: `rect` clamped to the
216
+ * frame, `documentRect` and `lastLineDocumentRect` in the document and unclamped, the `scroll`
217
+ * they were read at, always there. `inView`: whether any of it is inside the frame's viewport
218
+ * (false where the shell says so, or where `rect` lies wholly outside the viewport as the host
219
+ * reads it); hide UI attached to it while false. `orphaned`: it isn't in the page now (taken out,
220
+ * its words gone; or the frame has no selection, a new frame after a reload); `attached` again if
221
+ * it is found again by its anchor. The first report comes at the frame's next animation frame
222
+ * after the host asks, which is how a host tells a shell that follows a selection (an older one
223
+ * sends none). Geometry only, as `tracked`: no anchor, no words. The content's word.
224
+ */
225
+ | {
226
+ readonly type: "selectionTracked";
227
+ readonly state: "attached";
228
+ readonly rect: AnnotationRect;
229
+ readonly documentRect: AnnotationRect;
230
+ readonly lastLineDocumentRect?: AnnotationRect;
231
+ readonly scroll: AnnotationScroll;
232
+ readonly inView: boolean;
233
+ } | {
234
+ readonly type: "selectionTracked";
235
+ readonly state: "orphaned";
236
+ }
203
237
  /**
204
238
  * The person clicked the marker of a mark the host shows with a `count` (P104), or of a draft
205
239
  * (P107), or pressed Enter or Space on it (P133); `rect` is the marker's box, to open the host's
@@ -231,10 +265,16 @@ export declare const ANNOTATE_METHODS: {
231
265
  readonly anchored: "porthole/annotate.anchored";
232
266
  /** Frame → host: a mark's marker was clicked, or pressed from the keyboard (P104, P133). */
233
267
  readonly activated: "porthole/annotate.activated";
234
- /** Host → frame: follow one mark's box (`{ id }`), or none (`{ id: null }`) (P112). */
268
+ /**
269
+ * Host → frame: follow one mark's box (`{ id }`), or none (`{ id: null }`) (P112), or the
270
+ * selection last reported, highlighted while followed (`{ id: null, selection: true }`, P138: an
271
+ * older shell reads it as none).
272
+ */
235
273
  readonly track: "porthole/annotate.track";
236
274
  /** Frame → host: the followed mark's box, as it moves (P112). */
237
275
  readonly tracked: "porthole/annotate.tracked";
276
+ /** Frame → host: where the followed selection is, as it moves (P138). */
277
+ readonly selectionTracked: "porthole/annotate.selectionTracked";
238
278
  /** Host → frame: take the page's text selection away, telling nothing back (P115). */
239
279
  readonly clearSelection: "porthole/annotate.clearSelection";
240
280
  /**
@@ -30,10 +30,16 @@ export const ANNOTATE_METHODS = {
30
30
  anchored: "porthole/annotate.anchored",
31
31
  /** Frame → host: a mark's marker was clicked, or pressed from the keyboard (P104, P133). */
32
32
  activated: "porthole/annotate.activated",
33
- /** Host → frame: follow one mark's box (`{ id }`), or none (`{ id: null }`) (P112). */
33
+ /**
34
+ * Host → frame: follow one mark's box (`{ id }`), or none (`{ id: null }`) (P112), or the
35
+ * selection last reported, highlighted while followed (`{ id: null, selection: true }`, P138: an
36
+ * older shell reads it as none).
37
+ */
34
38
  track: "porthole/annotate.track",
35
39
  /** Frame → host: the followed mark's box, as it moves (P112). */
36
40
  tracked: "porthole/annotate.tracked",
41
+ /** Frame → host: where the followed selection is, as it moves (P138). */
42
+ selectionTracked: "porthole/annotate.selectionTracked",
37
43
  /** Host → frame: take the page's text selection away, telling nothing back (P115). */
38
44
  clearSelection: "porthole/annotate.clearSelection",
39
45
  /**
@@ -1,4 +1,4 @@
1
- import { type AnnotateMode, type AnnotationAnchor, type AnnotationMark, type AnnotationRect, type AnnotationReport, type AnnotationScroll } from "./types.ts";
1
+ import { type AnnotateMode, type AnnotationAnchor, type AnnotationMark, type AnnotationRect, type AnnotationReport, type AnnotationScroll, type AnnotationTrackTarget } 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
@@ -23,6 +23,15 @@ export declare function clampRect(rect: AnnotationRect, viewport: {
23
23
  readonly width: number;
24
24
  readonly height: number;
25
25
  } | null | undefined): AnnotationRect;
26
+ /**
27
+ * Whether a box the frame reported overlaps the frame's viewport (P138), before it is clamped: a
28
+ * box of no width or height counts where it lies strictly inside. Where the viewport isn't known,
29
+ * nothing is in it, as `clampRect` puts every box at the corner then.
30
+ */
31
+ export declare function inViewport(rect: AnnotationRect, viewport: {
32
+ readonly width: number;
33
+ readonly height: number;
34
+ } | null | undefined): boolean;
26
35
  /** A report from the frame, checked; null if malformed (it is then dropped). */
27
36
  export declare function parseReport(value: unknown): AnnotationReport | null;
28
37
  /** What the host may start with: elements, text, or both (default both). */
@@ -40,3 +49,10 @@ export declare const hasMarker: (mark: AnnotationMark) => boolean;
40
49
  * told one).
41
50
  */
42
51
  export declare function checkMarks(marks: readonly AnnotationMark[]): AnnotationMark[];
52
+ /**
53
+ * Whether what `annotations.track` is given names the selection (P138): an object whose own
54
+ * `selection` is `true`, and nothing else does (a mark's id is a string).
55
+ */
56
+ export declare const followsSelection: (target: AnnotationTrackTarget | undefined) => target is {
57
+ readonly selection: true;
58
+ };
@@ -115,6 +115,21 @@ export function clampRect(rect, viewport) {
115
115
  const bottom = within(rect.y + rect.height, height);
116
116
  return { x: left, y: top, width: right - left, height: bottom - top };
117
117
  }
118
+ /**
119
+ * Whether a box the frame reported overlaps the frame's viewport (P138), before it is clamped: a
120
+ * box of no width or height counts where it lies strictly inside. Where the viewport isn't known,
121
+ * nothing is in it, as `clampRect` puts every box at the corner then.
122
+ */
123
+ export function inViewport(rect, viewport) {
124
+ if (viewport === null || typeof viewport !== "object") {
125
+ return false;
126
+ }
127
+ const { width, height } = viewport;
128
+ if (!Number.isFinite(width) || !Number.isFinite(height)) {
129
+ return false;
130
+ }
131
+ return rect.x < width && rect.x + rect.width > 0 && rect.y < height && rect.y + rect.height > 0;
132
+ }
118
133
  const markId = (value) => text(value, LIMITS.id, 1);
119
134
  function results(value) {
120
135
  if (!Array.isArray(value) || value.length > LIMITS.marks) {
@@ -236,6 +251,37 @@ export function parseReport(value) {
236
251
  ...(scroll === undefined ? {} : { scroll }),
237
252
  };
238
253
  }
254
+ case "selectionTracked": {
255
+ // The followed selection (P138): gone, or where it is. New with its shell, so every box but
256
+ // the last line, and the scroll, are there; nothing about the page's words is.
257
+ if (value.state === "orphaned") {
258
+ return { type: "selectionTracked", state: "orphaned" };
259
+ }
260
+ if (value.state !== "attached" || typeof value.inView !== "boolean") {
261
+ return null;
262
+ }
263
+ const rect = parseRect(value.rect);
264
+ const documentRect = parseRect(value.documentRect);
265
+ const scroll = parseScroll(value.scroll);
266
+ const lastLineDocumentRect = value.lastLineDocumentRect === undefined
267
+ ? undefined
268
+ : parseRect(value.lastLineDocumentRect);
269
+ if (rect === null ||
270
+ documentRect === null ||
271
+ scroll === null ||
272
+ lastLineDocumentRect === null) {
273
+ return null;
274
+ }
275
+ return {
276
+ type: "selectionTracked",
277
+ state: "attached",
278
+ rect,
279
+ documentRect,
280
+ ...(lastLineDocumentRect === undefined ? {} : { lastLineDocumentRect }),
281
+ scroll,
282
+ inView: value.inView,
283
+ };
284
+ }
239
285
  default:
240
286
  return null;
241
287
  }
@@ -293,3 +339,12 @@ export function checkMarks(marks) {
293
339
  };
294
340
  });
295
341
  }
342
+ /**
343
+ * Whether what `annotations.track` is given names the selection (P138): an object whose own
344
+ * `selection` is `true`, and nothing else does (a mark's id is a string).
345
+ */
346
+ export const followsSelection = (target) => typeof target === "object" &&
347
+ target !== null &&
348
+ Object.hasOwn(target, "selection") &&
349
+ // A caller's word, untyped as JavaScript passes it: `true` and nothing else.
350
+ target.selection === true;