@botiverse/porthole 0.9.0 → 0.10.0
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/dist/annotate/types.d.ts +3 -1
- package/dist/annotate/validate.d.ts +7 -2
- package/dist/annotate/validate.js +11 -4
- package/dist/bridge/bridge.js +1 -51
- package/dist/bridge/unseen.d.ts +18 -0
- package/dist/bridge/unseen.js +71 -0
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/behavior.js +107 -68
- package/dist/conformance/clipboard.js +16 -14
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/limits.js +117 -64
- package/dist/conformance/probes.js +66 -49
- package/dist/conformance/served.js +66 -63
- package/dist/host/create-host.js +44 -2
- package/dist/platform/types.d.ts +4 -2
- package/dist/shell/annotate.d.ts +5 -3
- package/dist/shell/annotate.js +453 -100
- package/docs/ADOPTING.md +76 -0
- package/docs/DECISIONS.md +374 -13
- package/docs/DESIGN.md +166 -38
- package/docs/THREAT_MODEL.md +72 -25
- package/package.json +1 -1
- package/src/annotate/types.ts +3 -1
- package/src/annotate/validate.ts +12 -5
- package/src/bridge/bridge.ts +1 -60
- package/src/bridge/unseen.ts +82 -0
- package/src/conformance/behavior.ts +221 -69
- package/src/conformance/clipboard.ts +44 -14
- package/src/conformance/limits.ts +169 -76
- package/src/conformance/probes.ts +97 -49
- package/src/conformance/served.ts +112 -63
- package/src/host/create-host.ts +42 -2
- package/src/platform/types.ts +4 -2
- package/src/shell/annotate.ts +453 -100
package/dist/host/create-host.js
CHANGED
|
@@ -138,12 +138,47 @@ export function createHost(config, options = {}) {
|
|
|
138
138
|
toFrame(ANNOTATE_METHODS.start, { ...annotating });
|
|
139
139
|
}
|
|
140
140
|
};
|
|
141
|
+
/**
|
|
142
|
+
* The frame's viewport as the platform tells it now; undefined where it can't (no
|
|
143
|
+
* `viewport`, or one that answers no size or throws, P105): every box is then nothing at the
|
|
144
|
+
* frame's corner, and nothing throws out of the frame's listener.
|
|
145
|
+
*/
|
|
146
|
+
const frameViewport = () => {
|
|
147
|
+
try {
|
|
148
|
+
const viewport = surface?.viewport?.();
|
|
149
|
+
if (viewport === null || typeof viewport !== "object") {
|
|
150
|
+
return undefined;
|
|
151
|
+
}
|
|
152
|
+
const size = viewport;
|
|
153
|
+
const across = size.width;
|
|
154
|
+
const down = size.height;
|
|
155
|
+
return typeof across === "number" && typeof down === "number"
|
|
156
|
+
? { width: across, height: down }
|
|
157
|
+
: undefined;
|
|
158
|
+
}
|
|
159
|
+
catch {
|
|
160
|
+
return undefined;
|
|
161
|
+
}
|
|
162
|
+
};
|
|
163
|
+
/**
|
|
164
|
+
* Whether the person is known to have made no gesture just now (P105): the platform says the
|
|
165
|
+
* page has no transient activation, or fails to say. Where it can't tell (undefined), as for
|
|
166
|
+
* the gesture gate, a report passes.
|
|
167
|
+
*/
|
|
168
|
+
const noGesture = () => {
|
|
169
|
+
try {
|
|
170
|
+
return surface?.userActivation() === false;
|
|
171
|
+
}
|
|
172
|
+
catch {
|
|
173
|
+
return true;
|
|
174
|
+
}
|
|
175
|
+
};
|
|
141
176
|
/**
|
|
142
177
|
* Every box a report carries, clamped to the frame's viewport as it is now (P104): the page
|
|
143
178
|
* places the host's own UI nowhere outside its frame.
|
|
144
179
|
*/
|
|
145
180
|
const withinFrame = (report) => {
|
|
146
|
-
const viewport =
|
|
181
|
+
const viewport = frameViewport();
|
|
147
182
|
switch (report.type) {
|
|
148
183
|
case "selected":
|
|
149
184
|
case "activated":
|
|
@@ -162,7 +197,7 @@ export function createHost(config, options = {}) {
|
|
|
162
197
|
/**
|
|
163
198
|
* A report from the frame: checked, taken only while the host asked for it (a selection
|
|
164
199
|
* only in select mode, results only for its own marks, a marker's click only for a mark it
|
|
165
|
-
* shows with one), then through the bridge's gates.
|
|
200
|
+
* shows with one, within a gesture), then through the bridge's gates.
|
|
166
201
|
*/
|
|
167
202
|
const onAnnotation = (raw, through) => {
|
|
168
203
|
if (!isRecord(raw) ||
|
|
@@ -218,6 +253,13 @@ export function createHost(config, options = {}) {
|
|
|
218
253
|
if (!marks.some((mark) => mark.id === id && mark.count !== undefined)) {
|
|
219
254
|
return;
|
|
220
255
|
}
|
|
256
|
+
// A marker's real click gives the host's page transient activation (measured on all
|
|
257
|
+
// three engines, P105); a click a page posts at load, on a timer or on a scroll has
|
|
258
|
+
// none and is dropped. One posted on the person's own press in the content passes: the
|
|
259
|
+
// host's view guards itself against that (THREAT_MODEL §6).
|
|
260
|
+
if (noGesture()) {
|
|
261
|
+
return;
|
|
262
|
+
}
|
|
221
263
|
break;
|
|
222
264
|
}
|
|
223
265
|
}
|
package/dist/platform/types.d.ts
CHANGED
|
@@ -32,13 +32,15 @@ export interface Surface {
|
|
|
32
32
|
setColorScheme(scheme: ColorScheme): void;
|
|
33
33
|
/**
|
|
34
34
|
* Whether the embedding page has transient user activation now (a gesture in the frame
|
|
35
|
-
* activates its ancestors), or undefined where the platform can't tell.
|
|
35
|
+
* activates its ancestors), or undefined where the platform can't tell. The gesture gate reads
|
|
36
|
+
* it, and so does a marker's click (P105): false, or a throw, drops it.
|
|
36
37
|
*/
|
|
37
38
|
userActivation(): boolean | undefined;
|
|
38
39
|
/**
|
|
39
40
|
* The frame's viewport now, CSS px (its content box): what a box the frame reports is clamped
|
|
40
41
|
* to (P104). Undefined, or absent, where the platform can't tell: every reported box is then
|
|
41
|
-
* clamped to nothing, at the frame's corner
|
|
42
|
+
* clamped to nothing, at the frame's corner, as it is for an answer that isn't a size, or a
|
|
43
|
+
* throw (P105).
|
|
42
44
|
*/
|
|
43
45
|
viewport?(): {
|
|
44
46
|
readonly width: number;
|
package/dist/shell/annotate.d.ts
CHANGED
|
@@ -7,14 +7,16 @@
|
|
|
7
7
|
* The host drives it (`porthole/annotate.start|stop|show|focus|clear`) and it reports
|
|
8
8
|
* (`porthole/annotate.selected|unselected|cancelled|anchored|activated`):
|
|
9
9
|
* - picking an element: the element under the pointer (or finger) is outlined with its name; a
|
|
10
|
-
* click or tap picks it, and the content's own handlers never see that click
|
|
10
|
+
* click or tap picks it, and the content's own handlers never see that click (unless the content
|
|
11
|
+
* patched the DOM's built-ins, P105); Escape cancels;
|
|
11
12
|
* - selecting text: each selection that settles is reported, with where it is, and its clearing;
|
|
12
13
|
* - marks: each anchor is found in the content as it is now (its CSS selector, its text where it
|
|
13
14
|
* was, its text anywhere, its words with any spacing) and drawn over it, in a layer of the
|
|
14
15
|
* shell's own (a closed shadow root), again whenever the content changes; what can't be found
|
|
15
16
|
* is reported `orphaned`;
|
|
16
|
-
* - markers (P104): a mark with a count gets a small bubble with the number
|
|
17
|
-
* a click on it is reported (`activated`), and the
|
|
17
|
+
* - markers (P104): a mark with a count gets a small bubble with the number beside its anchor's
|
|
18
|
+
* last line (P105: in the line's gutter); a click on it is reported (`activated`), and the
|
|
19
|
+
* content's own handlers never see it;
|
|
18
20
|
* - following: while a mark has a marker, once a scroll, a resize or a change of the content
|
|
19
21
|
* settles, the marks that moved since the host was last told are reported, at most once a
|
|
20
22
|
* second, so the host's own UI beside a mark can follow.
|