@botiverse/porthole 0.10.0 → 0.13.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 +18 -6
- package/dist/annotate/validate.d.ts +11 -1
- package/dist/annotate/validate.js +18 -1
- package/dist/bridge/bridge.d.ts +8 -1
- package/dist/bridge/bridge.js +7 -0
- package/dist/bridge/unseen.d.ts +8 -0
- package/dist/bridge/unseen.js +17 -0
- package/dist/check/files.d.ts +2 -0
- package/dist/check/files.js +71 -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 +116 -0
- package/dist/check/scroll.js +1485 -0
- package/dist/config/capabilities.d.ts +16 -3
- package/dist/config/capabilities.js +1 -0
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/runtime.js +6 -0
- package/dist/guide/guide.js +1 -1
- package/dist/guide/runtime.js +2 -2
- package/dist/host/create-host.js +30 -3
- package/dist/host/types.d.ts +15 -0
- package/dist/index.d.ts +2 -1
- package/dist/index.js +1 -0
- package/dist/platform/focus-guard.d.ts +143 -0
- package/dist/platform/focus-guard.js +445 -0
- package/dist/platform/types.d.ts +18 -0
- package/dist/platform/web.js +22 -0
- package/dist/react/frame.d.ts +10 -1
- package/dist/react/frame.js +4 -0
- package/dist/runtime/requests.d.ts +5 -0
- package/dist/runtime/requests.js +41 -4
- package/dist/runtime/types.generated.js +1 -1
- package/dist/shell/annotate.d.ts +2 -1
- package/dist/shell/annotate.js +29 -12
- package/dist/shell/use.js +9 -1
- package/docs/ADOPTING.md +106 -5
- package/docs/ARCHITECTURE.md +2 -1
- package/docs/DECISIONS.md +741 -2
- package/docs/DESIGN.md +38 -9
- package/docs/THREAT_MODEL.md +146 -19
- package/package.json +1 -1
- package/src/annotate/types.ts +19 -6
- package/src/annotate/validate.ts +20 -1
- package/src/bridge/bridge.ts +17 -1
- package/src/bridge/unseen.ts +24 -0
- package/src/check/files.ts +72 -54
- package/src/check/lint.ts +24 -0
- package/src/check/markup.ts +53 -0
- package/src/check/scroll.ts +1825 -0
- package/src/config/capabilities.ts +16 -3
- package/src/conformance/runtime.ts +9 -0
- package/src/guide/guide.ts +1 -0
- package/src/guide/runtime.ts +2 -2
- package/src/host/create-host.ts +38 -3
- package/src/host/types.ts +13 -0
- package/src/index.ts +2 -0
- package/src/platform/focus-guard.ts +572 -0
- package/src/platform/types.ts +17 -0
- package/src/platform/web.ts +22 -0
- package/src/react/frame.tsx +12 -1
- package/src/runtime/requests.ts +50 -6
- package/src/runtime/types.generated.ts +1 -1
- package/src/shell/annotate.ts +29 -12
- package/src/shell/use.ts +9 -1
- package/types/runtime/v1/comments.d.ts +20 -6
package/docs/DESIGN.md
CHANGED
|
@@ -628,7 +628,10 @@ What both adopters still wrote after 0.2 moves into Porthole (ADOPTING.md is the
|
|
|
628
628
|
over the size, a document where a fragment goes that has no body, nested frames and plugins,
|
|
629
629
|
`document.write`. Warnings for the rest: a document sent as a widget (taken as its body,
|
|
630
630
|
`fragmentOf`), the clipboard, dialogs, forms, hosts outside egress, unpinned CDN libraries,
|
|
631
|
-
`position: fixed` in a flow layout, new windows without `openLink
|
|
631
|
+
`position: fixed` in a flow layout, new windows without `openLink`, the page's own styles
|
|
632
|
+
holding it to one screen (P106, P110: `src/check/scroll.ts`, a cascade of html, body and the
|
|
633
|
+
root's overflow, height and position; `lintFiles` reads the version's linked stylesheets too,
|
|
634
|
+
only those within its caps; advisory, so a throw in it says the page wasn't checked).
|
|
632
635
|
- **`admitContent(config, content, { refuseOn })`**: the show tool's gate. It refuses errors by
|
|
633
636
|
default with a text that says what to change; otherwise it shows the content (a widget's
|
|
634
637
|
document taken as its body) and returns the warnings as a note.
|
|
@@ -988,6 +991,10 @@ for that to lapse and click with raw input.
|
|
|
988
991
|
| Live data: a kept result is a read (P094) | a result the host pushed (`changed(result)`), or read after a stale answer, answers the frame's next read only past every gate a read has (level, names, rate, gesture, consent, confirm), with no new upstream call | `test/audit-gates.test.ts`; `leak/served/runtime.spec.ts`: "a read above the viewer's level: a result the host pushed is refused as a cold read is" | `live-held-read` → that case (all three) |
|
|
989
992
|
| The runtime: per-user data (P088) | `dbAccess`: `me` is the host's id; another's `data/users/<id>`, or anything else under `data`, refused at every level, in the bridge and the host | `test/runtime.test.ts`; `leak/served/runtime.spec.ts`: "a person's own data is theirs" | `db-private` → that case (all three) |
|
|
990
993
|
| The runtime: comments write-only (P090) | the bridge answers `comments` with `true` only for a handler's `true`; no read method | `test/runtime.test.ts`; `leak/served/runtime.spec.ts`: "comments are write-only" | `comments-result` → that case (all three) |
|
|
994
|
+
| The runtime: a comment's draft is visible text (P108) | the bridge refuses a draft that isn't a string, is blank, past 2,000 characters, or holds what a person can't see (`unseen`), before any handler | `test/runtime.test.ts`: "a draft (P108)"; `leak/served/runtime.spec.ts`: "a comment's draft is the host's to check" | `comment-draft` → that case (all three) |
|
|
995
|
+
| The runtime: a draft is visible text, strictly; the anchor beside it cleaned (P109) | a draft with a joiner (U+200C, U+200D) anywhere but between two letters or marks (first, last, doubled, beside a space or punctuation, in an emoji sequence), a line or paragraph separator, blank-looking text, more than 32 blanks or two blank lines in a row is refused; the label and quote lose what a person can't see, refused if nothing visible is left | `test/runtime.test.ts`: "a draft is visible text, strictly (P109)" | — (unit-tested: the bridge's own check, behind `comment-draft`'s) |
|
|
996
|
+
| The keyboard: the focus guard (P109) | a move of the keyboard from one of the host page's text fields into a display's frame that the person didn't make (no press on the frame, `:active` on Chromium and WebKit, the pointer coming over it on Firefox; no Tab; no gesture the page's own events don't explain) is undone once the move is over; three while typing within 10 s, or five within 2 s, stop the display | `test/focus-guard.test.ts`; `leak/served/runtime.spec.ts`: "a page that takes the keyboard while the person types in the host's composer…", "a page that takes the keyboard back on its own blur keeps none of it…" (GK-1), "a composer the host focuses with focusField…", "the person's own moves into the frame keep the keyboard…" | `focus-guard` → the first (all three) and the next two (Firefox); `focus-guard-watch` (the watch after a take-back, the look at every frame) → those two (Firefox) |
|
|
997
|
+
| The runtime: `comments.open` from the frame the person is in (P109) | its `user-activation` gate also needs the host page's focus in the calling frame (`CapabilitySpec.inFrame`, `Surface.focused`), after the focus guard | `leak/served/runtime.spec.ts`: "comments.open while the person types in the host's composer reaches no handler…" | `comments-in-frame` → that case (all three) |
|
|
991
998
|
| The asset library (P089, P091) | `/_blob/<id>` (or the frame's `<sealed base>__porthole/blob/<id>`) for an access to its artifact (a cookie, a sealed `Referer`, the sealed path), then the host's check, the store asked with it; typed by name, never a page, code only where trusted and uploaded code may run (asked at each load; by id alone, every artifact config must, P103), inert CSP, CORP, revalidated; the page's CSP opens `<origin>/_blob/` for images, media, fonts and data, for scripts and styles only where uploads are the admins' | `test/assets.test.ts` (a forged same-origin claim: 401; another artifact's session: 404; revoked: 403; bearer mode; a stricter config turns trusted code into a download, bearer mode too); `leak/served/runtime.spec.ts`: an upload loads in its frame; a set's page loads it; static `/_blob/` in a frame by `Referer` (Chromium, Firefox; WebKit sends only the origin: measured); "a script asset runs as code only if an admin uploaded it"; "scripts load from /_blob/ only where uploads are the admins'"; "an asset reaches only its own artifact's pages"; "an asset opened on its own runs nothing" | `blob-trusted` → the trusted-code case; `blob-script,blob-trusted` (two walls) → that case and the tab's CSP case; `blob-inert` → the opened-on-its-own case (all three; `scripts/controls.ts`) |
|
|
992
999
|
| Workers (P044, P045) | no Node module in `/server`; D1 tickets taken by one `DELETE … RETURNING` | `test/workers.test.ts` (workerd, no `nodejs_compat`, real D1: once per ticket, a race, anonymous, a revocation, flat names, reserved namespaces) | — |
|
|
993
1000
|
|
|
@@ -1027,13 +1034,13 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1027
1034
|
|-----------|---------|--------|
|
|
1028
1035
|
| host → frame | `porthole/annotate.start` | `{ elements, text }`: picking elements (the one under the pointer or finger outlined with its name; a click or tap picks it, never reaching the content; Escape cancels; one pick), selecting text (each settled selection), or both (a click picks, a drag selects) |
|
|
1029
1036
|
| host → frame | `porthole/annotate.stop` | — |
|
|
1030
|
-
| host → frame | `porthole/annotate.show` | `{ marks: [{ id, anchor, count? }], active? }`: drawn over the content in the shell's own layer (a closed shadow root), found again whenever the content changes; a mark with a `count` (0 to 999) also gets a marker (P104) |
|
|
1037
|
+
| host → frame | `porthole/annotate.show` | `{ marks: [{ id, anchor, count?, kind? }], active? }`: drawn over the content in the shell's own layer (a closed shadow root), found again whenever the content changes; a mark with a `count` (0 to 999) also gets a marker (P104); `kind: "draft"` (absent: posted) is drawn apart, with a marker and never a count (P107) |
|
|
1031
1038
|
| host → frame | `porthole/annotate.focus` | `{ id }`: scrolled into view inside the frame, made the active mark, flashed |
|
|
1032
1039
|
| host → frame | `porthole/annotate.clear` | — |
|
|
1033
1040
|
| frame → host | `porthole/annotate.selected` | `{ anchor, rect }`; after a scroll, the same selection again only if its box moved more than 0.5 px, on the follow-ups' clock (P105) |
|
|
1034
1041
|
| frame → host | `porthole/annotate.unselected` | — (the text selection went away) |
|
|
1035
1042
|
| frame → host | `porthole/annotate.cancelled` | — (Escape) |
|
|
1036
|
-
| frame → host | `porthole/annotate.anchored` | `{ results: [{ id, state: "attached" \| "orphaned", rect? }] }`: every mark after `show`, the one after `focus`, every mark when the content changed a state, and, while any mark has a `count
|
|
1043
|
+
| frame → host | `porthole/annotate.anchored` | `{ results: [{ id, state: "attached" \| "orphaned", rect? }] }`: every mark after `show`, the one after `focus`, every mark when the content changed a state, and, while any mark has a marker (a `count` or a draft, P107), once a scroll, a resize or a run of content changes has settled (150 ms quiet), only the marks that moved more than 0.5 px since the host was last told, at most one a second together with the selection's (P104, P105) |
|
|
1037
1044
|
| frame → host | `porthole/annotate.activated` | `{ id, rect }`: the person clicked a mark's marker; `rect` is the marker's (P104); taken only while the host's page has transient activation (P105) |
|
|
1038
1045
|
|
|
1039
1046
|
- **Anchors** are W3C Web Annotation selectors, at most one of each:
|
|
@@ -1078,8 +1085,17 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1078
1085
|
happened, by `:active`, `relatedTarget` and user activation. Markers step aside
|
|
1079
1086
|
while elements are picked. No tab stop, and the layer stays `aria-hidden`: the
|
|
1080
1087
|
host's own list of marks is the keyboard path.
|
|
1081
|
-
- **
|
|
1082
|
-
|
|
1088
|
+
- **Drafts** (P107). A mark with `kind: "draft"` (a comment not yet posted) has a
|
|
1089
|
+
marker whether or not it has a count, placed as a posted one's, and drawn apart: a
|
|
1090
|
+
dashed underline (a dashed outline on an element), a lighter fill, and a hollow
|
|
1091
|
+
marker (a light bubble with a dashed edge and the glyph's outline) with no number.
|
|
1092
|
+
`checkMarks` sends a posted mark as before (no `kind`), a draft without its count,
|
|
1093
|
+
and throws on any other kind; the shell draws no number for a draft and drops a
|
|
1094
|
+
mark of a kind it doesn't know. Its click is `activated`, its place `anchored`,
|
|
1095
|
+
and it is followed after a scroll, as a posted marker's.
|
|
1096
|
+
- **Following** (P104), only while a mark has a marker (a `count`, or a draft:
|
|
1097
|
+
P107). Each mark keeps what the host was last told (state and box); a settled
|
|
1098
|
+
scroll or resize (any scroller), or
|
|
1083
1099
|
a quiet run of content changes (one the deadline cut short is checked once quiet),
|
|
1084
1100
|
reports only what moved. A selection the host was told is told again after a
|
|
1085
1101
|
settled scroll only if its box moved (P105, with or without counts). Both share one
|
|
@@ -1093,8 +1109,8 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1093
1109
|
all of it, read what `show` sends (ids, anchors, counts), or fake any report. The
|
|
1094
1110
|
host takes a selection only while it asked for that kind, a cancel only while
|
|
1095
1111
|
picking, results only for its own marks, a marker's click only for a mark it shows
|
|
1096
|
-
with a count and only within a gesture (P105); it rebuilds
|
|
1097
|
-
within `ANNOTATION_LIMITS` (a label without what the person can't see, P105) and
|
|
1112
|
+
with a marker (a count or a draft) and only within a gesture (P105); it rebuilds
|
|
1113
|
+
each from known fields within `ANNOTATION_LIMITS` (a label without what the person can't see, P105) and
|
|
1098
1114
|
drops the rest, through the bridge's rate limit. UI hints only, never
|
|
1099
1115
|
permissions: what a report says decides where a comment is drawn, never who may
|
|
1100
1116
|
see or do anything. A view a report opens or moves guards its presses
|
|
@@ -1132,7 +1148,14 @@ the layer itself (`annotation-activated`, `annotation-activated-count`,
|
|
|
1132
1148
|
engine, a touch screen and a phone's emulation (iPhone 13, Pixel 5), content hearing
|
|
1133
1149
|
none of it (`marker-tap` → WebKit; `marker-click` too); on a 640 px column and a phone page's lines
|
|
1134
1150
|
with one marker each, no marker covering a word (`marker-place`, the marker just
|
|
1135
|
-
past its words as 0.9.0 had it);
|
|
1151
|
+
past its words as 0.9.0 had it); drafts (P107) drawn apart from posted marks on the
|
|
1152
|
+
same anchors (the frame's pixels and the words' own differ; on Chromium every draft's
|
|
1153
|
+
marker and line drawn as a draft's, no number though given a count), a draft's and a
|
|
1154
|
+
posted marker's clicks reported beside each other, none reaching the content
|
|
1155
|
+
(`marker-click` too), the
|
|
1156
|
+
page reading a draft's kind and never its count (`draft-count`), a raw `show` past
|
|
1157
|
+
`checkMarks` drawing a draft given a count without a number and dropping a mark of
|
|
1158
|
+
an unknown kind (`draft-shell-checks`), and drafts alone followed after a scroll; and ADOPTING.md's `guardPresses`, as written
|
|
1136
1159
|
there, taking no press within 500 ms of its view opening (a release on a menu item,
|
|
1137
1160
|
a double click's second press on a button or a trigger, a press held past the
|
|
1138
1161
|
arming) and the person's own press or key after.
|
|
@@ -1406,7 +1429,7 @@ control the tables above name to the registry):
|
|
|
1406
1429
|
| `annotation-activated` | `annotate.spec.ts` | `a hostile page fakes a marker's click: the host takes it only for a mark it shows with a marker` | — | — |
|
|
1407
1430
|
| `annotation-activated-count` | `annotate.spec.ts` | `a hostile page fakes a marker's click: the host takes it only for a mark it shows with a marker` | — | — |
|
|
1408
1431
|
| `marker-trusted` | `annotate.spec.ts` | `a hostile page fakes a marker's click: the host takes it only for a mark it shows with a marker` | — | — |
|
|
1409
|
-
| `marker-click` | `annotate.spec.ts` | `markers: a mark with a count gets a numbered bubble; its click is reported and never reaches the content`, `a marker's press, of any kind, moves nothing of the content's: no handler, no focus, no selection`, `a page that patches the event's built-ins neither hears a marker's press nor stops its report (P105)`, `a tap on a marker is reported on every engine, and the content hears none of it (P105)` | — | — |
|
|
1432
|
+
| `marker-click` | `annotate.spec.ts` | `markers: a mark with a count gets a numbered bubble; its click is reported and never reaches the content`, `a marker's press, of any kind, moves nothing of the content's: no handler, no focus, no selection`, `a page that patches the event's built-ins neither hears a marker's press nor stops its report (P105)`, `a tap on a marker is reported on every engine, and the content hears none of it (P105)`, `drafts (P107): a dashed line and a hollow marker with no number, apart from posted marks; their clicks are reported the same` | — | — |
|
|
1410
1433
|
| `marker-prevent` | `annotate.spec.ts` | `a marker's press, of any kind, moves nothing of the content's: no handler, no focus, no selection` | — | — |
|
|
1411
1434
|
| `marker-place` | `annotate.spec.ts` | `text markers cover no word: on a column page, and on a phone's lines with one marker each (P105, #36)` | — | — |
|
|
1412
1435
|
| `marker-tap` | `annotate.spec.ts` | nothing | WebKit: `a tap on a marker is reported on every engine, and the content hears none of it (P105)` | no probe can see it on Chromium and Firefox: they make a tap a click on the marker without a listener of its own (measured, P105) |
|
|
@@ -1414,6 +1437,8 @@ control the tables above name to the registry):
|
|
|
1414
1437
|
| `follow-throttle` | `annotate.spec.ts` | `an honest scroll session, long, in comment mode, leaves room for a marker's click: follow-ups, the selection's too, at most one a second` | — | — |
|
|
1415
1438
|
| `selection-follow` | `annotate.spec.ts` | `an honest scroll session, long, in comment mode, leaves room for a marker's click: follow-ups, the selection's too, at most one a second` | — | — |
|
|
1416
1439
|
| `follow-count` | `annotate.spec.ts` | `following: a host that gives no counts hears no follow-up after a scroll, as before markers` | — | — |
|
|
1440
|
+
| `draft-count` | `annotate.spec.ts` | `what the page reads of a draft (P107): that it is one, never its count; a posted mark as before` | — | — |
|
|
1441
|
+
| `draft-shell-checks` | `annotate.spec.ts` | `the shell's own checks on a raw show (P107): a draft draws no number, a kind it doesn't know is no mark` | — | — |
|
|
1417
1442
|
| `annotation-activated-gesture` | `annotate.spec.ts` | `a hostile page's marker click with no gesture is dropped; one on the person's own press is the host's view to guard (P105)` | — | — |
|
|
1418
1443
|
| `annotation-rect-clamp` | `annotate.spec.ts` | `a hostile page reports a box outside its frame: the host gets it clamped to the frame's viewport`, `marks: drawn over their anchors, one brought into view, an unfound one orphaned, all cleared`, `following: once a scroll settles, one report with only the marks that moved` | — | — |
|
|
1419
1444
|
| `authorize` | `served/authorize.spec.ts` | `a revoked subject's ticket opens nothing: a page and an app are denied, and the host is told`, `in a tab of its own, a revoked app and page are denied from the next request on` | Chromium, Firefox: `a framed app mid-session: its next request after revocation is denied, and its next load tells the host`, `a framed page mid-session: its next load after revocation is denied where the engine keeps its cookie` | — |
|
|
@@ -1438,6 +1463,10 @@ control the tables above name to the registry):
|
|
|
1438
1463
|
| `live-held-read` | `served/runtime.spec.ts` | `a read above the viewer's level: a result the host pushed is refused as a cold read is` | — | — |
|
|
1439
1464
|
| `db-private` | `served/runtime.spec.ts` | `a person's own data is theirs: another person's is refused, never reaching the service` | — | — |
|
|
1440
1465
|
| `comments-result` | `served/runtime.spec.ts` | `comments are write-only: the composer opens from a click, content hears only that` | — | — |
|
|
1466
|
+
| `focus-guard` | `served/runtime.spec.ts` | `a page that takes the keyboard while the person types in the host's composer gets a key or two at most, and is stopped` | Firefox: `a page that takes the keyboard back on its own blur keeps none of it: the composer keeps its words, and comments.open reaches no handler`, `a composer the host focuses with focusField, beside a page with the person's gesture that takes focus back on its blur, gets their words` | — |
|
|
1467
|
+
| `focus-guard-watch` | `served/runtime.spec.ts` | nothing | Firefox: `a page that takes the keyboard back on its own blur keeps none of it: the composer keeps its words, and comments.open reaches no handler`, `a composer the host focuses with focusField, beside a page with the person's gesture that takes focus back on its blur, gets their words` | no probe can see it on Chromium and WebKit: they blur the host's window on every move into a frame and a take-back lands, and a page can't take focus back from its own blur there (measured) |
|
|
1468
|
+
| `comments-in-frame` | `served/runtime.spec.ts` | `comments.open while the person types in the host's composer reaches no handler, by the page's own call or the shell's; from a press in the frame it does` | — | — |
|
|
1469
|
+
| `comment-draft` | `served/runtime.spec.ts` | `a comment's draft is the host's to check: past the limit, holding what a person can't see, or not text, it opens no composer (P108)` | — | — |
|
|
1441
1470
|
| `blob-script` | `served/runtime.spec.ts` | nothing | — | an untrusted script asset is served as a download (`blob-script,blob-trusted`) |
|
|
1442
1471
|
| `blob-trusted` | `served/runtime.spec.ts` | `a script asset runs as code only if an admin uploaded it where uploads are the admins'` | — | — |
|
|
1443
1472
|
| `blob-script,blob-trusted` | `served/runtime.spec.ts` | `a script asset runs as code only if an admin uploaded it where uploads are the admins'`, `scripts load from /_blob/ only where uploads are the admins' (a tab, its session)` | — | — |
|
package/docs/THREAT_MODEL.md
CHANGED
|
@@ -5,11 +5,18 @@ 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
|
-
|
|
10
|
-
conformance probes' messages and timing, not what they check. P104 (0.9.0's
|
|
11
|
-
a review of its own, and P105, in 0.10.0, is what it led to.
|
|
12
|
-
|
|
8
|
+
**Status.** This describes Porthole 0.13.0 (2026-10-27). A review on 2026-10-19 found gaps, and every decision it led to
|
|
9
|
+
has merged ([§8](#8-fixes-in-flight) lists them). P096 changed the negative-control runner and CI,
|
|
10
|
+
and the shipped conformance probes' messages and timing, not what they check. P104 (0.9.0's
|
|
11
|
+
annotation markers) had a review of its own, and P105, in 0.10.0, is what it led to. 0.11.0 was
|
|
12
|
+
never published (its release stopped at the CI gate), and 0.12.0 carries all of it: draft marks
|
|
13
|
+
(P107, §7 "Drafts": what a page learns from them and who may receive them), an advisory lint
|
|
14
|
+
(P106, no change to isolation), and `comments.open` with a draft (P108, §7: the host's duties
|
|
15
|
+
around it). The review of 0.12.0's drafts led to P109, in 0.13.0: a display can take the keyboard, which
|
|
16
|
+
`createHost` now gives back (§6, §7 "The keyboard"); `comments.open` needs the person in the
|
|
17
|
+
calling frame; a page's draft text is stricter, and the composer it fills is the person's to act
|
|
18
|
+
on (§7). 0.13.0 also makes P106's lint fail soft and read only what it may (P110, no change to
|
|
19
|
+
isolation).
|
|
13
20
|
|
|
14
21
|
## 1. Two layers
|
|
15
22
|
|
|
@@ -151,10 +158,19 @@ Whatever the use:
|
|
|
151
158
|
second click lands on the bubble's). Such a view takes no press of any kind for 500 ms after it
|
|
152
159
|
appears or moves (not a `click` only: menu triggers act on `pointerdown`, and menu items click
|
|
153
160
|
themselves on a release), ignores a press that began before that, opens beside the frame rather
|
|
154
|
-
than over the report's box where the layout allows, takes no focus when it opens, and puts
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
arms).
|
|
161
|
+
than over the report's box where the layout allows, takes no focus when it opens, and puts
|
|
162
|
+
nothing one click away that posts, submits, resolves, deletes or discards (a draft's view, P107,
|
|
163
|
+
included: no "Post" or "Submit review" in it). Its menus and popovers are part of it, portaled
|
|
164
|
+
ones too (P105; ADOPTING.md § Annotations has the code: the view `inert` while it arms).
|
|
165
|
+
- Know that a display can take the keyboard: a page calls `focus()` on its own input whenever it
|
|
166
|
+
likes (on Chromium and WebKit with no gesture), and what the person goes on typing goes to it.
|
|
167
|
+
`createHost` (every `PortholeView` too) gives focus back when it leaves one of the page's text
|
|
168
|
+
fields for a frame without the person's press on the frame or a Tab, tells the display
|
|
169
|
+
(`focusTaken`), and stops a display that keeps doing it (§7 "The keyboard", P109). Move focus
|
|
170
|
+
into a display yourself with `display.focus()`, never the frame's own `focus()`; move it into
|
|
171
|
+
your composer with `focusField(field)`, not the field's own `focus()` (Firefox ignores that while
|
|
172
|
+
a fighting frame holds focus); and with a platform of your own, implement its focus guard
|
|
173
|
+
(`focused`, `onFocusTaken`, `focus`) or accept that a display can read what is typed beside it.
|
|
158
174
|
- List every app origin in `appOrigins` (`hostOrigins` in `/server`): only those may frame content,
|
|
159
175
|
and only those are checked against the content domain for a shared site.
|
|
160
176
|
- Under the app runtime, run `defineRuntimeConformance` with `api` in CI (§7).
|
|
@@ -539,17 +555,40 @@ wall on three engines, and `defineHostConformance` runs it against a host's own
|
|
|
539
555
|
**The host must** do what [every host](#what-every-host-must-do) does, write the handlers (their
|
|
540
556
|
effects are its own), and group displays by page (S7).
|
|
541
557
|
|
|
542
|
-
**Annotations** (`annotate`, P053, P104). The shell that draws marks and reports anchors shares
|
|
558
|
+
**Annotations** (`annotate`, P053, P104, P107). The shell that draws marks and reports anchors shares
|
|
543
559
|
its realm with the content, so:
|
|
544
560
|
|
|
545
561
|
- *What content learns.* Everything the host sends in a `show` is posted into the frame's window,
|
|
546
562
|
where the content can listen: each mark's id, anchor and, where given, `count` (the number on
|
|
547
563
|
its marker). A host gives ids that say nothing (never a person's name or a comment's words), and
|
|
548
564
|
a count only where the page may know how many there are. Who commented and what they wrote stay
|
|
549
|
-
in the host's own UI, outside the frame
|
|
565
|
+
in the host's own UI, outside the frame, and so does what the person types there, within the
|
|
566
|
+
keyboard's limits below (P109).
|
|
567
|
+
- *Drafts* (P107). A mark with `kind: "draft"` (a comment its author hasn't posted) is drawn apart,
|
|
568
|
+
a dashed line and a hollow marker with no number, so the page also learns which of its marks are
|
|
569
|
+
drafts: that the person viewing it is writing a comment there, before they post it. That is new
|
|
570
|
+
information for the page, accepted where the page has no way out: drafts are the host's to send
|
|
571
|
+
only to their author's own frame (Porthole can't tell whose frame it is), the page is the one
|
|
572
|
+
being commented on and already sees where the person selects (`selected`), and closed egress
|
|
573
|
+
([§4](#4-two-lines-of-defense)) keeps it off the network. Closed egress doesn't cover the
|
|
574
|
+
channels the host itself opens, and through them a draft's existence, place and timing can
|
|
575
|
+
leave: a page with the runtime's `db` (writes) and `user` can call `user.get()`, read the marks
|
|
576
|
+
shown to it, and write "viewer A is drafting at section 3" where its author and other viewers
|
|
577
|
+
read it before A posts; once A posts, the page can tie that posted comment to A (the anchor and
|
|
578
|
+
the time match). Origins a config declares for egress (an MCP App's `connectDomains`, S5; an
|
|
579
|
+
`egress` a host opened in its own config; the `liveWidget` preset itself has none, P103), and a
|
|
580
|
+
host function that sends the page's words somewhere, are channels of the same kind (S4, and the
|
|
581
|
+
app runtime below). A host that sends drafts to such a page accepts that its author and other viewers can
|
|
582
|
+
learn of them. A draft carries nothing else: the host drops its count before the frame (control
|
|
583
|
+
`draft-count`), so a page can't read how many drafts are at an anchor unless the host sends a
|
|
584
|
+
mark per draft, and its id is the host's, as any mark's (random, never the draft's words); the
|
|
585
|
+
draft's words are typed into the host's composer, which the page can try to take the keyboard
|
|
586
|
+
from ("The keyboard" below). A host
|
|
587
|
+
that sends drafts into a frame others see (a shared screen, a frame several viewers share) tells
|
|
588
|
+
that page, and anything it draws for them, what its author hasn't posted.
|
|
550
589
|
- *What content can fake.* Any report: a selection while the host asks for one, where marks are,
|
|
551
|
-
and a marker's click (`activated`) for any mark the host shows with a count,
|
|
552
|
-
it and with any box. It can draw look-alike markers, or lay its own elements over Porthole's.
|
|
590
|
+
and a marker's click (`activated`) for any mark the host shows with a marker (a count, or a draft:
|
|
591
|
+
P107), without a click on it and with any box. It can draw look-alike markers, or lay its own elements over Porthole's.
|
|
553
592
|
The host takes each report only for what it asked for and its own shown ids, rebuilt within
|
|
554
593
|
`ANNOTATION_LIMITS`, at 120 a minute; `activated` for a mark without a marker, or an id it
|
|
555
594
|
doesn't show, is dropped (negative control `annotation-activated`). `activated` is also taken
|
|
@@ -606,8 +645,53 @@ its realm with the content, so:
|
|
|
606
645
|
follow-up reports, of the marks (while one has a marker) and of the person's selection after a
|
|
607
646
|
scroll, share one clock: at most one a second together, each only when its box moved (P105).
|
|
608
647
|
- So `activated` opens the host's own view of a mark it already shows, placed within the frame's
|
|
609
|
-
box (better: beside it), guarded as §6 says, and never acts on it (no
|
|
610
|
-
an anchor or a rect decides where something is drawn, never who may
|
|
648
|
+
box (better: beside it), guarded as §6 says, and never acts on it (no post, submit, discard,
|
|
649
|
+
resolve, delete or reply); an anchor or a rect decides where something is drawn, never who may
|
|
650
|
+
see or do anything.
|
|
651
|
+
|
|
652
|
+
**The keyboard** (P109). Any display, of any kind and any version, can move the keyboard into its
|
|
653
|
+
frame: `element.focus()` runs in the content's realm, where nothing of Porthole can stop it, and on
|
|
654
|
+
Chromium and WebKit it needs no gesture. What the person goes on typing then goes to the page,
|
|
655
|
+
which can keep it (`db`) or send it out through any egress it has. The page knows when it matters:
|
|
656
|
+
its shell reports `selected` when the host opens a composer on it, and draft marks (P107) say
|
|
657
|
+
where the person is writing. P107 and P108 didn't make this possible; they put the person's
|
|
658
|
+
unposted words beside the frame and tell the page when.
|
|
659
|
+
|
|
660
|
+
- *What holds* (the web platform's focus guard, in every `createHost` display): when focus leaves
|
|
661
|
+
one of the host page's text fields (a text area, an `<input>` that takes text, an editable region,
|
|
662
|
+
in open shadow roots too) for a display's frame, and the person didn't move it there, focus goes
|
|
663
|
+
back to the field once the engine has finished the move, the guard watches that it stays there
|
|
664
|
+
(a page that takes it again on its own blur, which the take-back fires, is caught, as is focus
|
|
665
|
+
left on nothing), and the display hears `focusTaken`. Three such moves within 10 s that came while
|
|
666
|
+
the person typed or that kept focus from staying back, or five within 2 s, stop the display. The
|
|
667
|
+
person moved it if they pressed Tab just before; pressed the frame (on Chromium and WebKit the
|
|
668
|
+
frame element is `:active` as focus moves; on Firefox, which doesn't blur the window or show the
|
|
669
|
+
press, the pointer came over the frame after the field got focus and after the person last
|
|
670
|
+
typed); made a gesture the host's own events don't explain (the page has activation, but no
|
|
671
|
+
key, press or click of its own for longer than activation lasts, and the field has had focus that
|
|
672
|
+
long: a press or an assistive technology's activation in a frame); or the host moved it
|
|
673
|
+
(`display.focus()`).
|
|
674
|
+
Measured on all three engines: a page calling `focus()` every 700 ms down to a busy loop, or
|
|
675
|
+
taking focus back on its own blur, while the person types a sentence gets no key of it on
|
|
676
|
+
Chromium and WebKit and at most one on Firefox before it is stopped or gives up (negative
|
|
677
|
+
controls `focus-guard`, and `focus-guard-watch` on Firefox); a press on the page's own field, a
|
|
678
|
+
Tab into the frame, and an activation in the frame that sends the host no event keep the
|
|
679
|
+
keyboard there. `comments.open` needs that focus in the calling frame, moved there by the
|
|
680
|
+
person, and not just after a press on the host's page (the app runtime, below).
|
|
681
|
+
- *What doesn't*: a page gets the keys typed before focus is back (on Firefox, the keys of an
|
|
682
|
+
animation frame: one in a sentence, measured on a slowed machine too; a few more can be lost to
|
|
683
|
+
nothing while a take-back is fought, and the composer then has focus again); on Firefox a host's plain
|
|
684
|
+
`focus()` doesn't move focus from a frame that holds it with the person's gesture and takes it
|
|
685
|
+
back on its blur (no focus event: the keys go to the frame), so a composer that opens focused
|
|
686
|
+
must use `focusField`; on Firefox a page keeps the keyboard if the pointer came over its frame after
|
|
687
|
+
the person last typed and after the field got focus (a person who typed, moved the pointer over
|
|
688
|
+
the frame, and types on without clicking); moves between two frames, or from what isn't a text
|
|
689
|
+
field, aren't judged (a frame beside another: S7); and a platform of the host's own has no guard
|
|
690
|
+
unless it implements one. The guard can take a person's own move for the page's (a press on
|
|
691
|
+
Firefox with the pointer resting over the frame since before the field got focus; an assistive
|
|
692
|
+
technology's activation within 5 s of their key or press on the page): focus goes back, and
|
|
693
|
+
their next press once the pointer has left the frame and come back, a Tab, or an activation 5 s
|
|
694
|
+
later keeps it.
|
|
611
695
|
|
|
612
696
|
### The app runtime
|
|
613
697
|
|
|
@@ -640,7 +724,19 @@ section.
|
|
|
640
724
|
code-typed asset runs as code only when an admin uploaded it where uploaded code may run, and
|
|
641
725
|
only while the config still lets uploaded code run, asked at every load, in bearer mode too
|
|
642
726
|
(where every artifact config must; P103); anything else is a download.
|
|
643
|
-
- `comments` is write-only: the page learns only whether the composer opened.
|
|
727
|
+
- `comments` is write-only: the page learns only whether the composer opened. It opens only from
|
|
728
|
+
a gesture with the host page's focus in the calling frame (P109: a press in it or a Tab into it;
|
|
729
|
+
not the person typing in the host's UI, nor a gesture in another display; negative control
|
|
730
|
+
`comments-in-frame`). A draft it gives (P108) is at most 2,000 characters of text a person can
|
|
731
|
+
see (P109): nothing invisible (zero-width characters, bidi and tag characters, controls but a
|
|
732
|
+
new line and a tab; U+200C and U+200D only between two letters or marks, where Persian and the
|
|
733
|
+
Indic scripts need them, never first, last, doubled, beside a space or punctuation, or in an
|
|
734
|
+
emoji sequence; a variation selector after a pictograph is fine), no line or paragraph
|
|
735
|
+
separator, not blank-looking, at most 32 blanks in a row and two blank lines in a row; anything
|
|
736
|
+
else is refused before the handler. A joiner between two letters that shapes nothing still
|
|
737
|
+
draws as nothing (about a bit per letter boundary, measured): accepted, as P100 accepts it. The anchor's
|
|
738
|
+
label and quote reach the handler without what a person can't see, and are refused if nothing
|
|
739
|
+
visible is left.
|
|
644
740
|
- `defineRuntimeConformance` checks the host's handlers, and with `api` its own API for `db`,
|
|
645
741
|
`artifact` and `assets`, with a forged context (a viewer claiming to be the owner, no rules).
|
|
646
742
|
|
|
@@ -656,6 +752,29 @@ section.
|
|
|
656
752
|
- Keep each person's data apart in its own stores, and refuse moved bases and versions
|
|
657
753
|
(`Refused("conflict")`).
|
|
658
754
|
- Handle abuse on shared pages (S4).
|
|
755
|
+
- Show a comment's draft (P108) whole, as the person's editable plain text in its own composer,
|
|
756
|
+
and post it only on the person's own Send, never on the page's word. Once posted, the comment is
|
|
757
|
+
the person's: mentions in it act as theirs, which is why they must see it all first. So (P109;
|
|
758
|
+
ADOPTING.md has the code):
|
|
759
|
+
- An open never replaces, appends to or moves what the person has typed, or the place they
|
|
760
|
+
chose: while the composer holds their words, answer `false`, or show the page's words as a
|
|
761
|
+
separate suggestion that takes no focus. (The page knows they are writing anyway: its
|
|
762
|
+
`selected`, and draft marks.)
|
|
763
|
+
- A composer the page filled takes no focus when it opens (keys stay where the person was
|
|
764
|
+
typing: what they type for the page must not land in a postable comment), and doesn't send on
|
|
765
|
+
Enter until the person has focused or edited it themselves: Send is a click until then. It is
|
|
766
|
+
a view the content brought (§6's guard): no press for 500 ms after it opens, Send not focused,
|
|
767
|
+
beside the frame where it can.
|
|
768
|
+
- It says the text is the page's ("Suggested by this page", or the page's name), drawn by the
|
|
769
|
+
host outside the frame, until the person edits it, and never shows it as one of their own
|
|
770
|
+
drafts: the host's own list of drafts is how a person finds theirs, not the frame's markers,
|
|
771
|
+
which a page can draw too.
|
|
772
|
+
- The draft's view (P107) and the composer put nothing one click away that posts, submits or
|
|
773
|
+
discards.
|
|
774
|
+
- Render a page-drafted comment as plain text, or show the person before Send what readers will
|
|
775
|
+
see: markup a markdown renderer hides (an HTML comment, a link definition) is still read by an
|
|
776
|
+
agent. Show the anchor's label and quote as isolated text (`<bdi>`, `dir="auto"`), and hand
|
|
777
|
+
them to a model only as the page's words.
|
|
659
778
|
|
|
660
779
|
**Not guaranteed**
|
|
661
780
|
|
|
@@ -664,12 +783,20 @@ section.
|
|
|
664
783
|
page's rules allow) can read it.
|
|
665
784
|
- `db` rewrites only paths: an id the page stores inside a document's data is returned as stored.
|
|
666
785
|
- In bearer mode, assets are served by id alone, without the host's check.
|
|
786
|
+
- A draft is the page's words in the person's composer: a person who posts it without reading
|
|
787
|
+
posts what the page chose, and an agent that reads the comment takes it as theirs. Porthole
|
|
788
|
+
bounds what can hide in it (visible text, 2,000 characters) and when it opens (a gesture with the
|
|
789
|
+
person in the calling frame, P109: before P109, any gesture on the host's page in the last 5 s,
|
|
790
|
+
typing in its own composer included); reading it is the person's. A page can still open the
|
|
791
|
+
composer on the person's own press in its frame, at a moment it chooses (the second click of a
|
|
792
|
+
double click, a field it asked them to type into): the composer's duties above are the bound.
|
|
667
793
|
|
|
668
794
|
## 8. Fixes in flight
|
|
669
795
|
|
|
670
|
-
The decisions below come from the 2026-10-19 review
|
|
671
|
-
|
|
672
|
-
|
|
796
|
+
The decisions below come from the 2026-10-19 review, and all of them have merged. Each row says
|
|
797
|
+
what was wrong, what holds now, and the limit its decision accepts, if any. Later reviews' decisions
|
|
798
|
+
are in the status line and in DECISIONS.md: P105 (after the review of P104), P109 (after the review
|
|
799
|
+
of 0.12.0's drafts).
|
|
673
800
|
|
|
674
801
|
| Decision | State | What it closes | Sections |
|
|
675
802
|
| --- | --- | --- | --- |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.13.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
|
@@ -81,11 +81,23 @@ export interface AnnotationMark {
|
|
|
81
81
|
* A marker (P104): with a count, the shell also draws a small bubble with this number (0 to
|
|
82
82
|
* `ANNOTATION_LIMITS.count`; above 99 it reads "99+", 0 draws the bubble alone) at the end of a
|
|
83
83
|
* text anchor and the top right of an element. The person can click it: the frame reports
|
|
84
|
-
* `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.
|
|
85
86
|
*/
|
|
86
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;
|
|
87
96
|
}
|
|
88
97
|
|
|
98
|
+
/** A posted comment's mark, or an unsubmitted draft's (P107). */
|
|
99
|
+
export type AnnotationMarkKind = "posted" | "draft";
|
|
100
|
+
|
|
89
101
|
/** Whether a mark's anchor was found in the content as it is now. */
|
|
90
102
|
export type AnchorState = "attached" | "orphaned";
|
|
91
103
|
|
|
@@ -110,16 +122,17 @@ export type AnnotationReport =
|
|
|
110
122
|
| { readonly type: "cancelled" }
|
|
111
123
|
/**
|
|
112
124
|
* Where the marked anchors are now: every mark after `show`, the focused one after `focus`,
|
|
113
|
-
* 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
|
|
114
127
|
* scroll, a resize or a change of the content has settled, only the marks that moved since the
|
|
115
128
|
* host was last told, at most once a second (P104).
|
|
116
129
|
*/
|
|
117
130
|
| { readonly type: "anchored"; readonly results: readonly AnchorResult[] }
|
|
118
131
|
/**
|
|
119
|
-
* The person clicked the marker of a mark the host shows with a `count` (P104)
|
|
120
|
-
* marker's box, to open the host's own UI beside it. The content can fake
|
|
121
|
-
* host shows with a
|
|
122
|
-
* 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.
|
|
123
136
|
*/
|
|
124
137
|
| { readonly type: "activated"; readonly id: string; readonly rect: AnnotationRect };
|
|
125
138
|
|
package/src/annotate/validate.ts
CHANGED
|
@@ -198,7 +198,19 @@ export function annotateMode(mode: AnnotateMode | undefined): Required<AnnotateM
|
|
|
198
198
|
return { elements, text: words };
|
|
199
199
|
}
|
|
200
200
|
|
|
201
|
-
/**
|
|
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
|
+
*/
|
|
202
214
|
export function checkMarks(marks: readonly AnnotationMark[]): AnnotationMark[] {
|
|
203
215
|
if (!Array.isArray(marks) || marks.length > LIMITS.marks) {
|
|
204
216
|
throw new TypeError(`annotations.show: at most ${LIMITS.marks} marks`);
|
|
@@ -216,7 +228,14 @@ export function checkMarks(marks: readonly AnnotationMark[]): AnnotationMark[] {
|
|
|
216
228
|
`annotations.show: mark ${index}'s count is a whole number from 0 to ${LIMITS.count}`,
|
|
217
229
|
);
|
|
218
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
|
+
}
|
|
219
235
|
seen.add(mark.id);
|
|
236
|
+
if (kind === "draft") {
|
|
237
|
+
return { id: mark.id, anchor, kind };
|
|
238
|
+
}
|
|
220
239
|
return { id: mark.id, anchor, ...(mark.count === undefined ? {} : { count: mark.count }) };
|
|
221
240
|
});
|
|
222
241
|
}
|
package/src/bridge/bridge.ts
CHANGED
|
@@ -71,7 +71,8 @@ import type {
|
|
|
71
71
|
* every capability its host function's own rate (P091, P095) → arguments well formed and within
|
|
72
72
|
* their limits → who may (P087: the level of each method the call runs for the viewer, a page's
|
|
73
73
|
* named data with or without a viewer, db's rules) → not muted, if confirm-gated → the own rate
|
|
74
|
-
* of each method it runs (P094: a batch's writes count each) → a user gesture, if gated so
|
|
74
|
+
* of each method it runs (P094: a batch's writes count each) → a user gesture, if gated so (and
|
|
75
|
+
* for `comments`, the host page's focus in the calling frame: P109) → the
|
|
75
76
|
* viewer's consent, if gated so → a person's confirmation, if gated so (at most 10 waiting) →
|
|
76
77
|
* shown to the person, if gated so (P100) → the handler (or, for a read, a result the host already
|
|
77
78
|
* gave for it, or for a stale-allowed one the host's cache).
|
|
@@ -106,6 +107,12 @@ export interface BridgeOptions {
|
|
|
106
107
|
readonly cached?: DataCache;
|
|
107
108
|
/** Whether the embedding page has user activation now; undefined where it can't tell. */
|
|
108
109
|
readonly userActivation?: () => boolean | undefined;
|
|
110
|
+
/**
|
|
111
|
+
* Whether the embedding page's focus is in this display's frame now (P109); undefined where it
|
|
112
|
+
* can't tell. A capability whose gesture must be in its frame (`inFrame`: `comments`) is refused
|
|
113
|
+
* without it.
|
|
114
|
+
*/
|
|
115
|
+
readonly focused?: () => boolean | undefined;
|
|
109
116
|
readonly onEvent: (event: BridgeEvent) => void;
|
|
110
117
|
/** The clock, in milliseconds (tests pass their own). */
|
|
111
118
|
readonly now?: () => number;
|
|
@@ -125,6 +132,10 @@ export interface BridgeOptions {
|
|
|
125
132
|
const isRecord = (value: unknown): value is Record<string, unknown> =>
|
|
126
133
|
value !== null && typeof value === "object" && !Array.isArray(value);
|
|
127
134
|
|
|
135
|
+
/** Whether `capability`'s gesture must be in its own frame (P109: the host page's focus there). */
|
|
136
|
+
const inFrame = (capability: CapabilityName): boolean =>
|
|
137
|
+
capabilitySpec(capability).inFrame === true;
|
|
138
|
+
|
|
128
139
|
const MAX_URL = 4_096;
|
|
129
140
|
|
|
130
141
|
/**
|
|
@@ -653,6 +664,11 @@ export function createBridge(options: BridgeOptions): DisplayBridge {
|
|
|
653
664
|
if (activated === false) {
|
|
654
665
|
return refuse<Result>(capability, "no-user-activation");
|
|
655
666
|
}
|
|
667
|
+
// A gesture in this frame, not anywhere on the host's page (P109): the person typing in
|
|
668
|
+
// the host's composer gives its page activation, which a frame's call would borrow.
|
|
669
|
+
if (inFrame(capability) && options.focused?.() === false) {
|
|
670
|
+
return refuse<Result>(capability, "no-user-activation");
|
|
671
|
+
}
|
|
656
672
|
}
|
|
657
673
|
if (gates.includes("consent")) {
|
|
658
674
|
const consent = options.consent;
|
package/src/bridge/unseen.ts
CHANGED
|
@@ -80,3 +80,27 @@ const UNSEEN_EACH = new RegExp(UNSEEN.source, "gu");
|
|
|
80
80
|
export function withoutUnseen(text: string): string {
|
|
81
81
|
return text.replace(UNSEEN_EACH, "");
|
|
82
82
|
}
|
|
83
|
+
|
|
84
|
+
/** A variation selector where an emoji has one: after a pictograph, or in a keycap. */
|
|
85
|
+
const EMOJI_SELECTORS = new RegExp(
|
|
86
|
+
"(?<=\\p{Extended_Pictographic})[\\uFE0E\\uFE0F]|(?<=[0-9#*])[\\uFE0E\\uFE0F](?=\\u20E3)",
|
|
87
|
+
"gu",
|
|
88
|
+
);
|
|
89
|
+
|
|
90
|
+
/**
|
|
91
|
+
* A joiner or non-joiner with a letter or mark on each side (P109): how Persian separates its
|
|
92
|
+
* letters (میخواهم) and the Indic scripts choose a half form or a conjunct (क्ष, എന്റെ). Never
|
|
93
|
+
* first or last, doubled, beside a space, punctuation or a pictograph: there it shapes nothing, and
|
|
94
|
+
* hides text or makes a blank-looking draft.
|
|
95
|
+
*/
|
|
96
|
+
const LETTER_JOINERS = /(?<=[\p{L}\p{M}])[\u200C\u200D](?=[\p{L}\p{M}])/gu;
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* Whether `text` holds what a person can't see, for text a page puts in the person's own words (a
|
|
100
|
+
* comment's draft, P109): `unseen`'s list, with only a joiner or non-joiner between two letters or
|
|
101
|
+
* marks let by (in any script: a person's text needs them, and one that draws as nothing there is
|
|
102
|
+
* a bit at most), and a variation selector right after a pictograph or in a keycap (❤️, 1️⃣). A
|
|
103
|
+
* joiner between pictographs (an emoji sequence) is refused: it can join any two.
|
|
104
|
+
*/
|
|
105
|
+
export const unseenStrict = (text: string): boolean =>
|
|
106
|
+
UNSEEN.test(text.replace(LETTER_JOINERS, "").replace(EMOJI_SELECTORS, ""));
|