@botiverse/porthole 0.15.3 → 0.16.1

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 (118) hide show
  1. package/CHANGELOG.md +70 -0
  2. package/dist/annotate/types.d.ts +15 -1
  3. package/dist/annotate/validate.js +19 -1
  4. package/dist/bridge/bridge.d.ts +1 -8
  5. package/dist/bridge/bridge.js +0 -7
  6. package/dist/bridge/types.d.ts +1 -1
  7. package/dist/check/page-source.js +1 -1
  8. package/dist/check/page.js +1 -1
  9. package/dist/compile/policy.d.ts +0 -7
  10. package/dist/compile/policy.js +1 -10
  11. package/dist/config/capabilities.d.ts +8 -14
  12. package/dist/config/capabilities.js +4 -5
  13. package/dist/config/schema.d.ts +2 -13
  14. package/dist/config/validate.js +0 -24
  15. package/dist/conformance/behavior.js +26 -37
  16. package/dist/conformance/clipboard.js +47 -1
  17. package/dist/conformance/harness-source.js +1 -1
  18. package/dist/displays/displays.js +1 -3
  19. package/dist/guide/limits.js +1 -1
  20. package/dist/guide/runtime.js +1 -1
  21. package/dist/host/create-host.d.ts +1 -1
  22. package/dist/host/create-host.js +8 -52
  23. package/dist/host/door.d.ts +1 -1
  24. package/dist/host/locate.d.ts +1 -1
  25. package/dist/host/locate.js +2 -2
  26. package/dist/host/outcome.d.ts +5 -12
  27. package/dist/host/outcome.js +8 -16
  28. package/dist/host/types.d.ts +6 -22
  29. package/dist/index.d.ts +2 -4
  30. package/dist/index.js +2 -4
  31. package/dist/isolation/served.d.ts +4 -14
  32. package/dist/isolation/served.js +7 -28
  33. package/dist/isolation/types.d.ts +2 -25
  34. package/dist/isolation/types.js +0 -23
  35. package/dist/platform/focus-field.d.ts +11 -0
  36. package/dist/platform/focus-field.js +18 -0
  37. package/dist/platform/types.d.ts +7 -23
  38. package/dist/platform/web.js +8 -106
  39. package/dist/presets/presets.d.ts +0 -2
  40. package/dist/presets/presets.js +0 -1
  41. package/dist/react/frame.d.ts +0 -8
  42. package/dist/react/frame.js +0 -4
  43. package/dist/runtime/contract.d.ts +2 -2
  44. package/dist/runtime/contract.js +2 -2
  45. package/dist/runtime/types.generated.js +6 -6
  46. package/dist/server/files.js +7 -23
  47. package/dist/server/host.d.ts +1 -1
  48. package/dist/server/index.d.ts +1 -1
  49. package/dist/server/index.js +4 -6
  50. package/dist/server/naming.js +1 -1
  51. package/dist/server/server.js +28 -166
  52. package/dist/server/types.d.ts +7 -7
  53. package/dist/shell/annotate.d.ts +3 -0
  54. package/dist/shell/annotate.js +15 -5
  55. package/dist/shell/plan.d.ts +0 -5
  56. package/dist/shell/plan.js +2 -4
  57. package/dist/shell/runtime.js +1 -268
  58. package/docs/ADOPTING.md +398 -1081
  59. package/docs/DECISIONS.md +172 -10
  60. package/docs/DESIGN.md +1114 -1388
  61. package/docs/PRINCIPLES.md +85 -1
  62. package/docs/THREAT_MODEL.md +658 -1127
  63. package/package.json +1 -1
  64. package/src/annotate/types.ts +12 -1
  65. package/src/annotate/validate.ts +23 -1
  66. package/src/bridge/bridge.ts +1 -17
  67. package/src/bridge/types.ts +1 -1
  68. package/src/check/page.ts +1 -1
  69. package/src/compile/policy.ts +1 -11
  70. package/src/config/capabilities.ts +8 -14
  71. package/src/config/schema.ts +2 -13
  72. package/src/config/validate.ts +0 -28
  73. package/src/conformance/behavior.ts +50 -52
  74. package/src/conformance/clipboard.ts +56 -1
  75. package/src/displays/displays.ts +1 -3
  76. package/src/guide/limits.ts +1 -1
  77. package/src/guide/runtime.ts +1 -1
  78. package/src/host/create-host.ts +8 -53
  79. package/src/host/door.ts +1 -1
  80. package/src/host/locate.ts +2 -2
  81. package/src/host/outcome.ts +8 -21
  82. package/src/host/types.ts +6 -20
  83. package/src/index.ts +2 -4
  84. package/src/isolation/served.ts +6 -34
  85. package/src/isolation/types.ts +2 -31
  86. package/src/platform/focus-field.ts +18 -0
  87. package/src/platform/types.ts +7 -22
  88. package/src/platform/web.ts +8 -129
  89. package/src/presets/presets.ts +0 -3
  90. package/src/react/frame.tsx +0 -10
  91. package/src/runtime/contract.ts +4 -4
  92. package/src/runtime/types.generated.ts +6 -6
  93. package/src/server/files.ts +4 -19
  94. package/src/server/host.ts +1 -1
  95. package/src/server/index.ts +4 -16
  96. package/src/server/naming.ts +1 -1
  97. package/src/server/server.ts +29 -189
  98. package/src/server/types.ts +7 -7
  99. package/src/shell/annotate.ts +15 -5
  100. package/src/shell/plan.ts +2 -9
  101. package/src/shell/runtime.ts +1 -268
  102. package/types/runtime/v1/artifact.d.ts +2 -3
  103. package/types/runtime/v1/assets.d.ts +1 -1
  104. package/types/runtime/v1/chat.d.ts +2 -2
  105. package/types/runtime/v1/comments.d.ts +1 -1
  106. package/types/runtime/v1/downloads.d.ts +2 -2
  107. package/types/runtime/v1/links.d.ts +2 -2
  108. package/dist/platform/focus-guard.d.ts +0 -288
  109. package/dist/platform/focus-guard.js +0 -838
  110. package/dist/server/nested.d.ts +0 -66
  111. package/dist/server/nested.js +0 -121
  112. package/dist/shell/frame.d.ts +0 -28
  113. package/dist/shell/frame.js +0 -407
  114. package/docs/ARCHITECTURE.md +0 -359
  115. package/docs/OBJECTIVES.md +0 -116
  116. package/src/platform/focus-guard.ts +0 -1114
  117. package/src/server/nested.ts +0 -157
  118. package/src/shell/frame.ts +0 -444
