@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.
Files changed (40) hide show
  1. package/dist/annotate/types.d.ts +42 -4
  2. package/dist/annotate/types.js +6 -1
  3. package/dist/annotate/validate.d.ts +16 -1
  4. package/dist/annotate/validate.js +33 -3
  5. package/dist/bridge/bridge.js +1 -51
  6. package/dist/bridge/unseen.d.ts +18 -0
  7. package/dist/bridge/unseen.js +71 -0
  8. package/dist/check/page-source.js +1 -1
  9. package/dist/conformance/behavior.js +107 -68
  10. package/dist/conformance/clipboard.js +16 -14
  11. package/dist/conformance/harness-source.js +1 -1
  12. package/dist/conformance/limits.js +117 -64
  13. package/dist/conformance/probes.js +66 -49
  14. package/dist/conformance/served.js +66 -63
  15. package/dist/host/create-host.js +75 -3
  16. package/dist/platform/types.d.ts +12 -1
  17. package/dist/platform/web.js +8 -0
  18. package/dist/react/frame.d.ts +6 -2
  19. package/dist/shell/annotate.d.ts +10 -3
  20. package/dist/shell/annotate.js +610 -39
  21. package/docs/ADOPTING.md +76 -0
  22. package/docs/ARCHITECTURE.md +2 -1
  23. package/docs/DECISIONS.md +516 -1
  24. package/docs/DESIGN.md +178 -20
  25. package/docs/THREAT_MODEL.md +92 -9
  26. package/package.json +1 -1
  27. package/src/annotate/types.ts +39 -5
  28. package/src/annotate/validate.ts +39 -3
  29. package/src/bridge/bridge.ts +1 -60
  30. package/src/bridge/unseen.ts +82 -0
  31. package/src/conformance/behavior.ts +221 -69
  32. package/src/conformance/clipboard.ts +44 -14
  33. package/src/conformance/limits.ts +169 -76
  34. package/src/conformance/probes.ts +97 -49
  35. package/src/conformance/served.ts +112 -63
  36. package/src/host/create-host.ts +75 -3
  37. package/src/platform/types.ts +9 -1
  38. package/src/platform/web.ts +10 -0
  39. package/src/react/frame.tsx +6 -2
  40. package/src/shell/annotate.ts +610 -39
@@ -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), then through the bridge's gates.
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) {
@@ -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.
@@ -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;
@@ -250,7 +250,10 @@ export interface PortholeFrameProps {
250
250
  * again to pick again.
251
251
  */
252
252
  readonly annotating?: AnnotateMode | null;
253
- /** The anchors to mark in the frame (the host's comments). Keep it stable (memoized). */
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. The content's word: UI hints, never permissions.
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. */
@@ -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; Escape cancels;
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.