@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.
- package/dist/annotate/types.d.ts +21 -7
- package/dist/annotate/validate.d.ts +18 -3
- package/dist/annotate/validate.js +29 -5
- package/dist/bridge/bridge.js +1 -51
- package/dist/bridge/unseen.d.ts +18 -0
- package/dist/bridge/unseen.js +71 -0
- package/dist/check/files.d.ts +2 -0
- package/dist/check/files.js +67 -50
- package/dist/check/lint.d.ts +8 -1
- package/dist/check/lint.js +18 -0
- package/dist/check/markup.d.ts +7 -0
- package/dist/check/markup.js +49 -0
- package/dist/check/page-source.js +1 -1
- package/dist/check/scroll.d.ts +100 -0
- package/dist/check/scroll.js +1429 -0
- package/dist/conformance/behavior.js +107 -68
- package/dist/conformance/clipboard.js +16 -14
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/limits.js +117 -64
- package/dist/conformance/probes.js +66 -49
- package/dist/conformance/runtime.js +6 -0
- package/dist/conformance/served.js +66 -63
- package/dist/guide/guide.js +1 -1
- package/dist/guide/runtime.js +2 -2
- package/dist/host/create-host.js +46 -4
- package/dist/index.d.ts +1 -1
- package/dist/platform/types.d.ts +4 -2
- package/dist/react/frame.d.ts +2 -1
- package/dist/runtime/requests.d.ts +5 -0
- package/dist/runtime/requests.js +16 -1
- package/dist/runtime/types.generated.js +1 -1
- package/dist/shell/annotate.d.ts +6 -3
- package/dist/shell/annotate.js +474 -104
- package/dist/shell/use.js +9 -1
- package/docs/ADOPTING.md +99 -1
- package/docs/ARCHITECTURE.md +2 -1
- package/docs/DECISIONS.md +764 -14
- package/docs/DESIGN.md +192 -42
- package/docs/THREAT_MODEL.md +109 -27
- package/package.json +1 -1
- package/src/annotate/types.ts +22 -7
- package/src/annotate/validate.ts +32 -6
- package/src/bridge/bridge.ts +1 -60
- package/src/bridge/unseen.ts +82 -0
- package/src/check/files.ts +68 -54
- package/src/check/lint.ts +24 -0
- package/src/check/markup.ts +53 -0
- package/src/check/scroll.ts +1757 -0
- package/src/conformance/behavior.ts +221 -69
- package/src/conformance/clipboard.ts +44 -14
- package/src/conformance/limits.ts +169 -76
- package/src/conformance/probes.ts +97 -49
- package/src/conformance/runtime.ts +9 -0
- package/src/conformance/served.ts +112 -63
- package/src/guide/guide.ts +1 -0
- package/src/guide/runtime.ts +2 -2
- package/src/host/create-host.ts +50 -4
- package/src/index.ts +1 -0
- package/src/platform/types.ts +4 -2
- package/src/react/frame.tsx +2 -1
- package/src/runtime/requests.ts +23 -1
- package/src/runtime/types.generated.ts +1 -1
- package/src/shell/annotate.ts +474 -104
- package/src/shell/use.ts +9 -1
- package/types/runtime/v1/comments.d.ts +14 -4
package/docs/THREAT_MODEL.md
CHANGED
|
@@ -5,10 +5,13 @@ What Porthole protects, from whom, and where that protection ends. For each way
|
|
|
5
5
|
guaranteed. [ADOPTING.md](ADOPTING.md) says how to set each one up, and
|
|
6
6
|
[DESIGN.md](DESIGN.md) lists every defense with the test that proves it.
|
|
7
7
|
|
|
8
|
-
**Status.** This describes Porthole 0.
|
|
9
|
-
decision it led to has merged
|
|
10
|
-
|
|
11
|
-
|
|
8
|
+
**Status.** This describes Porthole 0.12.0 (2026-10-26). A review on 2026-10-19 found gaps, and every
|
|
9
|
+
decision it led to has merged. P096 changed the negative-control runner and CI, and the shipped
|
|
10
|
+
conformance probes' messages and timing, not what they check. P104 (0.9.0's annotation markers) had
|
|
11
|
+
a review of its own, and P105, in 0.10.0, is what it led to. 0.11.0 adds draft marks (P107, §7
|
|
12
|
+
"Drafts": what a page learns from them and who may receive them) and an advisory lint (P106, no
|
|
13
|
+
change to isolation). 0.12.0 lets `comments.open` carry a draft (P108, §7: visible text only, and
|
|
14
|
+
the host's duties around it). [§8](#8-fixes-in-flight) lists the decisions.
|
|
12
15
|
|
|
13
16
|
## 1. Two layers
|
|
14
17
|
|
|
@@ -77,9 +80,9 @@ viewer and any declaration.
|
|
|
77
80
|
|
|
78
81
|
The leak suite attempts each channel in DESIGN.md's table from inside the content, on Chromium,
|
|
79
82
|
WebKit and Firefox, and most defenses have a negative control that takes the defense out to show
|
|
80
|
-
its probes then fail (DESIGN.md § "Egress hardening, each with its test"). CI runs
|
|
81
|
-
|
|
82
|
-
|
|
83
|
+
its probes then fail (DESIGN.md § "Egress hardening, each with its test"). CI runs every negative
|
|
84
|
+
control on all three engines, and a control passes only when its marked probes failed by their own
|
|
85
|
+
assertion (P096).
|
|
83
86
|
|
|
84
87
|
## 5. Out of scope
|
|
85
88
|
|
|
@@ -144,6 +147,16 @@ Whatever the use:
|
|
|
144
147
|
quoted text) only as text, never as HTML.
|
|
145
148
|
- Take what the frame reports about annotations as UI hints (where to draw, what to open), never
|
|
146
149
|
as permissions, and put nothing in a mark the page may not know (§7).
|
|
150
|
+
- Guard a view that a frame's report opens or moves (`activated`, `anchored`, `selected`: a
|
|
151
|
+
comment's bubble, a composer). The content chooses when it appears and where, so it can bring it
|
|
152
|
+
under a press the person meant for the content (a double click on the content's own button whose
|
|
153
|
+
second click lands on the bubble's). Such a view takes no press of any kind for 500 ms after it
|
|
154
|
+
appears or moves (not a `click` only: menu triggers act on `pointerdown`, and menu items click
|
|
155
|
+
themselves on a release), ignores a press that began before that, opens beside the frame rather
|
|
156
|
+
than over the report's box where the layout allows, takes no focus when it opens, and puts no
|
|
157
|
+
destructive action (resolve, delete) one click away. Its menus and popovers are part of it,
|
|
158
|
+
portaled ones too (P105; ADOPTING.md § Annotations has the code: the view `inert` while it
|
|
159
|
+
arms).
|
|
147
160
|
- List every app origin in `appOrigins` (`hostOrigins` in `/server`): only those may frame content,
|
|
148
161
|
and only those are checked against the content domain for a shared site.
|
|
149
162
|
- Under the app runtime, run `defineRuntimeConformance` with `api` in CI (§7).
|
|
@@ -528,7 +541,7 @@ wall on three engines, and `defineHostConformance` runs it against a host's own
|
|
|
528
541
|
**The host must** do what [every host](#what-every-host-must-do) does, write the handlers (their
|
|
529
542
|
effects are its own), and group displays by page (S7).
|
|
530
543
|
|
|
531
|
-
**Annotations** (`annotate`, P053, P104). The shell that draws marks and reports anchors shares
|
|
544
|
+
**Annotations** (`annotate`, P053, P104, P107). The shell that draws marks and reports anchors shares
|
|
532
545
|
its realm with the content, so:
|
|
533
546
|
|
|
534
547
|
- *What content learns.* Everything the host sends in a `show` is posted into the frame's window,
|
|
@@ -536,31 +549,87 @@ its realm with the content, so:
|
|
|
536
549
|
its marker). A host gives ids that say nothing (never a person's name or a comment's words), and
|
|
537
550
|
a count only where the page may know how many there are. Who commented and what they wrote stay
|
|
538
551
|
in the host's own UI, outside the frame.
|
|
552
|
+
- *Drafts* (P107). A mark with `kind: "draft"` (a comment its author hasn't posted) is drawn apart,
|
|
553
|
+
a dashed line and a hollow marker with no number, so the page also learns which of its marks are
|
|
554
|
+
drafts: that the person viewing it is writing a comment there, before they post it. That is new
|
|
555
|
+
information for the page, accepted where the page has no way out: drafts are the host's to send
|
|
556
|
+
only to their author's own frame (Porthole can't tell whose frame it is), the page is the one
|
|
557
|
+
being commented on and already sees where the person selects (`selected`), and closed egress
|
|
558
|
+
([§4](#4-two-lines-of-defense)) keeps it off the network. Closed egress doesn't cover the
|
|
559
|
+
channels the host itself opens, and through them a draft's existence, place and timing can
|
|
560
|
+
leave: a page with the runtime's `db` (writes) and `user` can call `user.get()`, read the marks
|
|
561
|
+
shown to it, and write "viewer A is drafting at section 3" where its author and other viewers
|
|
562
|
+
read it before A posts; once A posts, the page can tie that posted comment to A (the anchor and
|
|
563
|
+
the time match). Origins a config declares for egress (an MCP App's `connectDomains`, S5; an
|
|
564
|
+
`egress` a host opened in its own config; the `liveWidget` preset itself has none, P103), and a
|
|
565
|
+
host function that sends the page's words somewhere, are channels of the same kind (S4, and the
|
|
566
|
+
app runtime below). A host that sends drafts to such a page accepts that its author and other viewers can
|
|
567
|
+
learn of them. A draft carries nothing else: the host drops its count before the frame (control
|
|
568
|
+
`draft-count`), so a page can't read how many drafts are at an anchor unless the host sends a
|
|
569
|
+
mark per draft, and its id is the host's, as any mark's (random, never the draft's words). A host
|
|
570
|
+
that sends drafts into a frame others see (a shared screen, a frame several viewers share) tells
|
|
571
|
+
that page, and anything it draws for them, what its author hasn't posted.
|
|
539
572
|
- *What content can fake.* Any report: a selection while the host asks for one, where marks are,
|
|
540
|
-
and a marker's click (`activated`) for any mark the host shows with a count,
|
|
541
|
-
any box. It can draw look-alike markers, or lay its own elements over Porthole's.
|
|
542
|
-
each report only for what it asked for and its own shown ids, rebuilt within
|
|
573
|
+
and a marker's click (`activated`) for any mark the host shows with a marker (a count, or a draft:
|
|
574
|
+
P107), without a click on it and with any box. It can draw look-alike markers, or lay its own elements over Porthole's.
|
|
575
|
+
The host takes each report only for what it asked for and its own shown ids, rebuilt within
|
|
543
576
|
`ANNOTATION_LIMITS`, at 120 a minute; `activated` for a mark without a marker, or an id it
|
|
544
|
-
doesn't show, is dropped (negative control `annotation-activated`).
|
|
577
|
+
doesn't show, is dropped (negative control `annotation-activated`). `activated` is also taken
|
|
578
|
+
only while the host's page has transient user activation, which a real marker click or tap gives
|
|
579
|
+
it (P105, measured on all three engines; control `annotation-activated-gesture`). That stops a
|
|
580
|
+
page opening the host's view with no gesture at all, nothing more: activation lasts 5 s after any
|
|
581
|
+
gesture anywhere on the page (a click on the host's own UI, typing in the content, the click that
|
|
582
|
+
opened the display), and a fake posted then, on a timer or a scroll, is taken; one posted on the
|
|
583
|
+
person's own press in the content lands under their pointer. The guard on the host's view (§6) is
|
|
584
|
+
the defence, not this. Where the platform can't tell (a custom one whose `userActivation()`
|
|
585
|
+
answers undefined), the report passes, as the gesture gate does.
|
|
586
|
+
- *Labels.* An anchor's `label` is the page's text: the words selected, or an element's own words,
|
|
587
|
+
else its `alt`, `aria-label` or `title`, which the person never sees on the page. The host takes
|
|
588
|
+
out of every label everything a person can't see (every format character, bidi controls and
|
|
589
|
+
zero-width ones among them, every default-ignorable code point, variation selector, tag,
|
|
590
|
+
private-use character and control: P105, with none of P100's exceptions for emoji and shaped
|
|
591
|
+
letters, whose surroundings a page can fake), so what it shows is what it has. A text
|
|
592
|
+
anchor's quote (`exact`) keeps them, to be found again: a host that hands a quote or a label to
|
|
593
|
+
a model hands it the page's words, to be read as that, never as instructions.
|
|
545
594
|
- *Boxes.* Every box a report carries (`selected`, `activated`, `anchored`) is the page's word.
|
|
546
595
|
Porthole clamps each to the frame's viewport as it is when the report arrives, before the host
|
|
547
596
|
hears it: the part inside is kept, and a box wholly outside becomes one of no size on the
|
|
548
597
|
nearest edge (control `annotation-rect-clamp`). So a page can't make the host place its own UI
|
|
549
598
|
over the rest of the app. It still chooses any point inside its own frame: a box is a
|
|
550
|
-
positioning hint, never a fact about the content.
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
- *What
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
599
|
+
positioning hint, never a fact about the content. The box is in the frame's own CSS px, its
|
|
600
|
+
layout size: a host that scales or transforms the frame (a thumbnail, a zoomed preview) maps the
|
|
601
|
+
box through that transform before placing anything by it. A platform's `viewport()` that answers
|
|
602
|
+
no size, or throws, clamps every box to nothing at the frame's corner (P105). The frame's size is
|
|
603
|
+
read for every report the host takes, before the report's rate: a forced layout of the host's
|
|
604
|
+
page per message, which a repeated `ui/initialize` already causes (accepted, P105).
|
|
605
|
+
- *What holds, against content that patches none of the DOM's or JavaScript's built-ins.* A real
|
|
606
|
+
press or click on a marker reaches none of the content's handlers (the shell's first listener
|
|
607
|
+
stops it; control `marker-click`) and moves neither focus nor a selection (control
|
|
608
|
+
`marker-prevent`), so content can't act on it or cancel it; nor can it read or reach inside the
|
|
609
|
+
shell's layer (a closed shadow root). Content can still tell that a marker was pressed, and
|
|
610
|
+
roughly where: the pointer leaving its own element names the layer, the layer matches `:hover`
|
|
611
|
+
and `:active`, and the frame gets user activation.
|
|
612
|
+
- *What doesn't hold against content that does.* The shell shares the content's realm. It reads
|
|
613
|
+
and stops a marker's press through the platform's own functions and getters, kept before
|
|
614
|
+
content runs (P105, control `marker-originals`), so patching `Event`'s or `MouseEvent`'s
|
|
615
|
+
prototypes no longer lets content hear a press or make the shell misread one. But the layer's
|
|
616
|
+
nodes pass through built-ins content can replace (the shell's insertion guards call
|
|
617
|
+
`Element.prototype.matches` on them), so content can reach the closed shadow root that way,
|
|
618
|
+
read the markers and rewrite them (the review of P104, on all three engines). Nothing in the
|
|
619
|
+
layer is secret: it holds only what `show` sent, which the content can read anyway.
|
|
620
|
+
- *What content can always do.* Hide, shrink, move or cover the layer (its scripts can rewrite the
|
|
621
|
+
layer's style, lay elements over it, or transform the page it sits in), change its words so a
|
|
622
|
+
mark is orphaned, or flood the shared rate so real reports are refused. It can also make the
|
|
623
|
+
shell's own work dear by its layout: finding marks again and placing markers after a change of
|
|
624
|
+
the content runs in the frame, once per quiet run of changes, and each marker in view is placed
|
|
625
|
+
by a bounded number of hit tests (measured with 300 marks with counts in view: about 20 ms a
|
|
626
|
+
change; 200 in a 3,000-line block: 25 to 50 ms; P105). In an opaque frame that shares the host's
|
|
627
|
+
process, that time is the host's too ([§5](#5-out-of-scope)). An honest page's
|
|
628
|
+
follow-up reports, of the marks (while one has a marker) and of the person's selection after a
|
|
629
|
+
scroll, share one clock: at most one a second together, each only when its box moved (P105).
|
|
561
630
|
- So `activated` opens the host's own view of a mark it already shows, placed within the frame's
|
|
562
|
-
box, and never acts on it (no resolve, delete or reply);
|
|
563
|
-
something is drawn, never who may see or do anything.
|
|
631
|
+
box (better: beside it), guarded as §6 says, and never acts on it (no resolve, delete or reply);
|
|
632
|
+
an anchor or a rect decides where something is drawn, never who may see or do anything.
|
|
564
633
|
|
|
565
634
|
### The app runtime
|
|
566
635
|
|
|
@@ -593,7 +662,10 @@ section.
|
|
|
593
662
|
code-typed asset runs as code only when an admin uploaded it where uploaded code may run, and
|
|
594
663
|
only while the config still lets uploaded code run, asked at every load, in bearer mode too
|
|
595
664
|
(where every artifact config must; P103); anything else is a download.
|
|
596
|
-
- `comments` is write-only: the page learns only whether the composer opened.
|
|
665
|
+
- `comments` is write-only: the page learns only whether the composer opened. A draft it gives
|
|
666
|
+
(P108) is at most 2,000 characters of text a person can see: no zero-width, bidi or tag
|
|
667
|
+
characters, no controls but a new line and a tab (P100's `unseen`); anything else is refused
|
|
668
|
+
before the handler.
|
|
597
669
|
- `defineRuntimeConformance` checks the host's handlers, and with `api` its own API for `db`,
|
|
598
670
|
`artifact` and `assets`, with a forged context (a viewer claiming to be the owner, no rules).
|
|
599
671
|
|
|
@@ -609,6 +681,12 @@ section.
|
|
|
609
681
|
- Keep each person's data apart in its own stores, and refuse moved bases and versions
|
|
610
682
|
(`Refused("conflict")`).
|
|
611
683
|
- Handle abuse on shared pages (S4).
|
|
684
|
+
- Show a comment's draft (P108) whole, as the person's editable plain text in its own composer,
|
|
685
|
+
and post it only on the person's own Send, never on the page's word. A composer that opens with
|
|
686
|
+
a draft is a view the content brought (§6's guard): it takes no press, and no Enter that sends,
|
|
687
|
+
for 500 ms after it opens, doesn't focus Send, and opens beside the frame where it can. Once
|
|
688
|
+
posted, the comment is the person's: mentions in it act as theirs, which is why they must see
|
|
689
|
+
it all first.
|
|
612
690
|
|
|
613
691
|
**Not guaranteed**
|
|
614
692
|
|
|
@@ -617,6 +695,10 @@ section.
|
|
|
617
695
|
page's rules allow) can read it.
|
|
618
696
|
- `db` rewrites only paths: an id the page stores inside a document's data is returned as stored.
|
|
619
697
|
- In bearer mode, assets are served by id alone, without the host's check.
|
|
698
|
+
- A draft is the page's words in the person's composer: a person who posts it without reading
|
|
699
|
+
posts what the page chose, and an agent that reads the comment takes it as theirs. Porthole
|
|
700
|
+
bounds what can hide in it (visible text, 2,000 characters, a click to open); reading it is the
|
|
701
|
+
person's.
|
|
620
702
|
|
|
621
703
|
## 8. Fixes in flight
|
|
622
704
|
|
|
@@ -630,7 +712,7 @@ says what was wrong, what holds now, and the limit its decision accepts, if any.
|
|
|
630
712
|
| P093 | Merged | `intersectDeclarations` compared rules name by name, so a current wildcard didn't narrow a version's named rule, and a collection named `__proto__` was lost. Now the result allows exactly what both sides allow. | §7 |
|
|
631
713
|
| P094 | Merged | Without a viewer, a page's declared `data` names weren't held; a pushed result answered a read past `readData`'s gates; `db.batch` and `db.watch` skipped their inner methods' `methodGates`. Now each holds. | §4, S2, S4, §7 |
|
|
632
714
|
| P095 | Merged | What content sent was read before its gate: a log or error report was serialized whole first; waiting confirmations had no cap. Now the bridge reads it after the gate into bounded text, nothing a page sends throws out of an adapter, and at most 10 confirmations wait per display. | §5, S1, S5 |
|
|
633
|
-
| P096 |
|
|
715
|
+
| P096 | Merged | The negative-control runner counts a control that didn't run as passed, and CI runs the runtime's controls only. | §4 |
|
|
634
716
|
| P097 | Merged | A release waits for the same commit's CI. No guarantee here depends on it. | |
|
|
635
717
|
| P098 | Merged | A set's page whose notice came late was taken for a navigation away (red on Chromium since 0.6.0), and tests that waited a fixed time. Accepted: a files display may hold a frame that did navigate away for up to 2 s before starting it again, delivering nothing while it waits. | S1 |
|
|
636
718
|
| P099 | Merged | A served page in a tab had no sandbox: `window.open` sent input out, it could navigate its opener, open a picture-in-picture window, and ask for the camera, location or full screen. Now its headers carry its frame's sandbox and deny what its frame's `allow` doesn't grant, and the shell closes those on a tab too; the served suite probes self-navigation in frames and tabs. A browser without the Navigation API is an accepted limit. | S4 |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.12.0",
|
|
4
4
|
"description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
|
|
5
5
|
"homepage": "https://github.com/botiverse/porthole#readme",
|
|
6
6
|
"bugs": {
|
package/src/annotate/types.ts
CHANGED
|
@@ -50,7 +50,9 @@ export interface AnnotationAnchor {
|
|
|
50
50
|
/**
|
|
51
51
|
* A box in the frame's viewport, CSS px: add the frame element's position to place it on the page.
|
|
52
52
|
* The page's word: the host clamps each it reports to the frame's viewport (P104), so one wholly
|
|
53
|
-
* outside is a box of no size on the nearest edge. A positioning hint only.
|
|
53
|
+
* outside is a box of no size on the nearest edge. A positioning hint only. It is in the frame's
|
|
54
|
+
* own layout px: a host that scales or transforms the frame maps it through that transform too
|
|
55
|
+
* (P105).
|
|
54
56
|
*/
|
|
55
57
|
export interface AnnotationRect {
|
|
56
58
|
readonly x: number;
|
|
@@ -79,11 +81,23 @@ export interface AnnotationMark {
|
|
|
79
81
|
* A marker (P104): with a count, the shell also draws a small bubble with this number (0 to
|
|
80
82
|
* `ANNOTATION_LIMITS.count`; above 99 it reads "99+", 0 draws the bubble alone) at the end of a
|
|
81
83
|
* text anchor and the top right of an element. The person can click it: the frame reports
|
|
82
|
-
* `activated`. The content can read the number; give one only where the page may know it.
|
|
84
|
+
* `activated`. The content can read the number; give one only where the page may know it. A
|
|
85
|
+
* draft's is dropped (P107): its marker has no number.
|
|
83
86
|
*/
|
|
84
87
|
readonly count?: number;
|
|
88
|
+
/**
|
|
89
|
+
* What the mark is (P107): `"posted"` (the default, as absent) or `"draft"`, a comment its
|
|
90
|
+
* author hasn't submitted yet. A draft is drawn apart (a dashed line and a hollow marker with no
|
|
91
|
+
* number) and has a marker whether or not it has a count; its count is dropped before the mark
|
|
92
|
+
* goes to the frame. The content can read that a mark is a draft: send drafts only to their
|
|
93
|
+
* author's own frame.
|
|
94
|
+
*/
|
|
95
|
+
readonly kind?: AnnotationMarkKind;
|
|
85
96
|
}
|
|
86
97
|
|
|
98
|
+
/** A posted comment's mark, or an unsubmitted draft's (P107). */
|
|
99
|
+
export type AnnotationMarkKind = "posted" | "draft";
|
|
100
|
+
|
|
87
101
|
/** Whether a mark's anchor was found in the content as it is now. */
|
|
88
102
|
export type AnchorState = "attached" | "orphaned";
|
|
89
103
|
|
|
@@ -108,16 +122,17 @@ export type AnnotationReport =
|
|
|
108
122
|
| { readonly type: "cancelled" }
|
|
109
123
|
/**
|
|
110
124
|
* Where the marked anchors are now: every mark after `show`, the focused one after `focus`,
|
|
111
|
-
* every mark when the content changed one's state, and, while any mark has a `count`,
|
|
125
|
+
* every mark when the content changed one's state, and, while any mark has a marker (a `count`,
|
|
126
|
+
* or a draft, P107), once a
|
|
112
127
|
* scroll, a resize or a change of the content has settled, only the marks that moved since the
|
|
113
128
|
* host was last told, at most once a second (P104).
|
|
114
129
|
*/
|
|
115
130
|
| { readonly type: "anchored"; readonly results: readonly AnchorResult[] }
|
|
116
131
|
/**
|
|
117
|
-
* The person clicked the marker of a mark the host shows with a `count` (P104)
|
|
118
|
-
* marker's box, to open the host's own UI beside it. The content can fake
|
|
119
|
-
* host shows with a
|
|
120
|
-
* mark, never act on it.
|
|
132
|
+
* The person clicked the marker of a mark the host shows with a `count` (P104), or of a draft
|
|
133
|
+
* (P107); `rect` is the marker's box, to open the host's own UI beside it. The content can fake
|
|
134
|
+
* it for any mark the host shows with a marker, and can tell a real one happened: open the
|
|
135
|
+
* host's own view of that mark, never act on it.
|
|
121
136
|
*/
|
|
122
137
|
| { readonly type: "activated"; readonly id: string; readonly rect: AnnotationRect };
|
|
123
138
|
|
package/src/annotate/validate.ts
CHANGED
|
@@ -8,6 +8,7 @@ import {
|
|
|
8
8
|
type AnnotationReport,
|
|
9
9
|
type AnnotationSelector,
|
|
10
10
|
} from "./types.ts";
|
|
11
|
+
import { withoutUnseen } from "../bridge/unseen.ts";
|
|
11
12
|
|
|
12
13
|
/**
|
|
13
14
|
* The host's checks on what a frame says about annotations (P053), and on anchors a host stores
|
|
@@ -60,7 +61,12 @@ function selector(value: unknown): AnnotationSelector | null {
|
|
|
60
61
|
}
|
|
61
62
|
}
|
|
62
63
|
|
|
63
|
-
/**
|
|
64
|
+
/**
|
|
65
|
+
* An anchor, rebuilt from its known fields; null if any part is malformed or too large. Its label
|
|
66
|
+
* is text for the person, so what they couldn't see is taken out of it (P105: a wordless element's
|
|
67
|
+
* `alt`, `aria-label` or `title`, which the page never shows, can carry bidi controls or zero-width
|
|
68
|
+
* characters); its selectors' words are kept as they are, to be found again.
|
|
69
|
+
*/
|
|
64
70
|
export function parseAnchor(value: unknown): AnnotationAnchor | null {
|
|
65
71
|
if (!isRecord(value) || (value.kind !== "element" && value.kind !== "text")) {
|
|
66
72
|
return null;
|
|
@@ -85,7 +91,7 @@ export function parseAnchor(value: unknown): AnnotationAnchor | null {
|
|
|
85
91
|
if (value.kind === "text" ? !quote : !css && !quote) {
|
|
86
92
|
return null;
|
|
87
93
|
}
|
|
88
|
-
return { kind: value.kind, selectors, label: value.label };
|
|
94
|
+
return { kind: value.kind, selectors, label: withoutUnseen(value.label) };
|
|
89
95
|
}
|
|
90
96
|
|
|
91
97
|
const coordinate = (value: unknown): value is number =>
|
|
@@ -114,10 +120,11 @@ export function parseRect(value: unknown): AnnotationRect | null {
|
|
|
114
120
|
*/
|
|
115
121
|
export function clampRect(
|
|
116
122
|
rect: AnnotationRect,
|
|
117
|
-
viewport: { readonly width: number; readonly height: number } | undefined,
|
|
123
|
+
viewport: { readonly width: number; readonly height: number } | null | undefined,
|
|
118
124
|
): AnnotationRect {
|
|
119
|
-
const
|
|
120
|
-
const
|
|
125
|
+
const known = viewport !== null && typeof viewport === "object";
|
|
126
|
+
const width = known && Number.isFinite(viewport.width) ? viewport.width : 0;
|
|
127
|
+
const height = known && Number.isFinite(viewport.height) ? viewport.height : 0;
|
|
121
128
|
const within = (value: number, most: number) => Math.min(Math.max(value, 0), Math.max(0, most));
|
|
122
129
|
const left = within(rect.x, width);
|
|
123
130
|
const top = within(rect.y, height);
|
|
@@ -191,7 +198,19 @@ export function annotateMode(mode: AnnotateMode | undefined): Required<AnnotateM
|
|
|
191
198
|
return { elements, text: words };
|
|
192
199
|
}
|
|
193
200
|
|
|
194
|
-
/**
|
|
201
|
+
/**
|
|
202
|
+
* Whether a mark gets a marker, the one thing a person can click (P104): one with a `count`, and
|
|
203
|
+
* every draft (P107).
|
|
204
|
+
*/
|
|
205
|
+
export const hasMarker = (mark: AnnotationMark): boolean =>
|
|
206
|
+
mark.count !== undefined || mark.kind === "draft";
|
|
207
|
+
|
|
208
|
+
/**
|
|
209
|
+
* The host's marks, checked before they go to the frame; throws on the first bad one. Each is
|
|
210
|
+
* rebuilt as the frame gets it: a posted mark as 0.10.0 sent it (no `kind`), a draft with
|
|
211
|
+
* `kind: "draft"` and without its count (P107: a draft's marker shows no number, so the page isn't
|
|
212
|
+
* told one).
|
|
213
|
+
*/
|
|
195
214
|
export function checkMarks(marks: readonly AnnotationMark[]): AnnotationMark[] {
|
|
196
215
|
if (!Array.isArray(marks) || marks.length > LIMITS.marks) {
|
|
197
216
|
throw new TypeError(`annotations.show: at most ${LIMITS.marks} marks`);
|
|
@@ -209,7 +228,14 @@ export function checkMarks(marks: readonly AnnotationMark[]): AnnotationMark[] {
|
|
|
209
228
|
`annotations.show: mark ${index}'s count is a whole number from 0 to ${LIMITS.count}`,
|
|
210
229
|
);
|
|
211
230
|
}
|
|
231
|
+
const kind: unknown = mark.kind;
|
|
232
|
+
if (kind !== undefined && kind !== "posted" && kind !== "draft") {
|
|
233
|
+
throw new TypeError(`annotations.show: mark ${index}'s kind is "posted" or "draft"`);
|
|
234
|
+
}
|
|
212
235
|
seen.add(mark.id);
|
|
236
|
+
if (kind === "draft") {
|
|
237
|
+
return { id: mark.id, anchor, kind };
|
|
238
|
+
}
|
|
213
239
|
return { id: mark.id, anchor, ...(mark.count === undefined ? {} : { count: mark.count }) };
|
|
214
240
|
});
|
|
215
241
|
}
|
package/src/bridge/bridge.ts
CHANGED
|
@@ -12,6 +12,7 @@ import type { PortholeConfig } from "../config/schema.ts";
|
|
|
12
12
|
import { callGates, effectiveGates } from "../compile/policy.ts";
|
|
13
13
|
import { boundedText } from "./bounded-text.ts";
|
|
14
14
|
import { isJsonData } from "./json-data.ts";
|
|
15
|
+
import { unseen } from "./unseen.ts";
|
|
15
16
|
import { blockedNavigationMessage, cutText, withoutSealedAddresses } from "./navigation.ts";
|
|
16
17
|
import {
|
|
17
18
|
RUNTIME_HOST_FUNCTIONS,
|
|
@@ -165,66 +166,6 @@ function resourceUri(args: unknown): { uri: string } | null {
|
|
|
165
166
|
/** The most text blocks one model context update holds. */
|
|
166
167
|
const MAX_CONTEXT_BLOCKS = 100;
|
|
167
168
|
|
|
168
|
-
/**
|
|
169
|
-
* What a person can't see but a model reads (the review of P100): format characters (zero-width
|
|
170
|
-
* ones, bidi controls, the tags U+E0000–E007F, a soft hyphen, a byte-order mark), variation
|
|
171
|
-
* selectors (U+FE00–FE0F, U+E0100–E01EF), private-use characters, lone surrogates, every
|
|
172
|
-
* default-ignorable code point (the re-check: U+034F, Mongolian's free variation selectors, the
|
|
173
|
-
* Hangul fillers, Khmer's inherent vowels), and controls other than a new line and a tab. An update with any is refused, never escaped: an escaped one
|
|
174
|
-
* reads to the model differently from what the person was shown.
|
|
175
|
-
*/
|
|
176
|
-
const UNSEEN =
|
|
177
|
-
/[\p{Cf}\p{Co}\p{Cs}\p{Default_Ignorable_Code_Point}\u{FE00}-\u{FE0F}\u{E0100}-\u{E01EF}]|[^\P{Cc}\n\t]/u;
|
|
178
|
-
|
|
179
|
-
/**
|
|
180
|
-
* The parts of real emoji that draw as nothing alone, allowed only where an emoji has them (the
|
|
181
|
-
* re-review of P100): U+FE0E or U+FE0F directly after a pictograph, or after a keycap base
|
|
182
|
-
* (`[0-9#*]`) that U+20E3 follows; U+200D only between two pictographs, a selector or a skin tone
|
|
183
|
-
* after the first. Each carries at most one choice beside a visible emoji (a selector there or
|
|
184
|
-
* not, a joiner there or not), never letters a model would read. Tag characters stay refused:
|
|
185
|
-
* subdivision flags too.
|
|
186
|
-
*/
|
|
187
|
-
const EMOJI_PARTS =
|
|
188
|
-
"(?<=\\p{Extended_Pictographic})[\\uFE0E\\uFE0F]|(?<=[0-9#*])[\\uFE0E\\uFE0F](?=\\u20E3)|(?<=\\p{Extended_Pictographic}[\\uFE0F\\p{Emoji_Modifier}]?)\\u200D(?=\\p{Extended_Pictographic})";
|
|
189
|
-
|
|
190
|
-
/**
|
|
191
|
-
* The scripts whose letters U+200C and U+200D shape (Unicode's notes on the joiners: the cursive
|
|
192
|
-
* scripts, where they break or make a join, and the Indic ones and Myanmar, where they choose a
|
|
193
|
-
* conjunct, a half form or a ligature), by Script_Extensions.
|
|
194
|
-
*/
|
|
195
|
-
const SHAPING_SCRIPTS = [
|
|
196
|
-
"Arabic",
|
|
197
|
-
"Syriac",
|
|
198
|
-
"Nko",
|
|
199
|
-
"Mongolian",
|
|
200
|
-
"Devanagari",
|
|
201
|
-
"Bengali",
|
|
202
|
-
"Gurmukhi",
|
|
203
|
-
"Gujarati",
|
|
204
|
-
"Oriya",
|
|
205
|
-
"Tamil",
|
|
206
|
-
"Telugu",
|
|
207
|
-
"Kannada",
|
|
208
|
-
"Malayalam",
|
|
209
|
-
"Sinhala",
|
|
210
|
-
"Myanmar",
|
|
211
|
-
] as const;
|
|
212
|
-
|
|
213
|
-
const SHAPED = `[${SHAPING_SCRIPTS.map((name) => `\\p{scx=${name}}`).join("")}]`;
|
|
214
|
-
|
|
215
|
-
/**
|
|
216
|
-
* A joiner or non-joiner between two letters or marks of those scripts (Persian's میخواهم, a
|
|
217
|
-
* Hindi half form): the shape it chooses is what the person sees. One at a letter boundary, never
|
|
218
|
-
* doubled, first or last, or beside a letter of another script.
|
|
219
|
-
*/
|
|
220
|
-
const SHAPING_JOINERS = `(?<=[\\p{L}\\p{M}])(?<=${SHAPED})[\\u200C\\u200D](?=[\\p{L}\\p{M}])(?=${SHAPED})`;
|
|
221
|
-
|
|
222
|
-
/** What may be invisible alone and is allowed where it is seen: one pass, on the text as sent. */
|
|
223
|
-
const SEEN_IN_PLACE = new RegExp(`${EMOJI_PARTS}|${SHAPING_JOINERS}`, "gu");
|
|
224
|
-
|
|
225
|
-
/** Whether `text` holds what a person can't see, the parts of emoji and shaped letters aside. */
|
|
226
|
-
const unseen = (text: string): boolean => UNSEEN.test(text.replace(SEEN_IN_PLACE, ""));
|
|
227
|
-
|
|
228
169
|
/** Whether any string in `value`, a key or a value, holds what can't be seen (bounded JSON data). */
|
|
229
170
|
function holdsUnseen(value: unknown): boolean {
|
|
230
171
|
if (typeof value === "string") {
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a person can't see in text that a model or a host's UI reads (P100; P105 for labels): one
|
|
3
|
+
* definition, for the bridge's check of a model context update and the annotation labels' strip.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* What a person can't see but a model reads (the review of P100): format characters (zero-width
|
|
8
|
+
* ones, bidi controls, the tags U+E0000–E007F, a soft hyphen, a byte-order mark), variation
|
|
9
|
+
* selectors (U+FE00–FE0F, U+E0100–E01EF), private-use characters, lone surrogates, every
|
|
10
|
+
* default-ignorable code point (the re-check: U+034F, Mongolian's free variation selectors, the
|
|
11
|
+
* Hangul fillers, Khmer's inherent vowels), and controls other than a new line and a tab. An update with any is refused, never escaped: an escaped one
|
|
12
|
+
* reads to the model differently from what the person was shown.
|
|
13
|
+
*/
|
|
14
|
+
const UNSEEN =
|
|
15
|
+
/[\p{Cf}\p{Co}\p{Cs}\p{Default_Ignorable_Code_Point}\u{FE00}-\u{FE0F}\u{E0100}-\u{E01EF}]|[^\P{Cc}\n\t]/u;
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* The parts of real emoji that draw as nothing alone, allowed only where an emoji has them (the
|
|
19
|
+
* re-review of P100): U+FE0E or U+FE0F directly after a pictograph, or after a keycap base
|
|
20
|
+
* (`[0-9#*]`) that U+20E3 follows; U+200D only between two pictographs, a selector or a skin tone
|
|
21
|
+
* after the first. Each carries at most one choice beside a visible emoji (a selector there or
|
|
22
|
+
* not, a joiner there or not), never letters a model would read. Tag characters stay refused:
|
|
23
|
+
* subdivision flags too.
|
|
24
|
+
*/
|
|
25
|
+
const EMOJI_PARTS =
|
|
26
|
+
"(?<=\\p{Extended_Pictographic})[\\uFE0E\\uFE0F]|(?<=[0-9#*])[\\uFE0E\\uFE0F](?=\\u20E3)|(?<=\\p{Extended_Pictographic}[\\uFE0F\\p{Emoji_Modifier}]?)\\u200D(?=\\p{Extended_Pictographic})";
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* The scripts whose letters U+200C and U+200D shape (Unicode's notes on the joiners: the cursive
|
|
30
|
+
* scripts, where they break or make a join, and the Indic ones and Myanmar, where they choose a
|
|
31
|
+
* conjunct, a half form or a ligature), by Script_Extensions.
|
|
32
|
+
*/
|
|
33
|
+
const SHAPING_SCRIPTS = [
|
|
34
|
+
"Arabic",
|
|
35
|
+
"Syriac",
|
|
36
|
+
"Nko",
|
|
37
|
+
"Mongolian",
|
|
38
|
+
"Devanagari",
|
|
39
|
+
"Bengali",
|
|
40
|
+
"Gurmukhi",
|
|
41
|
+
"Gujarati",
|
|
42
|
+
"Oriya",
|
|
43
|
+
"Tamil",
|
|
44
|
+
"Telugu",
|
|
45
|
+
"Kannada",
|
|
46
|
+
"Malayalam",
|
|
47
|
+
"Sinhala",
|
|
48
|
+
"Myanmar",
|
|
49
|
+
] as const;
|
|
50
|
+
|
|
51
|
+
const SHAPED = `[${SHAPING_SCRIPTS.map((name) => `\\p{scx=${name}}`).join("")}]`;
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* A joiner or non-joiner between two letters or marks of those scripts (Persian's میخواهم, a
|
|
55
|
+
* Hindi half form): the shape it chooses is what the person sees. One at a letter boundary, never
|
|
56
|
+
* doubled, first or last, or beside a letter of another script.
|
|
57
|
+
*/
|
|
58
|
+
const SHAPING_JOINERS = `(?<=[\\p{L}\\p{M}])(?<=${SHAPED})[\\u200C\\u200D](?=[\\p{L}\\p{M}])(?=${SHAPED})`;
|
|
59
|
+
|
|
60
|
+
/** What may be invisible alone and is allowed where it is seen: one pass, on the text as sent. */
|
|
61
|
+
const SEEN_IN_PLACE = new RegExp(`${EMOJI_PARTS}|${SHAPING_JOINERS}`, "gu");
|
|
62
|
+
|
|
63
|
+
/** Whether `text` holds what a person can't see, the parts of emoji and shaped letters aside. */
|
|
64
|
+
export const unseen = (text: string): boolean => UNSEEN.test(text.replace(SEEN_IN_PLACE, ""));
|
|
65
|
+
|
|
66
|
+
/** Every code point `UNSEEN` names, each on its own. */
|
|
67
|
+
const UNSEEN_EACH = new RegExp(UNSEEN.source, "gu");
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* `text` without anything a person can't see (P105), for text Porthole only shows, never matches,
|
|
71
|
+
* as a wordless element's label is (an `alt`, `aria-label` or `title` the person never sees on the
|
|
72
|
+
* page): every format character (bidi controls and the zero-width ones among them), every
|
|
73
|
+
* default-ignorable code point, variation selector, private-use character and lone surrogate, and
|
|
74
|
+
* every control but a new line and a tab. No exceptions: not the parts of emoji, nor the joiners
|
|
75
|
+
* between shaped letters that `unseen` lets by, whose surroundings a page can fake (the review of
|
|
76
|
+
* P105: a Mongolian variation selector beside each joiner carried 48 of them through, a payload
|
|
77
|
+
* of six bytes). An emoji may lose its joiners (a family shows as its faces). Nothing `unseen`
|
|
78
|
+
* refuses is left.
|
|
79
|
+
*/
|
|
80
|
+
export function withoutUnseen(text: string): string {
|
|
81
|
+
return text.replace(UNSEEN_EACH, "");
|
|
82
|
+
}
|