@botiverse/porthole 0.16.0 → 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.
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
@@ -9629,3 +9632,57 @@ as abuse its own handler can't bound; or a host needs an opaque page inside a sh
9629
9632
  (`leak/served/*.spec.ts`, 142 more on full Chromium), not `leak/late-word.spec.ts` alone: with
9630
9633
  the nested cases gone the project had seven tests left, and a served display out of process is
9631
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).