@botiverse/porthole 0.9.0 → 0.12.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 (65) hide show
  1. package/dist/annotate/types.d.ts +21 -7
  2. package/dist/annotate/validate.d.ts +18 -3
  3. package/dist/annotate/validate.js +29 -5
  4. package/dist/bridge/bridge.js +1 -51
  5. package/dist/bridge/unseen.d.ts +18 -0
  6. package/dist/bridge/unseen.js +71 -0
  7. package/dist/check/files.d.ts +2 -0
  8. package/dist/check/files.js +67 -50
  9. package/dist/check/lint.d.ts +8 -1
  10. package/dist/check/lint.js +18 -0
  11. package/dist/check/markup.d.ts +7 -0
  12. package/dist/check/markup.js +49 -0
  13. package/dist/check/page-source.js +1 -1
  14. package/dist/check/scroll.d.ts +100 -0
  15. package/dist/check/scroll.js +1429 -0
  16. package/dist/conformance/behavior.js +107 -68
  17. package/dist/conformance/clipboard.js +16 -14
  18. package/dist/conformance/harness-source.js +1 -1
  19. package/dist/conformance/limits.js +117 -64
  20. package/dist/conformance/probes.js +66 -49
  21. package/dist/conformance/runtime.js +6 -0
  22. package/dist/conformance/served.js +66 -63
  23. package/dist/guide/guide.js +1 -1
  24. package/dist/guide/runtime.js +2 -2
  25. package/dist/host/create-host.js +46 -4
  26. package/dist/index.d.ts +1 -1
  27. package/dist/platform/types.d.ts +4 -2
  28. package/dist/react/frame.d.ts +2 -1
  29. package/dist/runtime/requests.d.ts +5 -0
  30. package/dist/runtime/requests.js +16 -1
  31. package/dist/runtime/types.generated.js +1 -1
  32. package/dist/shell/annotate.d.ts +6 -3
  33. package/dist/shell/annotate.js +474 -104
  34. package/dist/shell/use.js +9 -1
  35. package/docs/ADOPTING.md +99 -1
  36. package/docs/ARCHITECTURE.md +2 -1
  37. package/docs/DECISIONS.md +764 -14
  38. package/docs/DESIGN.md +192 -42
  39. package/docs/THREAT_MODEL.md +109 -27
  40. package/package.json +1 -1
  41. package/src/annotate/types.ts +22 -7
  42. package/src/annotate/validate.ts +32 -6
  43. package/src/bridge/bridge.ts +1 -60
  44. package/src/bridge/unseen.ts +82 -0
  45. package/src/check/files.ts +68 -54
  46. package/src/check/lint.ts +24 -0
  47. package/src/check/markup.ts +53 -0
  48. package/src/check/scroll.ts +1757 -0
  49. package/src/conformance/behavior.ts +221 -69
  50. package/src/conformance/clipboard.ts +44 -14
  51. package/src/conformance/limits.ts +169 -76
  52. package/src/conformance/probes.ts +97 -49
  53. package/src/conformance/runtime.ts +9 -0
  54. package/src/conformance/served.ts +112 -63
  55. package/src/guide/guide.ts +1 -0
  56. package/src/guide/runtime.ts +2 -2
  57. package/src/host/create-host.ts +50 -4
  58. package/src/index.ts +1 -0
  59. package/src/platform/types.ts +4 -2
  60. package/src/react/frame.tsx +2 -1
  61. package/src/runtime/requests.ts +23 -1
  62. package/src/runtime/types.generated.ts +1 -1
  63. package/src/shell/annotate.ts +474 -104
  64. package/src/shell/use.ts +9 -1
  65. package/types/runtime/v1/comments.d.ts +14 -4
package/docs/DECISIONS.md CHANGED
@@ -1109,7 +1109,7 @@ clipboard is closed to them otherwise. Item 1 of 0.1.3.
1109
1109
  shows the text); writing from inside the frame (P051).
1110
1110
  **Revisit when** MCP Apps defines a clipboard request (then the adapter maps it).
1111
1111
 
1112
- ## P053 · 2026-10-11 · Annotations are mechanism: the host's comments, anchored in content it can't trust · Accepted; amended by P104
1112
+ ## P053 · 2026-10-11 · Annotations are mechanism: the host's comments, anchored in content it can't trust · Accepted; amended by P104, P105
1113
1113
 
1114
1114
  **Decision.** A new optional capability, `annotate`, declared by the host. It is for inline widgets
1115
1115
  and artifact pages, and for MCP Apps views where the host chooses. With it, the host can:
@@ -1149,6 +1149,11 @@ host therefore:
1149
1149
  What a frame reports is a UI hint, never a permission. It decides where a comment is drawn,
1150
1150
  never who may see or do anything.
1151
1151
 
1152
+ A pick's click never reaches the content's own handlers only while the content patches none of
1153
+ the built-ins the shell calls then (P105): content that replaces `Event.prototype`'s
1154
+ `stopImmediatePropagation` hears it. Nothing it learns so is more than what it could tell anyway
1155
+ (that the person clicked, and where).
1156
+
1152
1157
  **Measured** (`leak/annotate.spec.ts`, on Chromium, WebKit and Firefox):
1153
1158
  - picking, cancelling, selecting, and both together;
1154
1159
  - marks, focus and clear;
