@botiverse/porthole 0.8.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 +42 -4
- package/dist/annotate/types.js +6 -1
- package/dist/annotate/validate.d.ts +16 -1
- package/dist/annotate/validate.js +33 -3
- 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 +75 -3
- package/dist/platform/types.d.ts +12 -1
- package/dist/platform/web.js +8 -0
- package/dist/react/frame.d.ts +6 -2
- package/dist/shell/annotate.d.ts +10 -3
- package/dist/shell/annotate.js +610 -39
- package/docs/ADOPTING.md +76 -0
- package/docs/ARCHITECTURE.md +2 -1
- package/docs/DECISIONS.md +516 -1
- package/docs/DESIGN.md +178 -20
- package/docs/THREAT_MODEL.md +92 -9
- package/package.json +1 -1
- package/src/annotate/types.ts +39 -5
- package/src/annotate/validate.ts +39 -3
- 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 +75 -3
- package/src/platform/types.ts +9 -1
- package/src/platform/web.ts +10 -0
- package/src/react/frame.tsx +6 -2
- package/src/shell/annotate.ts +610 -39
package/dist/host/create-host.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { ANNOTATE_METHODS, } from "../annotate/types.js";
|
|
2
|
-
import { annotateMode, checkMarks, parseReport } from "../annotate/validate.js";
|
|
2
|
+
import { annotateMode, checkMarks, clampRect, parseReport } from "../annotate/validate.js";
|
|
3
3
|
import { createBridge, onceConsent, } from "../bridge/bridge.js";
|
|
4
4
|
import { compile } from "../compile/compile.js";
|
|
5
5
|
import { servesFiles } from "../files/paths.js";
|
|
@@ -26,6 +26,7 @@ const REPORTS = {
|
|
|
26
26
|
[ANNOTATE_METHODS.unselected]: "unselected",
|
|
27
27
|
[ANNOTATE_METHODS.cancelled]: "cancelled",
|
|
28
28
|
[ANNOTATE_METHODS.anchored]: "anchored",
|
|
29
|
+
[ANNOTATE_METHODS.activated]: "activated",
|
|
29
30
|
};
|
|
30
31
|
const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
|
|
31
32
|
const STANDARD = new Set(MCP_APPS_STYLE_VARIABLES);
|
|
@@ -137,9 +138,66 @@ export function createHost(config, options = {}) {
|
|
|
137
138
|
toFrame(ANNOTATE_METHODS.start, { ...annotating });
|
|
138
139
|
}
|
|
139
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
|
+
};
|
|
176
|
+
/**
|
|
177
|
+
* Every box a report carries, clamped to the frame's viewport as it is now (P104): the page
|
|
178
|
+
* places the host's own UI nowhere outside its frame.
|
|
179
|
+
*/
|
|
180
|
+
const withinFrame = (report) => {
|
|
181
|
+
const viewport = frameViewport();
|
|
182
|
+
switch (report.type) {
|
|
183
|
+
case "selected":
|
|
184
|
+
case "activated":
|
|
185
|
+
return { ...report, rect: clampRect(report.rect, viewport) };
|
|
186
|
+
case "anchored":
|
|
187
|
+
return {
|
|
188
|
+
type: "anchored",
|
|
189
|
+
results: report.results.map((result) => result.rect === undefined
|
|
190
|
+
? result
|
|
191
|
+
: { ...result, rect: clampRect(result.rect, viewport) }),
|
|
192
|
+
};
|
|
193
|
+
default:
|
|
194
|
+
return report;
|
|
195
|
+
}
|
|
196
|
+
};
|
|
140
197
|
/**
|
|
141
198
|
* A report from the frame: checked, taken only while the host asked for it (a selection
|
|
142
|
-
* only in select mode, results only for its own marks
|
|
199
|
+
* only in select mode, results only for its own marks, a marker's click only for a mark it
|
|
200
|
+
* shows with one, within a gesture), then through the bridge's gates.
|
|
143
201
|
*/
|
|
144
202
|
const onAnnotation = (raw, through) => {
|
|
145
203
|
if (!isRecord(raw) ||
|
|
@@ -190,8 +248,22 @@ export function createHost(config, options = {}) {
|
|
|
190
248
|
report = { type: "anchored", results };
|
|
191
249
|
break;
|
|
192
250
|
}
|
|
251
|
+
case "activated": {
|
|
252
|
+
const { id } = report;
|
|
253
|
+
if (!marks.some((mark) => mark.id === id && mark.count !== undefined)) {
|
|
254
|
+
return;
|
|
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
|
+
}
|
|
263
|
+
break;
|
|
264
|
+
}
|
|
193
265
|
}
|
|
194
|
-
void through.call("annotate", report);
|
|
266
|
+
void through.call("annotate", withinFrame(report));
|
|
195
267
|
};
|
|
196
268
|
const needsAnnotate = (operation) => {
|
|
197
269
|
if (!annotates) {
|
package/dist/platform/types.d.ts
CHANGED
|
@@ -32,9 +32,20 @@ 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;
|
|
39
|
+
/**
|
|
40
|
+
* The frame's viewport now, CSS px (its content box): what a box the frame reports is clamped
|
|
41
|
+
* to (P104). Undefined, or absent, where the platform can't tell: every reported box is then
|
|
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).
|
|
44
|
+
*/
|
|
45
|
+
viewport?(): {
|
|
46
|
+
readonly width: number;
|
|
47
|
+
readonly height: number;
|
|
48
|
+
} | undefined;
|
|
38
49
|
/**
|
|
39
50
|
* The frame loaded a document other than the one it was given: the content navigated it. The
|
|
40
51
|
* framework starts it again from its content and reports it.
|
package/dist/platform/web.js
CHANGED
|
@@ -73,6 +73,14 @@ export const webPlatform = {
|
|
|
73
73
|
setColorScheme(scheme) {
|
|
74
74
|
frame.style.colorScheme = scheme;
|
|
75
75
|
},
|
|
76
|
+
viewport() {
|
|
77
|
+
const style = view.getComputedStyle(frame);
|
|
78
|
+
const width = frame.clientWidth - parseFloat(style.paddingLeft) - parseFloat(style.paddingRight);
|
|
79
|
+
const height = frame.clientHeight - parseFloat(style.paddingTop) - parseFloat(style.paddingBottom);
|
|
80
|
+
return Number.isFinite(width) && Number.isFinite(height)
|
|
81
|
+
? { width: Math.max(0, width), height: Math.max(0, height) }
|
|
82
|
+
: undefined;
|
|
83
|
+
},
|
|
76
84
|
userActivation() {
|
|
77
85
|
const activation = view.navigator.userActivation;
|
|
78
86
|
return activation === undefined ? undefined : activation.isActive;
|
package/dist/react/frame.d.ts
CHANGED
|
@@ -250,7 +250,10 @@ export interface PortholeFrameProps {
|
|
|
250
250
|
* again to pick again.
|
|
251
251
|
*/
|
|
252
252
|
readonly annotating?: AnnotateMode | null;
|
|
253
|
-
/**
|
|
253
|
+
/**
|
|
254
|
+
* The anchors to mark in the frame (the host's comments). A mark with a `count` gets a
|
|
255
|
+
* clickable marker (P104). Compared by value.
|
|
256
|
+
*/
|
|
254
257
|
readonly annotations?: readonly AnnotationMark[];
|
|
255
258
|
/**
|
|
256
259
|
* The mark to bring into view and make the active one; each new id focuses it. To focus the
|
|
@@ -262,7 +265,8 @@ export interface PortholeFrameProps {
|
|
|
262
265
|
} | null;
|
|
263
266
|
/**
|
|
264
267
|
* What the frame reported: a selection (an anchor and where it is), its clearing, a cancelled
|
|
265
|
-
* pick, where marks are
|
|
268
|
+
* pick, where marks are (again once a scroll settles: those that moved), a marker clicked
|
|
269
|
+
* (`activated`). The content's word: UI hints, never permissions.
|
|
266
270
|
*/
|
|
267
271
|
readonly onAnnotation?: (report: AnnotationReport) => void;
|
|
268
272
|
/** Draws the placeholder instead of the default one. */
|
package/dist/shell/annotate.d.ts
CHANGED
|
@@ -5,14 +5,21 @@
|
|
|
5
5
|
* in one).
|
|
6
6
|
*
|
|
7
7
|
* The host drives it (`porthole/annotate.start|stop|show|focus|clear`) and it reports
|
|
8
|
-
* (`porthole/annotate.selected|unselected|cancelled|anchored`):
|
|
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
|
-
* is reported `orphaned
|
|
16
|
+
* is reported `orphaned`;
|
|
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;
|
|
20
|
+
* - following: while a mark has a marker, once a scroll, a resize or a change of the content
|
|
21
|
+
* settles, the marks that moved since the host was last told are reported, at most once a
|
|
22
|
+
* second, so the host's own UI beside a mark can follow.
|
|
16
23
|
*
|
|
17
24
|
* It shares the realm with the content, which can interfere with all of it: the host takes its
|
|
18
25
|
* reports as UI hints only.
|