@botiverse/porthole 0.12.0 → 0.13.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 (47) hide show
  1. package/dist/bridge/bridge.d.ts +8 -1
  2. package/dist/bridge/bridge.js +7 -0
  3. package/dist/bridge/unseen.d.ts +8 -0
  4. package/dist/bridge/unseen.js +17 -0
  5. package/dist/check/files.js +14 -10
  6. package/dist/check/lint.js +1 -1
  7. package/dist/check/page-source.js +1 -1
  8. package/dist/check/scroll.d.ts +29 -13
  9. package/dist/check/scroll.js +74 -18
  10. package/dist/config/capabilities.d.ts +16 -3
  11. package/dist/config/capabilities.js +1 -0
  12. package/dist/conformance/harness-source.js +1 -1
  13. package/dist/guide/runtime.js +1 -1
  14. package/dist/host/create-host.js +27 -0
  15. package/dist/host/types.d.ts +15 -0
  16. package/dist/index.d.ts +1 -0
  17. package/dist/index.js +1 -0
  18. package/dist/platform/focus-guard.d.ts +143 -0
  19. package/dist/platform/focus-guard.js +445 -0
  20. package/dist/platform/types.d.ts +18 -0
  21. package/dist/platform/web.js +22 -0
  22. package/dist/react/frame.d.ts +8 -0
  23. package/dist/react/frame.js +4 -0
  24. package/dist/runtime/requests.js +34 -12
  25. package/dist/runtime/types.generated.js +1 -1
  26. package/docs/ADOPTING.md +85 -6
  27. package/docs/DECISIONS.md +355 -5
  28. package/docs/DESIGN.md +9 -2
  29. package/docs/THREAT_MODEL.md +121 -29
  30. package/package.json +1 -1
  31. package/src/bridge/bridge.ts +17 -1
  32. package/src/bridge/unseen.ts +24 -0
  33. package/src/check/files.ts +14 -10
  34. package/src/check/lint.ts +1 -1
  35. package/src/check/scroll.ts +106 -38
  36. package/src/config/capabilities.ts +16 -3
  37. package/src/guide/runtime.ts +1 -1
  38. package/src/host/create-host.ts +29 -0
  39. package/src/host/types.ts +13 -0
  40. package/src/index.ts +1 -0
  41. package/src/platform/focus-guard.ts +572 -0
  42. package/src/platform/types.ts +17 -0
  43. package/src/platform/web.ts +22 -0
  44. package/src/react/frame.tsx +10 -0
  45. package/src/runtime/requests.ts +36 -14
  46. package/src/runtime/types.generated.ts +1 -1
  47. package/types/runtime/v1/comments.d.ts +8 -4