@@ -3028,7 +3033,7 @@ store); `test/runtime.test.ts` (the CSP sources; upload limits and names).
3028
3033
  the public suffix list (CORP becomes defense in depth), or a host needs assets shared across
3029
3034
  artifacts (`copy_from`: a new id in the destination).
3030
3035
 
3031
- ## 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
3032
3037
 
3033
3038
  **Decision.** `comments` is a built-in (P086) host function served by a handler: `open({ name,
3034
3039
  label?, quote? })` (a name the page chose, ≤ 256 characters, `slide-3`, `refs/a.md#L12`; a label ≤
@@ -4590,7 +4595,7 @@ second wall on a tab); a host needs a served page to open windows from a tab (th
4590
4595
  `'self'` default (it joins `FRAME_DENIED_FEATURES`); or WebKit and Firefox apply
4591
4596
  `Permissions-Policy` to these features (the shell's device locks become the second wall there too).
4592
4597
 
4593
- ## P104 · 2026-10-20 · Annotation markers: a number at an anchor, a click the host hears, marks that follow a scroll · Accepted
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
4594
4599
 
4595
4600
  A host that shows its comments beside an artifact page wants, at each comment's anchor in the page,
4596
4601
  a small marker (a bubble and how many comments are there) that scrolls with the content; a click on
@@ -4675,20 +4680,27 @@ outline plain and unclear on its own.
4675
4680
  - What content can fake: an `activated` report for any mark the host shows with a count, without
4676
4681
  a click, and with any `rect` inside its frame (point 8); and look-alike markers drawn by its own elements (which
4677
4682
  report nothing unless it fakes one), or elements laid over Porthole's markers. The host takes a
4678
- fake only for its own shown ids, at the bridge's rate. So `activated` opens the host's own view
4679
- of that mark, placed near the rect within the frame's box, and never acts (no resolve, delete,
4680
- approve or reply on it).
4683
+ fake only for its own shown ids, at the bridge's rate (and, since P105, only within a gesture).
4684
+ So `activated` opens the host's own view of that mark, placed near the rect within the frame's
4685
+ box, and never acts (no resolve, delete, approve or reply on it). After the review of P104
4686
+ (P105): content can time a fake to the person's own press in the content, under their pointer,
4687
+ so that view also takes no press for 500 ms after it appears or moves, ignores a press that
4688
+ began before that, opens beside the frame where the layout allows, and has no destructive
4689
+ action one click away (THREAT_MODEL §6).
4681
4690
  - What content can tell: that a marker was pressed, and roughly where, though it gets none of the
4682
4691
  press's events. The pointer leaving its own element names the layer (`relatedTarget`), the layer
4683
- matches `:hover` and `:active`, and the frame gets user activation. It can't act on the click or
4684
- cancel it.
4685
- - What content can do to the layer: not read or reach inside it (a closed shadow root), but hide,
4686
- shrink, move or cover it. Its inline `!important` style holds against the content's style
4687
- sheets, and is set again at each draw, but the content's scripts can rewrite it in between, lay
4688
- elements over it, or transform the document it sits in. A host can't rely on a marker being
4689
- seen.
4692
+ matches `:hover` and `:active`, and the frame gets user activation. Content that patches none of
4693
+ the built-ins can't act on the click or cancel it; content that does could, until P105 read the
4694
+ press through the platform's own functions (it can still cover the layer).
4695
+ - What content can do to the layer: hide, shrink, move or cover it, and (P105: by patching a
4696
+ built-in the shell's insertion guards call on the layer's nodes, `Element.prototype.matches`)
4697
+ reach inside the closed shadow root, read the markers and rewrite them; nothing there is secret.
4698
+ Its inline `!important` style holds against the content's style sheets, and is set again at
4699
+ each draw, but the content's scripts can rewrite it in between, lay elements over it, or
4700
+ transform the document it sits in. A host can't rely on a marker being seen.
4690
4701
  - The rate limit is shared: a page that floods reports can crowd out real ones; it could before.
4691
- An honest page's follow-ups take at most 60 a minute (point 5).
4702
+ An honest page's follow-ups take at most 60 a minute (point 5; P105: the selection's re-reports
4703
+ after a scroll were outside that clock, and are on it now).
4692
4704
 
4693
4705
  **Tested.** `test/annotate.test.ts`: a count's bounds (0 and 999 kept; -1, 1.5, 1,000, NaN,
4694
4706
  Infinity, a string, null refused), the `activated` report's shape, and on `createHost` over a
@@ -4743,3 +4755,741 @@ inside the frame (then a focus model
4743
4755
  the content can't steal, likely the host's own overlay), a bubble must follow during a scroll (a
4744
4756
  coarser report, or the host drawing markers itself from `anchored`), or MCP Apps defines
4745
4757
  annotations.
