@botiverse/porthole 0.15.2 → 0.16.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 (109) hide show
  1. package/CHANGELOG.md +89 -0
  2. package/dist/bridge/bridge.d.ts +1 -8
  3. package/dist/bridge/bridge.js +0 -7
  4. package/dist/check/page-source.js +1 -1
  5. package/dist/check/page.js +1 -1
  6. package/dist/compile/policy.d.ts +0 -7
  7. package/dist/compile/policy.js +1 -10
  8. package/dist/config/capabilities.d.ts +8 -14
  9. package/dist/config/capabilities.js +4 -5
  10. package/dist/config/schema.d.ts +2 -13
  11. package/dist/config/validate.js +0 -24
  12. package/dist/conformance/behavior.js +26 -37
  13. package/dist/conformance/clipboard.js +47 -1
  14. package/dist/conformance/harness-source.js +1 -1
  15. package/dist/displays/displays.js +1 -3
  16. package/dist/guide/limits.js +1 -1
  17. package/dist/guide/runtime.js +1 -1
  18. package/dist/host/create-host.d.ts +1 -1
  19. package/dist/host/create-host.js +6 -51
  20. package/dist/host/door.d.ts +1 -1
  21. package/dist/host/locate.d.ts +1 -1
  22. package/dist/host/locate.js +2 -2
  23. package/dist/host/outcome.d.ts +5 -12
  24. package/dist/host/outcome.js +8 -16
  25. package/dist/host/types.d.ts +6 -22
  26. package/dist/index.d.ts +2 -4
  27. package/dist/index.js +2 -4
  28. package/dist/isolation/served.d.ts +9 -14
  29. package/dist/isolation/served.js +17 -31
  30. package/dist/isolation/types.d.ts +2 -19
  31. package/dist/isolation/types.js +0 -17
  32. package/dist/platform/focus-field.d.ts +11 -0
  33. package/dist/platform/focus-field.js +18 -0
  34. package/dist/platform/types.d.ts +6 -22
  35. package/dist/platform/web.js +8 -98
  36. package/dist/presets/presets.d.ts +0 -2
  37. package/dist/presets/presets.js +0 -1
  38. package/dist/react/frame.d.ts +0 -8
  39. package/dist/react/frame.js +0 -4
  40. package/dist/runtime/contract.d.ts +2 -2
  41. package/dist/runtime/contract.js +2 -2
  42. package/dist/runtime/types.generated.js +6 -6
  43. package/dist/server/files.js +7 -23
  44. package/dist/server/host.d.ts +1 -1
  45. package/dist/server/index.d.ts +1 -1
  46. package/dist/server/index.js +4 -6
  47. package/dist/server/naming.js +1 -1
  48. package/dist/server/pages.d.ts +9 -2
  49. package/dist/server/pages.js +28 -8
  50. package/dist/server/server.js +28 -166
  51. package/dist/server/types.d.ts +7 -7
  52. package/dist/shell/plan.js +2 -2
  53. package/dist/shell/runtime.js +1 -9
  54. package/docs/ADOPTING.md +42 -135
  55. package/docs/ARCHITECTURE.md +0 -33
  56. package/docs/DECISIONS.md +296 -9
  57. package/docs/DESIGN.md +27 -50
  58. package/docs/THREAT_MODEL.md +140 -242
  59. package/package.json +1 -1
  60. package/src/bridge/bridge.ts +1 -17
  61. package/src/check/page.ts +1 -1
  62. package/src/compile/policy.ts +1 -11
  63. package/src/config/capabilities.ts +8 -14
  64. package/src/config/schema.ts +2 -13
  65. package/src/config/validate.ts +0 -28
  66. package/src/conformance/behavior.ts +50 -52
  67. package/src/conformance/clipboard.ts +56 -1
  68. package/src/displays/displays.ts +1 -3
  69. package/src/guide/limits.ts +1 -1
  70. package/src/guide/runtime.ts +1 -1
  71. package/src/host/create-host.ts +6 -52
  72. package/src/host/door.ts +1 -1
  73. package/src/host/locate.ts +2 -2
  74. package/src/host/outcome.ts +8 -21
  75. package/src/host/types.ts +6 -20
  76. package/src/index.ts +2 -4
  77. package/src/isolation/served.ts +18 -37
  78. package/src/isolation/types.ts +2 -24
  79. package/src/platform/focus-field.ts +18 -0
  80. package/src/platform/types.ts +6 -21
  81. package/src/platform/web.ts +8 -116
  82. package/src/presets/presets.ts +0 -3
  83. package/src/react/frame.tsx +0 -10
  84. package/src/runtime/contract.ts +4 -4
  85. package/src/runtime/types.generated.ts +6 -6
  86. package/src/server/files.ts +4 -19
  87. package/src/server/host.ts +1 -1
  88. package/src/server/index.ts +4 -16
  89. package/src/server/naming.ts +1 -1
  90. package/src/server/pages.ts +38 -12
  91. package/src/server/server.ts +29 -189
  92. package/src/server/types.ts +7 -7
  93. package/src/shell/plan.ts +2 -2
  94. package/src/shell/runtime.ts +1 -9
  95. package/types/runtime/v1/artifact.d.ts +2 -3
  96. package/types/runtime/v1/assets.d.ts +1 -1
  97. package/types/runtime/v1/chat.d.ts +2 -2
  98. package/types/runtime/v1/comments.d.ts +1 -1
  99. package/types/runtime/v1/downloads.d.ts +2 -2
  100. package/types/runtime/v1/links.d.ts +2 -2
  101. package/dist/platform/focus-guard.d.ts +0 -252
  102. package/dist/platform/focus-guard.js +0 -764
  103. package/dist/server/nested.d.ts +0 -66
  104. package/dist/server/nested.js +0 -120
  105. package/dist/shell/frame.d.ts +0 -28
  106. package/dist/shell/frame.js +0 -338
  107. package/src/platform/focus-guard.ts +0 -999
  108. package/src/server/nested.ts +0 -156
  109. package/src/shell/frame.ts +0 -371