@@ -13,7 +13,8 @@ import type { CapabilityHandlers, Confirm, ConfirmDisplay, Consent, DataCache, H
13
13
  * every capability its host function's own rate (P091, P095) → arguments well formed and within
14
14
  * their limits → who may (P087: the level of each method the call runs for the viewer, a page's
15
15
  * named data with or without a viewer, db's rules) → not muted, if confirm-gated → the own rate
16
- * of each method it runs (P094: a batch's writes count each) → a user gesture, if gated so → the
16
+ * of each method it runs (P094: a batch's writes count each) → a user gesture, if gated so (and
17
+ * for `comments`, the host page's focus in the calling frame: P109) → the
17
18
  * viewer's consent, if gated so → a person's confirmation, if gated so (at most 10 waiting) →
18
19
  * shown to the person, if gated so (P100) → the handler (or, for a read, a result the host already
19
20
  * gave for it, or for a stale-allowed one the host's cache).
@@ -60,6 +61,12 @@ export interface BridgeOptions {
60
61
  readonly cached?: DataCache;
61
62
  /** Whether the embedding page has user activation now; undefined where it can't tell. */
62
63
  readonly userActivation?: () => boolean | undefined;
64
+ /**
65
+ * Whether the embedding page's focus is in this display's frame now (P109); undefined where it
66
+ * can't tell. A capability whose gesture must be in its frame (`inFrame`: `comments`) is refused
67
+ * without it.
68
+ */
69
+ readonly focused?: () => boolean | undefined;
63
70
  readonly onEvent: (event: BridgeEvent) => void;
64
71
  /** The clock, in milliseconds (tests pass their own). */
65
72
  readonly now?: () => number;
@@ -12,6 +12,8 @@ import { atLeast, higher } from "../runtime/levels.js";
12
12
  import { isCodeAsset, parseArtifactRequest, parseAssetRequest, parseCommentRequest, } from "../runtime/requests.js";
13
13
  import { defaultReason, isRefused, pendingReason, reasonOf, } from "./refusal.js";
14
14
  const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
15
+ /** Whether `capability`'s gesture must be in its own frame (P109: the host page's focus there). */
16
+ const inFrame = (capability) => capabilitySpec(capability).inFrame === true;
15
17
  const MAX_URL = 4_096;
16
18
  /**
17
19
  * The most confirmations one display has waiting at once (P095): past it a call is refused as
@@ -448,6 +450,11 @@ export function createBridge(options) {
448
450
  if (activated === false) {
449
451
  return refuse(capability, "no-user-activation");
450
452
  }
453
+ // A gesture in this frame, not anywhere on the host's page (P109): the person typing in
454
+ // the host's composer gives its page activation, which a frame's call would borrow.
455
+ if (inFrame(capability) && options.focused?.() === false) {
456
+ return refuse(capability, "no-user-activation");
457
+ }
451
458
  }
452
459
  if (gates.includes("consent")) {
453
460
  const consent = options.consent;
@@ -16,3 +16,11 @@ export declare const unseen: (text: string) => boolean;
16
16
  * refuses is left.
17
17
  */
18
18
  export declare function withoutUnseen(text: string): string;
19
+ /**
20
+ * Whether `text` holds what a person can't see, for text a page puts in the person's own words (a
21
+ * comment's draft, P109): `unseen`'s list, with only a joiner or non-joiner between two letters or
22
+ * marks let by (in any script: a person's text needs them, and one that draws as nothing there is
23
+ * a bit at most), and a variation selector right after a pictograph or in a keycap (❤️, 1️⃣). A
24
+ * joiner between pictographs (an emoji sequence) is refused: it can join any two.
25
+ */
26
+ export declare const unseenStrict: (text: string) => boolean;
@@ -69,3 +69,20 @@ const UNSEEN_EACH = new RegExp(UNSEEN.source, "gu");
69
69
  export function withoutUnseen(text) {
70
70
  return text.replace(UNSEEN_EACH, "");
71
71
  }
72
+ /** A variation selector where an emoji has one: after a pictograph, or in a keycap. */
73
+ const EMOJI_SELECTORS = new RegExp("(?<=\\p{Extended_Pictographic})[\\uFE0E\\uFE0F]|(?<=[0-9#*])[\\uFE0E\\uFE0F](?=\\u20E3)", "gu");
74
+ /**
75
+ * A joiner or non-joiner with a letter or mark on each side (P109): how Persian separates its
76
+ * letters (می‌خواهم) and the Indic scripts choose a half form or a conjunct (क्‍ष, എന്‍റെ). Never
77
+ * first or last, doubled, beside a space, punctuation or a pictograph: there it shapes nothing, and
78
+ * hides text or makes a blank-looking draft.
79
+ */
80
+ const LETTER_JOINERS = /(?<=[\p{L}\p{M}])[\u200C\u200D](?=[\p{L}\p{M}])/gu;
81
+ /**
82
+ * Whether `text` holds what a person can't see, for text a page puts in the person's own words (a
83
+ * comment's draft, P109): `unseen`'s list, with only a joiner or non-joiner between two letters or
84
+ * marks let by (in any script: a person's text needs them, and one that draws as nothing there is
85
+ * a bit at most), and a variation selector right after a pictograph or in a keycap (❤️, 1️⃣). A
86
+ * joiner between pictographs (an emoji sequence) is refused: it can join any two.
87
+ */
88
+ export const unseenStrict = (text) => UNSEEN.test(text.replace(LETTER_JOINERS, "").replace(EMOJI_SELECTORS, ""));
@@ -211,8 +211,10 @@ export function lintFiles(config, files, options = {}) {
211
211
  }
212
212
  }
213
213
  };
214
- // A stylesheet a page links or a stylesheet imports, found in the set by its path (P106).
215
- const decoded = new Map();
214
+ // A stylesheet a page links or a stylesheet imports, found in the set by its path (P106). The
215
+ // fewest characters it may hold first: the rule decodes its text only where it may read it, and
216
+ // nothing keeps it after (P110: kept for the set, one page linking 400 sheets of 240 KB held
217
+ // them all, 200 MB, for the 4 MiB the rule reads).
216
218
  const stylesheet = (href, from) => {
217
219
  if (href === "" || elsewhere(href) || href.startsWith("/")) {
218
220
  return null;
@@ -222,13 +224,15 @@ export function lintFiles(config, files, options = {}) {
222
224
  if (sheet === undefined || target === null) {
223
225
  return null;
224
226
  }
225
- // Decoded once for the whole set, however many pages link it.
226
- let text = decoded.get(target);
227
- if (text === undefined) {
228
- text = textOf(sheet).slice(0, SCANNED);
229
- decoded.set(target, text);
230
- }
231
- return { path: target, text };
227
+ // As bytes, at most 3 a character (after a BOM's 3): its fewest characters, and the bytes that
228
+ // hold its first SCANNED.
229
+ return typeof sheet === "string"
230
+ ? { path: target, least: sheet.length, text: () => sheet }
231
+ : {
232
+ path: target,
233
+ least: Math.max(0, Math.ceil(sheet.byteLength / 3) - 1),
234
+ text: () => textOf(sheet.subarray(0, 3 * SCANNED + 3)),
235
+ };
232
236
  };
233
237
  const it = config.mode === "mcp-app" ? "view" : config.mode === "inline" ? "widget" : "page";
234
238
  const maxPage = config.limits.maxBytes;
@@ -306,7 +310,7 @@ export function lintFiles(config, files, options = {}) {
306
310
  severity: "warning",
307
311
  message: held.message,
308
312
  path: held.path ?? path,
309
- line: held.line,
313
+ ...(held.line === undefined ? {} : { line: held.line }),
310
314
  });
311
315
  }
312
316
  }
@@ -174,7 +174,7 @@ export function lintPage(config, content, options) {
174
174
  rule: "scroll-lock",
175
175
  severity: "warning",
176
176
  message: held.message,
177
- line: held.line,
177
+ ...(held.line === undefined ? {} : { line: held.line }),
178
178
  });
179
179
  }
180
180
  const opens = /target\s*=\s*["']?_blank|\bwindow\s*\.\s*open\s*\(/u.exec(content);