package/docs/DECISIONS.md CHANGED
@@ -1,5 +1,8 @@
1
1
  # Decision log
2
2
 
3
+ A log, not required reading: the other docs describe how things are now, and cite entries here
4
+ by number (Pxxx) for why. P063 and P113 were never assigned.
5
+
3
6
  Append-only. Each entry records the decision, why, what we rejected, and **when to
4
7
  revisit**. To change a decision, add a new entry that supersedes the old one and
5
8
  mark the old one `Superseded by Pxxx`. The "revisit when" line is the most
@@ -4874,7 +4877,7 @@ when someone remembered, and what DESIGN.md said they fail had drifted from what
4874
4877
  a control's run makes a CI job too long (shard the controls across jobs), or the kit's app gains
4875
4878
  a weakening seam (then its controls join the registry).
4876
4879
 
4877
- ## P105 · 2026-10-20 · After the review of P104: a marker's click within a gesture and the host's view guarded, one clock for follow-ups, text markers beside their line · Accepted; amended by P133
4880
+ ## P105 · 2026-10-20 · After the review of P104: a marker's click within a gesture and the host's view guarded, one clock for follow-ups, text markers beside their line · Accepted; amended by P133; superseded in part by P149 (a marker's click within a gesture)
4878
4881
 
4879
4882
  Amends P104 (its points 1, 3, 5 and 7, and its Trust) and P053's Trust. From the independent
4880
4883
  review of P104 and 0.9.0 (botiverse/porthole#37: no P0 or P1, two P2s, six P3s) and from #36
@@ -5500,7 +5503,7 @@ the anchor). Negative control `comment-draft` (the draft taken as given) → the
5500
5503
  engine. `types/runtime/v1/check.ts` (the page-shaped call compiles); the runtime conformance's
