@botiverse/porthole 0.15.3 → 0.16.1

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 (118) hide show
  1. package/CHANGELOG.md +70 -0
  2. package/dist/annotate/types.d.ts +15 -1
  3. package/dist/annotate/validate.js +19 -1
  4. package/dist/bridge/bridge.d.ts +1 -8
  5. package/dist/bridge/bridge.js +0 -7
  6. package/dist/bridge/types.d.ts +1 -1
  7. package/dist/check/page-source.js +1 -1
  8. package/dist/check/page.js +1 -1
  9. package/dist/compile/policy.d.ts +0 -7
  10. package/dist/compile/policy.js +1 -10
  11. package/dist/config/capabilities.d.ts +8 -14
  12. package/dist/config/capabilities.js +4 -5
  13. package/dist/config/schema.d.ts +2 -13
  14. package/dist/config/validate.js +0 -24
  15. package/dist/conformance/behavior.js +26 -37
  16. package/dist/conformance/clipboard.js +47 -1
  17. package/dist/conformance/harness-source.js +1 -1
  18. package/dist/displays/displays.js +1 -3
  19. package/dist/guide/limits.js +1 -1
  20. package/dist/guide/runtime.js +1 -1
  21. package/dist/host/create-host.d.ts +1 -1
  22. package/dist/host/create-host.js +8 -52
  23. package/dist/host/door.d.ts +1 -1
  24. package/dist/host/locate.d.ts +1 -1
  25. package/dist/host/locate.js +2 -2
  26. package/dist/host/outcome.d.ts +5 -12
  27. package/dist/host/outcome.js +8 -16
  28. package/dist/host/types.d.ts +6 -22
  29. package/dist/index.d.ts +2 -4
  30. package/dist/index.js +2 -4
  31. package/dist/isolation/served.d.ts +4 -14
  32. package/dist/isolation/served.js +7 -28
  33. package/dist/isolation/types.d.ts +2 -25
  34. package/dist/isolation/types.js +0 -23
  35. package/dist/platform/focus-field.d.ts +11 -0
  36. package/dist/platform/focus-field.js +18 -0
  37. package/dist/platform/types.d.ts +7 -23
  38. package/dist/platform/web.js +8 -106
  39. package/dist/presets/presets.d.ts +0 -2
  40. package/dist/presets/presets.js +0 -1
  41. package/dist/react/frame.d.ts +0 -8
  42. package/dist/react/frame.js +0 -4
  43. package/dist/runtime/contract.d.ts +2 -2
  44. package/dist/runtime/contract.js +2 -2
  45. package/dist/runtime/types.generated.js +6 -6
  46. package/dist/server/files.js +7 -23
  47. package/dist/server/host.d.ts +1 -1
  48. package/dist/server/index.d.ts +1 -1
  49. package/dist/server/index.js +4 -6
  50. package/dist/server/naming.js +1 -1
  51. package/dist/server/server.js +28 -166
  52. package/dist/server/types.d.ts +7 -7
  53. package/dist/shell/annotate.d.ts +3 -0
  54. package/dist/shell/annotate.js +15 -5
  55. package/dist/shell/plan.d.ts +0 -5
  56. package/dist/shell/plan.js +2 -4
  57. package/dist/shell/runtime.js +1 -268
  58. package/docs/ADOPTING.md +398 -1081
  59. package/docs/DECISIONS.md +172 -10
  60. package/docs/DESIGN.md +1114 -1388
  61. package/docs/PRINCIPLES.md +85 -1
  62. package/docs/THREAT_MODEL.md +658 -1127
  63. package/package.json +1 -1
  64. package/src/annotate/types.ts +12 -1
  65. package/src/annotate/validate.ts +23 -1
  66. package/src/bridge/bridge.ts +1 -17
  67. package/src/bridge/types.ts +1 -1
  68. package/src/check/page.ts +1 -1
  69. package/src/compile/policy.ts +1 -11
  70. package/src/config/capabilities.ts +8 -14
  71. package/src/config/schema.ts +2 -13
  72. package/src/config/validate.ts +0 -28
  73. package/src/conformance/behavior.ts +50 -52
  74. package/src/conformance/clipboard.ts +56 -1
  75. package/src/displays/displays.ts +1 -3
  76. package/src/guide/limits.ts +1 -1
  77. package/src/guide/runtime.ts +1 -1
  78. package/src/host/create-host.ts +8 -53
  79. package/src/host/door.ts +1 -1
  80. package/src/host/locate.ts +2 -2
  81. package/src/host/outcome.ts +8 -21
  82. package/src/host/types.ts +6 -20
  83. package/src/index.ts +2 -4
  84. package/src/isolation/served.ts +6 -34
  85. package/src/isolation/types.ts +2 -31
  86. package/src/platform/focus-field.ts +18 -0
  87. package/src/platform/types.ts +7 -22
  88. package/src/platform/web.ts +8 -129
  89. package/src/presets/presets.ts +0 -3
  90. package/src/react/frame.tsx +0 -10
  91. package/src/runtime/contract.ts +4 -4
  92. package/src/runtime/types.generated.ts +6 -6
  93. package/src/server/files.ts +4 -19
  94. package/src/server/host.ts +1 -1
  95. package/src/server/index.ts +4 -16
  96. package/src/server/naming.ts +1 -1
  97. package/src/server/server.ts +29 -189
  98. package/src/server/types.ts +7 -7
  99. package/src/shell/annotate.ts +15 -5
  100. package/src/shell/plan.ts +2 -9
  101. package/src/shell/runtime.ts +1 -268
  102. package/types/runtime/v1/artifact.d.ts +2 -3
  103. package/types/runtime/v1/assets.d.ts +1 -1
  104. package/types/runtime/v1/chat.d.ts +2 -2
  105. package/types/runtime/v1/comments.d.ts +1 -1
  106. package/types/runtime/v1/downloads.d.ts +2 -2
  107. package/types/runtime/v1/links.d.ts +2 -2
  108. package/dist/platform/focus-guard.d.ts +0 -288
  109. package/dist/platform/focus-guard.js +0 -838
  110. package/dist/server/nested.d.ts +0 -66
  111. package/dist/server/nested.js +0 -121
  112. package/dist/shell/frame.d.ts +0 -28
  113. package/dist/shell/frame.js +0 -407
  114. package/docs/ARCHITECTURE.md +0 -359
  115. package/docs/OBJECTIVES.md +0 -116
  116. package/src/platform/focus-guard.ts +0 -1114
  117. package/src/server/nested.ts +0 -157
  118. package/src/shell/frame.ts +0 -444
