@botiverse/porthole 0.14.10 → 0.14.12
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 +36 -0
- package/dist/annotate/types.d.ts +35 -15
- package/dist/annotate/types.js +3 -1
- package/dist/annotate/validate.js +28 -3
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +8 -0
- package/dist/host/types.d.ts +11 -0
- package/dist/react/frame.d.ts +6 -0
- package/dist/react/frame.js +6 -0
- package/dist/react/view.js +1 -0
- package/dist/shell/annotate.d.ts +21 -7
- package/dist/shell/annotate.js +277 -43
- package/dist/shell/find.d.ts +1 -1
- package/dist/shell/find.js +1 -1
- package/docs/ADOPTING.md +52 -5
- package/docs/ARCHITECTURE.md +4 -3
- package/docs/DECISIONS.md +243 -2
- package/docs/DESIGN.md +57 -23
- package/docs/THREAT_MODEL.md +55 -5
- package/package.json +1 -1
- package/src/annotate/types.ts +35 -15
- package/src/annotate/validate.ts +33 -3
- package/src/host/create-host.ts +8 -0
- package/src/host/types.ts +11 -0
- package/src/react/frame.tsx +12 -0
- package/src/react/view.tsx +1 -0
- package/src/shell/annotate.ts +278 -43
- package/src/shell/find.ts +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,42 @@
|
|
|
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.12
|
|
8
|
+
|
|
9
|
+
- **Annotations: the keyboard back on a marker (P134).** `annotations.focusMark(id)` (React:
|
|
10
|
+
`focusMark(id)` on the `ref`) moves the DOM focus to that mark's marker in the frame. It is for
|
|
11
|
+
one moment: after Escape closed your own view of that mark, once it is closed. It carries no
|
|
12
|
+
content and reports nothing; with no such marker it does nothing and throws nothing. An older
|
|
13
|
+
shell ignores it.
|
|
14
|
+
- **Annotations: a marker's name (P134).** It reads `1 comment on "Paragraph 3. Filler…"`: the words
|
|
15
|
+
it is on, in quotes, with no element's tag. `anchor.label` and everything you store are unchanged.
|
|
16
|
+
- **Key or pointer (P134).** `activated` is unchanged. Read `document.activeElement` on your own page
|
|
17
|
+
as it arrives: the frame there means the focus is in the frame. A hint: a page can still forge
|
|
18
|
+
`activated` while the person is in the frame, and a host that moves the keyboard into its view on
|
|
19
|
+
this gates what posts from that view itself (ADOPTING, THREAT_MODEL §7).
|
|
20
|
+
- **Security (P134):** the shell's move uses the platform's `focus`, kept before content runs (control
|
|
21
|
+
`marker-focus`). No CSP, sandbox, egress or gate changes; the focus guard is untouched.
|
|
22
|
+
|
|
23
|
+
## 0.14.11
|
|
24
|
+
|
|
25
|
+
- **Annotations: markers are buttons (P133).** A marker is a real button in the frame's Tab order,
|
|
26
|
+
after the page's own stops and in reading order, named for what it is ("3 comments on …"; in
|
|
27
|
+
English). Enter or Space on it reports `activated` through the path a click takes, the same
|
|
28
|
+
gesture check included, unheard by the page's scripts, once for a key held down. The focus on a
|
|
29
|
+
marker lights its words and brings it into view. This reverses P104's "no tab stop": the page
|
|
30
|
+
shares that focus order, so a host keeps its own list of marks as the keyboard way that holds.
|
|
31
|
+
- **Annotations: a posted comment's marker sits at its paragraph's end (P133).** On the last line
|
|
32
|
+
of the block its words end in, just past the last word, or in the line's gutter where that
|
|
33
|
+
doesn't fit. A draft's stays beside its own words, and an element's on its corner.
|
|
34
|
+
- **Annotations: the last line (P133).** `selected`, each attached result of `anchored`, and
|
|
35
|
+
`tracked` now carry a `lastLineDocumentRect`, the last line with words on it (an element's whole
|
|
36
|
+
box) in the coordinates of `documentRect`, and `selected` carries the `scroll` it was read at, so
|
|
37
|
+
a host places its UI after the last line. Optional: an older shell sends neither (test for them),
|
|
38
|
+
and an older host drops them. Upgrade the content server (the shell) for all three.
|
|
39
|
+
- **Security (P133):** `lastLineDocumentRect` is the page's word, checked as any box and not clamped
|
|
40
|
+
to the frame: clip what you draw from it (THREAT_MODEL §6, ADOPTING). `rect` is clamped as before.
|
|
41
|
+
The keyboard on a marker is new (THREAT_MODEL §7): no CSP, sandbox, egress or gate changes.
|
|
42
|
+
|
|
7
43
|
## 0.14.10
|
|
8
44
|
|
|
9
45
|
- **Annotations: a mark's place in the document (P132).** Each attached result of an `anchored`
|
package/dist/annotate/types.d.ts
CHANGED
|
@@ -46,8 +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). A result's `documentRect` (P132)
|
|
50
|
-
*
|
|
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.
|
|
51
51
|
*/
|
|
52
52
|
export interface AnnotationRect {
|
|
53
53
|
readonly x: number;
|
|
@@ -86,20 +86,21 @@ export interface AnnotationMark {
|
|
|
86
86
|
readonly id: string;
|
|
87
87
|
readonly anchor: AnnotationAnchor;
|
|
88
88
|
/**
|
|
89
|
-
* A marker (P104): with a count, the shell also draws a small bubble with this number
|
|
90
|
-
* `ANNOTATION_LIMITS.count`, a larger one clamped to it (P116); above 99 it reads "99+", 0
|
|
91
|
-
* the bubble alone) at the end of a
|
|
92
|
-
*
|
|
93
|
-
* `activated`.
|
|
94
|
-
*
|
|
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
|
+
* the words it is on, quoted, an element's tag left out (P134). The content can read the number;
|
|
95
|
+
* give one only where the page may know it. A draft's is dropped (P107): its marker has no number.
|
|
95
96
|
*/
|
|
96
97
|
readonly count?: number;
|
|
97
98
|
/**
|
|
98
99
|
* What the mark is (P107): `"posted"` (the default, as absent) or `"draft"`, a comment its
|
|
99
100
|
* author hasn't submitted yet. A draft is drawn apart (a dashed line and a hollow marker with no
|
|
100
|
-
* number
|
|
101
|
-
*
|
|
102
|
-
* 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.
|
|
103
104
|
*/
|
|
104
105
|
readonly kind?: AnnotationMarkKind;
|
|
105
106
|
}
|
|
@@ -120,6 +121,13 @@ export interface AnchorResult {
|
|
|
120
121
|
* box, or to its own region beside the frame. Absent from an older shell. The page's word.
|
|
121
122
|
*/
|
|
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;
|
|
123
131
|
/**
|
|
124
132
|
* Its place in the document among the found marks, from 0 (P112): where it starts, offscreen
|
|
125
133
|
* marks included, for a host that lists marks in reading order. The content's word: an order to
|
|
@@ -129,11 +137,18 @@ export interface AnchorResult {
|
|
|
129
137
|
}
|
|
130
138
|
/** What the frame reports, once the host has checked it. */
|
|
131
139
|
export type AnnotationReport =
|
|
132
|
-
/**
|
|
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
|
+
*/
|
|
133
146
|
{
|
|
134
147
|
readonly type: "selected";
|
|
135
148
|
readonly anchor: AnnotationAnchor;
|
|
136
149
|
readonly rect: AnnotationRect;
|
|
150
|
+
readonly lastLineDocumentRect?: AnnotationRect;
|
|
151
|
+
readonly scroll?: AnnotationScroll;
|
|
137
152
|
}
|
|
138
153
|
/** The text selection went away. */
|
|
139
154
|
| {
|
|
@@ -171,18 +186,21 @@ export type AnnotationReport =
|
|
|
171
186
|
* adds the mark's `documentRect` and the document's `scroll`: the mark's box moves as the
|
|
172
187
|
* document scrolls, so a host following one mark hears the scroll at every animation frame where
|
|
173
188
|
* it changed, whether that mark is in the frame or not, and places every mark it holds a
|
|
174
|
-
* `documentRect` for (an `anchored` report's) without asking again.
|
|
189
|
+
* `documentRect` for (an `anchored` report's) without asking again. A newer one still (P133) adds
|
|
190
|
+
* its `lastLineDocumentRect`.
|
|
175
191
|
*/
|
|
176
192
|
| {
|
|
177
193
|
readonly type: "tracked";
|
|
178
194
|
readonly id: string;
|
|
179
195
|
readonly rect: AnnotationRect;
|
|
180
196
|
readonly documentRect?: AnnotationRect;
|
|
197
|
+
readonly lastLineDocumentRect?: AnnotationRect;
|
|
181
198
|
readonly scroll?: AnnotationScroll;
|
|
182
199
|
}
|
|
183
200
|
/**
|
|
184
201
|
* The person clicked the marker of a mark the host shows with a `count` (P104), or of a draft
|
|
185
|
-
* (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
|
|
186
204
|
* it for any mark the host shows with a marker, and can tell a real one happened: open the
|
|
187
205
|
* host's own view of that mark, never act on it.
|
|
188
206
|
*/
|
|
@@ -208,7 +226,7 @@ export declare const ANNOTATE_METHODS: {
|
|
|
208
226
|
readonly unselected: "porthole/annotate.unselected";
|
|
209
227
|
readonly cancelled: "porthole/annotate.cancelled";
|
|
210
228
|
readonly anchored: "porthole/annotate.anchored";
|
|
211
|
-
/** 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). */
|
|
212
230
|
readonly activated: "porthole/annotate.activated";
|
|
213
231
|
/** Host → frame: follow one mark's box (`{ id }`), or none (`{ id: null }`) (P112). */
|
|
214
232
|
readonly track: "porthole/annotate.track";
|
|
@@ -216,6 +234,8 @@ export declare const ANNOTATE_METHODS: {
|
|
|
216
234
|
readonly tracked: "porthole/annotate.tracked";
|
|
217
235
|
/** Host → frame: take the page's text selection away, telling nothing back (P115). */
|
|
218
236
|
readonly clearSelection: "porthole/annotate.clearSelection";
|
|
237
|
+
/** Host → frame: put the focus on one mark's marker (`{ id }`), telling nothing back (P134). */
|
|
238
|
+
readonly focusMark: "porthole/annotate.focusMark";
|
|
219
239
|
};
|
|
220
240
|
/** The most of each part of an anchor or report the host takes. */
|
|
221
241
|
export declare const ANNOTATION_LIMITS: {
|
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",
|
|
@@ -36,6 +36,8 @@ export const ANNOTATE_METHODS = {
|
|
|
36
36
|
tracked: "porthole/annotate.tracked",
|
|
37
37
|
/** Host → frame: take the page's text selection away, telling nothing back (P115). */
|
|
38
38
|
clearSelection: "porthole/annotate.clearSelection",
|
|
39
|
+
/** Host → frame: put the focus on one mark's marker (`{ id }`), telling nothing back (P134). */
|
|
40
|
+
focusMark: "porthole/annotate.focusMark",
|
|
39
41
|
};
|
|
40
42
|
/** The most of each part of an anchor or report the host takes. */
|
|
41
43
|
export const ANNOTATION_LIMITS = {
|
|
@@ -135,7 +135,9 @@ function results(value) {
|
|
|
135
135
|
const rect = each.rect === undefined ? undefined : parseRect(each.rect);
|
|
136
136
|
// Where it is in the document (P132): a box as `rect` is, never clamped.
|
|
137
137
|
const documentRect = each.documentRect === undefined ? undefined : parseRect(each.documentRect);
|
|
138
|
-
|
|
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) {
|
|
139
141
|
return null;
|
|
140
142
|
}
|
|
141
143
|
// A place among the marks (P112): a whole number below the most marks a show carries.
|
|
@@ -149,6 +151,7 @@ function results(value) {
|
|
|
149
151
|
state: "attached",
|
|
150
152
|
...(rect === undefined ? {} : { rect }),
|
|
151
153
|
...(documentRect === undefined ? {} : { documentRect }),
|
|
154
|
+
...(lastLineDocumentRect === undefined ? {} : { lastLineDocumentRect }),
|
|
152
155
|
...(order === undefined ? {} : { order }),
|
|
153
156
|
});
|
|
154
157
|
}
|
|
@@ -163,7 +166,21 @@ export function parseReport(value) {
|
|
|
163
166
|
case "selected": {
|
|
164
167
|
const anchor = parseAnchor(value.anchor);
|
|
165
168
|
const rect = parseRect(value.rect);
|
|
166
|
-
|
|
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
|
+
};
|
|
167
184
|
}
|
|
168
185
|
case "unselected":
|
|
169
186
|
return { type: "unselected" };
|
|
@@ -184,8 +201,15 @@ export function parseReport(value) {
|
|
|
184
201
|
const rect = parseRect(value.rect);
|
|
185
202
|
// A newer shell's (P132): where the mark is in the document, and how far it is scrolled.
|
|
186
203
|
const documentRect = value.documentRect === undefined ? undefined : parseRect(value.documentRect);
|
|
204
|
+
const lastLineDocumentRect = value.lastLineDocumentRect === undefined
|
|
205
|
+
? undefined
|
|
206
|
+
: parseRect(value.lastLineDocumentRect);
|
|
187
207
|
const scroll = value.scroll === undefined ? undefined : parseScroll(value.scroll);
|
|
188
|
-
if (!markId(value.id) ||
|
|
208
|
+
if (!markId(value.id) ||
|
|
209
|
+
rect === null ||
|
|
210
|
+
documentRect === null ||
|
|
211
|
+
lastLineDocumentRect === null ||
|
|
212
|
+
scroll === null) {
|
|
189
213
|
return null;
|
|
190
214
|
}
|
|
191
215
|
return {
|
|
@@ -193,6 +217,7 @@ export function parseReport(value) {
|
|
|
193
217
|
id: value.id,
|
|
194
218
|
rect,
|
|
195
219
|
...(documentRect === undefined ? {} : { documentRect }),
|
|
220
|
+
...(lastLineDocumentRect === undefined ? {} : { lastLineDocumentRect }),
|
|
196
221
|
...(scroll === undefined ? {} : { scroll }),
|
|
197
222
|
};
|
|
198
223
|
}
|