5501
5504
  comments case sends a draft.
5502
5505
 
5503
- ## P109 · 2026-10-26 · After the review of 0.12.0's drafts: the keyboard given back, `comments.open` from the frame the person is in, a page's draft the person's to act on, stricter draft text · Accepted
5506
+ ## P109 · 2026-10-26 · After the review of 0.12.0's drafts: the keyboard given back, `comments.open` from the frame the person is in, a page's draft the person's to act on, stricter draft text · Superseded in part by P149 (the keyboard given back, `comments.open` from the frame the person is in; the draft rules stand)
5504
5507
 
5505
5508
  Amends P090 and P108, and THREAT_MODEL §6 and §7. From the review of P107 and P108 at 0.12.0
5506
5509
  (2026-10-26: no P0, two P1s, three P2s, two P3s) and the review of the 0.11.0 and 0.12.0 releases
@@ -5845,7 +5848,7 @@ that throws gives the "wasn't checked" warning; `admitFiles` with `\ffffff` in a
5845
5848
  **Revisit when** a page's own document is ever shown outside the shell (then quirks mode is real),
5846
5849
  or an engine starts counting fixed boxes in what the viewport scrolls.
5847
5850
 
5848
- ## P111 · 2026-10-28 · A nested page: Porthole's shell at the framed address, the page its opaque child, and the shell's own activation decides the keyboard and `comments.open` · Accepted; amended by P148
5851
+ ## P111 · 2026-10-28 · A nested page: Porthole's shell at the framed address, the page its opaque child, and the shell's own activation decides the keyboard and `comments.open` · Superseded by P149
5849
5852
 
5850
5853
  **Context.** P109's focus guard and `comments.open`'s gate ask whether the person, not the page,
5851
5854
  moved the keyboard into a frame or clicked in it. In full Chromium a cross-site frame is out of
@@ -6112,7 +6115,7 @@ told selection kept: each alone fails the probe, measured on Chromium).
6112
6115
  **Revisit when** a host needs the element picked (`elements: true`) or a held block cleared too
6113
6116
  (they leave no highlight now), or the MCP Apps spec gains a host-to-view way to clear a selection.
6114
6117
 
6115
- ## P114 · 2026-10-28 · A nested page's shell on a label of its own, where nothing else is ever served · Accepted
6118
+ ## P114 · 2026-10-28 · A nested page's shell on a label of its own, where nothing else is ever served · Superseded by P149
6116
6119
 
6117
6120
  **Context.** porthole#56 (Ferry's audit of what merged after 0.13.0). P111 rests on the shell
6118
6121
  being a realm content can't reach (ARCHITECTURE "Trust boundaries" 4): the host trusts the shell's
@@ -6375,7 +6378,7 @@ pinned at the frame's top… takes a mouse click and a tap where it is drawn" (a
6375
6378
  pixels); "a mouse is as before…" (a click 11 px below or 4 px beside the bubble is the page's,
6376
6379
  with no touch and on a touch screen after a finger).
6377
6380
 
6378
- ## P120 · 2026-10-29 · A nested page's keyboard: a fight is judged without the shell, the shell is asked to look, a key is no press where the pointer is seen · Accepted; amended by P122
6381
+ ## P120 · 2026-10-29 · A nested page's keyboard: a fight is judged without the shell, the shell is asked to look, a key is no press where the pointer is seen · Superseded by P149
6379
6382
 
6380
6383
  Amends P111. **Context.** The audit of P111's guard (2026-10-28, NG-1, P0 on Firefox; porthole#56):
6381
6384
  a nested page that focuses its field as it loads and focuses it again whenever it loses focus read
@@ -6511,7 +6514,7 @@ out-of-process frame, says what turned activation on, or tells a frame's parent
6511
6514
  into it; or a host can tell a frame in its own process from one out of it before the pointer has
6512
6515
  been over one (then a first move into a nested page there is judged as 0.13 judged it, P120-1).
6513
6516
 
