@botiverse/porthole 0.10.0 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/dist/annotate/types.d.ts +18 -6
  2. package/dist/annotate/validate.d.ts +11 -1
  3. package/dist/annotate/validate.js +18 -1
  4. package/dist/bridge/bridge.d.ts +8 -1
  5. package/dist/bridge/bridge.js +7 -0
  6. package/dist/bridge/unseen.d.ts +8 -0
  7. package/dist/bridge/unseen.js +17 -0
  8. package/dist/check/files.d.ts +2 -0
  9. package/dist/check/files.js +71 -50
  10. package/dist/check/lint.d.ts +8 -1
  11. package/dist/check/lint.js +18 -0
  12. package/dist/check/markup.d.ts +7 -0
  13. package/dist/check/markup.js +49 -0
  14. package/dist/check/page-source.js +1 -1
  15. package/dist/check/scroll.d.ts +116 -0
  16. package/dist/check/scroll.js +1485 -0
  17. package/dist/config/capabilities.d.ts +16 -3
  18. package/dist/config/capabilities.js +1 -0
  19. package/dist/conformance/harness-source.js +1 -1
  20. package/dist/conformance/runtime.js +6 -0
  21. package/dist/guide/guide.js +1 -1
  22. package/dist/guide/runtime.js +2 -2
  23. package/dist/host/create-host.js +30 -3
  24. package/dist/host/types.d.ts +15 -0
  25. package/dist/index.d.ts +2 -1
  26. package/dist/index.js +1 -0
  27. package/dist/platform/focus-guard.d.ts +143 -0
  28. package/dist/platform/focus-guard.js +445 -0
  29. package/dist/platform/types.d.ts +18 -0
  30. package/dist/platform/web.js +22 -0
  31. package/dist/react/frame.d.ts +10 -1
  32. package/dist/react/frame.js +4 -0
  33. package/dist/runtime/requests.d.ts +5 -0
  34. package/dist/runtime/requests.js +41 -4
  35. package/dist/runtime/types.generated.js +1 -1
  36. package/dist/shell/annotate.d.ts +2 -1
  37. package/dist/shell/annotate.js +29 -12
  38. package/dist/shell/use.js +9 -1
  39. package/docs/ADOPTING.md +106 -5
  40. package/docs/ARCHITECTURE.md +2 -1
  41. package/docs/DECISIONS.md +741 -2
  42. package/docs/DESIGN.md +38 -9
  43. package/docs/THREAT_MODEL.md +146 -19
  44. package/package.json +1 -1
  45. package/src/annotate/types.ts +19 -6
  46. package/src/annotate/validate.ts +20 -1
  47. package/src/bridge/bridge.ts +17 -1
  48. package/src/bridge/unseen.ts +24 -0
  49. package/src/check/files.ts +72 -54
  50. package/src/check/lint.ts +24 -0
  51. package/src/check/markup.ts +53 -0
  52. package/src/check/scroll.ts +1825 -0
  53. package/src/config/capabilities.ts +16 -3
  54. package/src/conformance/runtime.ts +9 -0
  55. package/src/guide/guide.ts +1 -0
  56. package/src/guide/runtime.ts +2 -2
  57. package/src/host/create-host.ts +38 -3
  58. package/src/host/types.ts +13 -0
  59. package/src/index.ts +2 -0
  60. package/src/platform/focus-guard.ts +572 -0
  61. package/src/platform/types.ts +17 -0
  62. package/src/platform/web.ts +22 -0
  63. package/src/react/frame.tsx +12 -1
  64. package/src/runtime/requests.ts +50 -6
  65. package/src/runtime/types.generated.ts +1 -1
  66. package/src/shell/annotate.ts +29 -12
  67. package/src/shell/use.ts +9 -1
  68. package/types/runtime/v1/comments.d.ts +20 -6
package/docs/DECISIONS.md CHANGED
@@ -3033,7 +3033,7 @@ store); `test/runtime.test.ts` (the CSP sources; upload limits and names).
3033
3033
  the public suffix list (CORP becomes defense in depth), or a host needs assets shared across
3034
3034
  artifacts (`copy_from`: a new id in the destination).
3035
3035
 
3036
- ## P090 · 2026-10-18 · Comments from the page: the host's composer at the page's anchor, write-only · Accepted; amended by P091
3036
+ ## P090 · 2026-10-18 · Comments from the page: the host's composer at the page's anchor, write-only · Accepted; amended by P091, P108, P109
3037
3037
 