package/CHANGELOG.md CHANGED
@@ -4,6 +4,76 @@
4
4
  section); the reasons for every change are in [docs/DECISIONS.md](docs/DECISIONS.md), by the
5
5
  P-numbers below.
6
6
 
7
+ ## 0.16.1
8
+
9
+ - **An element pick says where it was picked** (P150, amends P133). An element pick's
10
+ `selected` report carries an optional `pointDocument`: the click, tap or hold point, in
11
+ `documentRect`'s document coordinates, sent only beside `scroll`; a keyboard pick carries none,
12
+ and nor does a text selection. A host may place its own UI there, for an element larger than
13
+ most of the frame, clipping it to the frame as it does `documentRect`. It is the page's word and
14
+ grants nothing; no isolation wall changes. A report whose point is malformed, has no `scroll`,
15
+ or sits on a text selection is dropped (`annotate:invalid`).
16
+ **For a host:** nothing to change; read `pointDocument` if you place UI on a pick. The
17
+ annotation script every served page carries changed with it (its pinned hash, P145).
18
+
19
+ ## 0.16.0
20
+
21
+ **Breaking.** What guessed at the person's intent is taken out (P149; supersedes P111, P114,
22
+ P120, P122, P136, P148, and parts of P105, P109, P121, P123). It began with a host's report
23
+ that a page's own comment button, pressed by a real person, was refused ("This needs a click"):
24
+ the checks below ran on a guess at where the person was, each release made the guess larger,
25
+ and none of them protected more than the moment a page asks. No isolation wall changes: origins,
26
+ sandboxes, CSP, tickets, the door and every message check are as in 0.15.3.
27
+
28
+ - **No proof of a click is asked, except for `copyText`.** Default gates: `sendPrompt`,
29
+ `openLink` and `downloadFile` are `confirm` and 30 a minute (they had no rate); `comments` is
30
+ 30 a minute alone; `artifact.publish` and `assets.delete` are `confirm`. A page may call them
31
+ as it loads or on a timer: each still ends at the person's confirmation, or at a composer that
32
+ posts nothing by itself, and declines still mute the display. A marker's `activated` is taken
33
+ with or without a gesture (a view it opens still takes no press for 500 ms: that is your
34
+ view's guard, ADOPTING § Annotations). `copyText` keeps its click. The `user-activation` gate
35
+ stays in the vocabulary: name it for any capability (`gates`) or method (`methodGates`) to get
36
+ 0.15's default back for it. `CapabilitySpec.inFrame` is gone.
37
+ **For a host:** remove any `gates` override you wrote only to drop `user-activation`; the
38
+ default is now what you overrode to, plus the rate. A handler for `comments` is asked more
39
+ freely: answer `false` while the person is writing, and space out or refuse a page whose opens
40
+ the person keeps closing. The manual and the typed runtime (`types/runtime/v1`) no longer say
41
+ "call it from a click" for these.
42
+ - **The focus guard is removed.** A display that takes the keyboard keeps it until the person
43
+ clicks back (the accepted risk of THREAT_MODEL §5; the guard could not hold it and refused
44
+ people's own clicks). Gone: the `focusTaken` event, `PortholeFrame`'s and `PortholeView`'s
45
+ `onFocusTaken`, `Surface.onFocusTaken`, the "kept taking the keyboard" content error.
46
+ `display.focus()` is the frame's own `focus()`. `focusField(field)` stays, as a plain helper.
47
+ `Surface.focused`, optional, is read by the find shortcut alone.
48
+ **For a host:** delete your `focusTaken` / `onFocusTaken` handlers. Nothing else to do.
49
+ - **Nested pages are removed** (`nested: true`). The config field is refused as unknown. Gone
50
+ from the main entry: `SHELL_STATE_METHOD`, `SHELL_GESTURE_MS`, `PAGE_SANDBOX_TOKENS`. Gone from
51
+ `/server`: `isNestedLabel`, `nestedLabelOf`, `nestedShellResponse`, `nestedShellCsp`,
52
+ `nestedFileCsp`, `nestedAncestors`, `NESTED_FILE_HEADERS`, `NESTED_FILES_PREFIX`. The
53
+ `porthole-` label prefix stays reserved (`PORTHOLE_LABEL_PREFIX`).
54
+ **For a host that used `nested: true`:** go back to a served page.
55
+ 1. Remove `nested: true` from the kind's options. The page is then framed on its scope's own
56
+ label, as every served artifact is, with `allow-same-origin`: it has that origin's storage
57
+ again (`localStorage` lasts; set `served.storage` as you would for any served kind), and
58
+ the asset library and Porthole's libraries, which nested pages never had.
59
+ 2. A nested page was opaque to its scope's other displays. A served one shares its scope's
60
+ origin with them (THREAT_MODEL S7): if displays in one scope must not reach each other,
61
+ give them different scopes.
62
+ 3. A content Worker of your own: drop the routes for the shell's label
63
+ (`porthole-<…>.<domain>`) and the calls to the helpers above; `/server` users have nothing
64
+ to change. An edge route for that label can go too.
65
+ 4. Do step 1 before you upgrade: 0.15 serves the kind as a served page once the field is
66
+ gone, on both sides, and 0.16.0 refuses a config that still has it.
67
+ - **The page runtime.** The shell runtime every served document inlines is 0.15.2's without the
68
+ nested-only renewal hook (nine lines); `use` and `legacy` are unchanged. A page published
69
+ under 0.15 runs under 0.16 unchanged, and its calls that needed a click no longer need one.
70
+ - **Conformance.** `12.prompt-gesture-confirm` is `12.prompt-confirm` (a prompt on load is
71
+ asked, and a no sends nothing); `12.raw-message` now expects a raw `ui/message` to be asked
72
+ too; `12.raw-copy` is new (a raw copy with no click is refused by the host). 28 negative
73
+ controls are removed with the code they weakened.
74
+ - **The find shortcut in a shadow root.** `focused` reads the `activeElement` of the frame's own
75
+ root, so a display mounted inside a shadow root no longer reads as unfocused.
76
+
7
77
  ## 0.15.3
8
78
 
9
79
  - **A nested page's real presses count, each of them** (P148, amends P111). A nested page's shell
@@ -47,7 +47,8 @@ export interface AnnotationAnchor {
47
47
  * outside is a box of no size on the nearest edge. A positioning hint only. It is in the frame's
48
48
  * own layout px: a host that scales or transforms the frame maps it through that transform too
49
49
  * (P105). A result's `documentRect` (P132) and a report's `lastLineDocumentRect` (P133) are the
50
- * same shape in the document's coordinates, and aren't clamped.
50
+ * same shape in the document's coordinates, and aren't clamped; nor is a pick's `pointDocument`
51
+ * (P150), a point there.
51
52
  */
52
53
  export interface AnnotationRect {
53
54
  readonly x: number;
@@ -168,6 +169,19 @@ export type AnnotationReport =
168
169
  readonly rect: AnnotationRect;
169
170
  readonly lastLineDocumentRect?: AnnotationRect;
170
171
  readonly scroll?: AnnotationScroll;
172
+ /**
173
+ * Where the person picked the element (P150): the point a click, a tap or a held finger
174
+ * picked it at, in the coordinates of `documentRect` (the point in the frame's viewport plus
175
+ * `scroll`), unclamped. For a host's UI by what was pointed at, where the element is larger
176
+ * than most of the frame: its place in the frame's viewport is this less `scroll`, which a
177
+ * host clips to the frame's box. Element picks only (a text selection that carries one is
178
+ * dropped), never without `scroll` (P137), and absent from a pick from the keyboard and from
179
+ * an older shell. The page's word: where to put the host's own UI, nothing more.
180
+ */
181
+ readonly pointDocument?: {
182
+ readonly x: number;
183
+ readonly y: number;
184
+ };
171
185
  }
172
186
  /** The text selection went away. */
173
187
  | {
@@ -93,6 +93,13 @@ export function parseRect(value) {
93
93
  * may be negative: an engine's overscroll); null for anything else.
94
94
  */
95
95
  export function parseScroll(value) {
96
+ return parsePoint(value);
97
+ }
98
+ /**
99
+ * A point (a pick's `pointDocument`, P150): two finite numbers within the coordinate limit, as a
100
+ * scroll is; null for anything else.
101
+ */
102
+ function parsePoint(value) {
96
103
  if (!isRecord(value) || !coordinate(value.x) || !coordinate(value.y)) {
97
104
  return null;
98
105
  }
@@ -193,19 +200,30 @@ export function parseReport(value) {
193
200
  ? undefined
194
201
  : parseRect(value.lastLineDocumentRect);
195
202
  const scroll = value.scroll === undefined ? undefined : parseScroll(value.scroll);
196
- if (anchor === null || rect === null || lastLineDocumentRect === null || scroll === null) {
203
+ // Where an element was picked (P150), in the document as the last line is.
204
+ const pointDocument = value.pointDocument === undefined ? undefined : parsePoint(value.pointDocument);
205
+ if (anchor === null ||
206
+ rect === null ||
207
+ lastLineDocumentRect === null ||
208
+ scroll === null ||
209
+ pointDocument === null) {
197
210
  return null;
198
211
  }
199
212
  // A pair, here (P137): a selection has never had one without the other.
200
213
  if ((lastLineDocumentRect === undefined) !== (scroll === undefined)) {
201
214
  return null;
202
215
  }
216
+ // A point only for an element, and with its scroll (P150, as P137): text has no point.
217
+ if (pointDocument !== undefined && (anchor.kind !== "element" || scroll === undefined)) {
218
+ return null;
219
+ }
203
220
  return {
204
221
  type: "selected",
205
222
  anchor,
206
223
  rect,
207
224
  ...(lastLineDocumentRect === undefined ? {} : { lastLineDocumentRect }),
208
225
  ...(scroll === undefined ? {} : { scroll }),
226
+ ...(pointDocument === undefined ? {} : { pointDocument }),
209
227
  };
210
228
  }
211
229
  case "unselected":
@@ -14,8 +14,7 @@ import type { CapabilityHandlers, Confirm, ConfirmDisplay, Consent, DataCache, H
14
14
  * every capability its host function's own rate (P091, P095) → arguments well formed and within
15
15
  * their limits → who may (P087: the level of each method the call runs for the viewer, a page's
16
16
  * named data with or without a viewer, db's rules) → not muted, if confirm-gated → the own rate
17
- * of each method it runs (P094: a batch's writes count each) → a user gesture, if gated so (and
18
- * for `comments`, the host page's focus in the calling frame: P109) → the
17
+ * of each method it runs (P094: a batch's writes count each) → a user gesture, if gated so → the
19
18
  * viewer's consent, if gated so → a person's confirmation, if gated so (at most 10 waiting) →
20
19
  * shown to the person, if gated so (P100) → the handler (or, for a read, a result the host already
21
20
  * gave for it, or for a stale-allowed one the host's cache).
@@ -67,12 +66,6 @@ export interface BridgeOptions {
67
66
  readonly cached?: DataCache;
68
67
  /** Whether the embedding page has user activation now; undefined where it can't tell. */
69
68
  readonly userActivation?: () => boolean | undefined;
70
- /**
71
- * Whether the embedding page's focus is in this display's frame now (P109); undefined where it
72
- * can't tell. A capability whose gesture must be in its frame (`inFrame`: `comments`) is refused
73
- * without it.
74
- */
75
- readonly focused?: () => boolean | undefined;
76
69
  readonly onEvent: (event: BridgeEvent) => void;
77
70
  /** The clock, in milliseconds (tests pass their own). */
78
71
  readonly now?: () => number;
@@ -13,8 +13,6 @@ import { atLeast, higher } from "../runtime/levels.js";
13
13
  import { isCodeAsset, parseArtifactRequest, parseAssetRequest, parseCommentRequest, } from "../runtime/requests.js";
14
14
  import { defaultReason, isRefused, pendingReason, reasonOf, } from "./refusal.js";
15
15
  const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
16
- /** Whether `capability`'s gesture must be in its own frame (P109: the host page's focus there). */
17
- const inFrame = (capability) => capabilitySpec(capability).inFrame === true;
18
16
  const MAX_URL = 4_096;
19
17
  /**
20
18
  * The most confirmations one display has waiting at once (P095): past it a call is refused as
@@ -452,11 +450,6 @@ export function createBridge(options) {
452
450
  if (activated === false) {
453
451
  return refuse(capability, "no-user-activation");
454
452
  }
455
- // A gesture in this frame, not anywhere on the host's page (P109): the person typing in
456
- // the host's composer gives its page activation, which a frame's call would borrow.
457
- if (inFrame(capability) && options.focused?.() === false) {
458
- return refuse(capability, "no-user-activation");
459
- }
460
453
  }
461
454
  if (gates.includes("consent")) {
462
455
  const consent = options.consent;
@@ -5,7 +5,7 @@ import type { DeclaredData, DeclaredDb } from "../runtime/declaration.ts";
5
5
  import type { ViewerInfo } from "../runtime/levels.ts";
6
6
  import type { RefusalReason } from "./refusal.ts";
7
7
  /**
8
- * The host-function bridge (ARCHITECTURE § Framework layer): carries a capability call from the
8
+ * The host-function bridge (DESIGN.md § Framework layer): carries a capability call from the
9
9
  * frame to the host's handler and its result back, checking at the boundary that the capability
10
10
  * is declared, that its arguments are well formed, and that every gate passes, in that order.
11
11
  * Adapters decode protocol messages into calls; the bridge alone decides whether they run.