6514
- ## P121 · 2026-10-29 · After the audit of 0.14.2: a nested page's shell held to its own label outside `/server`, one source for its files' CSP, what `clearSelection` tells the page, `tracked` guarded · Accepted
6517
+ ## P121 · 2026-10-29 · After the audit of 0.14.2: a nested page's shell held to its own label outside `/server`, one source for its files' CSP, what `clearSelection` tells the page, `tracked` guarded · Superseded in part by P149 (a nested page's shell held to its own label, one source for its files' CSP)
6515
6518
 
6516
6519
  Amends P114 and P115. From the audit of aedc412 (2026-10-29; no P0 or P1): two findings on nested
6517
6520
  pages (M1, P2; M2, P3) and two on annotations (AN-1, P2; AN-2, P3).
@@ -6580,7 +6583,7 @@ second display kind from the app under test, and what it would hold (a Worker's
6580
6583
  host's; left for when a host with its own Worker asks for one. Hiding the clear from the page:
6581
6584
  the `selectionchange` gives it away whatever the message says.
6582
6585
 
6583
- ## P122 · 2026-10-29 · After 0.14.4's CI: no press within 250 ms of the person's key, and the pointer rule reads the typing before an activation · Accepted
6586
+ ## P122 · 2026-10-29 · After 0.14.4's CI: no press within 250 ms of the person's key, and the pointer rule reads the typing before an activation · Superseded by P149
6584
6587
 
6585
6588
  Amends P120. **Context.** CI on 0.14.4 (run 40822963445, `loopback (chromium-oopif)`): P120's
6586
6589
  case "a page that starts taking the keyboard back on its own blur while the person types…" failed
@@ -6650,7 +6653,7 @@ pass on full Chromium, the headless shell and Firefox; `navigate-guard`, `pointe
6650
6653
  it (then the press itself can be told from a key, and the window can go).
6651
6654
 
6652
6655
 
6653
- ## P123 · 2026-10-29 · A page taking the keyboard is an accepted risk; the guard stays best effort · Accepted
6656
+ ## P123 · 2026-10-29 · A page taking the keyboard is an accepted risk; the guard stays best effort · Superseded in part by P149 (the risk stays accepted; the guard is gone)
6654
6657
 
6655
6658
  **Context.** P109, P120 and P122 built a guard that gives the keyboard back when a display moves
6656
6659
  focus into its frame while the person types in the host's page. P122's review (porthole#81) showed
@@ -7975,7 +7978,7 @@ Safari; Safari and iOS are unmeasured. Playwright emulates a focused window on e
7975
7978
  Safari shows `hasFocus` disagreeing with the host's `activeElement` after `display.focus()`; or a
7976
7979
  word must expire by itself (a host that sends many, or content that stays out for long).
7977
7980
 
7978
- ## P136 · 2026-11-06 · `display.focus()` reaches a nested page: the host's word to its shell, in a task of its own · Accepted
7981
+ ## P136 · 2026-11-06 · `display.focus()` reaches a nested page: the host's word to its shell, in a task of its own · Superseded by P149
7979
7982
 
7980
7983
  Amends P111 and closes P135's known gap (#proj-workspace:#214). Tenny's requirement, #proj-workspace:#211:
7981
7984
  `marker-late` covers the nested case.
@@ -9357,7 +9360,7 @@ would then be no better than the event, and no worse); a host needs marks in the
9357
9360
  scrollers to ride too (a timeline per scroller, named from the mark's nearest one); or decision 6's
9358
9361
  case is reported.
9359
9362
 
9360
- ## P148 · 2026-11-11 · A nested page's real presses, told to its shell over a port no content holds · Accepted
9363
+ ## P148 · 2026-11-11 · A nested page's real presses, told to its shell over a port no content holds · Superseded by P149
9361
9364
 
9362
9365
  Amends P111 (its "Rejected", and item 4 of its "Threat it re-opens"). From Raft (xxchan,
9363
9366
  2026-11-11): a page's own button that calls `comments.open`; the host answers with a dialog; the
@@ -9524,3 +9527,162 @@ held: a second wall behind item 2, held by the unit test).
9524
9527
  condition: this and the activation rule could then both go); a host reports the residual for
9525
9528
  controls that aren't native (then a rule for `role` that typing can't satisfy); or the 500 ms
9526
9529
  after a stall drops presses people notice.
9530
+
9531
+ ## P149 · 2026-11-11 · What guessed at the person's intent is taken out: nested pages, the focus guard, the proof of a click but `copyText`'s · Accepted
9532
+
9533
+ **Context.** A host reported that a page's own "comment" button, pressed by a real person,
9534
+ was refused: "This needs a click". The press was real. `comments.open` asked for a gesture
9535
+ *with the host page's focus in the calling frame* (P109), the host's page can't see a press
9536
+ inside a cross-site frame (out of process on full Chromium; no event on Firefox), and so the
9537
+ rule ran on a guess: `:active`, the pointer's place, the time since the last key, and for a
9538
+ nested page its shell's word on its activation (P111), then on which keys count (P120, P122),
9539
+ then on each real press told over a port (P148), with a storage design for nested pages next in
9540
+ line. Each step made the guess better and the machine larger, and each release still refused
9541
+ some real clicks. The question that should have come first: what does the check protect?
9542
+
9543
+ **What the checks protected.** Followed to the end, each one of them stops a page from *asking
9544
+ at a moment it picks*, never from doing:
9545
+
9546
+ - `sendPrompt`, `openLink`, `downloadFile`, `artifact.publish`, `assets.delete`: each already
9547
+ ends at the person's confirmation, shown the whole effect, and declines mute the display. A
9548
+ page that asks unprompted gets a dialog the person says no to.
9549
+ - `comments.open`: opens the host's composer with a draft that posts nothing by itself; the
9550
+ host's handler may answer no (P108's duties stand).
9551
+ - A marker's `activated`: opens the host's view of a mark, which takes no focus and no press
9552
+ for its first 500 ms (§6's guard stands).
9553
+ - The focus guard: gave the keyboard back when a page took it. P123 had already accepted that
9554
+ it couldn't hold (typing slower than one key per 250 ms passed it), so it was a wall with a
9555
+ known hole whose false positives were the person's own clicks.
9556
+
9557
+ And the proof itself proved little: the host-side check passed for any click anywhere on the
9558
+ host's page in the last 5 s, and the shell-side one is the content's own realm speaking.
9559
+
9560
+ **Decision.**
9561
+
9562
+ 1. **No proof of a click is asked by default, but `copyText`'s.** The default gates of
9563
+ `sendPrompt`, `openLink` and `downloadFile` are `confirm` and a rate of 30 a minute (they had
9564
+ no rate: the gesture was their bound, so they get one); `comments` keeps its rate alone;
9565
+ `artifact.publish` and `assets.delete` keep `confirm`. `copyText` keeps `user-activation`:
9566
+ it has no confirmation, the clipboard is the person's, and the browser's own rule for writing
9567
+ it is a gesture. The gate itself stays in the vocabulary: a host may name `user-activation`
9568
+ for any capability or method (`gates`, `methodGates`), and the shell and the bridge check it
9569
+ as before. `CapabilitySpec.inFrame` (P109's "in the calling frame") is removed.
9570
+ 2. **A marker's `activated` is taken with or without a gesture** (supersedes P105's point 2).
9571
+ Every other check on it stands: only for a mark the host shows with a marker, rebuilt,
9572
+ clamped, within the rate.
9573
+ 3. **The focus guard is removed** (supersedes P109's decisions 1 and 2; P123's risk stays
9574
+ accepted, now without a guard in front of it). No `focusTaken`, no `onFocusTaken`, no display
9575
+ stopped for taking the keyboard, no shell words about focus. `display.focus()` is the
9576
+ frame's own `focus()`. `focusField(field)` stays as a plain helper (it blurs a frame that
9577
+ holds the focus, then focuses the field: Firefox ignores a plain `focus()` there).
9578
+ `Surface.focused`, where a platform gives it, says only whether the keyboard is in the
9579
+ display (the frame's root's `activeElement`), and only the find shortcut reads it (P131).
9580
+ 4. **Nested pages are removed** (supersedes P111, P114, P120, P121's M1 and M2, P122, P136,
9581
+ P148). `nested: true` is no field; the shell document, its label (`porthole-<…>`), its
9582
+ namespace (`porthole/shell/*`), its press port and the `/server` routes and helpers for it
9583
+ are gone. They existed to give the guard and `comments.open` a realm the page couldn't speak
9584
+ for; with nothing left to ask it, the mode is a second way to serve a page with no reader.
9585
+ The label prefix `porthole-` stays reserved (`PORTHOLE_LABEL_PREFIX`): no host's naming makes
9586
+ one.
9587
+ 5. **What stays, and is not this kind of rule.** P135 and P137 (a late `focusMark` doesn't land
9588
+ once the person has moved on) guard the host's *own* move of the focus, not the page's. The
9589
+ find shortcut's focus rule (P131) refuses no real press: the key is always pressed in the
9590
+ frame. The host view's 500 ms (§6) is the host's own guard of its own controls.
9591
+
9592
+ **The served path.** No wall moves: origins, sandboxes, CSP, tickets, the door and every message
9593
+ check are as in 0.15.3. The page runtime every served document inlines is 0.15.2's with the
9594
+ nine lines of the nested-only renewal hook taken out (its pin in `test/framed-by.test.ts`);
9595
+ `use` and `legacy` are unchanged, and follow the plan's gates as they did.
9596
+
9597
+ **Rejected.** *Keep the checks and widen the guess again* (a storage relay for nested pages was
9598
+ designed next): the fifth step on the same road, for a check that protects a moment, not an
9599
+ effect. *Keep nested mode without the guard*, as an opaque page for scopes that distrust their
9600
+ own displays: no host uses it, and different scopes already give displays that distrust each
9601
+ other different origins (THREAT_MODEL S7); it can come back as its own decision with its own
9602
+ reader. *Remove `copyText`'s click too*: it is the one call with no person between the page and
9603
+ the effect. *Remove the `user-activation` gate from the vocabulary*: a host with a reason of its
9604
+ own may still want it, and `copyText` needs it.
9605
+
9606
+ **Cost.** A page can interrupt: a confirmation, a composer or a comment view at a moment the
9607
+ person didn't pick, within 30 a minute, until declines mute it. A page that takes the keyboard
9608
+ keeps it until the person clicks back. A host that wants the old default for one capability names
9609
+ the gate again (`gates: ["user-activation", "confirm"]`), with the false refusals that come with
9610
+ it. A host that served nested pages must go back to served ones (CHANGELOG 0.16.0 says how).
9611
+
9612
+ **Tested.** `test/bridge.test.ts` (a gesture gate refuses where named and for `copyText`;
9613
+ nothing else asks one); `test/agreement.test.ts` (every capability a page can call without a
9614
+ gesture has a default rate, P103's rule, now three more); `test/runtime-review.test.ts`
9615
+ (publish and delete: a confirmation with or without a gesture; a host's `methodGates` bring the
9616
+ gesture back, in the plan and the manual); `test/annotate.test.ts` (a marker's click taken
9617
+ whatever the platform says of activation, still only for a shown marker); `test/config.test.ts`
9618
+ (`nested` is refused as an unknown field); `test/sandbox.test.ts` (the static rule on
9619
+ `allow-same-origin`, re-homed from the nested suite); `test/framed-by.test.ts` (the runtime's
9620
+ pins). Conformance: `12.prompt-confirm` (a prompt on load is asked, and a no sends nothing),
9621
+ `12.raw-message` (a raw `ui/message` is asked too), `12.copy-text` and the new `12.raw-copy`
9622
+ (the gesture gate that stays, shell side and host side; controls `shell-gesture`,
9623
+ `host-gesture`). 28 negative controls go with the code they took out (the registry and
9624
+ DESIGN.md's table); `leak/late-word.spec.ts` keeps `chromium-oopif`'s one case.
9625
+
9626
+ **Revisit when** an engine tells a host's page, truthfully, that the person pressed inside a
9627
+ cross-site frame (then a check could be a fact, not a guess); a host reports the interruptions
9628
+ as abuse its own handler can't bound; or a host needs an opaque page inside a shared scope
9629
+ (nested pages' one use that was not the guard).
9630
+
9631
+ **Amended 2026-11-11, before the release.** `chromium-oopif` runs every served case too
9632
+ (`leak/served/*.spec.ts`, 142 more on full Chromium), not `leak/late-word.spec.ts` alone: with
9633
+ the nested cases gone the project had seven tests left, and a served display out of process is
9634
+ the setting the removed guesses failed in. No served case needed a change to pass there.
9635
+
9636
+ ## P150 · 2026-11-17 · An element pick says where it was picked (`pointDocument`) · Accepted
9637
+
9638
+ Amends P133 (what `selected` carries). From Raft (#proj-workspace:#315): a person picks an element
9639
+ that fills most of the frame (a long section, a whole card list) to comment on a part of it, and the
9640
+ host's comment card opens at the element's box, far from where they pointed.
9641
+
9642
+ **Context.** For an element pick the host knows the element's box (`rect`, clamped to the frame,
9643
+ P104) and its whole box in the document (`lastLineDocumentRect`, P133). Where that box is most of the
9644
+ frame, every place derived from it (its corner, its end, its middle) can be a screen away from what
9645
+ the person clicked. The shell knows the point: the element is found under it.
9646
+
9647
+ **Decision.**
9648
+ 1. **`pointDocument`** on `selected`, for an element picked by a pointer only: `{ x, y }`, the point
9649
+ the element was picked at in the frame's viewport (a click's or a tap's, the point the element is
9650
+ found under; a held finger's press, P112), plus the `scroll` the report already carries, in the
9651
+ coordinates of `documentRect` (P132). Read from the event's `clientX`/`clientY` and `placeOf`'s
9652
+ one scroll, so it and the last line agree. A pick from the keyboard (a click with no `detail`)
9653
+ has none, nor does a text selection.
9654
+ 2. **The host checks it** as it checks a `scroll`: two finite numbers within
9655
+ `ANNOTATION_LIMITS.coordinate`. A malformed one drops the whole report (a refusal, as a malformed
9656
+ box). One without `scroll` drops the report, as a last line without it does (P137): its place in
9657
+ the frame's viewport is it less the scroll. One on a text selection drops the report too: a shell
9658
+ never sends it there, and a report is dropped, never repaired (P053).
9659
+ 3. **Unclamped**, as `documentRect` and `lastLineDocumentRect` are: the host clips what it draws from
9660
+ it to the frame's box (THREAT_MODEL §6). `rect` stays clamped.
9661
+
9662
+ **Compatibility.** Optional and only added. An older shell sends none, and a host places by `rect`
9663
+ or the last line as before; an older host drops it (each report is rebuilt from known fields).
9664
+
9665
+ **Threat.** None opened, and no isolation change: no wall, gate, rate or method moves. It is the
9666
+ page's word, as every box is: a page can say any point, which places the host's own UI somewhere in
9667
+ the page's own document, and the host clips that to the frame, so it reaches no further than
9668
+ `documentRect` already does (P132). It grants nothing and is never a fact about the person's press:
9669
+ a page can send it for a pick that wasn't, within the checks a `selected` already has (taken only
9670
+ while the host asked for elements). The page learns nothing new (it goes from the frame to the host).
9671
+
9672
+ **Tested.** `test/annotate.test.ts` "the point picked (P150)": kept on an element pick, rebuilt from
9673
+ known fields, unclamped; malformed ones (`NaN`, `Infinity`, a string, no `y`, past the limit, an
9674
+ array) drop the report; none without `scroll`, none on a text selection; through `createHost`,
9675
+ `rect` clamped and the point as the shell said. `leak/annotate.spec.ts` "an element pick says where
9676
+ it was clicked…" (three engines; written here and not run, test runs being paused where it was
9677
+ written: CI runs it): a click on a block taller than the frame, the page scrolled, reports the
9678
+ click's point plus the scroll; a pick from the keyboard reports none.
9679
+
9680
+ **Rejected.**
9681
+ - The press (`pointerdown`) rather than the click's point: a press dragged past an element picks the
9682
+ one under the release, and a card at the press would sit beside the wrong element.
9683
+ - The point in the frame's viewport, clamped, like `rect`: it would move with every scroll, and a
9684
+ host following the pick (P138) places from document coordinates already.
9685
+ - A point on text selections: the selection's last line places a composer already (P133).
9686
+
9687
+ **Revisit when** a host wants the point followed as the element moves (P138's `selectionTracked`
9688
+ carries boxes only), or a pick from the keyboard should say a point (the focused element's own).