@botiverse/porthole 0.14.7 → 0.14.9

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 (87) hide show
  1. package/CHANGELOG.md +74 -0
  2. package/dist/bridge/bridge.d.ts +6 -0
  3. package/dist/bridge/bridge.js +5 -0
  4. package/dist/check/files.js +2 -0
  5. package/dist/check/lint.js +82 -3
  6. package/dist/check/page-source.js +1 -1
  7. package/dist/compile/policy.d.ts +17 -6
  8. package/dist/compile/policy.js +22 -7
  9. package/dist/config/capabilities.d.ts +16 -2
  10. package/dist/config/capabilities.js +8 -0
  11. package/dist/config/schema.d.ts +13 -0
  12. package/dist/config/validate.js +15 -0
  13. package/dist/conformance/harness-source.js +1 -1
  14. package/dist/conformance/kit.d.ts +5 -0
  15. package/dist/conformance/kit.js +21 -0
  16. package/dist/conformance/limits.js +10 -5
  17. package/dist/conformance/probes.js +139 -28
  18. package/dist/conformance/served.js +25 -4
  19. package/dist/find/types.d.ts +83 -0
  20. package/dist/find/types.js +29 -0
  21. package/dist/find/validate.d.ts +17 -0
  22. package/dist/find/validate.js +82 -0
  23. package/dist/guide/guide.js +2 -1
  24. package/dist/guide/limits.js +8 -1
  25. package/dist/host/create-host.js +249 -4
  26. package/dist/host/pass-on.js +3 -2
  27. package/dist/host/types.d.ts +51 -0
  28. package/dist/index.d.ts +4 -2
  29. package/dist/index.js +4 -1
  30. package/dist/presets/presets.d.ts +6 -0
  31. package/dist/presets/presets.js +6 -0
  32. package/dist/react/frame.d.ts +43 -0
  33. package/dist/react/frame.js +107 -3
  34. package/dist/react/view.js +2 -0
  35. package/dist/runtime/contract.d.ts +1 -1
  36. package/dist/runtime/contract.js +1 -1
  37. package/dist/server/files.js +4 -3
  38. package/dist/server/server.js +4 -1
  39. package/dist/shell/annotate.js +2 -95
  40. package/dist/shell/document.d.ts +3 -3
  41. package/dist/shell/document.js +5 -3
  42. package/dist/shell/find.d.ts +82 -0
  43. package/dist/shell/find.js +725 -0
  44. package/dist/shell/plan.d.ts +5 -0
  45. package/dist/shell/plan.js +2 -0
  46. package/dist/shell/runtime.d.ts +30 -1
  47. package/dist/shell/runtime.js +789 -105
  48. package/dist/shell/text.d.ts +17 -0
  49. package/dist/shell/text.js +140 -0
  50. package/docs/ADOPTING.md +103 -0
  51. package/docs/ARCHITECTURE.md +10 -3
  52. package/docs/DECISIONS.md +513 -1
  53. package/docs/DESIGN.md +40 -4
  54. package/docs/THREAT_MODEL.md +75 -6
  55. package/docs/insertion-entry-points.md +112 -0
  56. package/package.json +1 -1
  57. package/src/bridge/bridge.ts +7 -0
  58. package/src/check/files.ts +2 -0
  59. package/src/check/lint.ts +97 -8
  60. package/src/compile/policy.ts +23 -6
  61. package/src/config/capabilities.ts +13 -1
  62. package/src/config/schema.ts +13 -0
  63. package/src/config/validate.ts +16 -0
  64. package/src/conformance/kit.ts +22 -0
  65. package/src/conformance/limits.ts +10 -5
  66. package/src/conformance/probes.ts +149 -28
  67. package/src/conformance/served.ts +24 -4
  68. package/src/find/types.ts +86 -0
  69. package/src/find/validate.ts +101 -0
  70. package/src/guide/guide.ts +3 -1
  71. package/src/guide/limits.ts +9 -1
  72. package/src/host/create-host.ts +267 -4
  73. package/src/host/pass-on.ts +3 -2
  74. package/src/host/types.ts +52 -0
  75. package/src/index.ts +13 -0
  76. package/src/presets/presets.ts +15 -0
  77. package/src/react/frame.tsx +160 -1
  78. package/src/react/view.tsx +3 -0
  79. package/src/runtime/contract.ts +1 -1
  80. package/src/server/files.ts +8 -2
  81. package/src/server/server.ts +4 -1
  82. package/src/shell/annotate.ts +3 -95
  83. package/src/shell/document.ts +5 -3
  84. package/src/shell/find.ts +731 -0
  85. package/src/shell/plan.ts +7 -0
  86. package/src/shell/runtime.ts +792 -105
  87. package/src/shell/text.ts +140 -0
package/docs/DECISIONS.md CHANGED
@@ -6260,7 +6260,7 @@ Tested: `test/shell.test.ts` (`<`, `</`, `</di`, inside an attribute, and whole
6260
6260
  unchanged); `leak/react.spec.ts` "content streams through props…" (a draft cut after `</` and
6261
6261
  after `<` draws neither).
6262
6262
 
6263
- ## P118 · 2026-10-28 · React: `trackedAnnotation` and a handle with `clearSelection` · Accepted
6263
+ ## P118 · 2026-10-28 · React: `trackedAnnotation` and a handle with `clearSelection` · Accepted; amended by P131
6264
6264
 
6265
6265
  **Context.** Raft's web app (Kirby) shows displays through `PortholeFrame` and `PortholeView`,
6266
6266
  which hold the display handle inside: it could not follow a mark (`annotations.track`, P112) or
