@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.
@@ -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 = surface?.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
  }
@@ -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;
@@ -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; 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
16
  * is reported `orphaned`;
16
- * - markers (P104): a mark with a count gets a small bubble with the number at its anchor's end;
17
- * a click on it is reported (`activated`), and the content's own handlers never see it;
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.