@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
@@ -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.0 (2026-10-20). A review on 2026-10-19 found gaps, and every
9
- decision it led to has merged but P096. A note **open until P096** means the gap exists in 0.9.0 and
10
- P096 is its planned fix; once it merges, the note becomes a guarantee. [§8](#8-fixes-in-flight)
11
- lists the decisions.
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 the negative
81
- controls of the runtime only, and its runner can count a control that didn't run as passed (open
82
- until P096).
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, with no click and
541
- any box. It can draw look-alike markers, or lay its own elements over Porthole's. The host takes
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
- - *What holds.* A real press or click on a marker reaches none of the content's handlers (the
552
- shell's first listener stops it; control `marker-click`), so content can't act on it or cancel
553
- it. But content can tell that a marker was pressed, and roughly where: the pointer leaving its
554
- own element names the layer, the layer matches `:hover` and `:active`, and the frame gets user
555
- activation.
556
- - *What doesn't.* Content can't read or reach inside the shell's layer (a closed shadow root),
557
- but it can hide, shrink, move or cover it (its scripts can rewrite the layer's style, lay
558
- elements over it, or transform the page it sits in), change its words so a mark is orphaned, or
559
- flood the shared rate so real reports are refused. An honest page's follow-up reports (after a
560
- scroll) are at most one a second, and only while a mark has a marker.
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); an anchor or a rect decides where
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 | Planned | The negative-control runner counts a control that didn't run as passed, and CI runs the runtime's controls only. | §4 |
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.9.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": {
@@ -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`, once a
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); `rect` is the
118
- * marker's box, to open the host's own UI beside it. The content can fake it for any mark the
119
- * host shows with a count, and can tell a real one happened: open the host's own view of that
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
 
@@ -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
- /** An anchor, rebuilt from its known fields; null if any part is malformed or too large. */
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 width = viewport !== undefined && Number.isFinite(viewport.width) ? viewport.width : 0;
120
- const height = viewport !== undefined && Number.isFinite(viewport.height) ? viewport.height : 0;
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
- /** The host's marks, checked before they go to the frame; throws on the first bad one. */
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
  }
@@ -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
+ }