4758
+
4759
+ ## P096 · 2026-10-19 · The negative controls: one registry, every control run, and a run that proves nothing fails · Accepted
4760
+
4761
+ Amends P032 (what DESIGN.md records per control), P091's harness item (`scripts/controls.ts`) and
4762
+ P097's CI triggers. From the audit of 2026-10-19 (V01, V02).
4763
+
4764
+ **Decision**, by finding:
4765
+ 1. **V01: a control passes only on its probes' own failures.** The runner judged a control by the
4766
+ tests it found in Playwright's report and nothing else: it ignored the child's exit status,
4767
+ signal and spawn error and the report's own errors, so a run whose web server never started
4768
+ (`suites: []`) left nothing to check and passed; a skipped probe counted as failed; an engine
4769
+ asked for but absent from the report wasn't checked. The judgement is now a function of the
4770
+ child's whole result (`judge`, `leak/controls.ts`), and the script only runs and prints it.
4771
+ A spawn error, a signal, no JSON report, or any error in the report fails the control. Every
4772
+ engine asked must be in the report. Each test the control names must have failed by its own
4773
+ `expect` (Playwright's message carries the matcher's call): skipped (an `inapplicable` probe, a
4774
+ `test.skip`), never run, timed out, interrupted, or failed by anything else (a browser that
4775
+ didn't launch, a detached frame, a harness that threw) is no failure. Every other test of its
4776
+ specs must pass or be skipped as it always is. Then the exit status must be what the control
4777
+ implies (1 when it expects failures, 0 when it claims nothing fails), never simply 0, since a
4778
+ negative control's run exits 1 whether its probes failed or its server never started.
4779
+ `test/controls.test.ts` gives the judge synthetic reports (the audit's two: an empty report
4780
+ with a launch error, a skipped probe; and a missing engine, a timeout, a launch error as a
4781
+ probe's failure, a signal, no report, the wrong exit status): each fails. 264b12fa's runner,
4782
+ given the same reports by a fake Playwright, printed "as it should" and exited 0 for all three
4783
+ of the audit's cases.
4784
+ 2. **V02: one registry, every control, its probes per engine.** `CONTROLS` (`leak/controls.ts`) is
4785
+ every control the suite has: the specs it runs with and the tests it fails on each engine
4786
+ (`others: "fail"` where it takes out what every test stands on: `nonce`). It holds the single
4787
+ weakenings DESIGN.md says another wall covers (`frame-guard`, `attach-shadow`, `blob-script`,
4788
+ `self`, `sync-guard` off WebKit): each must fail nothing. The runner runs them all by default,
4789
+ and CI's controls job (one per engine, 90 minutes, its reports kept on failure) runs it.
4790
+ `test/controls.test.ts` holds the registry to `WEAKENINGS` (every weakening is run by a
4791
+ control, every control is made of weakenings), to the specs (each exists, and none is a spec
4792
+ the weakenings don't reach: `UNWEAKENED`, the kit's reference app, which runs Porthole in Node),
4793
+ to DESIGN.md (§ The negative controls is `controlsTable()` exactly, and every control the
4794
+ tables' "Negative control" columns name is in the registry), and to CI (the job runs
4795
+ `test:controls` with no names, on all three engines). A probe named by a control is every test
4796
+ whose title has it, so a control run with two specs of the same suite fails it in both.
4797
+ 3. **What running them all found** (0.7.0; Chromium 153, WebKit 26.6, Firefox 155). Every
4798
+ control's own probes fail on every engine; DESIGN.md's tables were older than the probes:
4799
+ - Probes added since that stand on an older wall, now named: `connect-src` → `14.silent`;
4800
+ `webrtc` → `14.workers`; `frame-guard,sync-guard` and `parser-entry-points` → `14.shell`;
4801
+ `sandbox` → `14.dialogs`, `14.windows`, and `14.print` (not WebKit: it prints nothing from a
4802
+ frame either way); `document-theme` → `14.theme-never`; `confirm-gate` → `14.windows`;
4803
+ `shell-gesture` → `12.copy-text`; `clipboard` → `14.shell` (WebKit, Firefox);
4804
+ `embedder-csp` → `5.host-origin`; every control with `sync-guard` → WebKit's `8.preconnect`;
4805
+ `navigate-guard` → P083's reports case; `report-unbounded` (P095) → `14.silent` too, on
4806
+ both host pages (its blocked-load report is read as the text it was); `navigate-guard` →
4807
+ P099's `served.domain.tab-links` too (the outside site hears the links).
4808
+ - Claims that no longer hold: `connect-src` fails `8.prefetch` on Chromium no more (the
4809
+ shell's hint guard holds it too); Firefox no longer holds `5.data` by itself (P035).
4810
+ - Probes that didn't fail by their assertions with their wall out, now fixed, each still
4811
+ passing with it in: under `embedder-csp`, `5.blob` (Firefox) and `5.data` (WebKit, Firefox)
4812
+ saw the navigated document run in 2 of 3 runs: its witness, a fetch at the document's end,
4813
+ raced the display's restart (P031's race, again). The witness is now the document's first
4814
+ act and a beacon, which the browser delivers after the frame is gone: 3 of 3 on each engine.
4815
+ Under `sandbox`, Firefox's print dialog held `14.print`'s click until the test timed out: the
4816
+ click and each look at the frame are bounded (`recorded`), so it fails by its assertion.
4817
+ Under `navigate-guard`, two `files.spec.ts` cases failed by a detached frame ("a page opens
4818
+ nothing else" clicked its next button in a page that had gone; the P083 reports case waited
4819
+ on the frame's clock): the first checks what reached the server after every click, the
4820
+ second waits on the host page's clock. On WebKit, once in four runs, a `live.spec.ts`
4821
+ navigation case threw "the display has no frame" while its display restarted: its first
4822
+ look (`showLive`) takes a missing frame as a look to repeat.
4823
+ - `nonce` fails every test of `strict-csp.spec.ts` (71 by their assertions, 15 by timing out,
4824
+ each engine): `others: "fail"`, with `0.opaque-origin` and `0.globals` failing by theirs.
4825
+ - `5.blob`, `5.data` and `14.print` are the shipped suite's (`/conformance`): an adopter's run
4826
+ of them sees the same, with no change to its API.
4827
+ 4. **CI runs once per commit of a pull request**: ci.yml's `push` is `main` only (was every branch,
4828
+ amending P097's `branches: ["**"]`), with `pull_request` and `workflow_dispatch`. A pull
4829
+ request's push ran every job twice, the controls with them; a push run can't be re-run by the
4830
+ agents, a pull request's can. The release gate reads main's push and dispatch runs, unchanged;
4831
+ `test/release.test.ts` pins the triggers. AGENTS.md says how to get CI before a pull request.
4832
+ 5. **After its review, a probe fails for the right reason, named exactly.** (a) A failed `expect`
4833
+ counted, a setup check too (`goto` not 200, a positive control): now a probe's deciding
4834
+ `expect` carries `probe: ` at the start of its message (`VERDICT`), in the shipped probes
4835
+ (`src/conformance`) and the spec tests the registry names, and only a failure whose error
4836
+ starts with it counts; the `nonce` control has a probe of its own in `strict-csp.spec.ts` (the
4837
+ shell drew and ran the content), since the suite's probes fail there before their verdicts.
4838
+ (b) "Fails nothing" was a label: every control that names no test on an engine now says why
4839
+ (`holds`), either by a combined control that takes its walls out with another's and fails
4840
+ something there (`link-rule,navigate-guard` is new for `link-rule`), or with a reason why no
4841
+ probe can see the wall (`self`: an opaque frame's `'self'` matches no origin; `url-origin` on
4842
+ WebKit, which keeps no framed cookie); the test checks the cover. (c) Entries named a part of a
4843
+ title; now a probe's `[id]`, a served case's id before its colon, or a test's whole title. (d)
4844
+ A test declared to fail (`test.fail`) that passes fails the control, unless it is a target.
4845
+ 6. **CI runs the controls in shards.** One engine's 57 controls outlasted a 90-minute job on CI's
4846
+ runners (all three cancelled). Each engine now runs four shards, `controls (<engine>, k/4)`,
4847
+ 60 minutes each (`--shard k/4`: the registry split by each control's measured weight, heaviest
4848
+ first to the lightest shard, so `nonce` shares its shard with small ones; stable for a
4849
+ registry), each uploading its reports and `verdicts.json`; the `controls` job puts them
4850
+ together (`--summary`) and fails if any control failed or never ran on an engine. A job's
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.
4855
+
4856
+ **Why.** PRINCIPLE 6: a wall never seen to fail proves nothing, and a check that says a wall was
4857
+ seen to fail when its run never happened is worse than no check. CI's "every control" was 7 of
4858
+ the 38 there were (57 now, with P094's, P095's, P099's, P100's, P101's and P104's); the rest ran by hand,
4859
+ when someone remembered, and what DESIGN.md said they fail had drifted from what they do.
4860
+ **Rejected.**
4861
+ - Requiring exit 0, or exit 1, alone: either is what a broken run can give.
4862
+ - Counting any failure of a named test: a browser that can't launch fails every test, and a spec
4863
+ whose every test is named (permissions, authorize) would pass a run that never reached Porthole.
4864
+ - Retrying: a named test that fails only sometimes is not a wall seen to fail; a test that fails
4865
+ besides them is either a dependency the registry must name, or a flaky probe to fix.
4866
+ - Parsing the prose columns of DESIGN.md's tables for each control's probes: the prose explains
4867
+ why; the generated table is the exact claim, and the test holds the prose to naming only
4868
+ controls that exist.
4869
+ - Running controls with `kit.spec.ts` until the kit's app applies weakenings: its walls are the
4870
+ core's, whose controls run against the leak and served harnesses.
4871
+ **Threat it re-opens.** None: no default, gate or policy changes; four probes see more.
4872
+ **Revisit when** Playwright's JSON report changes shape (the judge's tests pin the fields it reads),
4873
+ a control's run makes a CI job too long (shard the controls across jobs), or the kit's app gains
4874
+ a weakening seam (then its controls join the registry).
4875
+
4876
+ ## P105 · 2026-10-20 · After the review of P104: a marker's click within a gesture and the host's view guarded, one clock for follow-ups, text markers beside their line · Accepted
4877
+
4878
+ Amends P104 (its points 1, 3, 5 and 7, and its Trust) and P053's Trust. From the independent
4879
+ review of P104 and 0.9.0 (botiverse/porthole#37: no P0 or P1, two P2s, six P3s) and from #36
4880
+ (Ferry, taking 0.9.0: a text marker covered the next word). Measured on Chromium 153, WebKit 26.6
4881
+ and Firefox 155.
4882
+
4883
+ **Decision**, by finding:
4884
+ 1. **P2-2: the selection's re-report is a follow-up too.** After every settled scroll the shell
4885
+ sent the person's selection again (`selected`, since P053), whether its box had moved or not,
4886
+ outside P104's one-a-second clock. P104's own honest session (140 wheel turns 200 ms apart, a
4887
+ mark with a count) in comment mode (text selection on, one selection) sent 120 reports, the
4888
+ bridge's 120 a minute, and the marker's click after it was refused (`annotate:rate-limited`):
4889
+ the review's R5 on all three engines, and the extended test, failing first with 120 taken
4890
+ (Chromium, Firefox). Now the selection is told
4891
+ again only when its box moved more than 0.5 px since it was last told (or it changed, or went),
4892
+ and on the follow-ups' clock, which both kinds share: at most one report a second together, the
4893
+ latest (two in one tick leave the next second empty). The same session now gives 15 `anchored`
4894
+ and 15 `selected`, none refused, and the click is taken, on all three. A selection the person
4895
+ makes is told at once, as before; only the re-reports wait. A host without counts still hears
4896
+ the `anchored` reports 0.8 sent, and its selection again after a scroll only if it moved.
4897
+ 2. **P2-1: the host's view of a mark is the host's to guard, and `activated` needs a gesture.** A
4898
+ page can post `activated` for a shown mark on its own `pointerdown`, with the pointer's
4899
+ coordinates; the host had it 9 to 121 ms into the press (R4), so a double click asked for on
4900
+ the content's own button lands its second click on the bubble's Resolve. THREAT_MODEL §6 asked a
4901
+ 500 ms guard of confirmations only. Now it asks, of every host: a view that a frame's report
4902
+ opens or moves (`activated`, `anchored`, `selected`) takes no press for 500 ms after it appears
4903
+ or moves, ignores a press that began before that, opens beside the frame rather than over the
4904
+ report's box where the layout allows, takes no focus, and puts no destructive action one click
4905
+ away. ADOPTING.md § Annotations has the guard (`guardPresses`), P104's Trust says so.
4906
+ The narrowing, which holds: `createHost` takes `activated` only while `surface.userActivation()`
4907
+ isn't false (the gesture gate's reading: undefined, where a platform can't tell, passes; a
4908
+ throw drops it). A real marker click gives the host's page transient activation on all three
4909
+ engines, though the shell cancels the press (activation comes before the event is dispatched);
4910
+ a page's own post at load or on a timer has none (measured: a sandboxed frame's timer posts
4911
+ arrive with the host inactive; a click in it, its `mousedown` cancelled, activates the host).
4912
+ Playwright's `evaluate` is itself a gesture and activation lasts 5 s on all three, so the test
4913
+ asks nothing of either page for 7.5 s first. It stops a view opened with no gesture at all, and
4914
+ no more: activation lasts 5 s after any gesture anywhere on the page (a click on the host's own
4915
+ UI, typing in the content, the click that opened the display), and a fake posted then, on a
4916
+ timer or a scroll, is taken (point 9); one on the person's own press is R4. The host's duty
4917
+ above is the defence. A custom
4918
+ platform's `userActivation()` (already required) that answers false drops every marker click,
4919
+ as it refuses every gesture-gated call.
4920
+ 3. **#36: a text marker beside its line, not over the next word.** P104 drew it at the words' end,
4921
+ raised (left at their right + 2, top 12 px above the line): its lower 6 px lay over the next
4922
+ word's first letters, and on a narrow page, when the words ended at a wrapped line's start,
4923
+ between two lines. Now it is centred on the anchor's last line, at the first of these places
4924
+ that is inside the frame, clear of that line's words, and over nothing of the content's but a
4925
+ box holding the anchor, with nothing else between the words and it (the shell hit-tests the
4926
+ place with `elementsFromPoint`, its own layer aside): the line's gutter, just past the right
4927
+ edge of the anchor's block (its content box); where the frame is too narrow for that, the
4928
+ frame's right edge; where something else is beside the block (a table's next cell, a card in a
4929
+ row), just past the line's last word. Markers ending on one line of one block go together, in
4930
+ the order their words end. Where the bubble with its glyph fits in none of these, its number
4931
+ alone does (compact: 18 px for one digit, inside a phone page's 20 px padding); where that fits
4932
+ nowhere either, the group goes as far right as nothing else stands in the way, over the line's
4933
+ end. The pointer on a marker lights its words as the active mark's are. A draw now measures
4934
+ every marker before it changes a node, and leaves each marker that stays where it is in the
4935
+ layer: one taken out and put back mid-press lost its click on WebKit (seen once the pointer's
4936
+ arrival lit a mark and redrew). Element markers are placed as they were.
4937
+ Judged on screen (16 px text, line height 1.6; a centred 640 px column, and a 390 px page with
4938
+ full-width text and 20 px padding; anchors ending mid-line, at a line's end, at a wrapped line's
4939
+ start, two and three on one line, in a card, in a table cell, and elements; Chromium, Firefox,
4940
+ WebKit): on the column, no marker covers a glyph (0.9.0's touched 14 words); on the phone none
4941
+ does but where two or three anchors end on one full line, which covers that line's last letters
4942
+ (0.9.0's touched 13 words there, and sat between lines). The gutter is worse than 0.9.0's place
4943
+ in one way: a marker for words that end mid-line, or on a short line, sits up to the column's
4944
+ width from them, tied to them by the line, its order and their highlight (and, with a pointer,
4945
+ by the light on hover). Taken for the column it gives: which lines have comments reads at a
4946
+ glance, and a marker doesn't move as the line's words reflow.
4947
+ 4. **P3-1: the shell's guarantees say what they hold against.** The shell shares the content's
4948
+ realm and, at a marker's press, called the live prototypes: content that replaced
4949
+ `Event.prototype.stopImmediatePropagation` heard a real press (R1), one that redefined the
4950
+ `MouseEvent.prototype.clientX` getter made the shell miss the click (R2), and one that wrapped
4951
+ `Element.prototype.matches` got the closed shadow root from the shell's insertion guards and
4952
+ rewrote a marker (R3), on all three engines. Restated in THREAT_MODEL §7, P104's Trust, P053's
4953
+ Trust, DESIGN.md and the shell's comments: a press is unheard and can't be cancelled, and the
4954
+ layer is out of reach, against content that patches none of the built-ins (CHANGELOG 0.9.0's
4955
+ wording is the release's). The narrowing, small and a reading of the same functions: the
4956
+ marker's listener reads and stops a press through the platform's own functions and getters,
4957
+ kept before content runs, as the navigation guard does (`stopImmediatePropagation`;
4958
+ `preventDefault` as kept before a tab's shell locks its own; `target`, `type`, `button`,
4959
+ `clientX`, `clientY`; DOMRect's sides; `Reflect.apply`), and `tell` reads `window.parent` once
4960
+ (it is `[Replaceable]`). R1 and R2 no longer work (test and control `marker-originals`). R3
4961
+ still does, and picking's listeners still read the live prototypes. Nothing in the layer is
4962
+ secret.
4963
+ 5. **P3-2: controls for what had none.** `marker-prevent` (the press's `preventDefault` out: focus
4964
+ moves, on every engine). Its selection probe was blind: a click on a marker never changes a
4965
+ selection, with or without the cancel, since markers aren't selectable. So it now also drags
4966
+ from the marker over the next line's words, which WebKit then selects; Chromium and Firefox
4967
+ don't, either way (measured). `follow-throttle` (`FOLLOW_EVERY` 0: the honest session's count,
4968
+ now a `probe:` verdict); `follow-count`, with a test of its own (marks without counts, a scroll:
4969
+ nothing after the settle); `selection-follow` (0.9.0's re-report after every settle). DESIGN.md
4970
+ said `marker-click` covered focus and selection: it covers the handlers, `marker-prevent` focus
4971
+ and the selection.
4972
+ 6. **P3-3: a platform's `viewport()` that answers no size or throws** raised a TypeError out of the
4973
+ transport's listener (the report was dropped: closed, but out of the listener). Now
4974
+ `createHost` reads it in a `try` and takes only numbers, and `clampRect` takes null as unknown:
4975
+ every box is nothing at the frame's corner, and nothing throws.
4976
+ 7. **P3-5: labels lose what the person can't see.** P104 named a wordless element by its `alt`,
4977
+ `aria-label` or `title`, text the person never sees on the page, which could carry bidi
4978
+ controls or zero-width characters into the host's UI, or a model's context through a host
4979
+ that forwards it. `parseAnchor` (so `parseReport` and `checkMarks`) takes out of every label
4980
+ every character P100's rule names, with none of its exceptions (point 9), now one definition in
4981
+ `src/bridge/unseen.ts`. Selectors keep theirs, to be found again; THREAT_MODEL says a quote
4982
+ handed to a model is the page's words.
4983
+ 8. **P3-4 and P3-6: written down.** The frame's size is read for each report the host takes,
4984
+ before its rate: one forced layout of the host's page per message, which a repeated
4985
+ `ui/initialize` already causes (accepted; the clamp after the gate would sit in the bridge's
4986
+ delivery). A box is in the frame's own CSS px: a host that scales or transforms the frame maps
4987
+ it through that transform (THREAT_MODEL §7, ADOPTING.md, `AnnotationRect`).
4988
+
4989
+ 9. **After the review of 3969ebc** (no P0 or P1; R5, R1 and R2 hold, every control fails exactly
4990
+ its probes):
4991
+ - **P2-A: the guard in ADOPTING.md let presses through.** It caught `click` alone, and let one
4992
+ with `detail` 0 pass: a menu item that clicks itself when a press that began elsewhere ends
4993
+ on it (Radix's pattern; Base UI's items click on `mouseup`), and a trigger that acts on
4994
+ `pointerdown`, fired within 500 ms (the review's R9). Now the guard makes the view `inert`
4995
+ (and `pointer-events: none`) while it arms, so nothing in it takes a press, a click or focus, and
4996
+ after that it drops the end of a press that didn't begin on it (`pointerup`, `mouseup`,
4997
+ `touchend`, `click`) until one does, or a key. Portaled menus and popovers are outside the
4998
+ view: they go in a container inside it, or are guarded too, and close when it moves. §6 says
4999
+ a press of any kind. A leak test runs the snippet as ADOPTING.md has it (the review's three
5000
+ cases, a press held past the arming, then a press and a key that are taken); the old snippet
5001
+ fails it by the menu item's release.
5002
+ - **P2-B: a tap on a marker was never reported on WebKit** (since 0.9.0): WebKit made no click
5003
+ of a tap on the marker, whose only listener was the window's, though it did for a button.
5004
+ Each marker now has a click listener of its own, which never runs (the window's first
5005
+ listener stops every click on the layer): WebKit then clicks. A tap reports on all three
5006
+ engines, with a touch screen and in a phone's emulation (iPhone 13 on WebKit, Pixel 5 on
5007
+ Chromium; Firefox has none), after 6 s of nothing: the tap's own activation is what the host
5008
+ takes it by (measured: the host's page is active when the report arrives). The reference
5009
+ host's page now has a viewport meta, as a phone's page has: without it the emulation lays the
5010
+ page out 980 px wide at 0.4, and Playwright's taps land beside the frame. Control `marker-tap`
5011
+ (the listener out) fails the test on WebKit; Chromium and Firefox click a tap without it.
5012
+ - **P3-A: the label strip wasn't closed.** It kept P100's exceptions (the parts of emoji, a
5013
+ joiner between two shaped letters), and a Mongolian variation selector, itself a mark of a
5014
+ shaping script and default-ignorable, made a joiner beside it look shaped, then was taken out
5015
+ itself: a 107-character label kept 48 joiners, `rm -rf` in bits. Now every code point the rule
5016
+ names goes, no exceptions: an emoji in a label loses its joiners and selectors (its faces
5017
+ stay). Tested with that label, and 20,000 random ones from the review's pool, none of which
5018
+ leaves anything `unseen` refuses.
5019
+ - **P3-B:** THREAT_MODEL and point 2 said a page could no longer open the host's view at load, on
5020
+ a timer or on a scroll; within 5 s of any gesture anywhere on the page it can (the review's
5021
+ R7b). Both now say so, and that the guard is the defence.
5022
+ - **P3-C: placing markers after a change of the content was dear** (the longest task, 300
5023
+ paragraphs with counts: 44, 53 and 19 ms on Chromium, WebKit and Firefox; 200 marks in one
5024
+ 3,000-line `<pre>`: 168, 163 and 102 ms). A line's end was read from the whole rest of its
5025
+ block, for each marker; each hit test walked every mark and marker the last draw left in the
5026
+ layer (0.13 ms a test, measured); a mark's block was found again on every change. Now the
5027
+ line's end is read 64 characters at a time, only until the text leaves the line; the layer's
5028
+ marks and markers are out of the hit tests while places are tested (hidden in one task, never
5029
+ taken out of the page); a marker whose line is out of view is placed without a measure or a
5030
+ test; a block is kept while it still holds the words. Measured again: 18, 22 and 16 ms; 24,
5031
+ 48 and 40 ms (without counts: 5, 6 and 11; 13, 25 and 37). THREAT_MODEL and DESIGN say what it
5032
+ costs and that it is bounded.
5033
+ - **P3-D: nothing pinned #36.** A leak test now reads every word's glyph boxes against the points
5034
+ the layer takes (a 2 px grid) on the column page, all of its cases, and on the phone page's
5035
+ lines with one marker each: no marker covers a word, on all three engines. Control
5036
+ `marker-place` (the marker just past its words, centred on the line, as 0.9.0 placed it
5037
+ across) fails it. The press test's drag goes round the paragraph, so it holds wherever the
5038
+ marker is.
5039
+ - **P3-E:** CHANGELOG.md's Unreleased section says what a host sees change, what to act on first.
5040
+ - **CI's WebKit (PR #38):** `selection-follow` and `follow-throttle` failed nothing there: the
5041
+ honest session's verdict was a count of follow-ups over 140 wheel turns, and a slower runner
5042
+ settles fewer of them, so a shell without the clock stayed under it. The test now also
5043
+ scrolls eight times 300 ms apart from inside the frame, each a settle on any machine, and the
5044
+ host page notes when each follow-up arrives: the selection's re-reports, and the marks'
5045
+ follow-ups, must each come at least 700 ms apart (the clock keeps them 1 s apart; without it
5046
+ they come 300 ms apart). Both controls fail it on WebKit pinned to one CPU. That run also
5047
+ showed P104's settle test counting the script's steps, 30 ms apart, while a starved
5048
+ engine's scroll events bunched across a late frame: it counts the events now.
5049
+ - **P3-F:** THREAT_MODEL had P105 in §8 as merged and its status line naming it. As P104's own
5050
+ change did, it now describes what P105 does where it does it, without a §8 row; the release
5051
+ commit says what the document describes.
5052
+
5053
+ **API.** No signature changes. What a host may see change: `activated` is dropped while its page
5054
+ has no transient activation; the exported `parseAnchor` returns a label without invisible
5055
+ characters; `selected` comes again after a scroll only when its box moved, on the follow-ups'
5056
+ clock; text markers are elsewhere (`activated`'s box is the marker's, wherever it is drawn); a
5057
+ tap on a marker is reported on WebKit; ADOPTING.md's `guardPresses` takes `...parts` and returns
5058
+ `{ placed }` as before.
5059
+
5060
+ **Tested.** `test/annotate.test.ts`, on `createHost` over a stand-in platform: `activated` dropped
5061
+ where `userActivation()` answers false or throws, taken where it answers true or undefined; a
5062
+ `viewport()` answering null, a string, sizes as strings, throwing, or with a throwing getter: every
5063
+ box nothing at the corner, nothing thrown out of the listener; `clampRect(rect, null)`; a label's
5064
+ bidi override, zero-width, tag, soft hyphen and control characters taken out, emoji and a Persian
5065
+ joiner kept, a quote's soft hyphen kept, the host's own marks checked the same way.
5066
+ `leak/annotate.spec.ts`, on Chromium, WebKit and Firefox: the honest session in comment mode (its
5067
+ follow-ups, the selection's too, at most 45 in 28 s, nothing refused, the click after it taken;
5068
+ failed first with 120 on Chromium and Firefox); marks without counts told nothing after a scroll; a
5069
+ drag from a marker leaves the selection as it was; a page that patches
5070
+ `Event.prototype.stopImmediatePropagation` and `MouseEvent`'s `clientX` and `clientY` neither hears
5071
+ a marker's press nor stops its report; a page's `activated` posted 6.5 s after the marks arrived,
5072
+ with no gesture, not taken, and one on the person's own press in the content taken (the duty's
5073
+ case); the marker helpers find a marker where it is, by the points along its line where the layer
5074
+ takes the pointer. Negative controls, each alone, failing exactly their test on all three engines:
5075
+ `marker-prevent`, `marker-originals`, `follow-throttle`, `selection-follow`, `follow-count`,
5076
+ `annotation-activated-gesture`; and `marker-click` (now also failing the patched-prototypes case),
5077
+ `marker-trusted`, `annotation-activated`, `annotation-activated-count`, `annotation-checks` and
5078
+ `annotation-rect-clamp` again, as before.
5079
+
5080
+ **Tested, after the review of 3969ebc.** Unit: the review's label and the 20,000 random ones.
5081
+ Leak, on all three engines: the tap test (touch screen, iPhone 13, Pixel 5), the placement test,
5082
+ the guard test. Controls `marker-tap` and `marker-place`, and every control P105 added or touched,
5083
+ again.
5084
+
5085
+ **Threat it re-opens.** None: each point narrows what content can do or says what holds; no
5086
+ default, gate or policy loosens.
5087
+
5088
+ **Rejected.**
5089
+ - A budget of its own for `activated` (the review's other way for point 1): one clock keeps an
5090
+ honest page's follow-ups at half the shared rate, which leaves a click its room, without a second
5091
+ rate in the bridge (P104's reason). Two clocks, one a kind, would together be 120 a minute, the
5092
+ whole budget, on a session longer than a minute.
5093
+ - A token in each marker's report, so a host takes only the shell's: the content shares the
5094
+ shell's realm and would read it.
5095
+ - The marker at the line's last word everywhere: it covers nothing on the column either, but its
5096
+ place moves with each line's length and each reflow. It is the place in a cell or a card, where
5097
+ the gutter is someone else's.
5098
+ - #36's other way, a dot without a number by the words and the number on hover: there is no hover
5099
+ on a phone, and the number is what P104 is for. Compact keeps it.
5100
+ - Capturing `matches` and `querySelectorAll` for the insertion guards (R3): they run on every node
5101
+ the page inserts, through three prototypes; done right that is a change of its own to the
5102
+ shell's guards, for nothing secret.
5103
+ - Refusing a label with an invisible character, as P100 refuses an update: a label is only shown,
5104
+ and a selection with a soft hyphen is ordinary.
5105
+
5106
+ **Revisit when** a layout puts text beside a block that hit testing can't see (`pointer-events:
5107
+ none`), a host shows right-to-left text (the gutter is on the right), a host needs to place
5108
+ markers itself (then it draws them from `anchored`), an engine changes what gives a page
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
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
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 click (`user-activation`, 30 a minute), view level; content hears
5466
+ only whether the composer opened; no method reads a thread; the page never posts.
5467
+ 3. **The host's duties** (THREAT_MODEL §6 and §7, ADOPTING's example): show the draft whole, as the
5468
+ person's editable plain text, in its own composer; post it only on the person's Send; arm the
5469
+ composer as §6 arms a view the content brought: no press, and no Enter that sends, for 500 ms
5470
+ after it opens, Send not focused, beside the frame where the layout allows. Once posted the
5471
+ comment is the person's, mentions in it included: that is why they must see it all first.
5472
+ `defineRuntimeConformance` checks that the handler takes a draft (answers a boolean); that it
5473
+ never posts on its own can't be seen from a handler and is the host's.
5474
+
5475
+ **Why.** The comment is still the person's word: they see all of the text, can change or drop it,
5476
+ and post it themselves, as P090 requires. What the page saves them is typing.
5477
+ **Threats it opens, and their bounds.**
5478
+ - *Words the person didn't read:* a long draft hiding a line they wouldn't sign, or one an agent
5479
+ reading the comment later takes as their instruction. Bounded by visible text only (no hidden
5480
+ characters: the review found tags, U+200B and U+202E would otherwise pass), 2,000 characters, and
5481
+ the host showing it whole; reading it is the person's.
5482
+ - *Click-through:* before P108 a stray press on Send posted nothing; now the first click already
5483
+ loads a postable comment, and the page can place its button where Send will appear (the second
5484
+ click of a double click), or ask the person to press Enter. Bounded by the host's arming (above).
5485
+ **Rejected.** The page posting the comment (P090); a draft without a gesture; rich text or
5486
+ mentions resolved from the draft before posting (the host would be acting on the content's names);
5487
+ coercing what isn't text into text (`String(null)` is "null", which the person never meant).
5488
+ **Tested.** `test/runtime.test.ts` ("a draft (P108)": as given, a checklist too; past 2,000,
5489
+ blank, a number, null, a lone surrogate, tag characters, U+200B, U+202E, a bell: `invalid`, no
5490
+ handler); `leak/served/runtime.spec.ts` ("a comment's draft is the host's to check": from real
5491
+ clicks, a zero-width space, tags, 2,001 characters, a number and a string as options open nothing
5492
+ and reach no handler, a checklist reaches the composer; "comments are write-only": the draft beside
5493
+ the anchor). Negative control `comment-draft` (the draft taken as given) → the first case, every
5494
+ engine. `types/runtime/v1/check.ts` (the page-shaped call compiles); the runtime conformance's
5495
+ comments case sends a draft.