@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
@@ -45,9 +45,14 @@ export type CapabilityName = (typeof CAPABILITY_NAMES)[number];
45
45
  /**
46
46
  * What must hold before a call reaches the host's handler. A capability's gates all apply.
47
47
  *
48
- * - `user-activation`: the call follows a real user gesture in the frame. The shell refuses a call
49
- * without one, and the host checks its own page's activation (which a gesture in a child frame
50
- * propagates to). It stops calls made on load or on a timer; it is not proof of intent.
48
+ * - `user-activation`: the call follows a real user gesture. The shell refuses a call without one
49
+ * in its frame, but that check is the page's own (a page posts the call itself and skips it).
50
+ * The host checks its own page's transient activation, which a gesture in a child frame
51
+ * propagates to, and which lasts 5 s after any gesture anywhere on the host's page: a click on
52
+ * the host's own UI, or the person typing in its own composer, counts. So it stops calls made on
53
+ * load, or on a timer while nobody does anything; it is not proof that the gesture was in this
54
+ * frame, nor of intent. Where a capability needs that (`comments`, P109: its draft goes into
55
+ * the person's composer), the host also asks that its page's focus be in the calling frame.
51
56
  * - `confirm`: the host's `confirm` function shows a person the call's whole effect, and the call
52
57
  * goes only if they accept. No `confirm` function means the call is refused (fail closed).
53
58
  * - `rateLimit`: at most `perMinute` calls per display per minute; the rest are refused.
@@ -82,6 +87,13 @@ export interface CapabilitySpec {
82
87
  * Absent for what the shell does by itself (sizes, errors, annotations).
83
88
  */
84
89
  readonly request?: { readonly method: string; readonly sdk?: string };
90
+ /**
91
+ * Its `user-activation` gate also needs the person in the calling frame (P109): the host page's
92
+ * focus in that frame, which a press on it or a Tab into it gives and the focus guard keeps from
93
+ * a frame's own `focus()`. Activation alone lasts 5 s after any gesture on the host's page,
94
+ * typing in its own composer included.
95
+ */
96
+ readonly inFrame?: true;
85
97
  }
86
98
 
87
99
  const rate = (perMinute: number): Gate => ({ rateLimit: { perMinute } });
@@ -170,6 +182,7 @@ export const CAPABILITIES = {
170
182
  defaultGates: ["user-activation", rate(30)],
171
183
  served: "handler",
172
184
  request: { method: "porthole/call" },
185
+ inFrame: true,
173
186
  },
174
187
  /** This artifact's current version, and a new version of it, base-checked (P088). */
175
188
  artifact: { defaultGates: [rate(10)], served: "handler", request: { method: "porthole/call" } },
@@ -61,7 +61,7 @@ const CALLS: Readonly<Record<RuntimeCapabilityName, Readonly<Record<string, stri
61
61
  const WHAT: Readonly<Partial<Record<CapabilityName, (config: PortholeConfig) => string>>> = {
62
62
  user: () => "who is viewing: { id, name, level }, as the app says",
63
63
  comments: () =>
64
- "opens the app's comment composer at a place the page names (a stable name like slide-3 or refs/a.md#L12, a label, the quoted text), optionally starting with a draft (at most 2,000 characters of visible text, lines and tabs fine, no zero-width, bidi or tag characters; e.g. a button's \"Approved\" or a checklist to fill in); the person edits and posts it in the app, or doesn't. True if it opened. Write-only: a page never reads comments, and never posts one",
64
+ "opens the app's comment composer at a place the page names (a stable name like slide-3 or refs/a.md#L12, a label, the quoted text), optionally starting with a draft (at most 2,000 characters of visible text, lines and tabs fine, no zero-width characters, joiners only between two letters (Persian's or Hindi's are fine; an emoji joined with U+200D is refused; ❤️ is fine), no bidi or tag characters, line or paragraph separators, or runs of blanks; e.g. a button's \"Approved\" or a checklist to fill in); the person edits and posts it in the app, or doesn't. Call it from a click in the page. True if it opened. Write-only: a page never reads comments, and never posts one",
65
65
  copyText: () =>
66
66
  `copies text to the person's clipboard (at most ${MAX_COPY_CHARS.toLocaleString("en-US")} characters), and the app shows them what was copied; nothing else in the page can write the clipboard. True if copied`,
67
67
  openLink: () =>
@@ -29,6 +29,7 @@ import { locateServed } from "./locate.ts";
29
29
  import { watchOutcome, type OutcomeWatch } from "./outcome.ts";
30
30
  import type { FrameSource } from "../isolation/types.ts";
31
31
  import { webPlatform } from "../platform/web.ts";
32
+ import { TAKES } from "../platform/focus-guard.ts";
32
33
  import type { Surface } from "../platform/types.ts";
33
34
  import type { AdapterConnection, ProtocolAdapter, ShellConnection } from "../protocol/adapter.ts";
34
35
  import {
@@ -495,6 +496,29 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
495
496
  })