3038
3038
  **Decision.** `comments` is a built-in (P086) host function served by a handler: `open({ name,
3039
3039
  label?, quote? })` (a name the page chose, ≤ 256 characters, `slide-3`, `refs/a.md#L12`; a label ≤
@@ -4595,7 +4595,7 @@ second wall on a tab); a host needs a served page to open windows from a tab (th
4595
4595
  `'self'` default (it joins `FRAME_DENIED_FEATURES`); or WebKit and Firefox apply
4596
4596
  `Permissions-Policy` to these features (the shell's device locks become the second wall there too).
4597
4597
 
4598
- ## P104 · 2026-10-20 · Annotation markers: a number at an anchor, a click the host hears, marks that follow a scroll · Accepted; amended by P105
4598
+ ## P104 · 2026-10-20 · Annotation markers: a number at an anchor, a click the host hears, marks that follow a scroll · Accepted; amended by P105, P107
4599
4599
 
4600
4600
  A host that shows its comments beside an artifact page wants, at each comment's anchor in the page,
4601
4601
  a small marker (a bubble and how many comments are there) that scrolls with the content; a click on
@@ -4849,6 +4849,9 @@ P097's CI triggers. From the audit of 2026-10-19 (V01, V02).
4849
4849
  registry), each uploading its reports and `verdicts.json`; the `controls` job puts them
4850
4850
  together (`--summary`) and fails if any control failed or never ran on an engine. A job's
4851
4851
  name changed, so release.yml's REQUIRED_CI_JOBS lists the twelve shards and `controls`.
4852
+ Later (0.11.0, #46): a shard runs about 42 minutes, but a browser install that usually takes
4853
+ 20 seconds took 21 (apt mirrors) and the 60-minute shard was cancelled with every control it
4854
+ reached passing. A shard now allows 90 minutes, and its install fails on its own past 25.
4852
4855
 
4853
4856
  **Why.** PRINCIPLE 6: a wall never seen to fail proves nothing, and a check that says a wall was
4854
4857
  seen to fail when its run never happened is worse than no check. CI's "every control" was 7 of
@@ -5104,3 +5107,739 @@ default, gate or policy loosens.
5104
5107
  none`), a host shows right-to-left text (the gutter is on the right), a host needs to place
5105
5108
  markers itself (then it draws them from `anchored`), an engine changes what gives a page
5106
5109
  activation, or MCP Apps defines annotations.
5110
+
5111
+ ## P106 · 2026-10-23 · A page held to one screen by its own styles is warned before it is published · Accepted; amended by P110
5112
+
5113
+ From Raft's triage of its Artifacts (task #71): agents' first versions of high-fidelity mockups,
5114
+ bundled from an app's own code, carry the app shell's global styles, `html, body { height: 100%;
5115
+ overflow: hidden }` and `#root { position: fixed; height: 100dvh; overflow: hidden }`, right for
5116
+ the app and wrong for a long page in a frame: it doesn't scroll. 2 of 50 artifacts on the server
5117
+ had it (the first version broken, the second fixing it by overriding the styles); one also had an
5118
+ inner box take the wheel. Nothing told the agent: the manual spoke only of sideways overflow, and
5119
+ `admitFiles` didn't look.
5120
+
5121
+ **Decision.**
5122
+ 1. **`scroll-lock`, a warning** in `lintContent` (so `admitContent`) and `lintFiles` (so
5123
+ `admitFiles`), from `src/check/scroll.ts`: a cascade, read from the text, of the few
5124
+ properties that matter (overflow, height, max-height, position, top and bottom, with their
5125
+ shorthands) over the three elements that hold a document: html, body, and the body's one
5126
+ element of content (the root: `#root`, `#app`, a lone `div`; none where body has two). It
5127
+ warns where one of them holds the page and nothing below body scrolls itself:
5128
+ - html with overflow-y hidden or clip;
5129
+ - body with overflow-y hidden or clip, where html's overflow is visible or body is one screen;
5130
+ - the root with overflow-y hidden or clip, one screen tall;
5131
+ - any of them `position: fixed`, one screen tall.
5132
+ Nothing below body scrolls itself: no element in the page's own markup below body has
5133
+ `overflow` or `overflow-y` auto or scroll, by its `style=""`, by a Tailwind class (where
5134
+ Tailwind is loaded), or by a rule the check reads whose selector matches it (with the selectors
5135
+ the check can match; one it can't read, or that matches nothing in the markup, doesn't count).
5136
+ The root itself isn't such an element, by its `style=""`, its classes or a rule: it is in the
5137
+ cascade, so its own values decide. One screen tall with overflow-y auto or scroll, it scrolls
5138
+ the page (no warning); without a height it grows with what it holds and has nothing to scroll,
5139
+ so `html, body { height: 100%; overflow: hidden } #root { overflow-y: auto }`, or the same
5140
+ with `<div id="root" style="overflow: auto">`, is held. A root that scrolls in a height the
5141
+ check can't read is its own box, as an inner one is (no warning): under a flex or grid body
5142
+ (its `display`, or Tailwind's `flex`, `grid`; the root's height is the layout's: `flex-1`), or
5143
+ with a height of another shape (a length, `min()`, `var()`, a `calc()` other than below, an
5144
+ arbitrary `h-[…]`), where body itself is one screen tall. It is held where its height is the
5145
+ content's (unset, `auto`, `fit-content`, or 100% of a body that is) under a block body, and
5146
+ wherever body isn't one screen tall (a body that grows with the page holds a flex column that
5147
+ does too: `html { height: 100%; overflow: hidden } body { display: flex; flex-direction:
5148
+ column; overflow: hidden } #root { overflow: auto }` is held).
5149
+ Where one does, the page may scroll in that box (a dashboard's `main { flex: 1; overflow-y:
5150
+ auto }`), and the text can't tell which box holds the content: no warning; the manual's line on
5151
+ the wheel says the rest. Matched against at most 2,000 elements, 32 deep, 256 selectors and a
5152
+ million steps (each selector's compound and element tried once).
5153
+ **A page its script draws** (body holds at most one element of content, with no text, and the
5154
+ page has a script: `<div id="root"></div>`) has nothing to match: it is warned, but said as a
5155
+ page that looks held: "The page looks held to one screen in its frame: … If it is meant to fit
5156
+ one screen, or a box its script draws scrolls the content, ignore this; otherwise let it scroll
5157
+ as a document: …". A page with its content in the markup is told "The page won't scroll in its
5158
+ frame: … Unless it is meant to fit one screen, let it scroll as a document: …".
5159
+ One screen: height or max-height (or `block-size`, `max-block-size`) `100vh` (`dvh`, `svh`,
5160
+ `lvh`) or `calc(100vh - 4rem)` (the whole less one positive length: px, rem, em, %, vh),
5161
+ `100%` or `calc(100% - 56px)` of a one-screen parent (html's 100% is
5162
+ the frame's; Tailwind's arbitrary `h-[calc(100vh-4rem)]` read as Tailwind writes it, with
5163
+ spaces around `-` and `+`) or of the frame where it is fixed or absolute, or fixed or absolute with both top
5164
+ and bottom set (`inset: 0`). Measured with Playwright's Chromium and Firefox (a 3,000 px
5165
+ page, a 400 px frame, the wheel): each of these stops it; `body { overflow: hidden }` alone
5166
+ does (the viewport takes body's overflow), as does `#root { position: fixed; inset: 0 }`
5167
+ without any overflow; `#root { overflow: hidden }` without a height, `#root { height: 100% }`
5168
+ under a body as tall as its content, `html, body { height: 100% }` alone, and
5169
+ `overflow-x: hidden` alone don't; a one-screen `#root { overflow: auto }` under a held body
5170
+ scrolls in the root. WebKit couldn't run on the box; nothing here is engine-specific CSS.
5171
+ Why the markup: an app's whole stylesheet, bundled into a page, has scroll boxes of its own (a
5172
+ list, a sidebar) that a page may never draw; counting every such rule would leave the app
5173
+ shell's page, the case this is for, unwarned.
5174
+ 2. **What it reads:** `<style>` and `<link rel=stylesheet>` in document order (not for print, not
5175
+ alternate), the linked sheets found in the version and their `@import`s, `style=""` on the
5176
+ three, rules whose selectors it can match (type, id, class, `*`, `:root`, `:only-child`,
5177
+ `:first-child`, descendant and child), and, where the page loads Tailwind (its CDN, or a
5178
+ Tailwind stylesheet), the utilities that hold a page (`h-screen`, `h-full`, `overflow-hidden`,
5179
+ `fixed`, `inset-0`…). Specificity, order, `!important` and cascade layers pick each value, so
5180
+ a later override, as the triage's second versions wrote, is seen. A layer's place is where it is
5181
+ first declared or its block opens, a sub-layer's rules below its parent's own, unlayered rules
5182
+ above all layers, reversed for `!important`; each value is picked once every sheet is read.
5183
+ **Bounded:** a page's stylesheets are each read once (a sheet linked or imported again is read
5184
+ where it first comes), at most 32 of them and 4 MiB in all, its own `<style>` elements
5185
+ included; past that, the rest isn't read (a later one that fits still is). Each
5186
+ is asked of the caller once per place it is named from. The check is then linear in what it
5187
+ reads: ten sheets each importing the next six times read ten sheets, not 6^10; each element
5188
+ keeps, per longhand, only each layer's winner so far (within a layer, and within `!important`
5189
+ or `style=""`, specificity and order decide; the layers' order picks among those once all is
5190
+ read), and the layers' tree is built in place, so a sheet of 80,000 declarations, or an `@layer`
5191
+ of 80,000 names, costs what sixteen of 5,000 do. A rule's selectors are read one at a time, and
5192
+ a scroll rule's kept only while there is room for them (a 2 MiB rule of 300,000 selectors ran
5193
+ out of memory at 128 MB before). An element's classes are a set, and a compound
5194
+ selector of more than 32 ids and classes matches nothing, so matching a compound against an
5195
+ element is bounded work, for html, body and the root as for the elements below body: the size
5196
+ of the sheets and the size of the page add, not multiply. A layer named more than 16 deep
5197
+ (`a.b.c…`, with the layers it is in) isn't read: its rules are dropped, but its first 16 parts
5198
+ are declared where it comes, as a browser declares them, so the layers' order holds. A page's
5199
+ sheets name at most 1,024 layers (each, parents included): a new one past them isn't declared
5200
+ and its rules aren't read, as a layer too deep (each layer kept every value its rules gave:
5201
+ 2 MiB of anonymous layers needed 128 MB of heap, of layers 15 parts deep 256 MB, in 8daa075
5202
+ too). A layer's name with the layers it is in (`a.b.c`) is at most 256 characters: a longer
5203
+ one isn't declared, nor its rules or the layers in it read (each anonymous layer in a 1.9 MB
5204
+ one copied its name: out of memory at 1,024 MB; in a 1 MB one, past 300 s).
5205
+ **A version's pages** (`lintFiles`, so `admitFiles` at publish): the rule reads the pages an
5206
+ agent opens first, the entry and then the others in path order, at most 8 in all, each as a
5207
+ page alone (its sheets read as it streams them: nothing parsed is kept from one page to the
5208
+ next). Only the pages' paths are kept for it, and the eight it checks are decoded again there
5209
+ (keeping every page's text took 96 MB for 500 pages of 192 KB). The 8 share one budget: 8 MiB of stylesheet read, every sheet each page reads (one two
5210
+ pages link is read for each) and each page's own `<style>`, and two million steps of matching
5211
+ scroll rules against markup. A page that would spend more than is left isn't checked, nor are
5212
+ any after it, the cheap ones too. Where pages aren't checked (past 8, or past the budget), one
5213
+ warning says how many: "N pages not checked for scroll lock: the check reads the entry and at
5214
+ most 7 other pages, within one budget. If one of them holds html, body or its root to one
5215
+ screen (…), let it scroll as a document." A page over its size isn't read at all (its error
5216
+ says so) and isn't counted. A warning, so an unchecked page is a warning missed, never a
5217
+ refusal. Bounded: whatever a version holds, the rule reads at most 8 pages and 8 MiB of
5218
+ sheets (the review's 500 pages sharing a 250 KB sheet took 13.8 s; 999 pages sharing a 1 MB one
5219
+ now read 8). Why not read each sheet once for the version and replay it for each page (the
5220
+ fourth review's answer): its parsed rules took about 100 bytes a byte, kept for the version (a
5221
+ page with one 2 MiB sheet ran out of memory at 128 MB; eight with their own took 1.5 GB), for
5222
+ an advisory rule whose pages that matter are the ones an agent opens.
5223
+ 3. **The warning says what to do:** what holds it, as the page wrote it, and the rule that undoes
5224
+ it under the page's own selectors (so it wins by coming later; `!important` where the hold
5225
+ was). The page's CSS goes into the agent's context, so only values of a known shape are echoed
5226
+ (lengths, percentages, viewport units, 0, auto, hidden, clip, fixed, static…; else the property
5227
+ and `…`), each declaration (its `!important` included) and selector at most 60 characters, and
5228
+ a selector with escapes, other than plain characters or longer is given as the element's own
5229
+ name: `#root` where the root's id is plain and `#id` at most 60 characters (the id is page text
5230
+ too), else `body > div`, or `body > *` for an element HTML doesn't have (a custom element's
5231
+ name is page text too). Where that name has less specificity than the selector it stands for
5232
+ (`body > div` for a 61-character `#id`, `#root` for `body > #\72 oot.x`), the fix is
5233
+ `!important`, or it couldn't win. So: `add html, body, #root { height: auto; overflow: visible; position: static } after
5234
+ those rules`, `take h-screen overflow-hidden off body's class`, or `take … out of html's style
5235
+ attribute`. In `lintFiles` it names the stylesheet and line the hold is in; a page's own
5236
+ `<style>` is reported once.
5237
+ 4. **The manual** (the Pages section, every kind): "It scrolls as a document: unless it's meant to
5238
+ fit one screen (a game, a canvas), don't hold html, body or the element that holds it all to one
5239
+ screen (height: 100% or 100vh with overflow: hidden, or
5240
+ position: fixed), or what's below the first screen can't be reached. A box that scrolls by
5241
+ itself takes the wheel while the pointer is over it: keep those to parts of the page (a wide
5242
+ table, a long list), never the whole of it."
5243
+
5244
+ **Why.** The agent learns it at publish, with the fix in the words of its own CSS, instead of from
5245
+ a person who can't scroll. A warning and not a refusal: some pages are one-screen apps on purpose,
5246
+ and a text read can't be sure.
5247
+
5248
+ **Rejected.**
5249
+ - Overflow hidden on html or body only together with a one-screen height (the triage's first
5250
+ rule): body's overflow alone stops the viewport, measured above; requiring the height misses
5251
+ `body { overflow: hidden }`, which is the common way to stop a page's scroll.
5252
+ - Measuring it in a browser (`checkPage` comparing the document's scroll height with the frame):
5253
+ publish has no browser; a later check may add it, and then the wheel too.
5254
+ - Warning on an inner one-screen scroll box: it does scroll, and an app's sidebar is one; the
5255
+ manual says it instead.
5256
+ - Warning where a box below body scrolls, unless it is shown to hold the page: from the text, a
5257
+ box's height in a flex or grid layout can't be told, and the review's three cases (a flex
5258
+ `main`, Tailwind's dashboard, a `style="overflow: auto"`) were false warnings.
5259
+ - Any rule that gives something below body a scroll box silencing the warning (the first answer
5260
+ to that review): an app's bundled stylesheet always has one, and its pages went unwarned.
5261
+
5262
+ **Limits.** Not read: rules under `@media` (but `all` and `screen`), `@supports`, `@container`;
5263
+ `:is()`, `:where()`, `:not()`, attributes and sibling combinators (they match nothing); nested
5264
+ rules; values through `var()` or `calc()`; `@import … layer()` beyond a name; a layer named more
5265
+ than 16 deep; a sheet's second link or import; what scripts set; stylesheets from another origin;
5266
+ sheets past the budget. Each can miss a hold or an override (a warning then wrong, never
5267
+ a refusal). A body with stray unclosed tags may be taken as having one child. A root that scrolls
5268
+ under a flex or grid body, or with a height the check can't read, is taken as its own scroll box:
5269
+ where it is in fact as tall as its content (a flex column's item without `flex: 1`, a `min()`
5270
+ that comes to its content), the hold is missed. In a version, pages past the entry and 7 more,
5271
+ or past the budget (8 MiB of sheets, two million match steps), aren't checked: a warning says
5272
+ how many. A page's layers past 1,024, and a layer's name past 256 characters, aren't read: that
5273
+ misses a hold in them, and it can warn wrongly too, where the hold is in a layer read and what
5274
+ undoes it is in one that isn't (`html { overflow: hidden }` in layer `p0`, and `html { overflow:
5275
+ visible }` in a new layer past the cap). Known, to follow: the app shell's fix names
5276
+ only html (`add html { … }`), and body's overflow, which the viewport takes once html's is
5277
+ visible, is said by a second warning after it; an `!important` hold inside a layer can't be
5278
+ undone by the unlayered `!important` the fix suggests (a layer's `!important` beats it), so the
5279
+ same advice comes again; `display: -webkit-box` isn't taken as flex.
5280
+
5281
+ **Tested.** `test/check.test.ts` (a page held to one screen): the app shell's exact styles (the
5282
+ message and line), body or html hidden alone, the root by height, max-height and `inset: 0`, a
5283
+ lone `div` by `:only-child`, `style=""`, `!important`, a more specific hold over a later override,
5284
+ Tailwind's CDN utilities on body and a build's class rules; none for overflow hidden on the root
5285
+ without a height, a one-screen height without overflow hidden, `overflow-x: hidden`, an inner
5286
+ element, two body children, a one-screen scroll box in a held body, 100% of a content-tall body;
5287
+ later overrides (same `<style>`, a later one, `style=""`, unlayered over layered, a comment),
5288
+ part of an override not enough; the limits (`@media`, `@supports`, `var()`, `:is()`); the
5289
+ manual's line in the artifact, fill and inline manuals; after review: none where something below
5290
+ body scrolls in the markup (a flex `main`, Tailwind's dashboard, `style="overflow: auto"`), held
5291
+ where it only scrolls sideways; an app bundle (the shell's styles and `.message-list { overflow-y:
5292
+ auto }`, an empty `#root`) warned in the hedged words, silent with a `.message-list` in its markup
5293
+ (also through `#root > section .message-list`), held where the markup has no match, the selector
5294
+ can't be read (`:hover`) or doesn't match (`section > .message-list`); the shell's styles over
5295
+ content in the markup said flatly; a hostile `top:` value and a long one not echoed, an escaped
5296
+ selector given as `#root`; after the second review: a scroll rule on the root without a height
5297
+ held (`#root { overflow-y: auto }`, `body > div { overflow: auto }`), one screen tall not, a box in
5298
+ the root or one of two in body still a scroll box; a plain id of 1,400 characters given as `body >
5299
+ div` (in the rule, the fix and the style attribute's fix; the message 346 characters, 3,128
5300
+ before), one of 59 as `#id`; a layer 100,000 deep not read (it overflowed the stack), 16 deep read;
5301
+ 80,000 declarations of body and an `@layer` of 80,000 names timed against sixteen times 5,000
5302
+ (under eight times as long, and each under 2 s: about 0.06 s and 0.14 s here, 36.6 s and 36.3 s
5303
+ before); after the third review: html, body, the root and 24 paragraphs with 4,000 classes each
5304
+ against two 2 MB `.a.a….b` rules, timed against sixteen sixteenths of both (under eight times,
5305
+ under 2 s: 0.1 s here, 178 s before; a sixteenth of both took 0.74 s, a quarter 11 s), a
5306
+ compound of 32 classes read and 33 not, a deep layer's parents declared where it comes (`theme`
5307
+ before `reset`), `!important` within the 60 characters, a custom element as `body > *`, the root
5308
+ by its own `style="overflow: auto"` and Tailwind class held without a height and not with
5309
+ `h-full`, by `block-size`, `max-block-size` and `calc(100vh - 56px)`, and a `style="overflow:
5310
+ auto"` below the root still a scroll box; after the fourth review: the four app shells (a
5311
+ Tailwind flex column with a `flex-1 overflow-y-auto` root, `display: flex` with an inline-styled
5312
+ root, Tailwind's grid with an `overflow-auto` main, an `h-[calc(100vh-4rem)]` root) and `min()`,
5313
+ a longer `calc()` and a length silent, the content's heights (none, `fit-content`, `auto`, a
5314
+ `display: block` body, 100% of a content-tall body) held; `calc()` read only as a whole less one
5315
+ positive length (`- 1px + 2000px`, `- -2000px`, `-10px`, `var()` not), `calc(100% - 4rem)` one
5316
+ screen under a one-screen body and not under a content-tall one; an `@import` into a layer 17
5317
+ deep declaring its first 16 parts; with no root, a body child's `style=""` still a scroll box;
5318
+ the fix `!important` where `#root` or `body > div` stands for a more specific selector, not where
5319
+ it is the selector; after the fifth review: `:root { overflow: hidden }` and `* { height: 100%;
5320
+ overflow: hidden }` held (the fix under their own selectors), `#\72 oot` as specific as `#root`
5321
+ so no `!important`, a flex column under a body that grows with the page held, and a root of
5322
+ `640px` under such a body too; a layer opened early with nothing for the page losing to a later one, a sub-layer below
5323
+ its parent's own rules either way round. `test/files.test.ts`: a linked sheet (its
5324
+ path and line), an `@import`ed one, each page by what it links, overrides across sheets in either
5325
+ order, print, alternate and missing sheets, and `admitFiles`'s note; ten sheets each importing the
5326
+ next six times (11 asks, well under 2 s; without the budget it ran past 60 s), a thousand links to
5327
+ one sheet (asked once), and a hold past 32 sheets unread; `lintFiles` on a page linking a 1.8 MB
5328
+ sheet of 230,000 declarations for body, under 3 s (0.2 s; 285 s before); 999 pages sharing a 1
5329
+ MB sheet (a version's most files) the entry and 7 more checked, in that order, and "991 pages
5330
+ not checked" said, under 10 s (41 s before) and under four times what 8 pages cost; eight
5331
+ pages or fewer, no note; eight pages, the first five linking a sheet just under 2 MiB, four
5332
+ checked and the fifth stopping the rest, the three cheap ones after it too ("4 pages not
5333
+ checked"); a page's own `<style>` charged (three of 3.5 MiB, the third not checked, nor a cheap
5334
+ one after); four pages each spending a page's million match steps, two checked; in a child
5335
+ process under a 48 MB heap, one page linking a 2 MiB sheet of each of six shapes: `.kN{top:0}`,
5336
+ `div{top:0}`, one rule's 300,000 selectors, anonymous layers, layers 15 parts deep and named
5337
+ layers of six declarations (each runs in 32 MB; the fourth review's code ran out at 128 MB on the
5338
+ first three, 8daa075 on the third; 11c422f on the last three at 64 MB, the layers 15 parts
5339
+ deep at 128 MB too), and 500
5340
+ pages of 192 KB as bytes (8 checked, "492 pages not checked"; 11c422f ran out at 96 MB). After
5341
+ the sixth review: 1,023 layers and a new one read, 1,024 and a new one not, `a.b` with one place
5342
+ left not, an unlayered rule and a layer already named still read, an `@import … layer(z)` past
5343
+ them not read; a layer's name of 256 characters read and of 257 not, nor one of 250 with a
5344
+ sub-layer of 6; an `@import … layer()` of 256 characters read and of 257 not; a statement's
5345
+ 257-character name taking no place among the 1,024; a 1.9 MB layer name with 5,500 anonymous layers in it, under the 48 MB heap and
5346
+ 5 s (out of memory at 1,024 MB before); a page's own `<style>` past
5347
+ 4 MiB not read and the next one read; Tailwind's `h-[calc(100vh-4rem)] overflow-hidden` on the
5348
+ root held, `h-[calc(100vh--4rem)]` not one screen. The manual's examples and the
5349
+ Vite + React fixture still lint clean.
5350
+
5351
+ **Revisit when** `checkPage` measures scrolling in a browser (then this can defer to it), a host's
5352
+ viewer scrolls the frame itself (a page then can't be held), or the misses above show up in
5353
+ published pages.
5354
+
5355
+ ## P107 · 2026-10-23 · Draft marks: a person's unposted comments, a dashed line and a hollow marker with no number · Accepted
5356
+
5357
+ A host adding batch comments (Raft Artifacts) shows a person's unsubmitted comments, drafts, in the
5358
+ page while they write more: at their anchors, in a style apart from posted comments, so that what
5359
+ others can already read and what only the author has written so far don't look alike. P104's marks
5360
+ have one look (a solid underline, a filled numbered marker, or neither), and P104 rejected a style
5361
+ knob per mark for want of a need. This is the need: one state, not a knob.
5362
+
5363
+ **Decision.**
5364
+ 1. **`AnnotationMark.kind?: "posted" | "draft"`**, absent meaning posted. `checkMarks` checks it
5365
+ as it checks the other fields: any other value (a typo, another case, a number, null) throws,
5366
+ naming the mark. A posted mark is sent to the frame as 0.10.0 sent it (no `kind`, whether the host
5367
+ said `"posted"` or nothing), so nothing changes for a host that has no drafts, nor for the page.
5368
+ 2. **A draft has a marker, never a number.** Its `count` is still checked (a bad one throws: it is
5369
+ the host's bug) and then dropped: the frame gets `{ id, anchor, kind: "draft" }`. The shell, too,
5370
+ draws no number for a draft and drops a mark of a kind it doesn't know. A draft gets a marker
5371
+ with or without a count (`hasMarker`), so everything P104 and P105 give a mark with a marker it
5372
+ gets the same way: `activated` taken for its id (within a gesture), `anchored` with the rest,
5373
+ following after a scroll or a change of the content (a host whose only markers are drafts is
5374
+ followed), placement in the gutter, compact where it must, stepping aside while picking.
5375
+ 3. **Drawn apart.** A draft's text mark is a dashed 2 px underline (3 px when active) over a
5376
+ lighter fill than a posted mark's; an element's is P104's quiet outline, dashed. Its marker is
5377
+ hollow: a near-white bubble with a 1 px dashed amber edge and the bubble glyph's outline
5378
+ (stroked, not filled), no number, the same size as a posted marker without one (so placement is
5379
+ unchanged). Hover and active lighten it, as they do a posted one. The colors are the layer's own,
5380
+ as P104's are (the page's styles don't reach the layer), and read on light and dark pages. No
5381
+ new motion (the focus flash is the posted mark's). The shell has no forced-colors or
5382
+ high-contrast styles of its own; in forced colors a draft's dashed borders survive where the
5383
+ posted marks' box-shadow underline doesn't, which is the shell's gap, not this change's.
5384
+
5385
+ **Trust.** Unchanged in kind from P104; one thing more the page learns.
5386
+ - *What content can now learn:* which of its marks are drafts, that the person viewing it is
5387
+ writing a comment there before they post it. Accepted, and said in THREAT_MODEL §7: the host sends
5388
+ drafts only to their author's own frame (Porthole can't tell whose a frame is: it is the host's
5389
+ duty, said in ADOPTING.md); the page is the thing being commented on and already sees where that
5390
+ person selects (`selected`) and points; and closed egress keeps what it learns off the network.
5391
+ Not off the channels the host opens: with the runtime's `db` writes and `user`, a page can read
5392
+ who is viewing (`user.get()`) and which shown marks are drafts, and store "viewer A is drafting
5393
+ at section 3" where its author and other viewers read it before A posts, then tie A's posted
5394
+ comment to A by its anchor and time; origins a config declares for egress (an MCP App's
5395
+ `connectDomains`, an `egress` the host opened; the `liveWidget` preset has none, P103) carry it
5396
+ out the same way (THREAT_MODEL S4, S5, §7). So a draft's existence, place and timing are the page's to
5397
+ pass on wherever the host gave it a way, and ADOPTING.md says: don't send drafts to such a page,
5398
+ or accept that its author and other viewers can learn of them. Nothing else of a draft reaches
5399
+ it: not its count (dropped, control `draft-count`; a host that sends a mark per draft tells how
5400
+ many there are), and its id is the host's, which ADOPTING.md already asks to say nothing.
5401
+ - *What content can fake:* `activated` for a draft's id, as for any mark with a marker (P104,
5402
+ P105): the host's view of a draft opens on it, guarded as THREAT_MODEL §6 says, and never acts
5403
+ (no submit, no discard one click away).
5404
+ - *A shared frame:* a host that sends drafts into a frame several people see tells that page, and
5405
+ whatever it draws for them, what one of them hasn't posted. That is the host's choice to not make.
5406
+
5407
+ **API.** `AnnotationMark.kind`, `AnnotationMarkKind` (exported), `hasMarker` (internal to the host
5408
+ and its checks). `annotations.show` throws on a bad `kind` (React's `annotations` reports it
5409
+ through `onHostError`, kind `"annotations"`). No other change: posted marks, every report, the
5410
+ bridge's rate are as they were. The shell is the content server's: one from before P107, given a
5411
+ draft by a newer host, draws it as a posted mark without a marker (it ignores `kind` and has no
5412
+ count), so a host upgrades its content server's Porthole before sending drafts.
5413
+
5414
+ **Tested.** `test/annotate.test.ts`: `checkMarks` keeps a draft's kind and drops its count, sends
5415
+ `"posted"` as nothing, still refuses a draft's bad count, and throws on `"Draft"`, `"note"`, `""`,
5416
+ `"draft "`, 1, null, true and `{}`; on `createHost` over a stand-in platform, `activated` taken for a
5417
+ draft with and without a count, and dropped for a posted mark without one. `leak/annotate.spec.ts`,
5418
+ on Chromium, WebKit and Firefox: the same anchors as posted marks (count 0, so neither has a number)
5419
+ and then as drafts look different in the frame and on the words; on Chromium, every draft's marker
5420
+ and line carry the draft's style and the markers have no number though one draft was given 7; a
5421
+ draft and a posted mark together, each drawn its way, the draft's text and element markers' clicks
5422
+ and the posted one's reported for their ids, none reaching the content's listeners (control
5423
+ `marker-click`, the shell's stop out, fails it too); the page,
5424
+ listening to its own window, reads a draft as `{ id, anchor, kind }` and posted marks as before
5425
+ (control `draft-count`, the count left on drafts, fails exactly that test); a raw `show` posted to
5426
+ the frame from the host's page, past `checkMarks`, with a draft given a count and a mark of kind
5427
+ `"note"`: the draft's marker is a bubble without a number (by its clicked box on every engine, by
5428
+ its words on Chromium) and the unknown kind is neither anchored nor drawn (control
5429
+ `draft-shell-checks`, the shell's two checks out, fails exactly that test); drafts alone followed
5430
+ once a scroll settles. P104's and P105's marker tests and controls pass as before.
5431
+
5432
+ **Threat it re-opens.** None of Porthole's: no default, gate or policy loosens. The page learns one
5433
+ fact more (a mark is a draft), bounded by the host's duty above.
5434
+
5435
+ **Rejected.**
5436
+ - A style per mark (colors, dashes) for the host to choose: P104's reason; two states cover the
5437
+ need, and a style the host picks is one more thing the page reads.
5438
+ - Hiding that a mark is a draft from the page (drawing drafts the host's own way, over the frame):
5439
+ the host can't place over the frame what moves with the frame's scroll without the frame's
5440
+ reports, which is what markers are; and the author's own frame is the one place a draft goes.
5441
+ - A draft's count drawn as a number: a hollow marker with a number reads as posted; a host with
5442
+ several drafts at an anchor gives them one mark or several, as it likes.
5443
+ - A dot without the glyph: the bubble's outline reads as "a comment, not yet", and keeps the size,
5444
+ so a draft's marker sits where a posted one would.
5445
+
5446
+ **Revisit when** a host needs drafts in a frame others see (then the host draws them itself), a
5447
+ third state is asked for (resolved, private: then a state list, still not a style knob), the
5448
+ shell gets forced-colors styles, or MCP Apps defines annotations.
5449
+
5450
+ ## P108 · 2026-10-26 · A comment's draft from the page: text the composer starts with, never posted by the page · Accepted; amended by P109
5451
+
5452
+ Amends P090. A page that asks for decisions (Raft's "decision sheet": a card per question with
5453
+ "Approve" and "Needs changes" buttons) opens the host's composer at the card with `comments.open`
5454
+ (P090), and the person then types the same words every time. xxchan asked for the button to carry
5455
+ them (#proj-workspace, 2026-10-26).
5456
+
5457
+ **Decision.**
5458
+ 1. **`comments.open(anchor, { draft })`.** `draft` is text the composer starts with: a string, not
5459
+ blank, at most 2,000 characters (the quote's limit), well-formed, and nothing a person can't see
5460
+ (P100's `unseen`: no zero-width, bidi or tag characters, no controls but a new line and a tab,
5461
+ so a checklist is fine). Anything else refuses the call as `invalid` before any handler, as a
5462
+ draft that isn't a string does: the shell sends it as the page gave it (options that aren't an
5463
+ object send `null`), read after the click's check, so a getter that throws is a rejection. The
5464
+ handler gets `{ anchor, draft }`.
5465
+ 2. **The rest is P090's.** From a gesture (`user-activation`, 30 a minute), view level; content
5466
+ hears only whether the composer opened; no method reads a thread; the page never posts. (The
5467
+ review of 0.12.0, P109: that gate was the host page's activation, which any gesture on it gives
5468
+ for 5 s, the person typing in the host's own composer included, not "a click" in the frame;
5469
+ P109 asks for the person in the calling frame.)
5470
+ 3. **The host's duties** (THREAT_MODEL §6 and §7, ADOPTING's example): show the draft whole, as the
5471
+ person's editable plain text, in its own composer; post it only on the person's Send; arm the
5472
+ composer as §6 arms a view the content brought: no press, and no Enter that sends, for 500 ms
5473
+ after it opens, Send not focused, beside the frame where the layout allows. Once posted the
5474
+ comment is the person's, mentions in it included: that is why they must see it all first.
5475
+ (P109 adds: an open never replaces what the person typed; the composer takes no focus, sends
5476
+ on no Enter until the person has acted in it, and says the text is the page's.)
5477
+ `defineRuntimeConformance` checks that the handler takes a draft (answers a boolean); that it
5478
+ never posts on its own can't be seen from a handler and is the host's.
5479
+
5480
+ **Why.** The comment is still the person's word: they see all of the text, can change or drop it,
5481
+ and post it themselves, as P090 requires. What the page saves them is typing.
5482
+ **Threats it opens, and their bounds.**
5483
+ - *Words the person didn't read:* a long draft hiding a line they wouldn't sign, or one an agent
5484
+ reading the comment later takes as their instruction. Bounded by visible text only (no hidden
5485
+ characters: the review found tags, U+200B and U+202E would otherwise pass), 2,000 characters, and
5486
+ the host showing it whole; reading it is the person's.
5487
+ - *Click-through:* before P108 a stray press on Send posted nothing; now the first click already
5488
+ loads a postable comment, and the page can place its button where Send will appear (the second
5489
+ click of a double click), or ask the person to press Enter. Bounded by the host's arming (above).
5490
+ **Rejected.** The page posting the comment (P090); a draft without a gesture; rich text or
5491
+ mentions resolved from the draft before posting (the host would be acting on the content's names);
5492
+ coercing what isn't text into text (`String(null)` is "null", which the person never meant).
5493
+ **Tested.** `test/runtime.test.ts` ("a draft (P108)": as given, a checklist too; past 2,000,
5494
+ blank, a number, null, a lone surrogate, tag characters, U+200B, U+202E, a bell: `invalid`, no
5495
+ handler); `leak/served/runtime.spec.ts` ("a comment's draft is the host's to check": from real
5496
+ clicks, a zero-width space, tags, 2,001 characters, a number and a string as options open nothing
5497
+ and reach no handler, a checklist reaches the composer; "comments are write-only": the draft beside
5498
+ the anchor). Negative control `comment-draft` (the draft taken as given) → the first case, every
5499
+ engine. `types/runtime/v1/check.ts` (the page-shaped call compiles); the runtime conformance's
5500
+ comments case sends a draft.
5501
+
5502
+ ## P109 · 2026-10-26 · After the review of 0.12.0's drafts: the keyboard given back, `comments.open` from the frame the person is in, a page's draft the person's to act on, stricter draft text · Accepted
5503
+
5504
+ Amends P090 and P108, and THREAT_MODEL §6 and §7. From the review of P107 and P108 at 0.12.0
5505
+ (2026-10-26: no P0, two P1s, three P2s, two P3s) and the review of the 0.11.0 and 0.12.0 releases
5506
+ (three documentation findings). Both P1s are about the person at the keyboard beside the frame,
5507
+ where P107 and P108 put the person's unposted words (a composer, its drafts) and tell the page when.
5508
+
5509
+ - **D0 (P1).** A framed page calls `focus()` on its own input whenever it likes, and on Chromium and
5510
+ WebKit needs no gesture for it: the keyboard leaves the host's focused composer, and the rest of
5511
+ what the person types goes to the page (measured on all three engines, the take at once, the
5512
+ page's input then holding everything after it). True of every display since 0.1, not only of
5513
+ drafts; nothing in THREAT_MODEL, ADOPTING or the suite named focus as a channel, and §7's "what
5514
+ they wrote stay[s] in the host's own UI" didn't hold.
5515
+ - **D1 (P1).** The `comments` gate was the host page's transient activation, which lasts 5 s after
5516
+ any gesture anywhere on it, typing in the host's own composer included; the shell's click check is
5517
+ the page's own and a raw `porthole/call` skips it (on Firefox, where the person typing in the host
5518
+ gives the frame activation too, the shell's own call passed). So a page opened the composer with
5519
+ its draft every 2 s while the person typed their own comment, never clicked; P108's and §7's "a
5520
+ click to open" was wrong, and nothing said what an open does to a composer that holds the
5521
+ person's words.
5522
+ - **D2–D4 (P2).** The host duties let a page-drafted composer take focus (keys typed for the page
5523
+ land in it) and send on Enter after 500 ms; P107's "no submit, no discard one click away" in a
5524
+ draft's view wasn't in the host docs; nothing asked the composer to say its text came from the
5525
+ page, while the page can draw the person's own draft markers.
5526
+ - **D5, D6 (P3).** The draft's "visible text" kept P100's joiners between shaped letters and in
5527
+ emoji (identical pixels on all three engines: about a bit per letter boundary), U+2028/2029
5528
+ (drawn as nothing on Firefox and WebKit), and blank-looking text; the anchor's label and quote
5529
+ beside the draft weren't checked for any of it.
5530
+ - **R-1–R-3 (docs).** P108's duty wording (R-1, as D1); 0.11.0 was never published (its release
5531
+ stopped at the CI gate) though CHANGELOG and THREAT_MODEL read as if it were, and 0.12.0's notes
5532
+ left out 0.11.0's (R-2); THREAT_MODEL §8 and its status line were stale (R-3).
5533
+
5534
+ **Measured** (served frames on Porthole's own `createHost`, Chromium 153, Firefox 155, WebKit 26.6
5535
+ through Playwright 1.63; WebKit with libraries extracted on a box that lacks them):
5536
+ - What the host's page sees of a move into a frame. Chromium and WebKit blur its window as it
5537
+ happens; at that blur a press on the frame (a click, a held press, a tap) leaves the frame element
5538
+ `:active`, and a page's own `focus()` doesn't; a Tab is the host's own keydown just before.
5539
+ Firefox doesn't blur the host's window and shows no `:active` (false even while a press is
5540
+ held); a focusout on the field wasn't seen in these runs (the review of the guard saw one):
5541
+ `document.activeElement` changes, read at the next animation frame, and the pointer over the
5542
+ frame (`:hover`, `pointerover` on the frame element, for a touch too) is all it shows of a press.
5543
+ - Transient activation lasts 5.04–5.10 s after a gesture on all three, and Playwright's
5544
+ `evaluate` in a frame is a gesture there on all three.
5545
+ - Focus given back inside that blur (synchronously or in a microtask) leaves Chromium and WebKit
5546
+ split: the host's `activeElement` is its text area, the keys still go to the frame (all 47 of a
5547
+ sentence). Given back in a task after, it holds; Firefox takes it back only from a frame that was
5548
+ blurred first.
5549
+ - Nothing the host sets on the frame stops its `focus()`: an `inert` frame took focus 60 times in
5550
+ 2 s on Chromium and Firefox. So focus given back can't stop a page trying again, and each try
5551
+ leaves it the keys typed until focus is back.
5552
+ - With the guard below, a page calling `focus()` every 700 ms, 250 ms, 30 ms or in a busy loop
5553
+ while the person types a 47-character sentence 60 ms a key into the host's text area (one run
5554
+ each, on a loaded box): the composer kept every key on Chromium and WebKit and all but one in one
5555
+ of four runs on Firefox, and the display was stopped after three tries; without it the page got
5556
+ every key after its first try. Each try the guard undoes leaves the page the keys typed until
5557
+ focus is back, which is why it stops a page that keeps trying (point 1).
5558
+
5559
+ **Decision.**
5560
+ 1. **The focus guard** (`src/platform/focus-guard.ts`, in the web platform, so every `createHost`
5561
+ display and `PortholeView` has it, on by default with no option). When focus leaves one of the
5562
+ host page's text fields (a text area, a text-taking `<input>`, an editable region, inside open
5563
+ shadow roots too) for a display's frame, the move is the person's if:
5564
+ - the host moved it (`DisplayHandle.focus()`, new: a frame's `iframe.focus()` called by the host
5565
+ itself would be taken for the page's);
5566
+ - their last key on the page was Tab or Shift+Tab, within a second;
5567
+ - a press on the frame: where the engine tells the move as it happens (Chromium, WebKit), the
5568
+ frame element is `:active`; where it doesn't (Firefox), the pointer is over the frame and came
5569
+ over it after the text field got focus and after the person last typed on the page;
5570
+ - or a gesture the host's own events don't explain: the page has transient activation, and for
5571
+ longer than activation lasts (5 s) it saw no gesture of its own (a key, a press, a click, text
5572
+ typed) and the text field has had focus: the person pressed or activated something in a frame
5573
+ since (an assistive technology's activation moves no pointer and sends the host no key).
5574
+ Anything else is the page's: once the engine has finished the move, focus goes back to the text
5575
+ field (the frame blurred first), and the display hears `focusTaken` (`{ typing }`: a key on the
5576
+ page within the last second; React `onFocusTaken`). Three while the person types within 10 s,
5577
+ or five within 2 s, stop the display, as a frame that keeps navigating away is (P031): a
5578
+ `contentError`, "The content kept taking the keyboard from the page; it was stopped.", and
5579
+ `reload()` runs it again. A page that takes focus once on its own (an input it focuses on load)
5580
+ gets it taken back once, and isn't stopped.
5581
+ 2. **`comments` asks for the person in the calling frame** (`CapabilitySpec.inFrame`): its
5582
+ `user-activation` gate also needs the host page's focus in that frame (`Surface.focused()`),
5583
+ after the guard judged any move into it, so keys that reached the frame before focus went back
5584
+ count for nothing. A press in the frame or a Tab into it gives that focus (measured: a click on
5585
+ a button, on text or in a field puts the host's `activeElement` on the frame, on all three); the
5586
+ person typing in the host's UI, or a gesture in another display, doesn't. Refused as
5587
+ `no-user-activation`. The other gesture-gated functions keep the page's activation alone:
5588
+ `sendPrompt` and `callTool` are confirmed by the person, a copy shows its notice, a link opens a
5589
+ tab; none of them writes into the person's words.
5590
+ 3. **A page's draft is the person's to act on** (THREAT_MODEL §7 and ADOPTING, with code): an open
5591
+ never replaces, appends to or moves what the person typed or the place they chose (answer
5592
+ `false`, or show the page's words as a separate suggestion that takes no focus); a composer the
5593
+ page filled takes no focus when it opens and doesn't send on Enter until the person has focused
5594
+ or edited it themselves (Send is a click until then); it says the text is the page's ("Suggested
5595
+ by this page", drawn by the host outside the frame) until the person edits it, and never shows
5596
+ it as one of their own drafts (the host's own list of drafts is how a person finds theirs, not
5597
+ the frame's markers, which the page can draw too); and a view a frame's report opens, a draft's
5598
+ included, puts nothing one click away that posts, submits, resolves, deletes or discards.
5599
+ 4. **Stricter draft text** (`parseCommentRequest`): a draft is refused for any invisible character
5600
+ but a joiner or non-joiner with a letter or mark on each side (U+200C, U+200D: Persian's
5601
+ می‌خواهم, Hindi's क्‍ष, Malayalam's എന്‍റെ; in any script, since a person's text needs them
5602
+ wherever letters shape) and a variation selector after a pictograph or in a keycap (❤️, 1️⃣):
5603
+ so a joiner first or last, doubled, beside a space or punctuation, or in an emoji sequence
5604
+ (👩‍💻) is refused, where it shapes nothing and hides text or makes a blank-looking draft; a line or paragraph
5605
+ separator (U+2028, U+2029), blank-looking text (only spaces of any kind, blank lines and U+2800),
5606
+ more than 32 blanks in a row, or more than two blank lines in a row. The anchor's `label` and
5607
+ `quote` lose what a person can't see (P105's `withoutUnseen`, and U+2028/2029) and are refused if
5608
+ that leaves them blank: they are shown beside the draft, never posted as the person's words, so
5609
+ they are cleaned as P105 cleans an annotation's label rather than refused.
5610
+ 5. **The docs say what holds** (R-1–R-3): THREAT_MODEL §6 (what every host gets and must do about
5611
+ the keyboard; no action one click away in a draft's view), §7 (the keyboard, the composer's
5612
+ duties, the gate as it is), §8 (the 2026-10-19 review's decisions, all merged) and its status
5613
+ line; CHANGELOG marks 0.11.0 as never published, its changes shipped in 0.12.0, and carries its
5614
+ upgrade notes into the next version's; capabilities.ts says what `user-activation` is.
5615
+
5616
+ **Trust.** What holds, and what doesn't:
5617
+ - A page can still take the keyboard; what it gets is the keys typed until focus is back (none to
5618
+ one in a sentence, measured), and a page that keeps trying is stopped. On Firefox, which tells
5619
+ the host's page nothing of the move or of a press in the frame, the guard reads focus at each
5620
+ animation frame, so the keys typed in that frame go to the page; and a page can keep the
5621
+ keyboard while the pointer rests over its frame if it came over the frame after the person last
5622
+ typed on the page and after the text field got focus (a person who typed, moved the pointer over
5623
+ the frame, and types on without clicking). Accepted, and said in THREAT_MODEL §7.
5624
+ - A false take-back: a press on the frame on Firefox while the pointer has rested over it since
5625
+ before the text field got focus (a composer that opened on a selection in the frame), and an
5626
+ assistive technology's activation within 5 s of the person's own key or press on the page, are
5627
+ taken for the page's, and focus goes back to the text field; the next press once the pointer has
5628
+ left the frame and come back, a Tab, or an activation after those 5 s, is the person's. Firefox also
5629
+ focuses a frame's document but not its field on a press that follows typing in the host, with or
5630
+ without the guard (measured).
5631
+ - Moves between two frames, or into a frame from what isn't a text field, aren't judged: no text
5632
+ of the host's page goes with them (S7 covers a frame beside another).
5633
+ - A host with its own platform (a native web view) has no guard unless it implements `focused`,
5634
+ `onFocusTaken` and `focus` the same way; without `focused`, `comments` keeps the activation gate
5635
+ alone, as before.
5636
+
5637
+ **API.** `DisplayEvents.focusTaken` (`{ typing: boolean }`), `DisplayControls.focus()`,
5638
+ `PortholeFrameProps.onFocusTaken`; `Surface.focused?`, `onFocusTaken?`, `focus?` (the platform
5639
+ seam); `BridgeOptions.focused`; `CapabilitySpec.inFrame`. A draft or an anchor refused before is
5640
+ refused still; some accepted before are refused now (joiners, separators, blank runs), and a label
5641
+ or quote with invisible characters reaches the handler without them.
5642
+
5643
+ **Tested.** `test/focus-guard.test.ts`: `personMoved` per rule, per engine kind, the composer
5644
+ opened on a selection and the Tab window. `test/runtime.test.ts` (D5, D6): the review's payloads
5645
+ refused (a family emoji, a joiner first, last, doubled, beside a space or punctuation, U+2028,
5646
+ U+2029, a draft of U+2800, 1,900 no-break spaces, four blank lines), Persian, Hindi, Bengali and
5647
+ Malayalam with their joiners, ❤️, 1️⃣, 👍🏽 and a checklist pass; a label with a
5648
+ right-to-left override and tags, and a quote with a zero-width space, reach the handler without
5649
+ them, and one with nothing visible left is refused. `leak/served/runtime.spec.ts`, Chromium,
5650
+ WebKit and Firefox: "a page that takes the keyboard while the person types in the host's
5651
+ composer gets a key or two at most, and is stopped" (the pointer resting over the frame, the
5652
+ composer focused by the host as on `selected`, the page's `focus()` every 500 ms); "the person's
5653
+ own moves into the frame keep the keyboard" (a press on its field after typing in the composer, a
5654
+ Tab, an activation in the frame with no host event 5.5 s after the composer's last gesture);
5655
+ "comments.open while the person types in the host's composer reaches no handler, by the page's own
5656
+ call or the shell's; from a press in the frame it does"; "a page that takes the keyboard back on
5657
+ its own blur keeps none of it" (GK-1, below). Negative controls `focus-guard` (every move taken for
5658
+ the person's) → its two probes, and `comments-in-frame` (the focus check out) → its probe, every
5659
+ engine; `focus-guard-watch` (the watch after a take-back out) → the blur probe on Firefox.
5660
+
5661
+ A joiner between two letters that shapes nothing draws as nothing (the review's Devanagari and
5662
+ Arabic payloads, about a bit per letter boundary): accepted, as P100 accepts it, because refusing
5663
+ it refuses Persian and the Indic scripts' ordinary text (the coordinator's call after the first
5664
+ cut refused all joiners). A Malayalam word that ends in an old-style chillu (a virama and U+200D
5665
+ before a space) is refused; the atomic chillus (U+0D7A–U+0D7F) pass.
5666
+
5667
+ **Threat it re-opens.** None: no default, gate or policy loosens. A draft, a label or a quote
5668
+ refused before is refused still.
5669
+
5670
+ **Rejected.**
5671
+ - Making the frame `inert` while the person types (or after a take-back): it doesn't stop a
5672
+ cross-origin frame's `focus()` (measured), and it hides the frame from assistive technology.
5673
+ - Giving focus back inside the blur: Chromium and WebKit then show the text area focused while
5674
+ the keys go to the frame (measured), worse than no guard, since the host believes it.
5675
+ - The pointer over the frame as a press on every engine: the composer that opens on a selection
5676
+ has the pointer resting there, which is the case D0 is about; on Chromium and WebKit `:active`
5677
+ says more, and only Firefox, which says nothing else, falls back to it.
5678
+ - The focus check on every gesture gate: the others don't write into the person's words (above),
5679
+ and pages that call them from a gesture the host's page had (Playwright's evaluate in tests, a
5680
+ host button that forwards a click) would change behavior for no closed threat.
5681
+ - Refusing every joiner in a draft (the first cut): it refused Persian and the Indic scripts'
5682
+ ordinary text; P100's list of shaping scripts instead: any letters may need them, and the
5683
+ hiding needs a place where nothing shapes (a space, punctuation, an edge, a run), which is
5684
+ refused. Stripping rather than refusing: a draft is the page's words in the person's name,
5685
+ which Porthole refuses rather than rewrites (P100); a label and a quote are shown, never
5686
+ posted, so they are cleaned (P105).
5687
+
5688
+ **After the review of the guard** (2026-10-26, GK-1, P1 on Firefox; Chromium and WebKit held
5689
+ against every strategy tried). A page that only takes focus back on its own blur
5690
+ (`field.onblur = () => field.focus()`, no timer, no gesture) beat the guard on Firefox: 38 of 38
5691
+ keys of a sentence reached the frame, `focusTaken` fired once, the display was never stopped, and
5692
+ `comments.open` reached the handler 10 to 13 times. The take-back's `frame.blur()` fires the page's
5693
+ blur, whose `focus()` left Firefox's focus on `<body>`; the next look then took `<body>` for where
5694
+ focus was and stopped looking (it looked only while a text field had focus); and the person's keys
5695
+ went to the frame, so the page saw no typing to count. Now:
5696
+ - **The guard keeps watching after each take-back** (each animation frame, `HELD_MS` 300 ms): focus
5697
+ found in the frame again, or on nothing, is a take-back that failed (after `GIVE_BACK_MS`, 100 ms,
5698
+ for one that hasn't landed yet; at once for one taken again after it landed), given back again
5699
+ and counted as `failed`; the watch ends once focus has stayed in the field, the person presses
5700
+ the host's page or puts focus somewhere of theirs, or the frame presses through as the person's.
5701
+ A move into a text field from a frame is watched the same way, and focus going from a frame to
5702
+ nothing just after the person pressed a text field is taken back to it (on Firefox, a page with a
5703
+ gesture of the person's that fights back leaves focus there; the keys would be lost).
5704
+ - **The guard looks at each animation frame while any frame is guarded**, not only while a text
5705
+ field has focus, so it knows where focus is when it next moves (one read of the focused element a
5706
+ frame), and looks at once after a focusout.
5707
+ - **The stop counts a failed take-back like one made while the person typed**: three of either
5708
+ within 10 s, or five within 2 s. A person's own move never fails a take-back.
5709
+ - **`focused()` asks for the person's own move into the frame**: a frame that took focus when
5710
+ nothing of the host's had it (no press, Tab or unexplained gesture) holds it, but isn't the
5711
+ person's for a gesture gate; and it is false for 1 s after a press on the host's page that came
5712
+ after focus went into the frame (the press gives the page activation before focus leaves it).
5713
+ - **`focusField(field)`** (new export): the host's own move into one of its text fields, for a
5714
+ composer that opens focused. Firefox ignores a host's plain `focus()` while a frame that has a
5715
+ gesture of the person's (the selection that opened the composer) holds focus and takes it back on
5716
+ its blur: no focus event, the keys go to the frame (measured; Chromium and WebKit move it).
5717
+ `focusField` blurs the frame first and has the guard watch that focus lands, a frame that keeps it
5718
+ failing take-backs toward its stop. A host that opens a composer with a plain `focus()` beside
5719
+ such a page on Firefox isn't covered (THREAT_MODEL §7).
5720
+ Measured, the review's probe (`blurOnly`, `blurPlusInterval`, `focusoutOnly`; the person types a
5721
+ 38-character sentence 70 ms a key): Firefox before, 38 of 38 keys to the frame, never stopped, 10
5722
+ opens; after, at most 1 key to the frame, four `focusTaken`, stopped, no open; Chromium and WebKit
5723
+ 0 keys, no open, before and after. A page that fights with a gesture of the person's, the person
5724
+ clicking the composer: Firefox before, every key lost to `<body>` and nothing counted; after, 1 key
5725
+ to the frame, stopped. The host opening its composer with `focusField` beside such a page after the
5726
+ person's selection in it: Firefox, all but one key in the composer, stopped after three failed
5727
+ take-backs; with a plain `focus()`, every key to the frame. The new probes and the honest ones
5728
+ passed three times in a row on all three engines. Rejected: a one-off check of the give-back, or a
5729
+ focusout listener alone (the review tried both: the page's re-take races any single check).
5730
+
5731
+ CI's slower Firefox then failed the blur probe twice ("got ''"). Reproduced on two cores, four
5732
+ workers, 20 runs: 2 failed. The trace: the page's own `focus()` came late (its timer, under load)
5733
+ and met the person's press on the composer; Firefox left focus on `<body>` (not the frame, not the
5734
+ composer), no move the guard judged, so every key was lost to `<body>`, none reached the frame,
5735
+ and nothing was counted. Now a press on a text field that leaves focus on nothing within 300 ms is
5736
+ taken into that field (a take-back the page failed if a frame had focus as the person pressed),
5737
+ and a display stopped mid-fight gives the field focus back if Firefox leaves it on nothing as the
5738
+ frame goes. The probes wait for states (the page armed once its own activation lapsed, the frame
5739
+ holding focus, the fight over) instead of times.
5740
+
5741
+ **Revisit when** an engine stops blurring the host's window on a move into a frame, or shows a
5742
+ press on the frame without `:active`, or Firefox starts doing either (the guard then judges every
5743
+ engine alike); browsers give the embedder a way to stop a frame's `focus()` (Permissions Policy's
5744
+ `focus-without-user-activation`, Chromium-only and experimental today); a host needs drafts in a
5745
+ script whose joiners shape; or MCP Apps defines focus between a host and a view.
5746
+
5747
+ ## P110 · 2026-10-26 · After the audit of P106: the scroll-lock rule fails soft, reads only the sheets it may, and sees a fixed body · Accepted
5748
+
5749
+ Amends P106. The audit of 0.12.0 (2026-10-26, part "scroll") found no isolation surface in P106
5750
+ (text in, a string out, on the host's side) and five findings about what a page's text does to the
5751
+ call, and what it misses.
5752
+
5753
+ **Decision.**
5754
+ 1. **A CSS escape is read as CSS Syntax reads it** (S1). An escape of 0, a surrogate or past
5755
+ U+10FFFF (six hex digits reach U+FFFFFF) is U+FFFD. `String.fromCodePoint` threw on the last:
5756
+ one selector like `.\ffffff`, in a page, a linked sheet or a page past the entry, threw out of
5757
+ `lintContent`, `admitContent`, `lintFiles`, `admitFiles` and `checkPage`, and so failed the
5758
+ show or publish of a page browsers accept (0.10.0 had no such path).
5759
+ 2. **The rule fails soft.** It is advisory, so a throw inside it is that page not checked, never
5760
+ a failed lint: `scrollLock` catches it and says "The page wasn't checked for scroll lock: its
5761
+ styles couldn't be read. If it holds html, body or its root to one screen (…), let it scroll
5762
+ as a document.", a warning with the page's path and no line. The other pages of a version are
5763
+ still checked.
5764
+ 3. **Only the sheets the rule may read are asked for and decoded** (S2). A linked sheet is found
5765
+ with the fewest characters it may hold first (`LinkedSheet` gives `{ path, least, text() }`:
5766
+ a string's length; as bytes, a third of them less a BOM's, as UTF-8 takes at most 3 bytes a
5767
+ character), so `take` refuses one whose fewest characters are already past what's left (32
5768
+ sheets, a page's 4 MiB, the version's 8 MiB) before its text is decoded; once a page has read
5769
+ 32 sheets or 4 MiB, or the version's budget is spent, no sheet more is asked for. Otherwise it
5770
+ is decoded (as bytes, at most the 6 MiB that hold its first 2 MiB of characters), cut to 2 MiB
5771
+ of characters, and charged what it holds, or dropped if that doesn't fit. The caps count
5772
+ characters, as they did, whether the host gives strings or bytes: the first cut of this
5773
+ charged and cut a sheet given as bytes by its bytes, and the re-review showed that reads less
5774
+ in a way that also warns wrongly (an override past 2 MiB of a non-ASCII sheet's bytes, or in a
5775
+ sheet past the page's 4 MiB of them, went unread, and the hold before it was warned; as
5776
+ strings, the same version was silent). `lintFiles` keeps no decoded sheet past its read (it
5777
+ kept every one for the set).
5778
+ Measured with the audit's shape (one page linking 400 sheets of 240 KB, each with one CJK
5779
+ character, as bytes, 96 MB; node 24, arm64): before, out of memory under a 64 MB heap, and with
5780
+ 2 GB 209 MB of heap in use after the call, 445 MB peak RSS, 922 decodes of 198 M characters;
5781
+ after, it runs under a 32 MB heap, 28 MB in use after the call under 64 MB, 259-269 MB peak
5782
+ RSS (220-237 MB with the page linking none), 539 decodes of 104 M characters (522 and 100 M linking
5783
+ none: the rest is the 17 sheets that fit 4 MiB).
5784
+ 4. **A fixed body holds the page whatever its height** (S3), and **body's own overflow is the
5785
+ viewport's where html's is visible**. A fixed box adds nothing to what the frame scrolls, so
5786
+ `body { position: fixed; top: 0; left: 0; right: 0 }` (the scroll-lock libraries' way, as
5787
+ static CSS) holds it, as does `body { position: fixed; inset: 0; overflow: auto }` with html's
5788
+ overflow visible: the viewport takes body's `auto`, and body itself doesn't scroll. Both are
5789
+ warned now ("body (position: fixed) holds it to one screen …: add body { position: static }
5790
+ after those rules"). Where html's overflow isn't visible, body's own overflow decides, as
5791
+ before: `html { overflow: hidden } body { position: fixed; inset: 0; overflow: auto }`
5792
+ scrolls in body, and isn't warned. Measured on Chromium, Firefox and WebKit (WPE, with the
5793
+ audit's extracted libraries; a cross-origin 600x400 frame, a 3,050 px page, twelve wheel
5794
+ steps): both held on all three; with html hidden, and with `top: 0; height: 100%; overflow:
5795
+ auto` under html hidden, the end is reached on all three, and the rule is silent.
5796
+ 5. **The quirks-mode case is not one in Porthole** (S4). The audit's false warning,
5797
+ `html { overflow: hidden } body { height: 100%; overflow: auto }` with no doctype, scrolls
5798
+ when the page is its own document in quirks mode (body's 100% is then the frame's). Porthole
5799
+ never shows it so: every page, a version's files included, is rendered into the shell's
5800
+ `<!doctype html>` document (its head and body imported, `renderDocument`), which stays in
5801
+ standards mode. The same page rendered that way is held on all three engines (compatMode
5802
+ `CSS1Compat`), so the warning is right there, and the doctype is rightly not read.
5803
+ 6. **Not html's `style=""`** (the re-review, from P106). The shell imports a page's html
5804
+ attributes but `style` (`renderDocument`), so `<html style="height: 100%; overflow: hidden">`
5805
+ never applies in Porthole's frame: such a page scrolls on Chromium, Firefox and WebKit as the
5806
+ shell renders it (held only as a raw document). The rule warned it, and told the agent to edit
5807
+ the attribute, which would change nothing; it no longer reads it. Body's and the root's
5808
+ `style=""` are imported, and still read.
5809
+ 7. **The budget test has the minute its neighbours have** (S5), as do the two timing tests in
5810
+ `check.test.ts` (one took 5.5 s, past the default 5 s, at a load of 23): their own bounds are
5811
+ what they check.
5812
+
5813
+ **Why.** P106's rule is advice: whatever a page holds, it should cost what P106 says it costs and
5814
+ never stop a show or a publish. The fixed body is the one hold the audit found that every engine
5815
+ agrees on and that has no reading other than "held".
5816
+
5817
+ **Rejected.**
5818
+ - *The root fixed without a height as held too* (the audit's `#root { position: fixed; top: 0;
5819
+ width: 100% }`, held on all three engines): a card centered on the screen, `#root { position:
5820
+ fixed; top: 50%; left: 50%; transform: … }`, is the same shape and meant to fit; it would be
5821
+ warned for nothing. Nor html fixed: not measured, and not seen in pages. Both stay misses.
5822
+ - *Reading the doctype for quirks mode* (the audit's fix): the page is never in quirks mode in
5823
+ Porthole's frames (above); it would trade a right warning for a miss.
5824
+ - *A cache of decoded sheets for the version* (as before): a sheet two pages link is decoded for
5825
+ each now, which the version's 8 MiB already bounds; the cache held every linked sheet.
5826
+
5827
+ **Limits.** Added to P106's: the root or html fixed without a one-screen height; a fixed body
5828
+ without one, with its own `overflow: auto`, under an html of `overflow: auto` or `scroll` (body
5829
+ grows with what it holds, so likely nothing scrolls; taken as scrolling itself, not warned). Where a throw makes a page "not checked", the hold
5830
+ it may have is said only as that warning.
5831
+
5832
+ **Tested.** `test/check.test.ts` (P110): `\ffffff`, `\110000`, `\d800`, `\0` and `\10ffff` in a
5833
+ class and an id lint and admit; `\ffffff`, `\110000`, `\dfff` and `\0` read as U+FFFD (a
5834
+ `body.\ffffffx` rule holds a `<body class="�x">`); a fixed body with `top: 0` and no height warned (the message and
5835
+ the fix), with `inset: 0; overflow: auto` warned, neither under html hidden, a fixed root without
5836
+ a height not; html's `style="height: 100%; overflow: hidden"` not warned, body's
5837
+ `style="overflow: hidden"` warned. `test/files.test.ts`: one page linking 400 sheets asks for 32
5838
+ and decodes 32; of 240 KB each, decodes the 17 that fit 4 MiB, the rest asked for their fewest
5839
+ characters only; the re-review's two versions of megabytes of CJK CSS (an override past 2 MiB of a
5840
+ sheet's bytes, and one in a third sheet past 4 MiB of bytes) silent as strings and as bytes; a sheet finder
5841
+ that throws gives the "wasn't checked" warning; `admitFiles` with `\ffffff` in a linked sheet and
5842
+ `\110000` on a second page admits it, the hold after the escape found.
5843
+
5844
+ **Revisit when** a page's own document is ever shown outside the shell (then quirks mode is real),
5845
+ or an engine starts counting fixed boxes in what the viewport scrolls.