@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/CHANGELOG.md +12 -0
- package/dist/annotate/types.d.ts +15 -1
- package/dist/annotate/validate.js +19 -1
- package/dist/bridge/types.d.ts +1 -1
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +2 -1
- package/dist/platform/types.d.ts +1 -1
- package/dist/shell/annotate.d.ts +3 -0
- package/dist/shell/annotate.js +15 -5
- package/docs/ADOPTING.md +393 -980
- package/docs/DECISIONS.md +57 -0
- package/docs/DESIGN.md +1099 -1336
- package/docs/PRINCIPLES.md +85 -1
- package/docs/THREAT_MODEL.md +655 -997
- package/package.json +1 -1
- package/src/annotate/types.ts +12 -1
- package/src/annotate/validate.ts +23 -1
- package/src/bridge/types.ts +1 -1
- package/src/host/create-host.ts +2 -1
- package/src/platform/types.ts +1 -1
- package/src/shell/annotate.ts +15 -5
- package/docs/ARCHITECTURE.md +0 -326
- package/docs/OBJECTIVES.md +0 -116
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).
|