@botiverse/porthole 0.10.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 (68) hide show
  1. package/dist/annotate/types.d.ts +18 -6
  2. package/dist/annotate/validate.d.ts +11 -1
  3. package/dist/annotate/validate.js +18 -1
  4. package/dist/bridge/bridge.d.ts +8 -1
  5. package/dist/bridge/bridge.js +7 -0
  6. package/dist/bridge/unseen.d.ts +8 -0
  7. package/dist/bridge/unseen.js +17 -0
  8. package/dist/check/files.d.ts +2 -0
  9. package/dist/check/files.js +71 -50
  10. package/dist/check/lint.d.ts +8 -1
  11. package/dist/check/lint.js +18 -0
  12. package/dist/check/markup.d.ts +7 -0
  13. package/dist/check/markup.js +49 -0
  14. package/dist/check/page-source.js +1 -1
  15. package/dist/check/scroll.d.ts +116 -0
  16. package/dist/check/scroll.js +1485 -0
  17. package/dist/config/capabilities.d.ts +16 -3
  18. package/dist/config/capabilities.js +1 -0
  19. package/dist/conformance/harness-source.js +1 -1
  20. package/dist/conformance/runtime.js +6 -0
  21. package/dist/guide/guide.js +1 -1
  22. package/dist/guide/runtime.js +2 -2
  23. package/dist/host/create-host.js +30 -3
  24. package/dist/host/types.d.ts +15 -0
  25. package/dist/index.d.ts +2 -1
  26. package/dist/index.js +1 -0
  27. package/dist/platform/focus-guard.d.ts +143 -0
  28. package/dist/platform/focus-guard.js +445 -0
  29. package/dist/platform/types.d.ts +18 -0
  30. package/dist/platform/web.js +22 -0
  31. package/dist/react/frame.d.ts +10 -1
  32. package/dist/react/frame.js +4 -0
  33. package/dist/runtime/requests.d.ts +5 -0
  34. package/dist/runtime/requests.js +41 -4
  35. package/dist/runtime/types.generated.js +1 -1
  36. package/dist/shell/annotate.d.ts +2 -1
  37. package/dist/shell/annotate.js +29 -12
  38. package/dist/shell/use.js +9 -1
  39. package/docs/ADOPTING.md +106 -5
  40. package/docs/ARCHITECTURE.md +2 -1
  41. package/docs/DECISIONS.md +741 -2
  42. package/docs/DESIGN.md +38 -9
  43. package/docs/THREAT_MODEL.md +146 -19
  44. package/package.json +1 -1
  45. package/src/annotate/types.ts +19 -6
  46. package/src/annotate/validate.ts +20 -1
  47. package/src/bridge/bridge.ts +17 -1
  48. package/src/bridge/unseen.ts +24 -0
  49. package/src/check/files.ts +72 -54
  50. package/src/check/lint.ts +24 -0
  51. package/src/check/markup.ts +53 -0
  52. package/src/check/scroll.ts +1825 -0
  53. package/src/config/capabilities.ts +16 -3
  54. package/src/conformance/runtime.ts +9 -0
  55. package/src/guide/guide.ts +1 -0
  56. package/src/guide/runtime.ts +2 -2
  57. package/src/host/create-host.ts +38 -3
  58. package/src/host/types.ts +13 -0
  59. package/src/index.ts +2 -0
  60. package/src/platform/focus-guard.ts +572 -0
  61. package/src/platform/types.ts +17 -0
  62. package/src/platform/web.ts +22 -0
  63. package/src/react/frame.tsx +12 -1
  64. package/src/runtime/requests.ts +50 -6
  65. package/src/runtime/types.generated.ts +1 -1
  66. package/src/shell/annotate.ts +29 -12
  67. package/src/shell/use.ts +9 -1
  68. package/types/runtime/v1/comments.d.ts +20 -6
@@ -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" } },
@@ -588,6 +588,15 @@ export function defineRuntimeConformance(
588
588
  "open",
589
589
  );
590
590
  expect(typeof opened === "boolean", "comments.open answers a boolean");
591
+ // A draft (P108): the handler takes the new field (a strict schema of its own must not refuse it).
592
+ const drafted = ok(
593
+ await as(handlers, viewers.view)("comments", {
594
+ anchor: { name: "slide-3" },
595
+ draft: "Approved",
596
+ }),
597
+ "open with a draft",
598
+ );
599
+ expect(typeof drafted === "boolean", "comments.open with a draft answers a boolean");
591
600
  });
592
601
  }
593
602
  return cases;
@@ -253,6 +253,7 @@ function widget(c: Context): string {
253
253
  ),
254
254
  `- An SVG scales with the frame: its text shows at font-size × frame width ÷ viewBox width, so a 680-wide viewBox turns 12 into 5 px on a phone. Draw it for the phone: viewBox="0 0 ${viewBox} H", no text under 13, width="100%" style="max-width: 400px"; its text then shows at ${smallest} to ${largest} px on every screen. Or draw it 1 unit = 1 px with a script (topic chart).`,
