@botiverse/porthole 0.14.14 → 0.14.16
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 +58 -0
- package/dist/annotate/types.d.ts +50 -1
- package/dist/annotate/types.js +7 -1
- package/dist/annotate/validate.d.ts +26 -3
- package/dist/annotate/validate.js +64 -2
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +56 -6
- package/dist/host/types.d.ts +24 -3
- package/dist/index.d.ts +1 -1
- package/dist/react/frame.d.ts +20 -1
- package/dist/react/frame.js +59 -26
- package/dist/shell/annotate.d.ts +8 -2
- package/dist/shell/annotate.js +178 -11
- package/dist/shell/runtime.d.ts +10 -0
- package/dist/shell/runtime.js +72 -26
- package/docs/ADOPTING.md +50 -1
- package/docs/DECISIONS.md +370 -4
- package/docs/DESIGN.md +37 -6
- package/docs/THREAT_MODEL.md +32 -5
- package/package.json +1 -1
- package/src/annotate/types.ts +47 -1
- package/src/annotate/validate.ts +82 -3
- package/src/host/create-host.ts +59 -11
- package/src/host/types.ts +29 -3
- package/src/index.ts +1 -0
- package/src/react/frame.tsx +91 -33
- package/src/shell/annotate.ts +178 -11
- package/src/shell/runtime.ts +73 -26
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,64 @@
|
|
|
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.16
|
|
8
|
+
|
|
9
|
+
- **On a tab the shell asks no host (P139).** A page opened on a tab of its own no longer asks
|
|
10
|
+
`ui/initialize` 40 times over 10 s before the runtime says it has nothing to offer: there is no
|
|
11
|
+
host there to answer, so it says so at once, with no request and no timer. In a frame nothing
|
|
12
|
+
changes. `porthole.use` was already null at once on a tab, so pages draw as before.
|
|
13
|
+
- **The shell says how its handshake ended (P139).** The document's root (`<html>`) carries
|
|
14
|
+
`data-porthole-host`, kept when a whole page replaces the shell's body: `"none"` once no host
|
|
15
|
+
will answer (on a tab, before the page's own scripts run), `"answered"` once one has. A tool that shoots pages on a tab (a publish check) can wait for
|
|
16
|
+
it instead of a fixed 10 s, keeping the fixed wait where it is absent (an older shell). It is the
|
|
17
|
+
page's word, never a gate. Upgrade the content server for it.
|
|
18
|
+
- **Security (P139):** no CSP, sandbox, egress, gate or message changes. On a tab the shell sent
|
|
19
|
+
nothing before either (its parent is itself).
|
|
20
|
+
- **Annotations: a pick stays lit only for a host that follows it (P140, Ferryman's audit of
|
|
21
|
+
0.14.15).** 0.14.15 kept every pick outlined after `selected`, and every selection in the frame's
|
|
22
|
+
memory, for every host, including one that never follows the selection. Now that happens only for
|
|
23
|
+
a host that says it follows what is selected: `annotations.start({ ..., keepSelection: true })`
|
|
24
|
+
(React does it for you on a start made while `trackedSelection` is given; giving it or leaving it
|
|
25
|
+
out later restarts no mode). Any other host gets 0.14.14's
|
|
26
|
+
behaviour: the outline goes with the pick, and the frame keeps nothing. A follow asked before the
|
|
27
|
+
pick follows it without the option. **If you follow the selection after `selected`** (0.14.15's
|
|
28
|
+
sample, and React with `trackedSelection`), start with `keepSelection: true`, or give
|
|
29
|
+
`trackedSelection` from the first render (`false` until the composer opens): without it a newer
|
|
30
|
+
content server has nothing to follow and answers `orphaned`, so upgrade the host with the content
|
|
31
|
+
server.
|
|
32
|
+
- **Annotations: an unasked `selectionTracked` is no refusal (P140).** A host that follows no
|
|
33
|
+
selection drops it unread, as 0.14.14 did, instead of counting a malformed one as `invalid`.
|
|
34
|
+
- **Security (P140):** a narrowing: less drawn and less kept for a host that doesn't follow, and a
|
|
35
|
+
page's word read by fewer hosts. No CSP, sandbox, egress or gate changes; control
|
|
36
|
+
`track-selection-checks` covers the unread drop too.
|
|
37
|
+
|
|
38
|
+
## 0.14.15
|
|
39
|
+
|
|
40
|
+
- **Annotations: the selection followed (P138).** `annotations.track({ selection: true })` (React:
|
|
41
|
+
`trackedSelection`) follows what the last `selected` reported, the element picked or the words
|
|
42
|
+
selected, so your composer can stay beside it: `selectionTracked` reports come as `tracked` ones
|
|
43
|
+
do (at most 60 a second, the same boxes), with `inView` to hide the composer while it is out of
|
|
44
|
+
view, and `state: "orphaned"` while it isn't in the page. While it is followed the frame
|
|
45
|
+
highlights it, a picked element in the picking outline, so the page shows what the comment is
|
|
46
|
+
for. `track(null)`, a mark's id or `clear` ends it and the highlight (React: `trackedSelection`
|
|
47
|
+
false gives `trackedAnnotation` back). An older shell sends nothing and draws nothing: place by
|
|
48
|
+
`selected` until a `selectionTracked` comes. Upgrade the content server for the shell's part.
|
|
49
|
+
- **Annotations: a pick keeps its outline (P138, Tenny's review).** The element just picked stays
|
|
50
|
+
outlined after `selected`, so nothing flickers before you follow it, and the follow's highlight
|
|
51
|
+
takes over. Without a follow it ends as a selection does: the next pick or selection,
|
|
52
|
+
`clearSelection`, `start` or `stop`, `clear`, Escape in the frame, or the element leaving the
|
|
53
|
+
page. With an older host, this is the one change people see from a newer content server: the
|
|
54
|
+
outline no longer goes the moment they pick. Call `track({ selection: true })` before a `start` or
|
|
55
|
+
`stop` you send at the same time (React does).
|
|
56
|
+
- **Annotations: no re-sent `selected` while the selection is followed (P138, Tenny's review).** A
|
|
57
|
+
scroll no longer re-sends it once it settles (P105) while you follow it: `selectionTracked` says
|
|
58
|
+
where it is. New selections are reported as before, and once the following ends a scroll re-sends
|
|
59
|
+
it again.
|
|
60
|
+
- **Security (P138):** no CSP, sandbox, egress or gate changes. The host takes `selectionTracked`
|
|
61
|
+
only while it follows the selection, on `tracked`'s 60 a second (control
|
|
62
|
+
`track-selection-checks`). It carries boxes only. A composer that follows is a view a report
|
|
63
|
+
moves: guard it as THREAT_MODEL §6 says, and end the following on every close.
|
|
64
|
+
|
|
7
65
|
## 0.14.14
|
|
8
66
|
|
|
9
67
|
- **Nested pages: `display.focus()` reaches the page (P136).** It stopped at the page's shell on every
|
package/dist/annotate/types.d.ts
CHANGED
|
@@ -76,7 +76,24 @@ export interface AnnotateMode {
|
|
|
76
76
|
readonly elements?: boolean | "hold";
|
|
77
77
|
/** Text, by selecting it: each settled selection is reported, and its clearing. */
|
|
78
78
|
readonly text?: boolean;
|
|
79
|
+
/**
|
|
80
|
+
* That you follow what is selected (P140): `annotations.track({ selection: true })` once
|
|
81
|
+
* `selected` comes (React sets it while `trackedSelection` is given). Only then does the frame
|
|
82
|
+
* keep it for you to follow, the element just picked outlined until the follow takes over. Without
|
|
83
|
+
* it the frame keeps nothing and a pick's outline goes with the pick, as before 0.14.15; a follow
|
|
84
|
+
* asked before the pick still follows each selection reported while it lasts.
|
|
85
|
+
*/
|
|
86
|
+
readonly keepSelection?: boolean;
|
|
79
87
|
}
|
|
88
|
+
/**
|
|
89
|
+
* What `annotations.track` follows (P112, P138): a shown mark, by its id; the selection the frame
|
|
90
|
+
* last reported as `selected` (the element picked, or the words selected), highlighted in the
|
|
91
|
+
* frame while followed, and kept for a follow asked after `selected` only under `start`'s
|
|
92
|
+
* `keepSelection` (P140); or nothing (`null`). One at a time: each replaces the last.
|
|
93
|
+
*/
|
|
94
|
+
export type AnnotationTrackTarget = string | {
|
|
95
|
+
readonly selection: true;
|
|
96
|
+
} | null;
|
|
80
97
|
/**
|
|
81
98
|
* An anchor the host marks in the frame, under its own id. Everything here is sent into the
|
|
82
99
|
* frame, so the content can read it: give ids that say nothing (never a person's name or the
|
|
@@ -200,6 +217,32 @@ export type AnnotationReport =
|
|
|
200
217
|
readonly lastLineDocumentRect?: AnnotationRect;
|
|
201
218
|
readonly scroll?: AnnotationScroll;
|
|
202
219
|
}
|
|
220
|
+
/**
|
|
221
|
+
* Where the selection the host follows is (`annotations.track({ selection: true })`, P138): the
|
|
222
|
+
* element picked or the words selected, as the last `selected` reported them, at an animation
|
|
223
|
+
* frame where it moved or the frame's viewport changed size; at most 60 a second, together with
|
|
224
|
+
* `tracked` (one followed thing at a time). The same boxes as `tracked`'s: `rect` clamped to the
|
|
225
|
+
* frame, `documentRect` and `lastLineDocumentRect` in the document and unclamped, the `scroll`
|
|
226
|
+
* they were read at, always there. `inView`: whether any of it is inside the frame's viewport
|
|
227
|
+
* (false where the shell says so, or where `rect` lies wholly outside the viewport as the host
|
|
228
|
+
* reads it); hide UI attached to it while false. `orphaned`: it isn't in the page now (taken out,
|
|
229
|
+
* its words gone; or the frame has no selection, a new frame after a reload); `attached` again if
|
|
230
|
+
* it is found again by its anchor. The first report comes at the frame's next animation frame
|
|
231
|
+
* after the host asks, which is how a host tells a shell that follows a selection (an older one
|
|
232
|
+
* sends none). Geometry only, as `tracked`: no anchor, no words. The content's word.
|
|
233
|
+
*/
|
|
234
|
+
| {
|
|
235
|
+
readonly type: "selectionTracked";
|
|
236
|
+
readonly state: "attached";
|
|
237
|
+
readonly rect: AnnotationRect;
|
|
238
|
+
readonly documentRect: AnnotationRect;
|
|
239
|
+
readonly lastLineDocumentRect?: AnnotationRect;
|
|
240
|
+
readonly scroll: AnnotationScroll;
|
|
241
|
+
readonly inView: boolean;
|
|
242
|
+
} | {
|
|
243
|
+
readonly type: "selectionTracked";
|
|
244
|
+
readonly state: "orphaned";
|
|
245
|
+
}
|
|
203
246
|
/**
|
|
204
247
|
* The person clicked the marker of a mark the host shows with a `count` (P104), or of a draft
|
|
205
248
|
* (P107), or pressed Enter or Space on it (P133); `rect` is the marker's box, to open the host's
|
|
@@ -231,10 +274,16 @@ export declare const ANNOTATE_METHODS: {
|
|
|
231
274
|
readonly anchored: "porthole/annotate.anchored";
|
|
232
275
|
/** Frame → host: a mark's marker was clicked, or pressed from the keyboard (P104, P133). */
|
|
233
276
|
readonly activated: "porthole/annotate.activated";
|
|
234
|
-
/**
|
|
277
|
+
/**
|
|
278
|
+
* Host → frame: follow one mark's box (`{ id }`), or none (`{ id: null }`) (P112), or the
|
|
279
|
+
* selection last reported, highlighted while followed (`{ id: null, selection: true }`, P138: an
|
|
280
|
+
* older shell reads it as none).
|
|
281
|
+
*/
|
|
235
282
|
readonly track: "porthole/annotate.track";
|
|
236
283
|
/** Frame → host: the followed mark's box, as it moves (P112). */
|
|
237
284
|
readonly tracked: "porthole/annotate.tracked";
|
|
285
|
+
/** Frame → host: where the followed selection is, as it moves (P138). */
|
|
286
|
+
readonly selectionTracked: "porthole/annotate.selectionTracked";
|
|
238
287
|
/** Host → frame: take the page's text selection away, telling nothing back (P115). */
|
|
239
288
|
readonly clearSelection: "porthole/annotate.clearSelection";
|
|
240
289
|
/**
|
package/dist/annotate/types.js
CHANGED
|
@@ -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
|
-
/**
|
|
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,10 +23,26 @@ 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
|
-
/**
|
|
29
|
-
export
|
|
37
|
+
/** A mode as the frame gets it: `keepSelection` only where it is true (P140). */
|
|
38
|
+
export type StartedMode = Required<Omit<AnnotateMode, "keepSelection">> & {
|
|
39
|
+
readonly keepSelection?: true;
|
|
40
|
+
};
|
|
41
|
+
/**
|
|
42
|
+
* What the host may start with: elements, text, or both (default both); and whether it follows
|
|
43
|
+
* what is selected (`keepSelection`, P140).
|
|
44
|
+
*/
|
|
45
|
+
export declare function annotateMode(mode: AnnotateMode | undefined): StartedMode;
|
|
30
46
|
/**
|
|
31
47
|
* Whether a mark gets a marker, the one thing a person can click (P104): one with a `count`, and
|
|
32
48
|
* every draft (P107).
|
|
@@ -40,3 +56,10 @@ export declare const hasMarker: (mark: AnnotationMark) => boolean;
|
|
|
40
56
|
* told one).
|
|
41
57
|
*/
|
|
42
58
|
export declare function checkMarks(marks: readonly AnnotationMark[]): AnnotationMark[];
|
|
59
|
+
/**
|
|
60
|
+
* Whether what `annotations.track` is given names the selection (P138): an object whose own
|
|
61
|
+
* `selection` is `true`, and nothing else does (a mark's id is a string).
|
|
62
|
+
*/
|
|
63
|
+
export declare const followsSelection: (target: AnnotationTrackTarget | undefined) => target is {
|
|
64
|
+
readonly selection: true;
|
|
65
|
+
};
|
|
@@ -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,20 +251,58 @@ 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
|
}
|
|
242
288
|
}
|
|
243
|
-
/**
|
|
289
|
+
/**
|
|
290
|
+
* What the host may start with: elements, text, or both (default both); and whether it follows
|
|
291
|
+
* what is selected (`keepSelection`, P140).
|
|
292
|
+
*/
|
|
244
293
|
export function annotateMode(mode) {
|
|
245
294
|
const elements = mode?.elements ?? true;
|
|
246
295
|
const words = mode?.text ?? true;
|
|
296
|
+
const keep = mode?.keepSelection ?? false;
|
|
247
297
|
if ((typeof elements !== "boolean" && elements !== "hold") ||
|
|
248
298
|
typeof words !== "boolean" ||
|
|
249
299
|
(elements === false && !words)) {
|
|
250
300
|
throw new TypeError("annotations.start: elements, text, or both");
|
|
251
301
|
}
|
|
252
|
-
|
|
302
|
+
if (typeof keep !== "boolean") {
|
|
303
|
+
throw new TypeError("annotations.start: keepSelection is true or false");
|
|
304
|
+
}
|
|
305
|
+
return { elements, text: words, ...(keep ? { keepSelection: true } : {}) };
|
|
253
306
|
}
|
|
254
307
|
/**
|
|
255
308
|
* Whether a mark gets a marker, the one thing a person can click (P104): one with a `count`, and
|
|
@@ -293,3 +346,12 @@ export function checkMarks(marks) {
|
|
|
293
346
|
};
|
|
294
347
|
});
|
|
295
348
|
}
|
|
349
|
+
/**
|
|
350
|
+
* Whether what `annotations.track` is given names the selection (P138): an object whose own
|
|
351
|
+
* `selection` is `true`, and nothing else does (a mark's id is a string).
|
|
352
|
+
*/
|
|
353
|
+
export const followsSelection = (target) => typeof target === "object" &&
|
|
354
|
+
target !== null &&
|
|
355
|
+
Object.hasOwn(target, "selection") &&
|
|
356
|
+
// A caller's word, untyped as JavaScript passes it: `true` and nothing else.
|
|
357
|
+
target.selection === true;
|