@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/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,45 @@
|
|
|
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.11
|
|
8
|
+
|
|
9
|
+
- **Annotations: markers are buttons (P133).** A marker is a real button in the frame's Tab order,
|
|
10
|
+
after the page's own stops and in reading order, named for what it is ("3 comments on …"; in
|
|
11
|
+
English). Enter or Space on it reports `activated` through the path a click takes, the same
|
|
12
|
+
gesture check included, unheard by the page's scripts, once for a key held down. The focus on a
|
|
13
|
+
marker lights its words and brings it into view. This reverses P104's "no tab stop": the page
|
|
14
|
+
shares that focus order, so a host keeps its own list of marks as the keyboard way that holds.
|
|
15
|
+
- **Annotations: a posted comment's marker sits at its paragraph's end (P133).** On the last line
|
|
16
|
+
of the block its words end in, just past the last word, or in the line's gutter where that
|
|
17
|
+
doesn't fit. A draft's stays beside its own words, and an element's on its corner.
|
|
18
|
+
- **Annotations: the last line (P133).** `selected`, each attached result of `anchored`, and
|
|
19
|
+
`tracked` now carry a `lastLineDocumentRect`, the last line with words on it (an element's whole
|
|
20
|
+
box) in the coordinates of `documentRect`, and `selected` carries the `scroll` it was read at, so
|
|
21
|
+
a host places its UI after the last line. Optional: an older shell sends neither (test for them),
|
|
22
|
+
and an older host drops them. Upgrade the content server (the shell) for all three.
|
|
23
|
+
- **Security (P133):** `lastLineDocumentRect` is the page's word, checked as any box and not clamped
|
|
24
|
+
to the frame: clip what you draw from it (THREAT_MODEL §6, ADOPTING). `rect` is clamped as before.
|
|
25
|
+
The keyboard on a marker is new (THREAT_MODEL §7): no CSP, sandbox, egress or gate changes.
|
|
26
|
+
|
|
27
|
+
## 0.14.10
|
|
28
|
+
|
|
29
|
+
- **Annotations: a mark's place in the document (P132).** Each attached result of an `anchored`
|
|
30
|
+
report now has a `documentRect` (its box in the document: it stays put as the page scrolls, and
|
|
31
|
+
says where a mark scrolled out of the frame is), and the report a `scroll` (`{ x, y }`, how far
|
|
32
|
+
the document was scrolled as the boxes were read); `rect` is `documentRect` less `scroll`, then
|
|
33
|
+
clamped as before. `tracked` (P112) carries both too, so following one mark tells the document's
|
|
34
|
+
scroll at every animation frame where it changed, whether that mark is in view or not: a host
|
|
35
|
+
places every mark from one report and keeps them placed as the page scrolls, without asking
|
|
36
|
+
again. New exports: `AnnotationScroll`, `parseScroll`. Both fields are optional: an older shell
|
|
37
|
+
sends neither (test for `scroll`), and an older host drops them. Upgrade the content server (the
|
|
38
|
+
shell) for them.
|
|
39
|
+
- **Security (P132):** `documentRect` is the page's word and isn't clamped to the frame (a clamp
|
|
40
|
+
would erase the offscreen places it is for); Porthole checks it as any box (finite, within
|
|
41
|
+
`ANNOTATION_LIMITS.coordinate`, sizes not negative; a malformed one, or a malformed `scroll`,
|
|
42
|
+
drops the report). Clip what you draw from it to the frame's box, or to your own region beside
|
|
43
|
+
it (THREAT_MODEL §6, ADOPTING). `rect` is clamped as before. No CSP, sandbox, egress or gate
|
|
44
|
+
changes.
|
|
45
|
+
|
|
7
46
|
## 0.14.9
|
|
8
47
|
|
|
9
48
|
- **Find in page (P131):** a host's own find bar over a display. Declare `find`
|
package/dist/annotate/types.d.ts
CHANGED
|
@@ -46,7 +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).
|
|
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.
|
|
50
51
|
*/
|
|
51
52
|
export interface AnnotationRect {
|
|
52
53
|
readonly x: number;
|
|
@@ -54,6 +55,16 @@ export interface AnnotationRect {
|
|
|
54
55
|
readonly width: number;
|
|
55
56
|
readonly height: number;
|
|
56
57
|
}
|
|
58
|
+
/**
|
|
59
|
+
* How far the frame's document is scrolled when the boxes beside it were read (P132), CSS px: the
|
|
60
|
+
* top left of the document's root element (`<html>`), from the viewport's, negated (`window.scrollX`
|
|
61
|
+
* and `window.scrollY` on a page whose root has no margin). A box in the viewport is its
|
|
62
|
+
* `documentRect` less this. The page's word, as every box is.
|
|
63
|
+
*/
|
|
64
|
+
export interface AnnotationScroll {
|
|
65
|
+
readonly x: number;
|
|
66
|
+
readonly y: number;
|
|
67
|
+
}
|
|
57
68
|
/** What the person may point at while the host is asking. */
|
|
58
69
|
export interface AnnotateMode {
|
|
59
70
|
/**
|
|
@@ -75,20 +86,21 @@ export interface AnnotationMark {
|
|
|
75
86
|
readonly id: string;
|
|
76
87
|
readonly anchor: AnnotationAnchor;
|
|
77
88
|
/**
|
|
78
|
-
* A marker (P104): with a count, the shell also draws a small bubble with this number
|
|
79
|
-
* `ANNOTATION_LIMITS.count`, a larger one clamped to it (P116); above 99 it reads "99+", 0
|
|
80
|
-
* the bubble alone) at the end of a
|
|
81
|
-
*
|
|
82
|
-
* `activated`.
|
|
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
|
+
* `anchor.label`. The content can read the number; give one only where the page may know it. A
|
|
83
95
|
* draft's is dropped (P107): its marker has no number.
|
|
84
96
|
*/
|
|
85
97
|
readonly count?: number;
|
|
86
98
|
/**
|
|
87
99
|
* What the mark is (P107): `"posted"` (the default, as absent) or `"draft"`, a comment its
|
|
88
100
|
* author hasn't submitted yet. A draft is drawn apart (a dashed line and a hollow marker with no
|
|
89
|
-
* number
|
|
90
|
-
*
|
|
91
|
-
* 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.
|
|
92
104
|
*/
|
|
93
105
|
readonly kind?: AnnotationMarkKind;
|
|
94
106
|
}
|
|
@@ -101,6 +113,21 @@ export interface AnchorResult {
|
|
|
101
113
|
readonly state: AnchorState;
|
|
102
114
|
/** Where it is now, when attached. */
|
|
103
115
|
readonly rect?: AnnotationRect;
|
|
116
|
+
/**
|
|
117
|
+
* Where it is in the document (P132): `rect` as the shell read it, before the host clamped it,
|
|
118
|
+
* plus the report's `scroll`; so it stays where it is as the document scrolls, and says where a
|
|
119
|
+
* mark scrolled out of the frame is. Not clamped to the frame's viewport (an offscreen mark's is
|
|
120
|
+
* outside it: that is its point): a host places its own UI from it only clipped to the frame's
|
|
121
|
+
* box, or to its own region beside the frame. Absent from an older shell. The page's word.
|
|
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;
|
|
104
131
|
/**
|
|
105
132
|
* Its place in the document among the found marks, from 0 (P112): where it starts, offscreen
|
|
106
133
|
* marks included, for a host that lists marks in reading order. The content's word: an order to
|
|
@@ -110,11 +137,18 @@ export interface AnchorResult {
|
|
|
110
137
|
}
|
|
111
138
|
/** What the frame reports, once the host has checked it. */
|
|
112
139
|
export type AnnotationReport =
|
|
113
|
-
/**
|
|
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
|
+
*/
|
|
114
146
|
{
|
|
115
147
|
readonly type: "selected";
|
|
116
148
|
readonly anchor: AnnotationAnchor;
|
|
117
149
|
readonly rect: AnnotationRect;
|
|
150
|
+
readonly lastLineDocumentRect?: AnnotationRect;
|
|
151
|
+
readonly scroll?: AnnotationScroll;
|
|
118
152
|
}
|
|
119
153
|
/** The text selection went away. */
|
|
120
154
|
| {
|
|
@@ -138,20 +172,35 @@ export type AnnotationReport =
|
|
|
138
172
|
| {
|
|
139
173
|
readonly type: "anchored";
|
|
140
174
|
readonly results: readonly AnchorResult[];
|
|
175
|
+
/**
|
|
176
|
+
* How far the document was scrolled as the boxes were read (P132); with it, each attached
|
|
177
|
+
* result has its `documentRect`. Absent from an older shell: its results have no
|
|
178
|
+
* `documentRect` either, and only `rect` says where marks are.
|
|
179
|
+
*/
|
|
180
|
+
readonly scroll?: AnnotationScroll;
|
|
141
181
|
}
|
|
142
182
|
/**
|
|
143
183
|
* The box of the mark the host follows (`annotations.track`, P112), in the frame's viewport, at
|
|
144
184
|
* an animation frame where it moved: at most 60 a second, for that mark only, clamped to the
|
|
145
|
-
* frame. The content's word: where to put a card beside it, nothing more.
|
|
185
|
+
* frame. The content's word: where to put a card beside it, nothing more. A newer shell (P132)
|
|
186
|
+
* adds the mark's `documentRect` and the document's `scroll`: the mark's box moves as the
|
|
187
|
+
* document scrolls, so a host following one mark hears the scroll at every animation frame where
|
|
188
|
+
* it changed, whether that mark is in the frame or not, and places every mark it holds a
|
|
189
|
+
* `documentRect` for (an `anchored` report's) without asking again. A newer one still (P133) adds
|
|
190
|
+
* its `lastLineDocumentRect`.
|
|
146
191
|
*/
|
|
147
192
|
| {
|
|
148
193
|
readonly type: "tracked";
|
|
149
194
|
readonly id: string;
|
|
150
195
|
readonly rect: AnnotationRect;
|
|
196
|
+
readonly documentRect?: AnnotationRect;
|
|
197
|
+
readonly lastLineDocumentRect?: AnnotationRect;
|
|
198
|
+
readonly scroll?: AnnotationScroll;
|
|
151
199
|
}
|
|
152
200
|
/**
|
|
153
201
|
* The person clicked the marker of a mark the host shows with a `count` (P104), or of a draft
|
|
154
|
-
* (P107); `rect` is the marker's box, to open the host's
|
|
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
|
|
155
204
|
* it for any mark the host shows with a marker, and can tell a real one happened: open the
|
|
156
205
|
* host's own view of that mark, never act on it.
|
|
157
206
|
*/
|
|
@@ -177,7 +226,7 @@ export declare const ANNOTATE_METHODS: {
|
|
|
177
226
|
readonly unselected: "porthole/annotate.unselected";
|
|
178
227
|
readonly cancelled: "porthole/annotate.cancelled";
|
|
179
228
|
readonly anchored: "porthole/annotate.anchored";
|
|
180
|
-
/** 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). */
|
|
181
230
|
readonly activated: "porthole/annotate.activated";
|
|
182
231
|
/** Host → frame: follow one mark's box (`{ id }`), or none (`{ id: null }`) (P112). */
|
|
183
232
|
readonly track: "porthole/annotate.track";
|
package/dist/annotate/types.js
CHANGED
|
@@ -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",
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { type AnnotateMode, type AnnotationAnchor, type AnnotationMark, type AnnotationRect, type AnnotationReport } from "./types.ts";
|
|
1
|
+
import { type AnnotateMode, type AnnotationAnchor, type AnnotationMark, type AnnotationRect, type AnnotationReport, type AnnotationScroll } 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
|
|
@@ -8,6 +8,11 @@ import { type AnnotateMode, type AnnotationAnchor, type AnnotationMark, type Ann
|
|
|
8
8
|
export declare function parseAnchor(value: unknown): AnnotationAnchor | null;
|
|
9
9
|
/** A box in the frame's viewport; null unless every number is finite and sizes aren't negative. */
|
|
10
10
|
export declare function parseRect(value: unknown): AnnotationRect | null;
|
|
11
|
+
/**
|
|
12
|
+
* How far the document is scrolled (P132): two finite numbers within the coordinate limit (either
|
|
13
|
+
* may be negative: an engine's overscroll); null for anything else.
|
|
14
|
+
*/
|
|
15
|
+
export declare function parseScroll(value: unknown): AnnotationScroll | null;
|
|
11
16
|
/**
|
|
12
17
|
* A box the frame reported, clamped to the frame's viewport (`width` by `height`, CSS px, P104):
|
|
13
18
|
* each side is held within it, so what overlaps the viewport keeps the part inside, and what lies
|
|
@@ -88,6 +88,16 @@ export function parseRect(value) {
|
|
|
88
88
|
}
|
|
89
89
|
return { x, y, width, height };
|
|
90
90
|
}
|
|
91
|
+
/**
|
|
92
|
+
* How far the document is scrolled (P132): two finite numbers within the coordinate limit (either
|
|
93
|
+
* may be negative: an engine's overscroll); null for anything else.
|
|
94
|
+
*/
|
|
95
|
+
export function parseScroll(value) {
|
|
96
|
+
if (!isRecord(value) || !coordinate(value.x) || !coordinate(value.y)) {
|
|
97
|
+
return null;
|
|
98
|
+
}
|
|
99
|
+
return { x: value.x, y: value.y };
|
|
100
|
+
}
|
|
91
101
|
/**
|
|
92
102
|
* A box the frame reported, clamped to the frame's viewport (`width` by `height`, CSS px, P104):
|
|
93
103
|
* each side is held within it, so what overlaps the viewport keeps the part inside, and what lies
|
|
@@ -123,7 +133,11 @@ function results(value) {
|
|
|
123
133
|
return null;
|
|
124
134
|
}
|
|
125
135
|
const rect = each.rect === undefined ? undefined : parseRect(each.rect);
|
|
126
|
-
|
|
136
|
+
// Where it is in the document (P132): a box as `rect` is, never clamped.
|
|
137
|
+
const documentRect = each.documentRect === undefined ? undefined : parseRect(each.documentRect);
|
|
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) {
|
|
127
141
|
return null;
|
|
128
142
|
}
|
|
129
143
|
// A place among the marks (P112): a whole number below the most marks a show carries.
|
|
@@ -136,6 +150,8 @@ function results(value) {
|
|
|
136
150
|
id: each.id,
|
|
137
151
|
state: "attached",
|
|
138
152
|
...(rect === undefined ? {} : { rect }),
|
|
153
|
+
...(documentRect === undefined ? {} : { documentRect }),
|
|
154
|
+
...(lastLineDocumentRect === undefined ? {} : { lastLineDocumentRect }),
|
|
139
155
|
...(order === undefined ? {} : { order }),
|
|
140
156
|
});
|
|
141
157
|
}
|
|
@@ -150,7 +166,21 @@ export function parseReport(value) {
|
|
|
150
166
|
case "selected": {
|
|
151
167
|
const anchor = parseAnchor(value.anchor);
|
|
152
168
|
const rect = parseRect(value.rect);
|
|
153
|
-
|
|
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
|
+
};
|
|
154
184
|
}
|
|
155
185
|
case "unselected":
|
|
156
186
|
return { type: "unselected" };
|
|
@@ -158,7 +188,10 @@ export function parseReport(value) {
|
|
|
158
188
|
return { type: "cancelled" };
|
|
159
189
|
case "anchored": {
|
|
160
190
|
const checked = results(value.results);
|
|
161
|
-
|
|
191
|
+
const scroll = value.scroll === undefined ? undefined : parseScroll(value.scroll);
|
|
192
|
+
return checked === null || scroll === null
|
|
193
|
+
? null
|
|
194
|
+
: { type: "anchored", results: checked, ...(scroll === undefined ? {} : { scroll }) };
|
|
162
195
|
}
|
|
163
196
|
case "activated": {
|
|
164
197
|
const rect = parseRect(value.rect);
|
|
@@ -166,7 +199,27 @@ export function parseReport(value) {
|
|
|
166
199
|
}
|
|
167
200
|
case "tracked": {
|
|
168
201
|
const rect = parseRect(value.rect);
|
|
169
|
-
|
|
202
|
+
// A newer shell's (P132): where the mark is in the document, and how far it is scrolled.
|
|
203
|
+
const documentRect = value.documentRect === undefined ? undefined : parseRect(value.documentRect);
|
|
204
|
+
const lastLineDocumentRect = value.lastLineDocumentRect === undefined
|
|
205
|
+
? undefined
|
|
206
|
+
: parseRect(value.lastLineDocumentRect);
|
|
207
|
+
const scroll = value.scroll === undefined ? undefined : parseScroll(value.scroll);
|
|
208
|
+
if (!markId(value.id) ||
|
|
209
|
+
rect === null ||
|
|
210
|
+
documentRect === null ||
|
|
211
|
+
lastLineDocumentRect === null ||
|
|
212
|
+
scroll === null) {
|
|
213
|
+
return null;
|
|
214
|
+
}
|
|
215
|
+
return {
|
|
216
|
+
type: "tracked",
|
|
217
|
+
id: value.id,
|
|
218
|
+
rect,
|
|
219
|
+
...(documentRect === undefined ? {} : { documentRect }),
|
|
220
|
+
...(lastLineDocumentRect === undefined ? {} : { lastLineDocumentRect }),
|
|
221
|
+
...(scroll === undefined ? {} : { scroll }),
|
|
222
|
+
};
|
|
170
223
|
}
|
|
171
224
|
default:
|
|
172
225
|
return null;
|