package/docs/DECISIONS.md CHANGED
@@ -4874,7 +4874,7 @@ when someone remembered, and what DESIGN.md said they fail had drifted from what
4874
4874
  a control's run makes a CI job too long (shard the controls across jobs), or the kit's app gains
4875
4875
  a weakening seam (then its controls join the registry).
4876
4876
 
4877
- ## P105 · 2026-10-20 · After the review of P104: a marker's click within a gesture and the host's view guarded, one clock for follow-ups, text markers beside their line · Accepted; amended by P133
4877
+ ## P105 · 2026-10-20 · After the review of P104: a marker's click within a gesture and the host's view guarded, one clock for follow-ups, text markers beside their line · Accepted; amended by P133; superseded in part by P149 (a marker's click within a gesture)
4878
4878
 
4879
4879
  Amends P104 (its points 1, 3, 5 and 7, and its Trust) and P053's Trust. From the independent
4880
4880
  review of P104 and 0.9.0 (botiverse/porthole#37: no P0 or P1, two P2s, six P3s) and from #36
@@ -5500,7 +5500,7 @@ the anchor). Negative control `comment-draft` (the draft taken as given) → the
5500
5500
  engine. `types/runtime/v1/check.ts` (the page-shaped call compiles); the runtime conformance's
5501
5501
  comments case sends a draft.
5502
5502
 
5503
- ## P109 · 2026-10-26 · After the review of 0.12.0's drafts: the keyboard given back, `comments.open` from the frame the person is in, a page's draft the person's to act on, stricter draft text · Accepted
5503
+ ## P109 · 2026-10-26 · After the review of 0.12.0's drafts: the keyboard given back, `comments.open` from the frame the person is in, a page's draft the person's to act on, stricter draft text · Superseded in part by P149 (the keyboard given back, `comments.open` from the frame the person is in; the draft rules stand)
5504
5504
 
5505
5505
  Amends P090 and P108, and THREAT_MODEL §6 and §7. From the review of P107 and P108 at 0.12.0
5506
5506
  (2026-10-26: no P0, two P1s, three P2s, two P3s) and the review of the 0.11.0 and 0.12.0 releases
@@ -5845,7 +5845,7 @@ that throws gives the "wasn't checked" warning; `admitFiles` with `\ffffff` in a
5845
5845
  **Revisit when** a page's own document is ever shown outside the shell (then quirks mode is real),
5846
5846
  or an engine starts counting fixed boxes in what the viewport scrolls.
5847
5847
 
5848
- ## P111 · 2026-10-28 · A nested page: Porthole's shell at the framed address, the page its opaque child, and the shell's own activation decides the keyboard and `comments.open` · Accepted
5848
+ ## P111 · 2026-10-28 · A nested page: Porthole's shell at the framed address, the page its opaque child, and the shell's own activation decides the keyboard and `comments.open` · Superseded by P149
5849
5849
 
5850
5850
  **Context.** P109's focus guard and `comments.open`'s gate ask whether the person, not the page,
5851
5851
  moved the keyboard into a frame or clicked in it. In full Chromium a cross-site frame is out of
@@ -6112,7 +6112,7 @@ told selection kept: each alone fails the probe, measured on Chromium).
6112
6112
  **Revisit when** a host needs the element picked (`elements: true`) or a held block cleared too
6113
6113
  (they leave no highlight now), or the MCP Apps spec gains a host-to-view way to clear a selection.
6114
6114
 
6115
- ## P114 · 2026-10-28 · A nested page's shell on a label of its own, where nothing else is ever served · Accepted
6115
+ ## P114 · 2026-10-28 · A nested page's shell on a label of its own, where nothing else is ever served · Superseded by P149
6116
6116
 
