@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 +39 -0
- package/dist/annotate/types.d.ts +62 -13
- package/dist/annotate/types.js +1 -1
- package/dist/annotate/validate.d.ts +6 -1
- package/dist/annotate/validate.js +57 -4
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +5 -3
- package/dist/host/types.d.ts +3 -1
- package/dist/index.d.ts +2 -2
- package/dist/index.js +1 -1
- package/dist/react/frame.d.ts +2 -1
- package/dist/shell/annotate.d.ts +13 -5
- package/dist/shell/annotate.js +259 -48
- package/dist/shell/find.d.ts +1 -1
- package/dist/shell/find.js +1 -1
- package/docs/ADOPTING.md +60 -3
- package/docs/ARCHITECTURE.md +4 -3
- package/docs/DECISIONS.md +204 -2
- package/docs/DESIGN.md +61 -17
- package/docs/THREAT_MODEL.md +37 -3
- package/package.json +1 -1
- package/src/annotate/types.ts +72 -15
- package/src/annotate/validate.ts +65 -4
- package/src/host/create-host.ts +5 -3
- package/src/host/types.ts +3 -1
- package/src/index.ts +2 -1
- package/src/react/frame.tsx +2 -1
- package/src/shell/annotate.ts +259 -48
- package/src/shell/find.ts +1 -1
package/src/annotate/types.ts
CHANGED
|
@@ -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
|
|
87
|
-
* `ANNOTATION_LIMITS.count`, a larger one clamped to it (P116); above 99 it reads "99+", 0
|
|
88
|
-
* the bubble alone) at the end of a
|
|
89
|
-
*
|
|
90
|
-
* `activated`.
|
|
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
|
|
98
|
-
*
|
|
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
|
-
/**
|
|
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
|
-
| {
|
|
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
|
-
| {
|
|
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
|
|
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",
|
package/src/annotate/validate.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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;
|
package/src/host/create-host.ts
CHANGED
|
@@ -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
|
-
|
|
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 = {
|
|
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 {
|
package/src/react/frame.tsx
CHANGED
|
@@ -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
|
|
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
|