255
255
  `- The frame never scrolls sideways: nothing fixed wider than ${layout.minWidthPx} px; images max-width: 100%; a grid or flex child with long text min-width: 0; a wide table or code block in its own box with overflow-x: auto.`,
256
+ `- It scrolls as a document: unless it's meant to fit one screen (a game, a canvas), don't hold html, body or the element that holds it all to one screen (height: 100% or 100vh with overflow: hidden, or position: fixed), or what's below the first screen can't be reached. A box that scrolls by itself takes the wheel while the pointer is over it: keep those to parts of the ${noun} (a wide table, a long list), never the whole of it.`,
256
257
  "- Cards in a row wrap (flex-wrap: wrap; flex: 1 1 100px), or a grid of repeat(auto-fit, minmax(160px, 1fr)): at most 2 columns under 500 px, never a fixed repeat(3, …).",
257
258
  "- Touch: anything clickable is at least 44 px tall. Phones don't hover: what a hover shows, a tap (click) shows too.",
258
259
  fills
@@ -28,7 +28,7 @@ import { sizeWords } from "./limits.ts";
28
28
  /** How each method is called, as the manual writes it. */
29
29
  const CALLS: Readonly<Record<RuntimeCapabilityName, Readonly<Record<string, string>>>> = {
30
30
  user: { get: "user.get()" },
31
- comments: { open: "comments.open({ name, label, quote })" },
31
+ comments: { open: "comments.open({ name, label, quote }, { draft })" },
32
32
  clipboard: { copy: "clipboard.copy(text)" },
33
33
  links: { open: "links.open(url)" },
34
34
  downloads: { save: "downloads.save({ name, text | data })" },
@@ -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); the person writes it in the app. True if it opened. Write-only: a page never reads 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 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: () =>
@@ -4,7 +4,13 @@ import {
4
4
  type AnnotationMark,
5
5
  type AnnotationReport,
6
6
  } from "../annotate/types.ts";
7
- import { annotateMode, checkMarks, clampRect, parseReport } from "../annotate/validate.ts";
7
+ import {
8
+ annotateMode,
9
+ checkMarks,
10
+ clampRect,
11
+ hasMarker,
12
+ parseReport,
13
+ } from "../annotate/validate.ts";
8
14
  import {
9
15
  createBridge,
10
16
  onceConsent,
@@ -23,6 +29,7 @@ import { locateServed } from "./locate.ts";
23
29
  import { watchOutcome, type OutcomeWatch } from "./outcome.ts";
24
30
  import type { FrameSource } from "../isolation/types.ts";
25
31
  import { webPlatform } from "../platform/web.ts";
32
+ import { TAKES } from "../platform/focus-guard.ts";
26
33
  import type { Surface } from "../platform/types.ts";
27
34
  import type { AdapterConnection, ProtocolAdapter, ShellConnection } from "../protocol/adapter.ts";
28
35
  import {
@@ -253,7 +260,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
253
260
  /**
254
261
  * A report from the frame: checked, taken only while the host asked for it (a selection
255
262
  * only in select mode, results only for its own marks, a marker's click only for a mark it
256
- * shows with one, within a gesture), then through the bridge's gates.
263
+ * shows with one, a count's or a draft's, within a gesture), then through the bridge's gates.
257
264
  */
258
265
  const onAnnotation = (raw: unknown, through: HostFunctionBridge) => {
259
266
  if (
@@ -310,7 +317,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
310
317
  }
311
318
  case "activated": {
312
319
  const { id } = report;
313
- if (!marks.some((mark) => mark.id === id && mark.count !== undefined)) {
320
+ if (!marks.some((mark) => mark.id === id && hasMarker(mark))) {
314
321
  return;
315
322
  }
316
323
  // A marker's real click gives the host's page transient activation (measured on all
@@ -489,6 +496,29 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
489
496
  })
490
497
  : framed;
491
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
+ });
492
522
  const watch = watchOutcome({
493
523
  surface: created,
494
524
  source,
@@ -524,6 +554,8 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
524
554
  ...(options.show === undefined ? {} : { show: options.show }),
525
555
  ...(options.cached === undefined ? {} : { cached: options.cached }),
526
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?.(),
527
559
  onEvent: onBridge,
528
560
  ...(declaration === null ? {} : { declaration }),
529
561
  ...(viewer === undefined ? {} : { viewer }),
@@ -645,6 +677,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
645
677
  restarts = 0;
646
678
  run();
647
679
  },
680
+ focus() {
681
+ surface?.focus?.();
682
+ },
648
683
  destroy() {
649
684
  destroyed = true;
650
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,
@@ -333,6 +334,7 @@ export {
333
334
  type AnnotateMode,
334
335
  type AnnotationAnchor,
335
336
  type AnnotationMark,
337
+ type AnnotationMarkKind,
336
338
  type AnnotationRect,
337
339
  type AnnotationReport,
338
340
  type AnnotationSelector,