@@ -7019,3 +7019,515 @@ with one more frame ancestor, each turn the identity test red (the second, that
7019
7019
 
7020
7020
  **Revisit when** a host needs the door's answer to differ from its content route's (it must not:
7021
7021
  P125's invariant), or Porthole verifies a host's own tickets itself.
7022
+
7023
+ ## P127 · 2026-11-01 · A frame's size is taken at most once an animation frame after its first, and only when it changed · Accepted
7024
+
7025
+ From the audit of 2026-10-29 (C-1): `resize` has no gate (`capabilities.ts`), and the host applied
7026
+ every `size-changed` a frame sent: `setHeight` (a reflow of the host's page, for a display not in
7027
+ fill mode) and a `resize` to its listeners (the React binding re-renders on each). Porthole's shell
7028
+ already measures once an animation frame and only when the height changed; content that speaks the
7029
+ protocol itself need not, and could send thousands a second. Its reach is the tab showing it: it
7030
+ reads nothing and touches no other display, but it can make that tab slow.
7031
+
7032
+ **Decision.** A run's first size is taken at once (until then its frame has no height of its own:
7033
+ waiting a frame for it left the frame 0 px tall a frame longer than before, which the leak suite saw
7034
+ on WebKit). After it, the host keeps the last size a frame sent and takes it on the next animation
7035
+ frame of the container's window (at once where there is none): one `setHeight` and one `resize` an
7036
+ animation frame at most, and none for a size the same as the last one taken (height and width). A
7037
+ run started again drops a size still waiting and takes the new run's first size at once. Not a rate:
7038
+ a rate would refuse an honest page's sizes during an animation, where taking the last one per frame
7039
+ loses nothing a person can see.
7040
+
7041
+ **Threat.** None re-opened; a gate added. `resize` still has no `defaultGates`: what bounds it is the
7042
+ host, for every config.
7043
+
7044
+ **Revisit when** a host needs every intermediate size (none does: the frame's height is all the host
7045
+ draws), or `resize` gets a gate of its own.
7046
+
7047
+ ## P128 · 2026-11-01 · A page's own nested frames, opted into: `nestedFrames: "own"` · Accepted
7048
+
7049
+ xxchan (product owner, Raft #proj-workspace:04df2a51, message 14100c19, 2026-11-01): Raft's
7050
+ Artifacts should let a page have nested frames of its own, as Claude's Artifacts do. That means an
7051
+ `<iframe>` of a file of the same artifact (the same version's files, by a relative address) and a
7052
+ `srcdoc` frame load and run; frames of other sites stay blocked. He accepted the trade-off below
7053
+ (a nested frame is a realm of its own that the shell's hardening never reaches, so WebRTC is
7054
+ there; Claude has the same). It weakens a security default, so it is **opt-in per config**, and
7055
+ every other host keeps today's behaviour without changing anything. Amends P006 (the shell's
7056
+ defenses for channels a CSP doesn't cover: nested frames), P030 (guarded elements) and P082 (a set
7057
+ page's `frame-src`), for configs that opt in only.
7058
+
7059
+ **Decision.**
7060
+ - **The switch.** `PortholeConfig.nestedFrames: "none" | "own"` (`presets.*({ nestedFrames })`,
7061
+ a display kind's `options`). Absent or `"none"` is the default: the plan, the CSPs, the manual
7062
+ and the lint are the same as before. `"own"` is refused for url mode (no shell), for a nested page
7063
+ (`nested: true`, P111: its page is an opaque origin, which no `frame-ancestors` source matches, so
7064
+ none of its own files could be framed; not measured), and by `presets.liveWidget` (P079: no
7065
+ network of its own, and a child frame has WebRTC).
7066
+ - **The shell** (`plan.nestedFrames: "own"`, step 3 of the runtime) keeps an `<iframe>` (HTML
7067
+ namespace) with a `srcdoc` attribute (which wins over any `src`), or whose `src`, resolved by the
7068
+ platform's URL parser against the document's base, is under the version's own files' address
7069
+ (`plan.files.base`, P082). Everything else is removed as before: `frame`, `frameset`, `object`,
7070
+ `embed`, `portal`, `fencedframe`; an iframe without `src` or `srcdoc` (its `about:blank`), or of
7071
+ another path of the origin, another origin, `data:`, `blob:` or `javascript:`. The rule is one
7072
+ pure function (`OWN_FRAME`, spliced into the runtime as `HELD_BACK` is) that uses no prototype
7073
+ method content could replace, given the attributes and the base through the platform's own
7074
+ getters, kept before content runs. A frame that is kept can't become one that isn't: a change to
7075
+ it (an attribute, an IDL setter such as `src`, an attribute node or map, `toggleAttribute`) that
7076
+ would make it so first takes it out of the document, synchronously, as P030 does for a link or
7077
+ meta; the observer watches `src` and `srcdoc` as the backstop. Opaque frames and single pages
7078
+ have no files: there only `srcdoc` frames are kept.
7079
+ - **The CSP.** The frame's own policy is unchanged (`frame-src 'none'`): a `srcdoc` frame needs no
7080
+ source (P033 measured it loads under the embedding page's `frame-src 'none'`). A page of a file
7081
+ set opens `frame-src` to its version's files, the same source its scripts load from
7082
+ (`fileSetDirectives(config)`, `fileSetCspDirectives(…, opened)`): never another origin, never
7083
+ `'self'`, and not `child-src` (every engine Porthole supports reads frames from `frame-src`,
7084
+ P038). The embedding page's `frame-src` is unchanged.
7085
+ - **The server.** Below a file set's base, `frame-ancestors` names the page's own origin before
7086
+ the app's, so the set's pages frame its files (`frame-ancestors` names every ancestor). The
7087
+ ticket's answer, the shell's own pages and every other display keep the app's origins alone.
7088
+ Every page of a set is served in the shell (P081), so a page of the set in a child frame has its
7089
+ own shell: it takes messages only from the host origins, which its parent isn't. That child
7090
+ realm is same-origin with its parent, which is content, so the parent can reach the child's
7091
+ built-ins before the child's shell captures them; the shell's "captured before content runs"
7092
+ hardening (P129) is not guaranteed there, which is part of what opting in gives up (below).
7093
+ - **The lint.** `nested-frame` stays an error; under `"own"` it names only what never loads: a
7094
+ `<frame>`, `<object>` or `<embed>`, an iframe of another site (any scheme, `//`), of the origin's
7095
+ root (`/`), or with neither `src` nor `srcdoc`, and one with a relative `src` where there are no
7096
+ files. Its message says what does load. `lintFiles` looks an iframe's `src` up in the set.
7097
+ - **The manual** says which frames load ("an <iframe> of one of the page's own files (a relative
7098
+ src) or with srcdoc loads, set before it is added"), from the same config
7099
+ (`test/agreement.test.ts`).
7100
+ - **Raft** opts in on its artifact kind: `defineDisplays({ artifact: { preset: "artifact",
7101
+ options: { …, nestedFrames: "own" } } })` (`raftContentDisplays.ts` in the content Worker, and
7102
+ the web's `RAFT_ARTIFACT_DISPLAYS`, kept equal).
7103
+
7104
+ **Threat it re-opens** (for a config that opts in; accepted by xxchan).
7105
+ - **A child frame is a realm of its own, where the shell never ran** (steps 1, 2, 5 and 6 of the
7106
+ runtime): in a `srcdoc` frame, and in the `about:blank` document every new iframe starts with
7107
+ (which a same-origin page reaches in the task that added it), the WebRTC constructors are there,
7108
+ so content can reach any STUN or TURN server outside `connect-src` and carry what it holds out
7109
+ (`webrtc 'block'` stops it only in an engine that honors it); resource hints there are not
7110
+ removed (a `dns-prefetch` or `preconnect` reaches any host); `document.write` works. In a served
7111
+ page (`allow-same-origin`), its kept frames are its own origin, so it reaches their realms
7112
+ directly; in an opaque frame, a child is a new opaque origin (the sandbox is inherited) whose own
7113
+ script still runs. In short: a page that opts in has WebRTC, and egress is closed only as far as
7114
+ CSP closes it (P006's other walls are the CSP's, and they hold in the child: it inherits its
7115
+ parent's policy, or, a page of the set, is served with its own).
7116
+ - **The clipboard** (P051): the frame's `allow` denies `clipboard-read` and `clipboard-write`,
7117
+ and a child's features are its parent's at most, so the async Clipboard API stays closed. But
7118
+ the shell's guards don't run there: `execCommand("copy")` from a click in the child, and its
7119
+ copy and cut listeners, can put text the person didn't select on their clipboard
7120
+ (pastejacking), without `copyText` and the host's notice.
7121
+ - **Navigation.** A child frame's navigations, its own or its parent's of it, are governed by its
7122
+ embedding document's `frame-src` (the page's): a set's page frames only its version's path, an
7123
+ opaque frame nothing. So a child carries data out by navigating only to its own version's path,
7124
+ which reaches the host's content server, as a fetch there does (P082, P084). A child that
7125
+ navigates the page itself is stopped by the page's navigation guard and the app's `frame-src`,
7126
+ as before (P079). The sandbox is inherited: no popups, forms, downloads, modals or top
7127
+ navigation in a child.
7128
+ - **No new reach into the host.** A child is on the content's origin (or an opaque one); a
7129
+ file set's files now name that origin in `frame-ancestors`, which is the page's own: anything on
7130
+ it is already same-origin with the page.
7131
+
7132
+ **Why.** Pages people make with agents frame their own pages (a slide in a deck, a chart page in a
7133
+ report) and draw demos in `srcdoc` frames, which Claude's Artifacts run; removing them breaks those
7134
+ pages in Raft. Frames of other sites stay out: each would be a channel to its site.
7135
+
7136
+ **Rejected.** On by default (CLAUDE.md: never weaken a default silently; other hosts keep the
7137
+ strict rule). Running Porthole's shell in `srcdoc` children: the page reaches a child's realm
7138
+ before any script of ours could (its `about:blank`), so it would cost the page its frames' markup
7139
+ and buy nothing against content that wants out. An allowlist of other origins (as MCP Apps'
7140
+ `frameDomains`): not asked for, and each origin is a channel out.
7141
+
7142
+ **Tested** (written 2026-11-01, not yet run: run `pnpm check`, `pnpm test:leak` on Chromium, WebKit
7143
+ and Firefox, and `test:controls own-frame-rule` and `frame-guard,sync-guard` before release).
7144
+ Unit: `test/config.test.ts` (default off in every preset and plan; the refusals; a display kind's
7145
+ option reaches its served and opaque configs), `test/shell.test.ts` (`OWN_FRAME`'s rule, case by
7146
+ case; the plan), `test/files.test.ts` (a set's page frames its version's path only; served, its
7147
+ files' `frame-ancestors` and the ticket's; `lintFiles`), `test/check.test.ts` (the lint),
7148
+ `test/agreement.test.ts` (shell ↔ CSP ↔ manual, for a Raft-shaped and an inline config). Browser:
7149
+ probes `4.own-external` (another site, a relative `src` with no files, `data:`, a plugin, an empty iframe:
7150
+ none stays, the canary hears nothing), `4.own-turned` (a kept frame turned elsewhere by a setter,
7151
+ an attribute, a map, `toggleAttribute` leaves), `4.own-default` (the same frames, without the
7152
+ option: none runs), and `leak/served/files.spec.ts`'s "a page's own frames" (its own file, with its
7153
+ shell, a srcdoc and a frame it made run; another site, `/`, `/__porthole/d/…`, `../../`, plugins
7154
+ stay out; by default none). Negative control `own-frame-rule` (the rule keeps every iframe) fails
7155
+ `4.own-external` and `4.own-turned`; `frame-guard,sync-guard` fails the three
7156
+ probes that need a frame removed. Measured (CI, all three engines): under an opaque inline widget
7157
+ a `srcdoc` child's scripts don't run (it inherits the frame's nonce policy), so there the option
7158
+ keeps only frames that stay inert; on a served page (Raft's Artifacts) a `srcdoc` frame and a frame
7159
+ of its own files load and run. The served case's frames of elsewhere stand on two walls, each
7160
+ with its control: the shell's rule takes them out of the tree (`own-frame-rule` fails "stays out
7161
+ of the tree"), and the page's `frame-src` (its version's path; a `srcdoc` child inherits it)
7162
+ stops what a frame left there would load (`own-frame-rule,own-frame-src` fails "loads nothing"
7163
+ too; the rule alone out, `frame-src` holds it). A served page's shell and CSP are made in the
7164
+ served harness's process, so the two weakenings reach it there (the rule in `SERVED`, the header
7165
+ rewritten by the harness): an earlier run edited only the sources the browser loads, so neither
7166
+ reached a served page and the case looked held by "more than one wall" (CI, 9843f99: the combined
7167
+ control blind on Chromium). `navigate-guard` and `file-self` alone leave it held, by the rule.
7168
+
7169
+ Also accepted (Tenny's review): a same-origin `srcdoc` child has its own realm's untouched natives
7170
+ (`Document.prototype.write`, `Element.prototype.setHTMLUnsafe`, …) and can call them on the
7171
+ parent's document, so the parent shell's own hooks (the `document.write` lock, the declarative
7172
+ shadow DOM check) can be bypassed too, not only absent in the child. The CSP still closes the
7173
+ network the same way, so no way out is added beyond those named above, but "the parent page's
7174
+ guards stay whole" does not hold under `"own"`. A host's content origin must be the artifact's
7175
+ alone (Raft: `w-<uuid>.<content domain>`, one per artifact), since a file set's `frame-ancestors`
7176
+ names it.
7177
+
7178
+ **Revisit when** a host asks for frames of other origins (an allowlist, with its own channel
7179
+ accepted), a nested page (P111) needs frames of its own, Claude's Artifacts change their rule, or
7180
+ every engine closes WebRTC through CSP in every realm (then the trade-off is the clipboard's only).
7181
+
7182
+ ## P129 · 2026-11-04 · The shell's guards call only built-ins captured before content runs · Accepted
7183
+
7184
+ **Decision.** Step 3's frame guard and its MutationObserver, the before-change backstop, and the
7185
+ synchronous insertion and HTML-parse guards (`strip`, `admit`, the insertion wrappers, `watched`,
7186
+ `beforeChange`, the `innerHTML`/`outerHTML`/`insertAdjacentHTML`/`execCommand` wrappers, the
7187
+ attribute-turn guards) read every built-in they use through references captured before any content
7188
+ runs, and call each one only through `callOf` — the DOM `nodeType`, `isConnected`, `parentNode`,
7189
+ `childNodes`, `shadowRoot`, `localName`, `namespaceURI`, `baseURI` getters; `querySelectorAll` (by
7190
+ node type), `remove`, `cloneNode`, `createTextNode`, `createElement(NS)`, `setAttributeNS`,
7191
+ `removeAttribute`, `attachShadow`, the kept insertion methods; the `NodeList` `length` getter;
7192
+ `WeakSet` `has`/`add`, `WeakMap` `get`/`set`; `MutationObserver.observe`; the `MutationRecord`
7193
+ `addedNodes`/`type`/`target` and `Attr` `name`/`namespaceURI`/`value`/`ownerElement` getters. It
7194
+ calls none of them as a member on an object content controls, and reaches none through
7195
+ `Function.prototype.call`/`apply`/`bind`: `callOf` is `Reflect.apply` itself, kept before content
7196
+ and invoked directly, so what the guard calls and with what is never seen by anything content later
7197
+ puts on `Function.prototype`. It also walks and decides without any replaceable `Array`/`Object`
7198
+ prototype method: live collections are indexed loops over the captured length getter (never
7199
+ `Array.from`, `for…of`, or the spread, whose `Array.prototype[Symbol.iterator]` is replaceable), the
7200
+ arguments it passes on are prototype-less lists given to `callOf`, and the positional decision in the
7201
+ insertion wrappers is a lookup built before content, not `Array.prototype.indexOf`. This extends
7202
+ P128's rule (which already read `matches`, `OWN_FRAME`'s inputs and the navigation getters this way)
7203
+ and P030's guard to every built-in the guard touches. Default behaviour is unchanged; no config,
7204
+ CSP, plan or manual moves.
7205
+
7206
+ **Why.** The guard inspects objects content controls, so it must not depend on anything content can
7207
+ replace first — a prototype method or getter, the global `Array.from` or array iterator,
7208
+ `Array.prototype.indexOf`, or `Function.prototype.apply`/`call`/`bind` — otherwise a page could make
7209
+ the guard overlook a frame-like element it must remove. The invariant — **the shell's guards call
7210
+ only built-ins captured before content runs** — is the property the fix establishes, and
7211
+ `test/shell.test.ts` asserts it generically (the guard captures each built-in once, `callOf` is
7212
+ `Reflect.apply` captured first, and the whole guard-and-wrapper region of the source makes no live
7213
+ `.call(`, `.apply(`, `.bind(`, `.querySelectorAll(`, `.remove()`, `Array.from(`, `.cloneNode(`,
7214
+ `.indexOf(`, `.forEach(` or `document.createTextNode(` call).
7215
+
7216
+ **Rejected.** Capturing only `matches` (P128's extent), or only the walk's getters and methods: the
7217
+ insertion wrappers still reached built-ins through `.apply`, `.call` and `Array.prototype.indexOf`,
7218
+ which content can replace to the same end. Leaving the walk on `Array.from`/`for…of`/the spread:
7219
+ `Array.from` and `Array.prototype[Symbol.iterator]` are replaceable too. Checking a value and then
7220
+ forwarding the original argument: the platform reads the argument again, so a value that converts
7221
+ to a benign string when checked and a guarded one when the platform reads it would slip past; each
7222
+ inspected name or value is pinned to a single conversion (`once`) and that reading is both checked
7223
+ and forwarded.
7224
+
7225
+ **Where this does not reach.** The invariant is for a shell in its own realm, which runs first
7226
+ there. Under `nestedFrames: "own"` (P128), a kept child frame is a realm the shell shares with
7227
+ content that can reach it first: a page of a set in a child frame is same-origin with its parent,
7228
+ and the parent is content, so it can touch that realm's built-ins before the child's shell captures
7229
+ them. There the "captured before content runs" ordering is not guaranteed — as P128 records, a
7230
+ config that opts in gives up the shell's defenses inside its own frames and stands on the CSP there.
7231
+ This fix changes nothing about that trade-off; it holds for the top-level shell every config has.
7232
+
7233
+ **Tested** (written 2026-11-04; run `pnpm check` and `pnpm test:leak` on Chromium, WebKit and
7234
+ Firefox before release). Unit: `test/shell.test.ts` (the capture table and the no-live-call
7235
+ invariant). The leak suite's frame and hint probes (item 4, the served "own" cases) stand as the
7236
+ behavioural check; a probe that replaces each captured built-in before inserting a nested frame,
7237
+ with its negative control, belongs with the leak suite when the egress-probe harness is next
7238
+ extended.
7239
+
7240
+ **Revisit when** a new built-in is used anywhere in the guard or a new guarded channel is added
7241
+ (capture it the same way and extend the invariant test), or the leak suite gains the
7242
+ per-built-in replacement probe.
7243
+
7244
+ ## P130 · 2026-11-04 · Every insertion entry point is guarded, every subtree producer strips, and by default no frame-like element can be made · Accepted
7245
+
7246
+ **Decision.** The shell's frame guard (step 3, P030, P129) holds one invariant: **every insertion
7247
+ entry point is guarded, every subtree producer strips before returning, and under the default
7248
+ configuration no frame-capable element can exist in a content-reachable tree.** The list of entry
7249
+ points and how each is guarded is [insertion-entry-points.md](insertion-entry-points.md);
7250
+ `test/shell.test.ts` checks every row against the runtime.
7251
+ - **Insertion.** Every DOM method or setter that connects a node runs its node arguments through
7252
+ the same synchronous `admit`/`strip`, whatever the parent (connected or detached), on built-ins
7253
+ captured before content runs and called through `callOf` (P129): the P030 methods, `moveBefore`
7254
+ where an engine has it, `HTMLSelectElement.add` and `HTMLOptionsCollection.add`, and the
7255
+ `document.body` and `HTMLTableElement` `tHead`/`tFoot`/`caption` setters (a refused value refuses
7256
+ the set: a setter has no harmless stand-in).
7257
+ - **Producers.** Every API that hands content a subtree it can insert later strips it
7258
+ synchronously before it returns: `DOMParser.parseFromString` (every MIME type),
7259
+ `Document.parseHTMLUnsafe` and `Document.parseHTML`, `HTMLTemplateElement.content` (and what a
7260
+ template's `innerHTML` fills), `DOMImplementation.createHTMLDocument`/`createDocument`,
7261
+ `Range.createContextualFragment`, `XSLTProcessor.transformToFragment`/`transformToDocument`,
7262
+ `XMLHttpRequest` `responseXML` and a document `response`, `Document.importNode` (the clone) and
7263
+ `adoptNode` (the node; one that is itself frame-like is refused). `strip` enters what
7264
+ `querySelectorAll` doesn't: each template's content and each open shadow root's tree, at any
7265
+ depth (a work list, not recursion).
7266
+ - **Creation, under the default configuration.** `createElement` and `createElementNS` refuse a
7267
+ `FRAMES` name (any case, any namespace, the local name after a prefix included) with a neutral
7268
+ error, as `document.write` is refused; so does `CustomElementRegistry.define` with an `extends`
7269
+ naming one (its constructor would make one). With the parsers stripped, nothing else makes a
7270
+ frame-like element (`cloneNode` and `importNode` copy trees that hold none; `Option`, `Image`
7271
+ and `Audio` make their own kinds), so the indexed setters that can't be wrapped
7272
+ (`select[i] = …`, `options[i] = …`, `length`) have nothing to connect. Under `nestedFrames:
7273
+ "own"` (P128) creation stays open and the guards decide when a frame is connected or changed.
7274
+ The manual says so from the same config ("making one in script throws", default only).
7275
+ - **Markup methods the shell doesn't know** (one a later engine adds, on Element, ShadowRoot,
7276
+ Document, DocumentFragment or Range, with `HTML` in its name) are refused.
7277
+ - **Editing.** A `beforeinput` listener the shell registers before content runs (on `window`,
7278
+ capturing, with the platform's own getters) cancels a paste, a drop, a replacement or a yank
7279
+ (`insertFromPaste`, `insertFromPasteAsQuotation`, `insertFromDrop`, `insertReplacementText`,
7280
+ `insertFromYank`) whose data carries any type but `text/plain`, and inserts its plain text
7281
+ through the editor's `insertText`, which carries no markup. Only the browser's own events are
7282
+ acted on. Composition events can't be cancelled and carry text alone.
7283
+ - **Read once.** Every value a guard inspects and forwards passes as it is only if it is a string,
7284
+ number, boolean, bigint, `null` or `undefined` itself (`value === undefined`); anything else is
7285
+ converted once, and that reading is both checked and forwarded; a symbol, or a conversion that
7286
+ throws, is refused (`PASSES_AS_IS`, `ONCE`). `attachShadow`'s `init` is read field by field,
7287
+ once, into a fresh object with no prototype, which is all the platform is given.
7288
+
7289
+ **Why.** A guard that covers most entry points is as strong as the one it doesn't: the invariant
7290
+ is stated over all of them, producers included, so a subtree can't reach the document by a route
7291
+ the list doesn't name. Refusing creation makes the invariant hold for trees content builds by hand
7292
+ too, where no producer is involved. Under the default configuration no page needs a frame-like
7293
+ element: the lint already reports every one (`nested-frame`), and the guard removes them.
7294
+
7295
+ **Rejected.** Covering the indexed setters by stripping at the producers alone: a tree built by
7296
+ hand is no producer's. Replacing a refused element with a placeholder at creation: a page would
7297
+ get an element that silently isn't what it asked for; a refusal says why. Letting editing insert
7298
+ markup and relying on the observer: the editor connects it before the observer's microtask.
7299
+
7300
+ **Under `nestedFrames: "own"`** the creation refusal doesn't apply, and P128's trade-offs stand.
7301
+
7302
+ **Tested** (written 2026-11-04, not yet run: run `pnpm check`, `pnpm test:leak` on Chromium,
7303
+ WebKit and Firefox, and `test:controls` before release). Unit: `test/shell.test.ts` (every entry
7304
+ of the list found in the runtime, the doc's rows and statuses matching; `PASSES_AS_IS` and `ONCE`
7305
+ in isolation, fail-closed cases included; the creation refusal only under the default
7306
+ configuration), `test/agreement.test.ts` (the manual's sentence, default only). The `sync-guard` negative control also takes out the creation refusal and the
7307
+ producers' strips. The conformance probes that build a frame-like element with `createElement`
7308
+ (4.light-dom, 4.sync-realm, the shadow-root and plugin cases, 4.own-default, 7.base-plugins,
7309
+ 14.shell, and the served egress case) count a refusal at creation under the default configuration
7310
+ as the guard holding, and record it ("refused at creation"); with the refusal taken out (the
7311
+ `sync-guard` control) they build the element as before.
7312
+
7313
+ **Revisit when** an engine adds an insertion or parsing entry point (add it to the list, the
7314
+ runtime and the test), the default configuration is to allow frames, or the leak suite's probes
7315
+ cover each row.
7316
+
7317
+ ## P131 · 2026-11-04 · Find in page: the host's find bar, the shell's matches in a layer of its own (`find`) · Accepted
7318
+
7319
+ Raft's task: an Artifact viewer's find bar, like the thread panel's "search this thread": a query
7320
+ box, previous and next, a "3/12" count, highlights, Escape closes. The host can't read a display's
7321
+ text (its frame is another origin, opaque or the content's own), and the browser's own find gives
7322
+ it no count, no UI of its own and no say over Cmd+F. Only the shell, in the frame, can find the
7323
+ words and draw over them, so Porthole provides that part; the bar is the host's. Amends P118: the
7324
+ React handle holds `find` and `clearFind` beside `clearSelection`. Holds to P129 and P130: the find
7325
+ runtime calls only built-ins captured before content runs, and its layer's nodes go in only
7326
+ through the guarded insertion methods (**Drawing**, below).
7327
+
7328
+ **Decision.**
7329
+ - **A capability, `find`**, declared per config (`capabilities: { find: {} }`; in no preset by
7330
+ default; Raft opts in on its artifact kind). Served as an event, as `annotate` is; its default
7331
+ gate is a rate (120 a minute) on what the frame says unasked. The manual's entry tells the agent
7332
+ the person may search the page's words with the app's find bar (keep them as text) and that a
7333
+ page handling Cmd+F itself keeps the key (`test/agreement.test.ts` covers it). A url-mode app has
7334
+ no shell and declares no capability: find there is the browser's.
7335
+ - **The protocol** (own-prefixed, P002; `FIND_METHODS`):
7336
+ - `porthole/find.query`, host → frame, a **request**: `{ query, direction?: "next" | "prev" |
7337
+ "none", caseSensitive?: boolean }`, answered with `{ total, active, capped?: true, rect? }`:
7338
+ how many matches (at most `FIND_LIMITS.matches`, 1,000; `capped`: it stopped looking, there may
7339
+ be more), the current one from 1 (0 for none), and the current one's box in the frame's
7340
+ viewport once it was scrolled into view. A new query makes current the first match at or after
7341
+ the viewport's top (`prev`: the one before it); the same query with `next` or `prev` moves on
7342
+ from the current one by its place, wrapping; `none` keeps it. An empty query (or only spaces)
7343
+ clears and answers `{ total: 0, active: 0 }`. A query that a later query or a clear
7344
+ superseded before the shell ran it is answered with an error (`-32800`, "superseded by a later
7345
+ query"), which the host makes `"unsupported"` as it does any error (**Only the latest**,
7346
+ below).
7347
+ - `porthole/find.clear`, host → frame: highlights gone, query forgotten.
7348
+ - `porthole/find.handled { handled }`, host → frame: whether the host draws its own find bar.
7349
+ - `porthole/find.requested {}`, frame → host: the person pressed the shortcut (below).
7350
+ - `porthole/find.updated { total, active, capped? }`, frame → host: the matches changed while a
7351
+ query is shown (the content changed), at most once a second.
7352
+ - **Matching** (`FIND_MATCH`, one pure function spliced into the runtime, unit-tested): over
7353
+ annotations' text index (`TEXT_INDEX`, moved out of the annotation runtime and spliced into both:
7354
+ the body's text nodes, without scripts, styles, noscript and templates; the same text and
7355
+ offsets as before, now read through built-ins captured before content runs, P129).
7356
+ Case-insensitive unless asked (`RegExp` with `iu`: Unicode simple case folding, offsets kept),
7357
+ loose about spacing as annotations' `squash` is (trimmed; a run of white space in the query
7358
+ matches any run in the text), every other character literal (no pattern syntax reaches the
7359
+ expression). A match counts only if it has a box (text that is drawn: not `display: none`, not
7360
+ a closed `<details>`). At most 1,000 kept, 10,000 looked at, a query of at most 256 code units
7361
+ (the host refuses longer, the shell cuts).
7362
+ - **Drawing**: a layer of the shell's own, a closed shadow root over the content with the same
7363
+ forced inline style as annotations' layer (one constant, a test holds them equal), apart from
7364
+ it; a match is a light warm fill with a thin edge, the current one stronger with a ring (neither
7365
+ looks like a comment's yellow underline). Boxes from `Range.getClientRects`, only for matches in
7366
+ view, redrawn at each scroll and resize (an animation frame), and found again once a run of
7367
+ changes settles (150 ms quiet, at most a second late), the current match kept by its place. The
7368
+ current match is brought into view, centred, in its scrolling ancestors first (innermost first,
7369
+ `overflow` auto, scroll or overlay that overflows), then in the window; instantly. The selection
7370
+ is never touched (annotations would report it as the person's).
7371
+ - **Only the latest** (`FIND_LATEST`, one pure function spliced into the runtime, unit-tested). A
7372
+ search is synchronous, and on a large page long (measured: 150-730 ms on a page of 30,000
7373
+ spans), so a bar that asks at every key queued a search per key (50 queries at once took 14-22
7374
+ s). A query that comes while none waits, and not within 16 ms of the end of the last one run, is
7375
+ run at once, answered before any content's listener could answer it, as before. Otherwise it
7376
+ waits for the next task, after the messages already queued; a later query supersedes it, and a
7377
+ clear drops it, each answering it with the superseded error at once. A burst is so at most two
7378
+ searches: the one running and the latest. What a waiting query will search is read from the
7379
+ host's message when it comes (each field once, as an own property) and kept as those values,
7380
+ never read from the message again (P129). The host sends only the latest of the queries asked
7381
+ while a frame loads, and answers the others `"unsupported"`.
7382
+ - **Built-ins and insertion (P129, P130).** Every built-in the find runtime and the text index call
7383
+ once content may have run is captured before content runs and called only through `callOf`:
7384
+ `createRange`, `createTreeWalker` and the walker's `nextNode`, the `nodeType`, `localName`,
7385
+ `nodeValue`, `parentElement`, `body` and `documentElement` getters, `Range`'s `setStart`,
7386
+ `setEnd`, `collapse`, `comparePoint`, `startContainer` and boxes, `DOMRectList`'s and `DOMRect`'s
7387
+ getters, the sizes, `getComputedStyle` and `getPropertyValue`, `scrollBy`, the `style` getter and
7388
+ `cssText` accessors, the `className` and `nonce` setters, `Map`'s `set`/`get`/`has`, `RegExp` and
7389
+ its `exec`, the timers, `postMessage`, `MutationObserver.observe` and the `MutationRecord`
7390
+ getters, the `MessageEvent` `data`/`origin`/`source` getters, `KeyboardEvent`'s getters, and the
7391
+ platform's `preventDefault`. No live `.call`, `.apply` or `.bind`, no `Array`/`Object` prototype
7392
+ method (`map`, `concat`, `indexOf`, `push`, `for…of`, `Object.assign`) and no `Math` function:
7393
+ its lists are the shell's prototype-less ones (`listOf`, `pushTo`, also given to `FIND_MATCH`),
7394
+ its lookups and answers objects with no prototype. What it reads from the host's message (the
7395
+ event's fields, the request's own properties) is read once, and only a string, number or boolean
7396
+ is acted on; a box's numbers are read once and only numbers are used. The layer's nodes are made
7397
+ and inserted only through the shell's guarded methods, which step 3 wrapped before the find
7398
+ runtime runs (it is spliced after the guard and takes them then): `createElement` (A21 of
7399
+ [insertion-entry-points.md](insertion-entry-points.md)), `attachShadow` (A19), `appendChild`
7400
+ (A1), `replaceChildren` on an element and a shadow root (A2), and the `textContent` setter
7401
+ (A5). It inserts nothing into the content's own trees, and its inline styles go through CSSOM
7402
+ (`cssText`), not a `style` attribute.
7403
+ - **The shortcut**: Cmd+F on Apple's platforms (`navigator.platform`, read before content runs),
7404
+ Ctrl+F elsewhere, no Alt or Shift (`FIND_SHORTCUT`, unit-tested; on a layout whose letters aren't
7405
+ Latin, the key in F's place). Read in a listener on the window as the key bubbles, after the
7406
+ page's own: only while the host said `handled`, only a trusted key, and only one the page didn't
7407
+ take (`defaultPrevented`: a page with a find of its own keeps its key). Then the shell cancels
7408
+ the browser's find and says `requested`. Otherwise the key is left alone: a host without its own
7409
+ bar keeps the browser's.
7410
+ - **The host** (`display.find`): `query(query, { direction, caseSensitive })` resolves with the
7411
+ checked answer (its box clamped to the frame's viewport, P104) or `"unsupported"`: a config
7412
+ without `find`, an error (an older shell answers `-32601`, "isn't offered here"; the shell's own
7413
+ fallback now leaves `porthole/find.query` to the find runtime where it is declared), a malformed
7414
+ answer, or none within `FIND_LIMITS.timeoutMs` (3 s) of the frame running (asked before, the
7415
+ load's time too). A query too long, or options that aren't these, reject with a `TypeError`.
7416
+ `clear()`; `takeShortcut(take)` sends `handled`. The shortcut is kept and given to every frame
7417
+ the display runs. The query holds only for the content it was asked of: every new run (a
7418
+ `reload()`, a restart after the content navigated its frame away, so a new location) and other
7419
+ content (`setContent` with content that doesn't continue what was given; more of a streamed
7420
+ page does) forget it, answer what waits `"unsupported"` and, for other content, clear the frame
7421
+ running now. A new page is so never searched with the last one's query (not even unheard: the
7422
+ shell's scrolling and its layer would tell the page which of its words matched) unless the host
7423
+ asks again; the host clears its find bar then (ADOPTING).
7424
+ Events: `findRequested` (taken only while the host takes the shortcut and the platform says the
7425
+ page's focus is in the frame, or can't tell) and `findUpdated` (taken only while a query is
7426
+ shown); both checked (`parseFindReport`) and through the bridge's rate.
7427
+ - **React**: the handle (`PortholeFrameHandle`, P118) adds `find(query, options)` and
7428
+ `clearFind()`: with no display running, `"unsupported"`, and the query is kept, with what the
7429
+ frame showed when it was asked (`findScopeOf`: the config, instance with its version,
7430
+ declaration, viewer and generation by value, the document, the content). A display made later
7431
+ that shows the same (the frame neared the screen again; the content continued) finds it again
7432
+ and tells `onFindUpdated`; any other (`sameFindScope` false: another source, document, version
7433
+ or config, a new generation, content that doesn't continue it) forgets it. A refused query is `onHostError`
7434
+ (kind `"find"`) and `"unsupported"`, never a rejection. `onFindRequested`, given, makes the
7435
+ frame's shortcut the host's (`takeShortcut(true)`); `onFindUpdated` hears updates.
7436
+
7437
+ **Why a capability, gated per config** (THREAT_MODEL §7). Find gives content no power: nothing it
7438
+ can call, nothing of the host's it can read. But:
7439
+ 1. The query is the person's words, typed in the host's own UI, and it is posted into the content's
7440
+ realm, where the page can read it (each keystroke, for a bar that searches as the person
7441
+ types). A page with a way out (an MCP App's `connectDomains`, S5; egress a host opened; the
7442
+ runtime's `db` and other carriers, `mayPassOn`) can send what the person searched for to its
7443
+ author. A host opts in per config, knowing which displays may learn that.
7444
+ 2. The shell carries nothing the config doesn't declare (PRINCIPLE 4): a host that upgrades gets
7445
+ no new listener or message in its existing displays.
7446
+ 3. What the frame says unasked goes through the bridge, with a rate, as annotations' reports do.
7447
+
7448
+ **Accepted exposure.** The page can read every query the host sends it: the search runs in the
7449
+ page's document, so the query is in the page's realm (and, without reading the message, the
7450
+ shell's scrolling and its layer show the page which of its words matched). This was accepted by
7451
+ the product owner, with hosts sending queries on a pause or Enter rather than at every key, which
7452
+ limits what the page sees of the person's typing (ADOPTING).
7453
+ Accepted by xxchan (product owner, Raft #proj-workspace:e56d96e4, message 3d68e461, 2026-11-04):
7454
+ the page can read the queries sent to it; hosts send them on a pause or Enter, only while their
7455
+ find bar is open.
7456
+
7457
+ **Threat.** No wall moves: no CSP, sandbox, `allow`, egress or storage changes, nothing secret
7458
+ enters the frame, and annotations behave as before (the text index moved into a shared constant,
7459
+ spliced in the same place, and now reads through captured built-ins, P129). New on the message
7460
+ boundary:
7461
+ - *What content learns*: the query, whether it is case-sensitive, each move (next, previous), when
7462
+ the bar opens and closes, and whether the host draws its own bar.
7463
+ - *What content can say*: any count, any current match, any box inside its frame (clamped), and
7464
+ `updated` while a query is shown. All of it the content's word: a find bar's numbers, never a
7465
+ fact about the content. `requested` it can say at will, but the host takes it only with the
7466
+ page's focus in the frame (the web platform's focus guard: a press on the frame or a Tab put it
7467
+ there, P109). Without that rule a page could open the host's bar, which takes focus, while the
7468
+ person types in the host's composer, and their next keys would go into the bar, and so into the
7469
+ frame as queries. With the person already in the frame, the page has their keys anyway, and a bar
7470
+ opening moves the keyboard out of it. Negative control `find-requested-focus`.
7471
+ - *What content can always do*: hide, cover or move the layer, change its words so the count
7472
+ changes, keep the key from the shell (its own `preventDefault`, as intended; or stopping the
7473
+ event, which leaves the browser's find to open), patch built-ins to reach the closed shadow root
7474
+ (as annotations' layer, P105), or make the search dear by its size (linear in its text, bounded
7475
+ by the limits above; found again at most once a second while it changes; in an opaque frame that
7476
+ shares the host's process that time is the host's too, as annotations' is, §5); a burst of
7477
+ queries costs at most two searches (**Only the latest**).
7478
+
7479
+ **Rejected.**
7480
+ - The CSS Custom Highlight API (as P053 and P104 rejected it for marks): `CSS.highlights` is the
7481
+ content's registry, to read, clear or restyle; the shell's drawing must be its own.
7482
+ - `window.find()` or the browser's find: non-standard or out of reach, no count, and it moves the
7483
+ selection, which annotations report as the person's.
7484
+ - Always on, ungated: every display's page would get the person's search terms after an upgrade, a
7485
+ third-party MCP App's (S5) included.
7486
+ - A find bar drawn in the frame: the content could cover or fake it; the host's own UI is the
7487
+ point.
7488
+ - Taking Cmd+F wherever `find` is declared: a host without a bar of its own would lose the
7489
+ browser's find. And a notification only (no request): an older shell couldn't say it doesn't
7490
+ know it, and the host would wait out a timeout for every query.
7491
+ - The host searching text the page sends it: a new channel for the page's words into the host's
7492
+ UI, and its word of its own text anyway.
7493
+
7494
+ **Not covered** (each a gap a host may hear about): text in open shadow roots, in a page's own
7495
+ nested frames (P128) or in form fields' values, words in images or a canvas (the manual says to keep
7496
+ them as text), and words split across elements with no space between in the text (a table's
7497
+ cells: "foo bar" doesn't find `<td>foo</td><td>bar</td>`). Escape and Cmd+G in the frame are the
7498
+ page's: the host's bar closes and moves on from its own UI.
7499
+
7500
+ **Tested** (written 2026-11-04, not yet run: the authoring machine runs no tests; run `pnpm check`,
7501
+ `pnpm test:leak` on Chromium, WebKit and Firefox, and `pnpm --filter @botiverse/porthole
7502
+ test:controls find-requested-focus` before merging). Unit, `test/find.test.ts`: the matching
7503
+ (case, Unicode folding, spacing, literal syntax, no overlaps, the limits, `keep`, ten times the most
7504
+ looked at), the shortcut rule, the host's checks (`parseFindResult`, `parseFindReport`,
7505
+ `checkFindQuery`), only the latest query (`FIND_LATEST`: at once when nothing is queued, a burst
7506
+ of fifty as two searches with the rest answered superseded, a clear dropping what waits, its
7507
+ splice reading a request once), the shell (the runtime only where declared, beside annotations' with the text
7508
+ index in both, a plain script, the built-ins taken before the message listener, no live call or
7509
+ replaceable prototype method in the find runtime or the text index and the layer inserted through
7510
+ the guarded methods (P129, P130), the same layer style, no Highlight API, the fallback leaving the
7511
+ request alone), `createHost` over a stand-in
7512
+ platform (asked once the frame ran, its own id only, the box clamped; `-32601`, malformed and no
7513
+ answer are `"unsupported"`; nothing without `find`; an empty query clears; a query too long
7514
+ rejects; the shortcut sent to every frame, `requested` only while taken and with the page's focus;
7515
+ `updated` only while a query is shown; a reload, a restart after a navigation away and other
7516
+ content forget the query, content continued keeps it; a query cleared before the frame ran
7517
+ answers nothing; a query waiting when its frame stops is `"unsupported"` and never sent to the
7518
+ next frame; of the queries asked while the frame loads only the latest is sent; a superseded
7519
+ answer is `"unsupported"`; a destroyed display answers `"unsupported"`), the React handle's scope
7520
+ (`findScopeOf`, `sameFindScope`: the same content again or continued, by value, versus another
7521
+ generation, content, document, config, viewer, source or version), and the bridge (an event, a
7522
+ refusal, the rate). `test/agreement.test.ts`: a case
7523
+ with `find`, and Raft's shape with it. `test/react-ssr.test.ts`: the handle's and props' types.
7524
+ Browser, `leak/find.spec.ts` (three engines): highlights in the closed layer, next and previous into
7525
+ view (a scrolling box too), the box, case, clear; a change found again and told; a page's own query
7526
+ message ignored; the shortcut the browser's until taken, then the host's, a page's own find keeping
7527
+ it; and the hostile page's `requested` while the person types in the host's composer (the control's
7528
+ probe, with its positive control: taken with the person in the frame).
7529
+
7530
+ **Revisit when** a host needs matches in open shadow roots or a page's own frames, the person's
7531
+ Escape or Cmd+G in the frame should reach the host's bar, a host searches as the person types and
7532
+ wants the page not to see each keystroke (debounce in the host first), or engines give a frame a
7533
+ highlight registry content can't reach.
package/docs/DESIGN.md CHANGED
@@ -990,6 +990,7 @@ for that to lapse and click with raw input.
990
990
  | Files: the version's own path in the CSP (P082) | `fileSetCspDirectives`: `<origin><base>` (tab) or `<origin>/__porthole/f/` (frame) in the seven loading directives; never `'self'` | `leak/served/files.spec.ts`: a page loads no other version's files; a way out past the base is blocked | `file-self` → those two cases (another version's data and module load; `%2e%2e` past the base reaches the server; all three) |
991
991
  | Files in a frame: access in the path (P083) | the ticket's answer is the entry; `/__porthole/f/<AES-GCM sealed session>/`; `history.replaceState` before anything loads; the host's check per file; an address opens on its own for an hour (then only the running page's own same-origin loads, till the session ends), renewed by the shell; reported as `./`, never whole | `test/files.test.ts` (sealed: no viewer or subject in it; another origin, a tampered or ended one: 401; revoked: 403; its hour, the page's own loads after it, renewal; redaction); `test/workers.test.ts` (workerd); every framed case of `leak/served/files.spec.ts` on WebKit (no cookie in frames), its reports never naming the address, its renewal under a moved clock | — |
992
992
  | Files: pages navigate within the set (P084, P098) | the guard lets a navigation to a page under `files.base` go, after `porthole/navigating`, and the page it opened says so as it arrives, each naming its version; the host takes the next load as that page, or the load the notice came after: a load no notice for the mounted version explained waits `LATE_NOTICE_MS` holding the frame (nothing it says reaches the display), then starts it again | `leak/served/files.spec.ts`: a link opens another page in the frame, the display goes on, also with the leaving page's notice dropped or every notice late; a non-page file, `/`, `/__porthole/d/…` never open; `test/pages-of-set.test.ts`: another version's notice or a hello first restarts at once, nothing is answered during the wait | `navigate-guard` → the three link cases, "opens nothing else" and the sealed-address reports case (all three; the last measured failing before P098 too) |
993
+ | A page's own nested frames, opt-in (P128) | `nestedFrames: "own"` (off by default): the shell keeps an iframe with `srcdoc` or whose `src` is under `files.base` (`OWN_FRAME`, through the platform's getters) and removes every other frame and plugin as before; a kept frame leaves before a change would point it elsewhere (P030's guard; the observer watches `src`/`srcdoc`); a set's page has `frame-src` its version's path, its files `frame-ancestors` its own origin and the app's; refused for url mode, nested pages, live widgets. Inside a child frame none of the shell's defenses run (accepted) | `4.own-external`, `.own-turned`, `.own-default` (opaque: a srcdoc child's scripts don't run there, measured); `leak/served/files.spec.ts` "a page's own frames": its file (with its shell), a srcdoc and a made frame run; another site, `/`, `/__porthole/d/…`, `../../`, plugins stay out; by default none runs; `test/shell.test.ts`, `test/files.test.ts`, `test/check.test.ts` | `own-frame-rule` → `4.own-external`, `4.own-turned`, the served "stays out of the tree"; `own-frame-rule,own-frame-src` → that and "loads nothing" (the page's `frame-src`, the second wall); `frame-guard,sync-guard` → `4.own-external`, `4.own-turned`, `4.own-default` |
993
994
  | A page on a tab of its own (P099) | every served page's CSP header carries the frame's sandbox (`sandbox allow-scripts allow-same-origin`, `servedSandboxDirective`) and its `Permissions-Policy` denies what the frame's `allow` doesn't grant (`servedPermissionsPolicy`); on a tab the shell answers `window.open` with null (but `_self`), refuses picture-in-picture windows, devices, location, full screen, passkeys, the share sheet, payments (Apple Pay too) and a video's full screen; its navigation guard (P079) stops the page navigating itself, and `navigation.navigate()` and a tab's `open(…, "_self")` ask its rule before they start (the address read once, through the platform's own functions); a tab's links are followed by the shell as clicked (cancelled in its first listener, found through the composed path, closed shadow roots made open to it), never by the browser; a lock that can't take says so (`data-porthole-unfixed`, a report to the host) | `test/server.test.ts`, `test/files.test.ts`, `test/policy.test.ts`, `test/agreement.test.ts` (every served page, in a frame, on a tab, without fetch metadata; never a script, a url-mode app or Porthole's own pages; the header held to the frame's `allow`); served conformance `served.domain.tab-window-open`, `.tab-escapes` (a target=_blank link clicked past the shell, forms, a blob download, `prompt`), `.tab-opener` (its opener sent elsewhere), `.tab-navigation` (a `blob:` document of its own and an outside site, each from a fresh tab by `location`, `assign`, `replace`, a link past the shell, `navigation.navigate()` and `open(…, "_self")`, the last two given a two-faced address too, a link and `navigate()` with the built-ins lying), `.tab-links` (a link's `href`, `target` or `download` changed after the shell read it, a link in an open or closed shadow root; a fragment link still jumps, a cancelled one goes nowhere), `.tab-devices` (location, camera and microphone granted by the browser, full screen after a click), `.tab-prompts` (a passkey, a payment to a canary method, a share, a video's full screen: each refused at once); `test/permissions-policy.test.ts` (the denied list against Chromium's, checked in); `leak/served/tab.spec.ts`: those five, a file set's page on a tab (its module, fetch and links to its own pages work; nothing else opens), a frame's sealed address opened on a tab | `tab-sandbox` → tab-escapes, tab-opener, the file set's and the sealed address's cases (all three); `tab-sandbox,window-open` → those and tab-window-open (all three; picture-in-picture opens on Chromium and Firefox, absent on WebKit); `permissions-policy,device-locks` → tab-devices (all three), tab-prompts (Chromium, Firefox; WebKit refused each at once here either way); `device-locks` alone → tab-devices on WebKit and Firefox (they don't apply the header; Chromium holds), tab-prompts on Firefox; `window-open` or `permissions-policy` alone → none; `navigate-guard` → tab-navigation, tab-links (all three; P096 measured the second); `navigate-ask` (the rule asked first, alone) → tab-navigation and tab-links on WebKit (Chromium and Firefox hold by the event); `link-rule` (the browser follows links again) → tab-links and tab-navigation on WebKit; `scripts/controls.ts` |
994
995
  | The runtime: a page's declaration (P086) | the bridge refuses a capability the page didn't declare (`undeclared`), on `porthole/call` and 0.6's requests alike, before any handler | `test/runtime.test.ts`; `leak/served/runtime.spec.ts`: "an undeclared capability: null from use, refused when sent anyway, its handler never asked" | `runtime-declaration` → that case (all three) |
995
996
  | The runtime: levels (P087) | each method's least level against the host's viewer, before any handler | `test/runtime.test.ts`, `test/assets.test.ts` (the grant's level to the bridge); `leak/served/runtime.spec.ts`: "a method above the viewer's level: forbidden, its handler never asked" | `runtime-level` → that case, and P094's "a read above the viewer's level: a result the host pushed is refused as a cold read is", whose reads stand on it (all three) |
@@ -1180,6 +1181,38 @@ a selection away from a page that patched `Selection.prototype.removeAllRanges`,
1180
1181
  nothing back, leaves marks and drafts found, and the same words selected again are told
1181
1182
  (`clear-selection`).
1182
1183
 
1184
+ ### Find in page
1185
+
1186
+ A host's own find bar over a display (P131), where the config declares `find`:
1187
+
1188
+ - **Shell.** `FIND_RUNTIME` (`src/shell/find.ts`), spliced in as the annotation runtime is, before
1189
+ content runs. It finds a query (`porthole/find.query`, a request) in annotations' text index
1190
+ (`TEXT_INDEX`, `src/shell/text.ts`, shared), case-insensitive and loose about spacing
1191
+ (`FIND_MATCH`), only matches that are drawn, at most 1,000; draws them in a layer of its own (a
1192
+ closed shadow root, annotations' layer style), the current one apart, redrawn on scroll and
1193
+ resize and found again as the content changes (`porthole/find.updated`, at most once a second);
1194
+ brings the current one into view through its scrolling ancestors and the window; and, while the
1195
+ host says it draws its own bar (`porthole/find.handled`), cancels the browser's find on Cmd+F or
1196
+ Ctrl+F a page didn't take (`FIND_SHORTCUT`) and says `porthole/find.requested`. Like the guards
1197
+ (P129), it and the text index call only built-ins captured before content runs, through
1198
+ `callOf`; its layer goes in through the guarded insertion methods (P130,
1199
+ [insertion-entry-points.md](insertion-entry-points.md) § The shell's own layers).
1200
+ - **Host API.** `display.find.query(query, { direction, caseSensitive })` → `{ total, active,
1201
+ capped?, rect? }` or `"unsupported"` (no `find`, an older shell's `-32601`, a malformed answer, no
1202
+ answer in `FIND_LIMITS.timeoutMs`, a query superseded by a later one: the shell searches only the
1203
+ latest of a burst, `FIND_LATEST`), `clear()`, `takeShortcut(take)`; the query holds only for the
1204
+ content it was asked of (a new run or other content forgets it); events `findRequested`
1205
+ (only while taken, with the page's focus in the frame) and `findUpdated` (only while a query is
1206
+ shown), checked and rate-limited through the bridge. React: `onFindRequested`, `onFindUpdated`,
1207
+ and the handle's `find` and `clearFind`.
1208
+ - **Trust.** The page reads every query; what it says back is a find bar's numbers. Tests:
1209
+ `test/find.test.ts` (the matching and its limits, the shortcut rule, the checks, the shell's
1210
+ splice and built-ins, only the latest query, `createHost`'s requests, answers, forgetting and
1211
+ gates, the React handle's scope); `leak/find.spec.ts`
1212
+ on three engines (highlights, next and previous into view, a scrolling box, a change found again,
1213
+ the shortcut the host's only while taken and the page's own find keeping it, and a hostile page's
1214
+ `requested` while the person types in the host's composer dropped: `find-requested-focus`).
1215
+
1183
1216
  ## The shell runtime
1184
1217
 
1185
1218
  The runtime (`src/shell/runtime.ts`, plain ES2020, no build) runs first in every
@@ -1263,7 +1296,7 @@ how content behaves, each one line derived from the config (`manualLimits`, P064
1263
1296
  | `workers` | blob: Web Workers work; no service workers; no WebRTC | always | `14.workers`, `3.webrtc` |
1264
1297
  | `sound` | sound plays only from a click | always | `14.sound` |
1265
1298
  | `address` | about:srcdoc (opaque) or its own address with Porthole's ticket (domain) | always | `14.address`, `served.domain.address` |
1266
- | `shell` | document.write/open throw; nested frames removed; full screen and clipboard closed | always | `14.shell`, `4.document-write`, `4.light-dom` |
1299
+ | `shell` | document.write/open throw; nested frames removed (with `nestedFrames: "own"`, P128: but `srcdoc` ones and frames of the page's own files); full screen and clipboard closed | always | `14.shell`, `4.document-write`, `4.light-dom`, `4.own-external` |
1267
1300
  | `storage` (interactive topic) | per isolation; in domain mode reads and writes can throw: try/catch | always | `14.storage`, `served.domain.storage-scope` |
1268
1301
 
1269
1302
  Three more limits sit outside the list:
@@ -1422,10 +1455,12 @@ control the tables above name to the registry):
1422
1455
  |---------|----------|-----------------------|---------------|-----------------------------|
1423
1456
  | `connect-src` | `leak.spec.ts` | `[1.connect]`, `[14.silent]` | — | — |
1424
1457
  | `webrtc` | `leak.spec.ts` | `[3.webrtc]`, `[14.workers]` | — | — |
1425
- | `frame-guard` | `leak.spec.ts` | nothing | — | the synchronous guard drops what the observer would (`frame-guard,sync-guard`) |
1426
- | `attach-shadow` | `leak.spec.ts` | nothing | — | the synchronous guard reaches a closed shadow root's frames as they connect (`attach-shadow,sync-guard`) |
1458
+ | `frame-guard` | `leak.spec.ts` | nothing | — | the synchronous guard drops what the observer would, or refuses it at creation (P130) (`frame-guard,sync-guard`) |
1459
+ | `attach-shadow` | `leak.spec.ts` | nothing | — | the synchronous guard refuses the frame at creation (P130), and reaches a closed shadow root's frames as they connect (`attach-shadow,sync-guard`) |
1427
1460
  | `sync-guard` | `leak.spec.ts` | nothing | WebKit: `[8.preconnect]` | on Chromium and Firefox the observer removes what the synchronous guard would, and no preconnect opens even unsandboxed (measured) (`frame-guard,sync-guard`) |
1428
- | `frame-guard,sync-guard` | `leak.spec.ts` | `[4.light-dom]`, `[4.sync-realm]`, `[4.plugins]`, `[4.foreign-object]`, `[4.template-clone]`, `[7.base-plugins]`, `[14.shell]` | WebKit: `[8.preconnect]` | — |
1461
+ | `frame-guard,sync-guard` | `leak.spec.ts` | `[4.light-dom]`, `[4.sync-realm]`, `[4.plugins]`, `[4.foreign-object]`, `[4.template-clone]`, `[7.base-plugins]`, `[14.shell]`, `[4.own-external]`, `[4.own-turned]`, `[4.own-default]` | WebKit: `[8.preconnect]` | — |
1462
+ | `own-frame-rule` | `leak.spec.ts`, `served/files.spec.ts` | `[4.own-external]`, `[4.own-turned]`, `a page's own frames, opted in (P128): a frame of another site, of another path of its origin, or a plugin stays out of the tree` | — | — |
1463
+ | `own-frame-rule,own-frame-src` | `served/files.spec.ts` | `a page's own frames, opted in (P128): a frame of another site, of another path of its origin, or a plugin stays out of the tree`, `a page's own frames, opted in (P128): a frame of another site or of another path of its origin loads nothing` | — | — |
1429
1464
  | `attach-shadow,sync-guard` | `leak.spec.ts` | `[4.closed-shadow]`, `[4.shadow-nested]` | WebKit: `[8.preconnect]` | — |
1430
1465
  | `declarative-shadow` | `leak.spec.ts` | `[4.declarative-shadow]` | — | — |
1431
1466
  | `parser-entry-points` | `leak.spec.ts` | `[4.document-write]`, `[14.shell]` | — | — |
@@ -1511,6 +1546,7 @@ control the tables above name to the registry):
1511
1546
  | `blob-trusted` | `served/runtime.spec.ts` | `a script asset runs as code only if an admin uploaded it where uploads are the admins'` | — | — |
1512
1547
  | `blob-script,blob-trusted` | `served/runtime.spec.ts` | `a script asset runs as code only if an admin uploaded it where uploads are the admins'`, `scripts load from /_blob/ only where uploads are the admins' (a tab, its session)` | — | — |
1513
1548
  | `blob-inert` | `served/runtime.spec.ts` | `an asset opened on its own runs nothing, on a tab with the artifact's session` | — | — |
1549
+ | `find-requested-focus` | `find.spec.ts` | `a hostile page says the find shortcut was pressed while the person types in the host's composer: the host's find bar stays shut (P131)` | — | — |
1514
1550
 
1515
1551
  ## Milestones
1516
1552