@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.
- package/CHANGELOG.md +89 -0
- package/dist/bridge/bridge.d.ts +1 -8
- package/dist/bridge/bridge.js +0 -7
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +1 -1
- package/dist/compile/policy.d.ts +0 -7
- package/dist/compile/policy.js +1 -10
- package/dist/config/capabilities.d.ts +8 -14
- package/dist/config/capabilities.js +4 -5
- package/dist/config/schema.d.ts +2 -13
- package/dist/config/validate.js +0 -24
- package/dist/conformance/behavior.js +26 -37
- package/dist/conformance/clipboard.js +47 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/displays/displays.js +1 -3
- package/dist/guide/limits.js +1 -1
- package/dist/guide/runtime.js +1 -1
- package/dist/host/create-host.d.ts +1 -1
- package/dist/host/create-host.js +6 -51
- package/dist/host/door.d.ts +1 -1
- package/dist/host/locate.d.ts +1 -1
- package/dist/host/locate.js +2 -2
- package/dist/host/outcome.d.ts +5 -12
- package/dist/host/outcome.js +8 -16
- package/dist/host/types.d.ts +6 -22
- package/dist/index.d.ts +2 -4
- package/dist/index.js +2 -4
- package/dist/isolation/served.d.ts +9 -14
- package/dist/isolation/served.js +17 -31
- package/dist/isolation/types.d.ts +2 -19
- package/dist/isolation/types.js +0 -17
- package/dist/platform/focus-field.d.ts +11 -0
- package/dist/platform/focus-field.js +18 -0
- package/dist/platform/types.d.ts +6 -22
- package/dist/platform/web.js +8 -98
- package/dist/presets/presets.d.ts +0 -2
- package/dist/presets/presets.js +0 -1
- package/dist/react/frame.d.ts +0 -8
- package/dist/react/frame.js +0 -4
- package/dist/runtime/contract.d.ts +2 -2
- package/dist/runtime/contract.js +2 -2
- package/dist/runtime/types.generated.js +6 -6
- package/dist/server/files.js +7 -23
- package/dist/server/host.d.ts +1 -1
- package/dist/server/index.d.ts +1 -1
- package/dist/server/index.js +4 -6
- package/dist/server/naming.js +1 -1
- package/dist/server/pages.d.ts +9 -2
- package/dist/server/pages.js +28 -8
- package/dist/server/server.js +28 -166
- package/dist/server/types.d.ts +7 -7
- package/dist/shell/plan.js +2 -2
- package/dist/shell/runtime.js +1 -9
- package/docs/ADOPTING.md +42 -135
- package/docs/ARCHITECTURE.md +0 -33
- package/docs/DECISIONS.md +296 -9
- package/docs/DESIGN.md +27 -50
- package/docs/THREAT_MODEL.md +140 -242
- package/package.json +1 -1
- package/src/bridge/bridge.ts +1 -17
- package/src/check/page.ts +1 -1
- package/src/compile/policy.ts +1 -11
- package/src/config/capabilities.ts +8 -14
- package/src/config/schema.ts +2 -13
- package/src/config/validate.ts +0 -28
- package/src/conformance/behavior.ts +50 -52
- package/src/conformance/clipboard.ts +56 -1
- package/src/displays/displays.ts +1 -3
- package/src/guide/limits.ts +1 -1
- package/src/guide/runtime.ts +1 -1
- package/src/host/create-host.ts +6 -52
- package/src/host/door.ts +1 -1
- package/src/host/locate.ts +2 -2
- package/src/host/outcome.ts +8 -21
- package/src/host/types.ts +6 -20
- package/src/index.ts +2 -4
- package/src/isolation/served.ts +18 -37
- package/src/isolation/types.ts +2 -24
- package/src/platform/focus-field.ts +18 -0
- package/src/platform/types.ts +6 -21
- package/src/platform/web.ts +8 -116
- package/src/presets/presets.ts +0 -3
- package/src/react/frame.tsx +0 -10
- package/src/runtime/contract.ts +4 -4
- package/src/runtime/types.generated.ts +6 -6
- package/src/server/files.ts +4 -19
- package/src/server/host.ts +1 -1
- package/src/server/index.ts +4 -16
- package/src/server/naming.ts +1 -1
- package/src/server/pages.ts +38 -12
- package/src/server/server.ts +29 -189
- package/src/server/types.ts +7 -7
- package/src/shell/plan.ts +2 -2
- package/src/shell/runtime.ts +1 -9
- package/types/runtime/v1/artifact.d.ts +2 -3
- package/types/runtime/v1/assets.d.ts +1 -1
- package/types/runtime/v1/chat.d.ts +2 -2
- package/types/runtime/v1/comments.d.ts +1 -1
- package/types/runtime/v1/downloads.d.ts +2 -2
- package/types/runtime/v1/links.d.ts +2 -2
- package/dist/platform/focus-guard.d.ts +0 -252
- package/dist/platform/focus-guard.js +0 -764
- package/dist/server/nested.d.ts +0 -66
- package/dist/server/nested.js +0 -120
- package/dist/shell/frame.d.ts +0 -28
- package/dist/shell/frame.js +0 -338
- package/src/platform/focus-guard.ts +0 -999
- package/src/server/nested.ts +0 -156
- 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 ·
|
|
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` ·
|
|
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 ·
|
|
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 ·
|
|
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 ·
|
|
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 ·
|
|
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 ·
|
|
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 ·
|
|
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.
|