6117
6117
  **Context.** porthole#56 (Ferry's audit of what merged after 0.13.0). P111 rests on the shell
6118
6118
  being a realm content can't reach (ARCHITECTURE "Trust boundaries" 4): the host trusts the shell's
@@ -6375,7 +6375,7 @@ pinned at the frame's top… takes a mouse click and a tap where it is drawn" (a
6375
6375
  pixels); "a mouse is as before…" (a click 11 px below or 4 px beside the bubble is the page's,
6376
6376
  with no touch and on a touch screen after a finger).
6377
6377
 
6378
- ## P120 · 2026-10-29 · A nested page's keyboard: a fight is judged without the shell, the shell is asked to look, a key is no press where the pointer is seen · Accepted; amended by P122
6378
+ ## P120 · 2026-10-29 · A nested page's keyboard: a fight is judged without the shell, the shell is asked to look, a key is no press where the pointer is seen · Superseded by P149
6379
6379
 
6380
6380
  Amends P111. **Context.** The audit of P111's guard (2026-10-28, NG-1, P0 on Firefox; porthole#56):
6381
6381
  a nested page that focuses its field as it loads and focuses it again whenever it loses focus read
@@ -6511,7 +6511,7 @@ out-of-process frame, says what turned activation on, or tells a frame's parent
6511
6511
  into it; or a host can tell a frame in its own process from one out of it before the pointer has
6512
6512
  been over one (then a first move into a nested page there is judged as 0.13 judged it, P120-1).
6513
6513
 
6514
- ## P121 · 2026-10-29 · After the audit of 0.14.2: a nested page's shell held to its own label outside `/server`, one source for its files' CSP, what `clearSelection` tells the page, `tracked` guarded · Accepted
6514
+ ## P121 · 2026-10-29 · After the audit of 0.14.2: a nested page's shell held to its own label outside `/server`, one source for its files' CSP, what `clearSelection` tells the page, `tracked` guarded · Superseded in part by P149 (a nested page's shell held to its own label, one source for its files' CSP)
6515
6515
 
6516
6516
  Amends P114 and P115. From the audit of aedc412 (2026-10-29; no P0 or P1): two findings on nested
6517
6517
  pages (M1, P2; M2, P3) and two on annotations (AN-1, P2; AN-2, P3).
@@ -6580,7 +6580,7 @@ second display kind from the app under test, and what it would hold (a Worker's
6580
6580
  host's; left for when a host with its own Worker asks for one. Hiding the clear from the page:
6581
6581
  the `selectionchange` gives it away whatever the message says.
6582
6582
 
6583
- ## P122 · 2026-10-29 · After 0.14.4's CI: no press within 250 ms of the person's key, and the pointer rule reads the typing before an activation · Accepted
6583
+ ## P122 · 2026-10-29 · After 0.14.4's CI: no press within 250 ms of the person's key, and the pointer rule reads the typing before an activation · Superseded by P149
6584
6584
 
6585
6585
  Amends P120. **Context.** CI on 0.14.4 (run 40822963445, `loopback (chromium-oopif)`): P120's
6586
6586
  case "a page that starts taking the keyboard back on its own blur while the person types…" failed
@@ -6650,7 +6650,7 @@ pass on full Chromium, the headless shell and Firefox; `navigate-guard`, `pointe
6650
6650
  it (then the press itself can be told from a key, and the window can go).
6651
6651
 
6652
6652
 
6653
- ## P123 · 2026-10-29 · A page taking the keyboard is an accepted risk; the guard stays best effort · Accepted
6653
+ ## P123 · 2026-10-29 · A page taking the keyboard is an accepted risk; the guard stays best effort · Superseded in part by P149 (the risk stays accepted; the guard is gone)
6654
6654
 
6655
6655
  **Context.** P109, P120 and P122 built a guard that gives the keyboard back when a display moves
6656
6656
  focus into its frame while the person types in the host's page. P122's review (porthole#81) showed
@@ -7975,7 +7975,7 @@ Safari; Safari and iOS are unmeasured. Playwright emulates a focused window on e
7975
7975
  Safari shows `hasFocus` disagreeing with the host's `activeElement` after `display.focus()`; or a
7976
7976
  word must expire by itself (a host that sends many, or content that stays out for long).
7977
7977
 
7978
- ## P136 · 2026-11-06 · `display.focus()` reaches a nested page: the host's word to its shell, in a task of its own · Accepted
7978
+ ## P136 · 2026-11-06 · `display.focus()` reaches a nested page: the host's word to its shell, in a task of its own · Superseded by P149
7979
7979
 
7980
7980
  Amends P111 and closes P135's known gap (#proj-workspace:#214). Tenny's requirement, #proj-workspace:#211:
7981
7981
  `marker-late` covers the nested case.
@@ -9158,6 +9158,20 @@ each fail exactly their probe on all three. The old spec with its document in tw
9158
9158
  route (then it needs its own entry, never `access`), or a browser stops exposing
9159
9159
  `ancestorOrigins` to a framed page.
9160
9160
 
9161
+ **Amended in 0.15.3, after the audit of 0.15.1 (N1): the helpers that take host origins check
9162
+ them.** Decision 4 says every helper that takes host origins or `framedBy` throws on a bad one.
9163
+ For `framedBy` that held (`ancestorsOf`). For host origins it held in `createServer`, the host kit
9164
+ and `frameShellScript`, and not in four helpers a content Worker of a host's own calls itself:
9165
+ `statusPage`, `doorResponse`, `doorStatusResponse` and `nestedShellCsp` took `hostOrigins` as they
9166
+ came, so `https://app.example:0` passed and `"https://a; script-src *"` went into the
9167
+ `Content-Security-Policy` header as written. What they are given is the host's own configuration,
9168
+ not content's, so nothing reached them that a host didn't write; the claim was wrong, and a header
9169
+ built from an unchecked string is not something to leave. Each now runs `hostOriginProblem` over
9170
+ every origin and throws a `TypeError` naming itself (`doorResponse: hostOrigins: …`), with
9171
+ `frameAncestors` given or not; an embed's status pages name no host and check none. And the
9172
+ exported `isHostOrigin` now says no to what `hostOriginProblem` refuses (`:0`, a port past 65535 or
9173
+ with a leading zero, a host the URL parser rewrites): it tested the shape alone. `test/origins.test.ts`.
9174
+
9161
9175
  ## P146 · 2026-11-10 · CI's full set runs before a release, not on every push · Accepted
9162
9176
 
9163
9177
  Amends P096 (its decision 4: what a push runs; its decision 6: the shards run by hand) and P097
@@ -9342,3 +9356,276 @@ P132's reports (through the root's box; here through `scrollTop`, the number the
9342
9356
  would then be no better than the event, and no worse); a host needs marks in the page's own