496
497
  : framed;
497
498
  surface = created;
499
+ // The focus guard undid a move of the keyboard into this frame (P109): heard each time,
500
+ // and a frame that keeps taking it is stopped, as one that keeps navigating away is.
501
+ const takes: { at: number; counts: boolean }[] = [];
502
+ created.onFocusTaken?.(({ typing, failed }) => {
503
+ const at = Date.now();
504
+ // While the person typed, or a take-back that failed (the keys then go to the frame and
505
+ // the page sees no typing): either counts toward the first rule.
506
+ takes.push({ at, counts: typing || failed });
507
+ const within = (ms: number) => takes.filter((take) => at - take.at <= ms);
508
+ emit("focusTaken", { typing });
509
+ if (
510
+ surface === created &&
511
+ (within(TAKES.typing.withinMs).filter((take) => take.counts).length >=
512
+ TAKES.typing.most ||
513
+ within(TAKES.any.withinMs).length >= TAKES.any.most)
514
+ ) {
515
+ stop();
516
+ contentError("The content kept taking the keyboard from the page; it was stopped.");
517
+ }
518
+ while (takes.length > 0 && at - (takes[0] as { at: number }).at > TAKES.typing.withinMs) {
519
+ takes.shift();
520
+ }
521
+ });
498
522
  const watch = watchOutcome({
499
523
  surface: created,
500
524
  source,
@@ -530,6 +554,8 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
530
554
  ...(options.show === undefined ? {} : { show: options.show }),
531
555
  ...(options.cached === undefined ? {} : { cached: options.cached }),
532
556
  userActivation: () => created.userActivation(),
557
+ // The person in this frame (P109): the page's focus in it, after the focus guard.
558
+ focused: () => created.focused?.(),
533
559
  onEvent: onBridge,
534
560
  ...(declaration === null ? {} : { declaration }),
535
561
  ...(viewer === undefined ? {} : { viewer }),
@@ -651,6 +677,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
651
677
  restarts = 0;
652
678
  run();
653
679
  },
680
+ focus() {
681
+ surface?.focus?.();
682
+ },
654
683
  destroy() {
655
684
  destroyed = true;
656
685
  stop();
package/src/host/types.ts CHANGED
@@ -201,6 +201,14 @@ export interface DisplayEvents {
201
201
  readonly refused: { readonly capability: CapabilityName; readonly refusal: Refusal };
202
202
  /** Too many declines: the display stops asking until it runs again. */
203
203
  readonly muted: undefined;
204
+ /**
205
+ * The content moved the keyboard into its frame from one of the page's text fields without the
206
+ * person (no press on the frame, no Tab, P109), and focus went back where it was; `typing`: the
207
+ * person had pressed a key on the page within the last second. The content's doing. Three while
208
+ * typing within 10 s, or five within 2 s, stop the display (`contentError` says so; `reload()`
209
+ * runs it again).
210
+ */
211
+ readonly focusTaken: { readonly typing: boolean };
204
212
  /**
205
213
  * What the frame reported about annotations (`annotate`, P053), checked and taken only while
206
214
  * the host asked for it: a selection, its clearing, a cancelled pick, where marks are. The
@@ -242,6 +250,11 @@ export interface DisplayControls {
242
250
  readonly annotations: AnnotationControls;
243
251
  /** Runs the content again from the start, in a new frame. */
244
252
  reload(): void;
253
+ /**
254
+ * Moves focus into the display's frame, as the host's own move: from one of the page's text
255
+ * fields, a frame's own `focus()` is taken for the content's and undone (P109).
256
+ */
257
+ focus(): void;
245
258
  /** Tears the view down and removes the frame. */
246
259
  destroy(): void;
247
260
  }
package/src/index.ts CHANGED
@@ -275,6 +275,7 @@ export type {
275
275
  DbContext,
276
276
  } from "./bridge/types.ts";
277
277
  export { createHost } from "./host/create-host.ts";
278
+ export { focusField } from "./platform/focus-guard.ts";
278
279
  // The client half of the host kit, and the display registry (P072).
279
280
  export {
280
281
  entryTarget,