9343
9357
  scrollers to ride too (a timeline per scroller, named from the mark's nearest one); or decision 6's
9344
9358
  case is reported.
9359
+
9360
+ ## P148 · 2026-11-11 · A nested page's real presses, told to its shell over a port no content holds · Superseded by P149
9361
+
9362
+ Amends P111 (its "Rejected", and item 4 of its "Threat it re-opens"). From Raft (xxchan,
9363
+ 2026-11-11): a page's own button that calls `comments.open`; the host answers with a dialog; the
9364
+ person cancels it and presses the button again, and nothing happens ("This needs a click"), nor at
9365
+ the next press; some seconds later it works. Raft's pages are served, not nested: in full Chromium
9366
+ the host's page sees no press in their frame, and a press there counts only once the host's page
9367
+ has had no gesture of its own for 5 s (P109). ADOPTING's answer is to nest such pages (P111). But a
9368
+ nested page had the same dead button, for the 5 s after any gesture (below), so nesting was no
9369
+ answer to this report until that was closed. This decision closes it; it changes nothing for a
9370
+ page that isn't nested. Designed on one page first, attacked by Ferryman before any code (his
9371
+ findings are items 2, 4 and 5 below), accepted by the CTO with the bounds of item 1.
9372
+
9373
+ **Context.** P111 takes "the person is in this frame" from the shell's own transient activation
9374
+ turning on: within the last second, with no trusted press or key on the host's page since. An
9375
+ activation stays on for about 5 s, so a press in the page within 5 s of the last gesture turns
9376
+ nothing on, and a press in the page within 5 s of a press on the host's page can't be told from
9377
+ the page borrowing the host's. P111 accepted that. In use it is a button that does nothing:
9378
+ `leak/served/nested-press.spec.ts`'s first case, run against 0.15.2, has a press one second after
9379
+ a press on the host's page refused on full Chromium and on Firefox (the headless shell and WebKit
9380
+ show the host's page the press on the frame itself, and pass).
9381
+
9382
+ P111 rejected "the page's runtime reporting its own gestures (the page's word, in the page's
9383
+ realm)": the runtime and the content share a document, and whatever the runtime posts to the
9384
+ shell, the content can post from the same window. That holds for a message to a window. It doesn't
9385
+ for a `MessagePort` only the runtime holds, carrying an event only the browser makes.
9386
+
9387
+ **Decision.**
9388
+ 1. **A port per load, from the shell.** At each `load` of its page's frame the shell makes a
9389
+ `MessageChannel`, keeps one end and posts the other to the page (`porthole/shell/press-port`,
9390
+ in the shell's own namespace, which it passes neither way). It hears only the port of the
9391
+ frame's last load, and forgets what it heard of a press before that load.
9392
+ 2. **The runtime takes it before any content runs, and no content ever holds it.** The first
9393
+ listener there is (on `window`, capturing) takes the port from the first message that is the
9394
+ browser's own (`isTrusted`), from the parent read at the runtime's start, naming the method,
9395
+ with exactly one port, and stops the event there. Every other event of that name is stopped
9396
+ too. One that fails a check doesn't use up the one port (a page that dispatches a
9397
+ `MessageEvent` of its own before the shell's arrives would otherwise have the real port dropped:
9398
+ no press forged, but the feature silently off). The port lives in the runtime's closure.
9399
+ Two walls this rests on, both already there, now named as its preconditions:
9400
+ `document.open()` takes every listener off a window, the runtime's among them, and a document
9401
+ opened and closed again fires the frame's `load` again (measured on Chromium 153 and Firefox
9402
+ 155, and WebKit here): the runtime's lock on `Document.prototype.open`, `write` and `writeln`
9403
+ (there for declarative shadow DOM) is what keeps a page from hearing the port in the runtime's
9404
+ place; and a nested page is `sandbox="allow-scripts"`, so every frame of its own is another
9405
+ opaque origin, with no unlocked `open` to borrow. If the lock on any of the three couldn't be
9406
+ fixed in place, or any built-in this uses is missing, or the plan names no host, **none of it is
9407
+ installed**: no port is taken and no press is told, and the host has the shell's activation
9408
+ alone, as before.
9409
+ 3. **What is told is that there was a press, and nothing else**: no place, no target, no time. The
9410
+ shell notes when it heard it, on its own clock, and tells the host in its state (`pressed`: how
9411
+ long ago; `presses`: how many it has heard, so the host knows a new one).
9412
+ 4. **What a press is** (every one the browser's own event, read through getters kept before
9413
+ content ran):
9414
+ - a mouse going down (`pointerdown`, `pointerType` `mouse`);
9415
+ - a finger or a pen coming up (`pointerup`, any other `pointerType`). A finger that scrolls goes
9416
+ down too and ends in `pointercancel`: counted as it lands, scrolling the page would open the
9417
+ gate for a second. This is HTML's own list of what activates;
9418
+ - Enter or Space going down, not a repeat of a held key, on a native control that isn't
9419
+ editable: `button`, `summary`, `input` of type button, submit or reset; Enter alone on
9420
+ `a[href]`. By tag and type, never `role`, which is the content's word: `role="button"` on a
9421
+ text field (or on a custom element around one) would make every space typed there a press,
9422
+ and P120's "typing is no press" would be the content's to decide. A custom element is never
9423
+ one, so the focus inside its shadow tree, open or closed, tells nothing;
9424
+ - a click on such a control (an assistive technology activates a button with a click alone),
9425
+ but none while a key is down (from the browser's own `keydown` to its `keyup`, or the next
9426
+ press of a pointer): the key's own press was judged as it went down, where it went down.
9427
+ Without that, content that moves the focus to its button inside the `keydown` of an Enter
9428
+ typed in a text field gets the button a click of the browser's own, the focus on it
9429
+ (Ferryman, on the code: measured on Chromium 153 and Firefox 155, and WebKit here); and a
9430
+ held key's repeats give a button a click each. Behind it, not the click a form gives its
9431
+ submit button for Enter in another of its controls (the two forms read through each
9432
+ control's own `form`: a field tied by its `form` attribute is not inside the form's
9433
+ element).
9434
+ 5. **The host judges a press told exactly as an activation that turned on.** For a second
9435
+ (`SHELL_GESTURE_MS`), a move of focus into the frame, or a `comments.open`, is the person's,
9436
+ **with no trusted press or key on the host's page since** (the design page had this signal
9437
+ need no quiet host; it keeps one, which costs the case this is for nothing: the dialog's
9438
+ Cancel is before the press). And, as for an activation: not a press told in a fight over a
9439
+ text field (P120), not one within 250 ms of the person's key on the host's page (P122), not
9440
+ one told within a second of their typing with the pointer elsewhere, where the host's page
9441
+ sees the pointer (P120), and not one told in or just after a stall of the shell (below). A
9442
+ press told while the focus is already in the frame makes the frame the person's from there on,
9443
+ as a move they made into it does.
9444
+ 6. **A stalled shell.** The shell notes a press when it hears it. Where the page shares the
9445
+ shell's thread, a page that holds it from its own click handler makes that as late as it
9446
+ likes, past the person going back to the host's page (P111, after its review). An activation
9447
+ seen after a stall is uncertain because the look that sees it turn on is the first look after
9448
+ the stall, and says its gap. A press is another message: when the page lets go, the shell's own
9449
+ timer may run first and say the stall, and the press follow a moment later with no gap of its
9450
+ own (seen on the first cut of this decision: `leak/served/nested-stall.spec.ts` failed on
9451
+ Chromium with frames in process). So the host notes when the shell was last seen to have
9452
+ stalled (a report or a heartbeat after more than `SHELL_STALL_MS` of silence, or a report that
9453
+ says such a gap), and a press told within `SHELL_AFTER_STALL_MS` (500 ms) of that is no one's.
9454
+ 7. **What the page says next follows the press.** A call made in the press's own handler (a tap's
9455
+ click, a key's click) leaves the page a moment after the press does, on another channel, and
9456
+ could arrive first. After it tells a press, the runtime holds what it posts to its host until
9457
+ the shell answers on the port, which the shell does only after it has told the host; 250 ms
9458
+ without an answer and it holds nothing back. Content that posts past the runtime orders its
9459
+ own messages, at its own cost.
9460
+ 8. **A load that isn't a new document.** WebKit fires the frame's `load` for a navigation within
9461
+ the document (P142). The shell then sends a second port to a runtime that takes only one, and
9462
+ would hear the first no more. That runtime answers the second port on the first (`1`: this
9463
+ document is still here), which only it can, and the shell goes back to the first and shuts the
9464
+ new one. A new document's runtime never has the port before.
9465
+ 9. **Nested pages only** (`plan.press`, from `nested: true`). A served, opaque or proxied page's
9466
+ runtime carries the code and installs none of it; their plans are as before.
9467
+
9468
+ **Why the rejected alternative holds now.** What P111 feared was the content speaking as the
9469
+ runtime. It can't post on a port it never holds (2), and can't make the runtime post for an event
9470
+ it made up (4: `isTrusted` is an own, unforgeable property of each event; nothing else it could
9471
+ shape decides, since the tag, type, key, repeat, pointer type, target and form are read through
9472
+ getters taken before it ran). The runtime's word here stands where its other walls do (the
9473
+ navigation guard, P129, P130): its code runs first and calls only what it kept.
9474
+
9475
+ **What it does not say.** Which element was pressed, or that the press was meant for the call
9476
+ that follows. That is the activation rule's own limit. Content can put the focus on its own
9477
+ button and wait for the person's Enter meant for something else: with the shell's activation off
9478
+ that already passed for a gesture (P111, P120's residual); now it does within 5 s of the last
9479
+ gesture too, under the same rules of item 5.
9480
+
9481
+ **Threat.** One message more from the shell to the page (a port, nothing in it), two content-free
9482
+ values on that port, and two numbers more in the shell's state. No secret is in any of them. The
9483
+ gate P111 keeps shut for 5 s after any gesture now opens for a second after a real press in the
9484
+ page: the case P111's "Threat it re-opens" (4) accepted as a loss is the one given back. A page
9485
+ that could take the port could tell presses that never were, and with the person active on the
9486
+ host's page within 5 s open a comment composer or keep the keyboard: items 2 and 4 are what
9487
+ stands in the way, each with a control that takes it out.
9488
+
9489
+ **Residual.** A key on a control that isn't native (a `div` with `role="button"`, a custom
9490
+ element) tells nothing: the 5 s of P111 stay for it. So they do on an engine where the runtime
9491
+ can't install all of this (one without `PointerEvent`, say): nothing is told there. A press within 500 ms
9492
+ of a stall of the shell is dropped, a slow page's own included. The shell's stamp is when it
9493
+ heard the press, a message's time after it was made: a press on the host's page within that time
9494
+ of a press in the page reads as before it.
9495
+
9496
+ **Tested.** `test/nested.test.ts` (the shell's script in a stub page): one port per load; a press
9497
+ is told to the host before it is answered; anything else on the port is none; a new load's port
9498
+ replaces the last and forgets its press; "still here" restores the port before; the plan asks
9499
+ only a nested page; `shellPress`, `shellSaw` and `personMoved` on a press told.
9500
+ `leak/served/nested-press.spec.ts`, real input only, on full Chromium, the headless shell, WebKit
9501
+ and Firefox: a second and a third press after presses on the host's page open `comments` (refused
9502
+ before this decision on full Chromium and Firefox); Enter on the page's button, its call made in the key's
9503
+ own click, is allowed (not Firefox, where a page's own `focus()` puts no key on its button); a
9504
+ page's `focus()` 700 ms after a second press, the person back in the host's composer, is taken
9505
+ back; every event a page can dispatch tells nothing; typing in a text field, one with
9506
+ `role="button"`, one in a custom element with that role, and an editable button tells nothing; a
9507
+ held key is one press; Enter typed in a field tells none though the page moves the focus to its
9508
+ button as the key goes down, and none though a form clicks its button for it; a
9509
+ finger that scrolls tells none and a tap one (Chromium, the only engine a test can drag a finger
9510
+ on); content's first listener hears no port; a port message content sends itself first is not
9511
+ taken and takes no place (Firefox makes no such event); a page can't open its document again,
9512
+ at a later moment or as soon as it runs; a press after a link within the document is heard; the
9513
+ host's rule on a press told after a stall.
9514
+ Negative controls, each failing its probe on every engine it names: `press-untrusted`,
9515
+ `press-role`, `press-editable`, `press-repeat`, `press-key-click`, `press-submit` (behind
9516
+ `press-key-click`: it fails its probe with both out), `press-touch-down` (Chromium),
9517
+ `press-port-heard`, `press-port-forged` (Chromium, WebKit), `press-open-lock`,
9518
+ `press-still-here` (WebKit), `press-host-input`, and `shell-stall` (now this rule's too). No
9519
+ control for item 7 (an order between two channels: with the hold out it is lost only sometimes),
9520
+ nor for "only the last load's port" (nothing of a document outlives it to speak on the port it
9521
+ held: a second wall behind item 2, held by the unit test).
9522
+
9523
+ **Revisit when** an engine shows the host's page a press in an out-of-process frame (P111's own
9524
+ condition: this and the activation rule could then both go); a host reports the residual for
9525
+ controls that aren't native (then a rule for `role` that typing can't satisfy); or the 500 ms
9526
+ after a stall drops presses people notice.
9527
+
9528
+ ## P149 · 2026-11-11 · What guessed at the person's intent is taken out: nested pages, the focus guard, the proof of a click but `copyText`'s · Accepted
9529
+
9530
+ **Context.** A host reported that a page's own "comment" button, pressed by a real person,
9531
+ was refused: "This needs a click". The press was real. `comments.open` asked for a gesture
9532
+ *with the host page's focus in the calling frame* (P109), the host's page can't see a press
9533
+ inside a cross-site frame (out of process on full Chromium; no event on Firefox), and so the
9534
+ rule ran on a guess: `:active`, the pointer's place, the time since the last key, and for a
9535
+ nested page its shell's word on its activation (P111), then on which keys count (P120, P122),
9536
+ then on each real press told over a port (P148), with a storage design for nested pages next in
9537
+ line. Each step made the guess better and the machine larger, and each release still refused
9538
+ some real clicks. The question that should have come first: what does the check protect?
9539
+
9540
+ **What the checks protected.** Followed to the end, each one of them stops a page from *asking
9541
+ at a moment it picks*, never from doing:
9542
+
9543
+ - `sendPrompt`, `openLink`, `downloadFile`, `artifact.publish`, `assets.delete`: each already
9544
+ ends at the person's confirmation, shown the whole effect, and declines mute the display. A
9545
+ page that asks unprompted gets a dialog the person says no to.
9546
+ - `comments.open`: opens the host's composer with a draft that posts nothing by itself; the
9547
+ host's handler may answer no (P108's duties stand).
9548
+ - A marker's `activated`: opens the host's view of a mark, which takes no focus and no press
9549
+ for its first 500 ms (§6's guard stands).
9550
+ - The focus guard: gave the keyboard back when a page took it. P123 had already accepted that
9551
+ it couldn't hold (typing slower than one key per 250 ms passed it), so it was a wall with a
9552
+ known hole whose false positives were the person's own clicks.
9553
+
9554
+ And the proof itself proved little: the host-side check passed for any click anywhere on the
9555
+ host's page in the last 5 s, and the shell-side one is the content's own realm speaking.
9556
+
9557
+ **Decision.**
9558
+
9559
+ 1. **No proof of a click is asked by default, but `copyText`'s.** The default gates of
9560
+ `sendPrompt`, `openLink` and `downloadFile` are `confirm` and a rate of 30 a minute (they had
9561
+ no rate: the gesture was their bound, so they get one); `comments` keeps its rate alone;
9562
+ `artifact.publish` and `assets.delete` keep `confirm`. `copyText` keeps `user-activation`:
9563
+ it has no confirmation, the clipboard is the person's, and the browser's own rule for writing
9564
+ it is a gesture. The gate itself stays in the vocabulary: a host may name `user-activation`
9565
+ for any capability or method (`gates`, `methodGates`), and the shell and the bridge check it
9566
+ as before. `CapabilitySpec.inFrame` (P109's "in the calling frame") is removed.
9567
+ 2. **A marker's `activated` is taken with or without a gesture** (supersedes P105's point 2).
9568
+ Every other check on it stands: only for a mark the host shows with a marker, rebuilt,
9569
+ clamped, within the rate.
9570
+ 3. **The focus guard is removed** (supersedes P109's decisions 1 and 2; P123's risk stays
9571
+ accepted, now without a guard in front of it). No `focusTaken`, no `onFocusTaken`, no display
9572
+ stopped for taking the keyboard, no shell words about focus. `display.focus()` is the
9573
+ frame's own `focus()`. `focusField(field)` stays as a plain helper (it blurs a frame that
9574
+ holds the focus, then focuses the field: Firefox ignores a plain `focus()` there).
9575
+ `Surface.focused`, where a platform gives it, says only whether the keyboard is in the
9576
+ display (the frame's root's `activeElement`), and only the find shortcut reads it (P131).
9577
+ 4. **Nested pages are removed** (supersedes P111, P114, P120, P121's M1 and M2, P122, P136,
9578
+ P148). `nested: true` is no field; the shell document, its label (`porthole-<…>`), its
9579
+ namespace (`porthole/shell/*`), its press port and the `/server` routes and helpers for it
9580
+ are gone. They existed to give the guard and `comments.open` a realm the page couldn't speak
9581
+ for; with nothing left to ask it, the mode is a second way to serve a page with no reader.
9582
+ The label prefix `porthole-` stays reserved (`PORTHOLE_LABEL_PREFIX`): no host's naming makes
9583
+ one.
9584
+ 5. **What stays, and is not this kind of rule.** P135 and P137 (a late `focusMark` doesn't land
9585
+ once the person has moved on) guard the host's *own* move of the focus, not the page's. The
9586
+ find shortcut's focus rule (P131) refuses no real press: the key is always pressed in the
9587
+ frame. The host view's 500 ms (§6) is the host's own guard of its own controls.
9588
+
9589
+ **The served path.** No wall moves: origins, sandboxes, CSP, tickets, the door and every message
9590
+ check are as in 0.15.3. The page runtime every served document inlines is 0.15.2's with the
9591
+ nine lines of the nested-only renewal hook taken out (its pin in `test/framed-by.test.ts`);
9592
+ `use` and `legacy` are unchanged, and follow the plan's gates as they did.
9593
+
9594
+ **Rejected.** *Keep the checks and widen the guess again* (a storage relay for nested pages was
9595
+ designed next): the fifth step on the same road, for a check that protects a moment, not an
9596
+ effect. *Keep nested mode without the guard*, as an opaque page for scopes that distrust their
9597
+ own displays: no host uses it, and different scopes already give displays that distrust each
9598
+ other different origins (THREAT_MODEL S7); it can come back as its own decision with its own
9599
+ reader. *Remove `copyText`'s click too*: it is the one call with no person between the page and
9600
+ the effect. *Remove the `user-activation` gate from the vocabulary*: a host with a reason of its
9601
+ own may still want it, and `copyText` needs it.
9602
+
9603
+ **Cost.** A page can interrupt: a confirmation, a composer or a comment view at a moment the
9604
+ person didn't pick, within 30 a minute, until declines mute it. A page that takes the keyboard
9605
+ keeps it until the person clicks back. A host that wants the old default for one capability names
9606
+ the gate again (`gates: ["user-activation", "confirm"]`), with the false refusals that come with
9607
+ it. A host that served nested pages must go back to served ones (CHANGELOG 0.16.0 says how).
9608
+
9609
+ **Tested.** `test/bridge.test.ts` (a gesture gate refuses where named and for `copyText`;
9610
+ nothing else asks one); `test/agreement.test.ts` (every capability a page can call without a
9611
+ gesture has a default rate, P103's rule, now three more); `test/runtime-review.test.ts`
9612
+ (publish and delete: a confirmation with or without a gesture; a host's `methodGates` bring the
9613
+ gesture back, in the plan and the manual); `test/annotate.test.ts` (a marker's click taken
9614
+ whatever the platform says of activation, still only for a shown marker); `test/config.test.ts`
9615
+ (`nested` is refused as an unknown field); `test/sandbox.test.ts` (the static rule on
9616
+ `allow-same-origin`, re-homed from the nested suite); `test/framed-by.test.ts` (the runtime's
9617
+ pins). Conformance: `12.prompt-confirm` (a prompt on load is asked, and a no sends nothing),
9618
+ `12.raw-message` (a raw `ui/message` is asked too), `12.copy-text` and the new `12.raw-copy`
9619
+ (the gesture gate that stays, shell side and host side; controls `shell-gesture`,
9620
+ `host-gesture`). 28 negative controls go with the code they took out (the registry and
9621
+ DESIGN.md's table); `leak/late-word.spec.ts` keeps `chromium-oopif`'s one case.
9622
+
9623
+ **Revisit when** an engine tells a host's page, truthfully, that the person pressed inside a
9624
+ cross-site frame (then a check could be a fact, not a guess); a host reports the interruptions
9625
+ as abuse its own handler can't bound; or a host needs an opaque page inside a shared scope
9626
+ (nested pages' one use that was not the guard).
9627
+
9628
+ **Amended 2026-11-11, before the release.** `chromium-oopif` runs every served case too
9629
+ (`leak/served/*.spec.ts`, 142 more on full Chromium), not `leak/late-word.spec.ts` alone: with
9630
+ the nested cases gone the project had seven tests left, and a served display out of process is
9631
+ the setting the removed guesses failed in. No served case needed a change to pass there.