@botiverse/porthole 0.9.0 → 0.10.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 +3 -1
- package/dist/annotate/validate.d.ts +7 -2
- package/dist/annotate/validate.js +11 -4
- 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/page-source.js +1 -1
- 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/served.js +66 -63
- package/dist/host/create-host.js +44 -2
- package/dist/platform/types.d.ts +4 -2
- package/dist/shell/annotate.d.ts +5 -3
- package/dist/shell/annotate.js +453 -100
- package/docs/ADOPTING.md +76 -0
- package/docs/DECISIONS.md +374 -13
- package/docs/DESIGN.md +166 -38
- package/docs/THREAT_MODEL.md +72 -25
- package/package.json +1 -1
- package/src/annotate/types.ts +3 -1
- package/src/annotate/validate.ts +12 -5
- package/src/bridge/bridge.ts +1 -60
- package/src/bridge/unseen.ts +82 -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/served.ts +112 -63
- package/src/host/create-host.ts +42 -2
- package/src/platform/types.ts +4 -2
- package/src/shell/annotate.ts +453 -100
package/docs/ADOPTING.md
CHANGED
|
@@ -246,6 +246,82 @@ createHost(config, {
|
|
|
246
246
|
Myanmar (Persian's میخواهم). Subdivision flags (tag characters) don't. Your own `show` resolves only once that very update is visible: if a later update of
|
|
247
247
|
the display replaces it before it is drawn, reject, and it doesn't go.
|
|
248
248
|
|
|
249
|
+
### Annotations: comments on a display
|
|
250
|
+
|
|
251
|
+
With `annotate` declared (`capabilities: { annotate: {} }`), a host lets people point at a
|
|
252
|
+
display and keeps its comments beside it ([P053](DECISIONS.md), P104). Everything the frame
|
|
253
|
+
reports is the page's word: a hint where to draw, never a permission. A mark's `count` puts a
|
|
254
|
+
numbered marker beside its words; a click on one is `activated`.
|
|
255
|
+
|
|
256
|
+
```js
|
|
257
|
+
display.annotations.show(comments.map((c) => ({ id: c.markId, anchor: c.anchor, count: c.replies })));
|
|
258
|
+
display.annotations.start({ elements: false, text: true }); // comment mode: the person selects words
|
|
259
|
+
display.on("annotation", (report) => {
|
|
260
|
+
if (report.type === "selected") composer.openBeside(frame, report.rect, report.anchor);
|
|
261
|
+
if (report.type === "activated") bubble.openBeside(frame, report.rect, report.id);
|
|
262
|
+
if (report.type === "anchored") bubble.follow(report.results);
|
|
263
|
+
});
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
- **Ids say nothing, and a count only where the page may know it**: the content reads every
|
|
267
|
+
`show`. Who wrote what stays in your view, outside the frame.
|
|
268
|
+
- **The content chooses when your view opens and where** (it can post `activated` for a mark you
|
|
269
|
+
show on the person's own press in the content, under their pointer, P105), so a view that a
|
|
270
|
+
report opens or moves takes no press of any kind for 500 ms after it appears or moves (no
|
|
271
|
+
`pointerdown`, `pointerup`, `click` or key: menu triggers act on a press, and menu items click
|
|
272
|
+
themselves on a release), ignores a press that began before that, opens beside the frame rather
|
|
273
|
+
than over `rect` where the layout allows, takes no focus, and has no destructive action (resolve,
|
|
274
|
+
delete) one click away. Making it `inert` while it arms does all of the first:
|
|
275
|
+
|
|
276
|
+
```js
|
|
277
|
+
// Call placed() each time the view appears or moves. For 500 ms it takes nothing (inert: no
|
|
278
|
+
// press, no click, no focus; the pointer reaches what is under it), then only a press or a key
|
|
279
|
+
// that began on it after that.
|
|
280
|
+
function guardPresses(...parts) {
|
|
281
|
+
let timer = 0;
|
|
282
|
+
let fresh = false;
|
|
283
|
+
for (const part of parts) {
|
|
284
|
+
part.addEventListener("pointerdown", () => (fresh = true), true);
|
|
285
|
+
part.addEventListener("keydown", () => (fresh = true), true);
|
|
286
|
+
for (const type of ["pointerup", "mouseup", "touchend", "click"]) {
|
|
287
|
+
part.addEventListener(type, (event) => {
|
|
288
|
+
if (!fresh) {
|
|
289
|
+
event.preventDefault();
|
|
290
|
+
event.stopPropagation();
|
|
291
|
+
}
|
|
292
|
+
}, true);
|
|
293
|
+
}
|
|
294
|
+
}
|
|
295
|
+
const arm = (on) => {
|
|
296
|
+
for (const part of parts) {
|
|
297
|
+
part.inert = on;
|
|
298
|
+
part.style.pointerEvents = on ? "none" : "";
|
|
299
|
+
}
|
|
300
|
+
};
|
|
301
|
+
return {
|
|
302
|
+
placed() {
|
|
303
|
+
fresh = false;
|
|
304
|
+
arm(true);
|
|
305
|
+
clearTimeout(timer);
|
|
306
|
+
timer = setTimeout(() => arm(false), 500);
|
|
307
|
+
},
|
|
308
|
+
};
|
|
309
|
+
}
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
Menus and popovers the view opens are part of it, but a portaled one (Base UI's, Radix's) is
|
|
313
|
+
drawn outside it, where this guard doesn't reach: give it a container inside the view (both take
|
|
314
|
+
one, `container`), or pass that container to `guardPresses` too, and close it each time the view
|
|
315
|
+
appears or moves.
|
|
316
|
+
|
|
317
|
+
- **Boxes are in the frame's CSS px**, clamped to its viewport (P104): add the frame element's
|
|
318
|
+
position. A frame you scale or transform (a thumbnail, a zoomed preview) needs the box mapped
|
|
319
|
+
through that transform too (`frame.getBoundingClientRect().width / frame.clientWidth` for a
|
|
320
|
+
plain scale), or your view lands off by the difference.
|
|
321
|
+
- **Labels and quotes are the page's text**: shown only as text. Porthole takes out of a label what
|
|
322
|
+
the person can't see; a quote (`exact`) keeps it, to be found again. Hand either to a model only
|
|
323
|
+
as the page's words.
|
|
324
|
+
|
|
249
325
|
## 4. Served pages: the host kit
|
|
250
326
|
|
|
251
327
|
### Local development
|
package/docs/DECISIONS.md
CHANGED
|
@@ -1109,7 +1109,7 @@ clipboard is closed to them otherwise. Item 1 of 0.1.3.
|
|
|
1109
1109
|
shows the text); writing from inside the frame (P051).
|
|
1110
1110
|
**Revisit when** MCP Apps defines a clipboard request (then the adapter maps it).
|
|
1111
1111
|
|
|
1112
|
-
## P053 · 2026-10-11 · Annotations are mechanism: the host's comments, anchored in content it can't trust · Accepted; amended by P104
|
|
1112
|
+
## P053 · 2026-10-11 · Annotations are mechanism: the host's comments, anchored in content it can't trust · Accepted; amended by P104, P105
|
|
1113
1113
|
|
|
1114
1114
|
**Decision.** A new optional capability, `annotate`, declared by the host. It is for inline widgets
|
|
1115
1115
|
and artifact pages, and for MCP Apps views where the host chooses. With it, the host can:
|
|
@@ -1149,6 +1149,11 @@ host therefore:
|
|
|
1149
1149
|
What a frame reports is a UI hint, never a permission. It decides where a comment is drawn,
|
|
1150
1150
|
never who may see or do anything.
|
|
1151
1151
|
|
|
1152
|
+
A pick's click never reaches the content's own handlers only while the content patches none of
|
|
1153
|
+
the built-ins the shell calls then (P105): content that replaces `Event.prototype`'s
|
|
1154
|
+
`stopImmediatePropagation` hears it. Nothing it learns so is more than what it could tell anyway
|
|
1155
|
+
(that the person clicked, and where).
|
|
1156
|
+
|
|
1152
1157
|
**Measured** (`leak/annotate.spec.ts`, on Chromium, WebKit and Firefox):
|
|
1153
1158
|
- picking, cancelling, selecting, and both together;
|
|
1154
1159
|
- marks, focus and clear;
|
|
@@ -4590,7 +4595,7 @@ second wall on a tab); a host needs a served page to open windows from a tab (th
|
|
|
4590
4595
|
`'self'` default (it joins `FRAME_DENIED_FEATURES`); or WebKit and Firefox apply
|
|
4591
4596
|
`Permissions-Policy` to these features (the shell's device locks become the second wall there too).
|
|
4592
4597
|
|
|
4593
|
-
## P104 · 2026-10-20 · Annotation markers: a number at an anchor, a click the host hears, marks that follow a scroll · Accepted
|
|
4598
|
+
## P104 · 2026-10-20 · Annotation markers: a number at an anchor, a click the host hears, marks that follow a scroll · Accepted; amended by P105
|
|
4594
4599
|
|
|
4595
4600
|
A host that shows its comments beside an artifact page wants, at each comment's anchor in the page,
|
|
4596
4601
|
a small marker (a bubble and how many comments are there) that scrolls with the content; a click on
|
|
@@ -4675,20 +4680,27 @@ outline plain and unclear on its own.
|
|
|
4675
4680
|
- What content can fake: an `activated` report for any mark the host shows with a count, without
|
|
4676
4681
|
a click, and with any `rect` inside its frame (point 8); and look-alike markers drawn by its own elements (which
|
|
4677
4682
|
report nothing unless it fakes one), or elements laid over Porthole's markers. The host takes a
|
|
4678
|
-
fake only for its own shown ids, at the bridge's rate
|
|
4679
|
-
of that mark, placed near the rect within the frame's
|
|
4680
|
-
approve or reply on it).
|
|
4683
|
+
fake only for its own shown ids, at the bridge's rate (and, since P105, only within a gesture).
|
|
4684
|
+
So `activated` opens the host's own view of that mark, placed near the rect within the frame's
|
|
4685
|
+
box, and never acts (no resolve, delete, approve or reply on it). After the review of P104
|
|
4686
|
+
(P105): content can time a fake to the person's own press in the content, under their pointer,
|
|
4687
|
+
so that view also takes no press for 500 ms after it appears or moves, ignores a press that
|
|
4688
|
+
began before that, opens beside the frame where the layout allows, and has no destructive
|
|
4689
|
+
action one click away (THREAT_MODEL §6).
|
|
4681
4690
|
- What content can tell: that a marker was pressed, and roughly where, though it gets none of the
|
|
4682
4691
|
press's events. The pointer leaving its own element names the layer (`relatedTarget`), the layer
|
|
4683
|
-
matches `:hover` and `:active`, and the frame gets user activation.
|
|
4684
|
-
cancel it
|
|
4685
|
-
|
|
4686
|
-
|
|
4687
|
-
|
|
4688
|
-
|
|
4689
|
-
|
|
4692
|
+
matches `:hover` and `:active`, and the frame gets user activation. Content that patches none of
|
|
4693
|
+
the built-ins can't act on the click or cancel it; content that does could, until P105 read the
|
|
4694
|
+
press through the platform's own functions (it can still cover the layer).
|
|
4695
|
+
- What content can do to the layer: hide, shrink, move or cover it, and (P105: by patching a
|
|
4696
|
+
built-in the shell's insertion guards call on the layer's nodes, `Element.prototype.matches`)
|
|
4697
|
+
reach inside the closed shadow root, read the markers and rewrite them; nothing there is secret.
|
|
4698
|
+
Its inline `!important` style holds against the content's style sheets, and is set again at
|
|
4699
|
+
each draw, but the content's scripts can rewrite it in between, lay elements over it, or
|
|
4700
|
+
transform the document it sits in. A host can't rely on a marker being seen.
|
|
4690
4701
|
- The rate limit is shared: a page that floods reports can crowd out real ones; it could before.
|
|
4691
|
-
An honest page's follow-ups take at most 60 a minute (point 5
|
|
4702
|
+
An honest page's follow-ups take at most 60 a minute (point 5; P105: the selection's re-reports
|
|
4703
|
+
after a scroll were outside that clock, and are on it now).
|
|
4692
4704
|
|
|
4693
4705
|
**Tested.** `test/annotate.test.ts`: a count's bounds (0 and 999 kept; -1, 1.5, 1,000, NaN,
|
|
4694
4706
|
Infinity, a string, null refused), the `activated` report's shape, and on `createHost` over a
|
|
@@ -4743,3 +4755,352 @@ inside the frame (then a focus model
|
|
|
4743
4755
|
the content can't steal, likely the host's own overlay), a bubble must follow during a scroll (a
|
|
4744
4756
|
coarser report, or the host drawing markers itself from `anchored`), or MCP Apps defines
|
|
4745
4757
|
annotations.
|
|
4758
|
+
|
|
4759
|
+
## P096 · 2026-10-19 · The negative controls: one registry, every control run, and a run that proves nothing fails · Accepted
|
|
4760
|
+
|
|
4761
|
+
Amends P032 (what DESIGN.md records per control), P091's harness item (`scripts/controls.ts`) and
|
|
4762
|
+
P097's CI triggers. From the audit of 2026-10-19 (V01, V02).
|
|
4763
|
+
|
|
4764
|
+
**Decision**, by finding:
|
|
4765
|
+
1. **V01: a control passes only on its probes' own failures.** The runner judged a control by the
|
|
4766
|
+
tests it found in Playwright's report and nothing else: it ignored the child's exit status,
|
|
4767
|
+
signal and spawn error and the report's own errors, so a run whose web server never started
|
|
4768
|
+
(`suites: []`) left nothing to check and passed; a skipped probe counted as failed; an engine
|
|
4769
|
+
asked for but absent from the report wasn't checked. The judgement is now a function of the
|
|
4770
|
+
child's whole result (`judge`, `leak/controls.ts`), and the script only runs and prints it.
|
|
4771
|
+
A spawn error, a signal, no JSON report, or any error in the report fails the control. Every
|
|
4772
|
+
engine asked must be in the report. Each test the control names must have failed by its own
|
|
4773
|
+
`expect` (Playwright's message carries the matcher's call): skipped (an `inapplicable` probe, a
|
|
4774
|
+
`test.skip`), never run, timed out, interrupted, or failed by anything else (a browser that
|
|
4775
|
+
didn't launch, a detached frame, a harness that threw) is no failure. Every other test of its
|
|
4776
|
+
specs must pass or be skipped as it always is. Then the exit status must be what the control
|
|
4777
|
+
implies (1 when it expects failures, 0 when it claims nothing fails), never simply 0, since a
|
|
4778
|
+
negative control's run exits 1 whether its probes failed or its server never started.
|
|
4779
|
+
`test/controls.test.ts` gives the judge synthetic reports (the audit's two: an empty report
|
|
4780
|
+
with a launch error, a skipped probe; and a missing engine, a timeout, a launch error as a
|
|
4781
|
+
probe's failure, a signal, no report, the wrong exit status): each fails. 264b12fa's runner,
|
|
4782
|
+
given the same reports by a fake Playwright, printed "as it should" and exited 0 for all three
|
|
4783
|
+
of the audit's cases.
|
|
4784
|
+
2. **V02: one registry, every control, its probes per engine.** `CONTROLS` (`leak/controls.ts`) is
|
|
4785
|
+
every control the suite has: the specs it runs with and the tests it fails on each engine
|
|
4786
|
+
(`others: "fail"` where it takes out what every test stands on: `nonce`). It holds the single
|
|
4787
|
+
weakenings DESIGN.md says another wall covers (`frame-guard`, `attach-shadow`, `blob-script`,
|
|
4788
|
+
`self`, `sync-guard` off WebKit): each must fail nothing. The runner runs them all by default,
|
|
4789
|
+
and CI's controls job (one per engine, 90 minutes, its reports kept on failure) runs it.
|
|
4790
|
+
`test/controls.test.ts` holds the registry to `WEAKENINGS` (every weakening is run by a
|
|
4791
|
+
control, every control is made of weakenings), to the specs (each exists, and none is a spec
|
|
4792
|
+
the weakenings don't reach: `UNWEAKENED`, the kit's reference app, which runs Porthole in Node),
|
|
4793
|
+
to DESIGN.md (§ The negative controls is `controlsTable()` exactly, and every control the
|
|
4794
|
+
tables' "Negative control" columns name is in the registry), and to CI (the job runs
|
|
4795
|
+
`test:controls` with no names, on all three engines). A probe named by a control is every test
|
|
4796
|
+
whose title has it, so a control run with two specs of the same suite fails it in both.
|
|
4797
|
+
3. **What running them all found** (0.7.0; Chromium 153, WebKit 26.6, Firefox 155). Every
|
|
4798
|
+
control's own probes fail on every engine; DESIGN.md's tables were older than the probes:
|
|
4799
|
+
- Probes added since that stand on an older wall, now named: `connect-src` → `14.silent`;
|
|
4800
|
+
`webrtc` → `14.workers`; `frame-guard,sync-guard` and `parser-entry-points` → `14.shell`;
|
|
4801
|
+
`sandbox` → `14.dialogs`, `14.windows`, and `14.print` (not WebKit: it prints nothing from a
|
|
4802
|
+
frame either way); `document-theme` → `14.theme-never`; `confirm-gate` → `14.windows`;
|
|
4803
|
+
`shell-gesture` → `12.copy-text`; `clipboard` → `14.shell` (WebKit, Firefox);
|
|
4804
|
+
`embedder-csp` → `5.host-origin`; every control with `sync-guard` → WebKit's `8.preconnect`;
|
|
4805
|
+
`navigate-guard` → P083's reports case; `report-unbounded` (P095) → `14.silent` too, on
|
|
4806
|
+
both host pages (its blocked-load report is read as the text it was); `navigate-guard` →
|
|
4807
|
+
P099's `served.domain.tab-links` too (the outside site hears the links).
|
|
4808
|
+
- Claims that no longer hold: `connect-src` fails `8.prefetch` on Chromium no more (the
|
|
4809
|
+
shell's hint guard holds it too); Firefox no longer holds `5.data` by itself (P035).
|
|
4810
|
+
- Probes that didn't fail by their assertions with their wall out, now fixed, each still
|
|
4811
|
+
passing with it in: under `embedder-csp`, `5.blob` (Firefox) and `5.data` (WebKit, Firefox)
|
|
4812
|
+
saw the navigated document run in 2 of 3 runs: its witness, a fetch at the document's end,
|
|
4813
|
+
raced the display's restart (P031's race, again). The witness is now the document's first
|
|
4814
|
+
act and a beacon, which the browser delivers after the frame is gone: 3 of 3 on each engine.
|
|
4815
|
+
Under `sandbox`, Firefox's print dialog held `14.print`'s click until the test timed out: the
|
|
4816
|
+
click and each look at the frame are bounded (`recorded`), so it fails by its assertion.
|
|
4817
|
+
Under `navigate-guard`, two `files.spec.ts` cases failed by a detached frame ("a page opens
|
|
4818
|
+
nothing else" clicked its next button in a page that had gone; the P083 reports case waited
|
|
4819
|
+
on the frame's clock): the first checks what reached the server after every click, the
|
|
4820
|
+
second waits on the host page's clock. On WebKit, once in four runs, a `live.spec.ts`
|
|
4821
|
+
navigation case threw "the display has no frame" while its display restarted: its first
|
|
4822
|
+
look (`showLive`) takes a missing frame as a look to repeat.
|
|
4823
|
+
- `nonce` fails every test of `strict-csp.spec.ts` (71 by their assertions, 15 by timing out,
|
|
4824
|
+
each engine): `others: "fail"`, with `0.opaque-origin` and `0.globals` failing by theirs.
|
|
4825
|
+
- `5.blob`, `5.data` and `14.print` are the shipped suite's (`/conformance`): an adopter's run
|
|
4826
|
+
of them sees the same, with no change to its API.
|
|
4827
|
+
4. **CI runs once per commit of a pull request**: ci.yml's `push` is `main` only (was every branch,
|
|
4828
|
+
amending P097's `branches: ["**"]`), with `pull_request` and `workflow_dispatch`. A pull
|
|
4829
|
+
request's push ran every job twice, the controls with them; a push run can't be re-run by the
|
|
4830
|
+
agents, a pull request's can. The release gate reads main's push and dispatch runs, unchanged;
|
|
4831
|
+
`test/release.test.ts` pins the triggers. AGENTS.md says how to get CI before a pull request.
|
|
4832
|
+
5. **After its review, a probe fails for the right reason, named exactly.** (a) A failed `expect`
|
|
4833
|
+
counted, a setup check too (`goto` not 200, a positive control): now a probe's deciding
|
|
4834
|
+
`expect` carries `probe: ` at the start of its message (`VERDICT`), in the shipped probes
|
|
4835
|
+
(`src/conformance`) and the spec tests the registry names, and only a failure whose error
|
|
4836
|
+
starts with it counts; the `nonce` control has a probe of its own in `strict-csp.spec.ts` (the
|
|
4837
|
+
shell drew and ran the content), since the suite's probes fail there before their verdicts.
|
|
4838
|
+
(b) "Fails nothing" was a label: every control that names no test on an engine now says why
|
|
4839
|
+
(`holds`), either by a combined control that takes its walls out with another's and fails
|
|
4840
|
+
something there (`link-rule,navigate-guard` is new for `link-rule`), or with a reason why no
|
|
4841
|
+
probe can see the wall (`self`: an opaque frame's `'self'` matches no origin; `url-origin` on
|
|
4842
|
+
WebKit, which keeps no framed cookie); the test checks the cover. (c) Entries named a part of a
|
|
4843
|
+
title; now a probe's `[id]`, a served case's id before its colon, or a test's whole title. (d)
|
|
4844
|
+
A test declared to fail (`test.fail`) that passes fails the control, unless it is a target.
|
|
4845
|
+
6. **CI runs the controls in shards.** One engine's 57 controls outlasted a 90-minute job on CI's
|
|
4846
|
+
runners (all three cancelled). Each engine now runs four shards, `controls (<engine>, k/4)`,
|
|
4847
|
+
60 minutes each (`--shard k/4`: the registry split by each control's measured weight, heaviest
|
|
4848
|
+
first to the lightest shard, so `nonce` shares its shard with small ones; stable for a
|
|
4849
|
+
registry), each uploading its reports and `verdicts.json`; the `controls` job puts them
|
|
4850
|
+
together (`--summary`) and fails if any control failed or never ran on an engine. A job's
|
|
4851
|
+
name changed, so release.yml's REQUIRED_CI_JOBS lists the twelve shards and `controls`.
|
|
4852
|
+
|
|
4853
|
+
**Why.** PRINCIPLE 6: a wall never seen to fail proves nothing, and a check that says a wall was
|
|
4854
|
+
seen to fail when its run never happened is worse than no check. CI's "every control" was 7 of
|
|
4855
|
+
the 38 there were (57 now, with P094's, P095's, P099's, P100's, P101's and P104's); the rest ran by hand,
|
|
4856
|
+
when someone remembered, and what DESIGN.md said they fail had drifted from what they do.
|
|
4857
|
+
**Rejected.**
|
|
4858
|
+
- Requiring exit 0, or exit 1, alone: either is what a broken run can give.
|
|
4859
|
+
- Counting any failure of a named test: a browser that can't launch fails every test, and a spec
|
|
4860
|
+
whose every test is named (permissions, authorize) would pass a run that never reached Porthole.
|
|
4861
|
+
- Retrying: a named test that fails only sometimes is not a wall seen to fail; a test that fails
|
|
4862
|
+
besides them is either a dependency the registry must name, or a flaky probe to fix.
|
|
4863
|
+
- Parsing the prose columns of DESIGN.md's tables for each control's probes: the prose explains
|
|
4864
|
+
why; the generated table is the exact claim, and the test holds the prose to naming only
|
|
4865
|
+
controls that exist.
|
|
4866
|
+
- Running controls with `kit.spec.ts` until the kit's app applies weakenings: its walls are the
|
|
4867
|
+
core's, whose controls run against the leak and served harnesses.
|
|
4868
|
+
**Threat it re-opens.** None: no default, gate or policy changes; four probes see more.
|
|
4869
|
+
**Revisit when** Playwright's JSON report changes shape (the judge's tests pin the fields it reads),
|
|
4870
|
+
a control's run makes a CI job too long (shard the controls across jobs), or the kit's app gains
|
|
4871
|
+
a weakening seam (then its controls join the registry).
|
|
4872
|
+
|
|
4873
|
+
## P105 · 2026-10-20 · After the review of P104: a marker's click within a gesture and the host's view guarded, one clock for follow-ups, text markers beside their line · Accepted
|
|
4874
|
+
|
|
4875
|
+
Amends P104 (its points 1, 3, 5 and 7, and its Trust) and P053's Trust. From the independent
|
|
4876
|
+
review of P104 and 0.9.0 (botiverse/porthole#37: no P0 or P1, two P2s, six P3s) and from #36
|
|
4877
|
+
(Ferry, taking 0.9.0: a text marker covered the next word). Measured on Chromium 153, WebKit 26.6
|
|
4878
|
+
and Firefox 155.
|
|
4879
|
+
|
|
4880
|
+
**Decision**, by finding:
|
|
4881
|
+
1. **P2-2: the selection's re-report is a follow-up too.** After every settled scroll the shell
|
|
4882
|
+
sent the person's selection again (`selected`, since P053), whether its box had moved or not,
|
|
4883
|
+
outside P104's one-a-second clock. P104's own honest session (140 wheel turns 200 ms apart, a
|
|
4884
|
+
mark with a count) in comment mode (text selection on, one selection) sent 120 reports, the
|
|
4885
|
+
bridge's 120 a minute, and the marker's click after it was refused (`annotate:rate-limited`):
|
|
4886
|
+
the review's R5 on all three engines, and the extended test, failing first with 120 taken
|
|
4887
|
+
(Chromium, Firefox). Now the selection is told
|
|
4888
|
+
again only when its box moved more than 0.5 px since it was last told (or it changed, or went),
|
|
4889
|
+
and on the follow-ups' clock, which both kinds share: at most one report a second together, the
|
|
4890
|
+
latest (two in one tick leave the next second empty). The same session now gives 15 `anchored`
|
|
4891
|
+
and 15 `selected`, none refused, and the click is taken, on all three. A selection the person
|
|
4892
|
+
makes is told at once, as before; only the re-reports wait. A host without counts still hears
|
|
4893
|
+
the `anchored` reports 0.8 sent, and its selection again after a scroll only if it moved.
|
|
4894
|
+
2. **P2-1: the host's view of a mark is the host's to guard, and `activated` needs a gesture.** A
|
|
4895
|
+
page can post `activated` for a shown mark on its own `pointerdown`, with the pointer's
|
|
4896
|
+
coordinates; the host had it 9 to 121 ms into the press (R4), so a double click asked for on
|
|
4897
|
+
the content's own button lands its second click on the bubble's Resolve. THREAT_MODEL §6 asked a
|
|
4898
|
+
500 ms guard of confirmations only. Now it asks, of every host: a view that a frame's report
|
|
4899
|
+
opens or moves (`activated`, `anchored`, `selected`) takes no press for 500 ms after it appears
|
|
4900
|
+
or moves, ignores a press that began before that, opens beside the frame rather than over the
|
|
4901
|
+
report's box where the layout allows, takes no focus, and puts no destructive action one click
|
|
4902
|
+
away. ADOPTING.md § Annotations has the guard (`guardPresses`), P104's Trust says so.
|
|
4903
|
+
The narrowing, which holds: `createHost` takes `activated` only while `surface.userActivation()`
|
|
4904
|
+
isn't false (the gesture gate's reading: undefined, where a platform can't tell, passes; a
|
|
4905
|
+
throw drops it). A real marker click gives the host's page transient activation on all three
|
|
4906
|
+
engines, though the shell cancels the press (activation comes before the event is dispatched);
|
|
4907
|
+
a page's own post at load or on a timer has none (measured: a sandboxed frame's timer posts
|
|
4908
|
+
arrive with the host inactive; a click in it, its `mousedown` cancelled, activates the host).
|
|
4909
|
+
Playwright's `evaluate` is itself a gesture and activation lasts 5 s on all three, so the test
|
|
4910
|
+
asks nothing of either page for 7.5 s first. It stops a view opened with no gesture at all, and
|
|
4911
|
+
no more: activation lasts 5 s after any gesture anywhere on the page (a click on the host's own
|
|
4912
|
+
UI, typing in the content, the click that opened the display), and a fake posted then, on a
|
|
4913
|
+
timer or a scroll, is taken (point 9); one on the person's own press is R4. The host's duty
|
|
4914
|
+
above is the defence. A custom
|
|
4915
|
+
platform's `userActivation()` (already required) that answers false drops every marker click,
|
|
4916
|
+
as it refuses every gesture-gated call.
|
|
4917
|
+
3. **#36: a text marker beside its line, not over the next word.** P104 drew it at the words' end,
|
|
4918
|
+
raised (left at their right + 2, top 12 px above the line): its lower 6 px lay over the next
|
|
4919
|
+
word's first letters, and on a narrow page, when the words ended at a wrapped line's start,
|
|
4920
|
+
between two lines. Now it is centred on the anchor's last line, at the first of these places
|
|
4921
|
+
that is inside the frame, clear of that line's words, and over nothing of the content's but a
|
|
4922
|
+
box holding the anchor, with nothing else between the words and it (the shell hit-tests the
|
|
4923
|
+
place with `elementsFromPoint`, its own layer aside): the line's gutter, just past the right
|
|
4924
|
+
edge of the anchor's block (its content box); where the frame is too narrow for that, the
|
|
4925
|
+
frame's right edge; where something else is beside the block (a table's next cell, a card in a
|
|
4926
|
+
row), just past the line's last word. Markers ending on one line of one block go together, in
|
|
4927
|
+
the order their words end. Where the bubble with its glyph fits in none of these, its number
|
|
4928
|
+
alone does (compact: 18 px for one digit, inside a phone page's 20 px padding); where that fits
|
|
4929
|
+
nowhere either, the group goes as far right as nothing else stands in the way, over the line's
|
|
4930
|
+
end. The pointer on a marker lights its words as the active mark's are. A draw now measures
|
|
4931
|
+
every marker before it changes a node, and leaves each marker that stays where it is in the
|
|
4932
|
+
layer: one taken out and put back mid-press lost its click on WebKit (seen once the pointer's
|
|
4933
|
+
arrival lit a mark and redrew). Element markers are placed as they were.
|
|
4934
|
+
Judged on screen (16 px text, line height 1.6; a centred 640 px column, and a 390 px page with
|
|
4935
|
+
full-width text and 20 px padding; anchors ending mid-line, at a line's end, at a wrapped line's
|
|
4936
|
+
start, two and three on one line, in a card, in a table cell, and elements; Chromium, Firefox,
|
|
4937
|
+
WebKit): on the column, no marker covers a glyph (0.9.0's touched 14 words); on the phone none
|
|
4938
|
+
does but where two or three anchors end on one full line, which covers that line's last letters
|
|
4939
|
+
(0.9.0's touched 13 words there, and sat between lines). The gutter is worse than 0.9.0's place
|
|
4940
|
+
in one way: a marker for words that end mid-line, or on a short line, sits up to the column's
|
|
4941
|
+
width from them, tied to them by the line, its order and their highlight (and, with a pointer,
|
|
4942
|
+
by the light on hover). Taken for the column it gives: which lines have comments reads at a
|
|
4943
|
+
glance, and a marker doesn't move as the line's words reflow.
|
|
4944
|
+
4. **P3-1: the shell's guarantees say what they hold against.** The shell shares the content's
|
|
4945
|
+
realm and, at a marker's press, called the live prototypes: content that replaced
|
|
4946
|
+
`Event.prototype.stopImmediatePropagation` heard a real press (R1), one that redefined the
|
|
4947
|
+
`MouseEvent.prototype.clientX` getter made the shell miss the click (R2), and one that wrapped
|
|
4948
|
+
`Element.prototype.matches` got the closed shadow root from the shell's insertion guards and
|
|
4949
|
+
rewrote a marker (R3), on all three engines. Restated in THREAT_MODEL §7, P104's Trust, P053's
|
|
4950
|
+
Trust, DESIGN.md and the shell's comments: a press is unheard and can't be cancelled, and the
|
|
4951
|
+
layer is out of reach, against content that patches none of the built-ins (CHANGELOG 0.9.0's
|
|
4952
|
+
wording is the release's). The narrowing, small and a reading of the same functions: the
|
|
4953
|
+
marker's listener reads and stops a press through the platform's own functions and getters,
|
|
4954
|
+
kept before content runs, as the navigation guard does (`stopImmediatePropagation`;
|
|
4955
|
+
`preventDefault` as kept before a tab's shell locks its own; `target`, `type`, `button`,
|
|
4956
|
+
`clientX`, `clientY`; DOMRect's sides; `Reflect.apply`), and `tell` reads `window.parent` once
|
|
4957
|
+
(it is `[Replaceable]`). R1 and R2 no longer work (test and control `marker-originals`). R3
|
|
4958
|
+
still does, and picking's listeners still read the live prototypes. Nothing in the layer is
|
|
4959
|
+
secret.
|
|
4960
|
+
5. **P3-2: controls for what had none.** `marker-prevent` (the press's `preventDefault` out: focus
|
|
4961
|
+
moves, on every engine). Its selection probe was blind: a click on a marker never changes a
|
|
4962
|
+
selection, with or without the cancel, since markers aren't selectable. So it now also drags
|
|
4963
|
+
from the marker over the next line's words, which WebKit then selects; Chromium and Firefox
|
|
4964
|
+
don't, either way (measured). `follow-throttle` (`FOLLOW_EVERY` 0: the honest session's count,
|
|
4965
|
+
now a `probe:` verdict); `follow-count`, with a test of its own (marks without counts, a scroll:
|
|
4966
|
+
nothing after the settle); `selection-follow` (0.9.0's re-report after every settle). DESIGN.md
|
|
4967
|
+
said `marker-click` covered focus and selection: it covers the handlers, `marker-prevent` focus
|
|
4968
|
+
and the selection.
|
|
4969
|
+
6. **P3-3: a platform's `viewport()` that answers no size or throws** raised a TypeError out of the
|
|
4970
|
+
transport's listener (the report was dropped: closed, but out of the listener). Now
|
|
4971
|
+
`createHost` reads it in a `try` and takes only numbers, and `clampRect` takes null as unknown:
|
|
4972
|
+
every box is nothing at the frame's corner, and nothing throws.
|
|
4973
|
+
7. **P3-5: labels lose what the person can't see.** P104 named a wordless element by its `alt`,
|
|
4974
|
+
`aria-label` or `title`, text the person never sees on the page, which could carry bidi
|
|
4975
|
+
controls or zero-width characters into the host's UI, or a model's context through a host
|
|
4976
|
+
that forwards it. `parseAnchor` (so `parseReport` and `checkMarks`) takes out of every label
|
|
4977
|
+
every character P100's rule names, with none of its exceptions (point 9), now one definition in
|
|
4978
|
+
`src/bridge/unseen.ts`. Selectors keep theirs, to be found again; THREAT_MODEL says a quote
|
|
4979
|
+
handed to a model is the page's words.
|
|
4980
|
+
8. **P3-4 and P3-6: written down.** The frame's size is read for each report the host takes,
|
|
4981
|
+
before its rate: one forced layout of the host's page per message, which a repeated
|
|
4982
|
+
`ui/initialize` already causes (accepted; the clamp after the gate would sit in the bridge's
|
|
4983
|
+
delivery). A box is in the frame's own CSS px: a host that scales or transforms the frame maps
|
|
4984
|
+
it through that transform (THREAT_MODEL §7, ADOPTING.md, `AnnotationRect`).
|
|
4985
|
+
|
|
4986
|
+
9. **After the review of 3969ebc** (no P0 or P1; R5, R1 and R2 hold, every control fails exactly
|
|
4987
|
+
its probes):
|
|
4988
|
+
- **P2-A: the guard in ADOPTING.md let presses through.** It caught `click` alone, and let one
|
|
4989
|
+
with `detail` 0 pass: a menu item that clicks itself when a press that began elsewhere ends
|
|
4990
|
+
on it (Radix's pattern; Base UI's items click on `mouseup`), and a trigger that acts on
|
|
4991
|
+
`pointerdown`, fired within 500 ms (the review's R9). Now the guard makes the view `inert`
|
|
4992
|
+
(and `pointer-events: none`) while it arms, so nothing in it takes a press, a click or focus, and
|
|
4993
|
+
after that it drops the end of a press that didn't begin on it (`pointerup`, `mouseup`,
|
|
4994
|
+
`touchend`, `click`) until one does, or a key. Portaled menus and popovers are outside the
|
|
4995
|
+
view: they go in a container inside it, or are guarded too, and close when it moves. §6 says
|
|
4996
|
+
a press of any kind. A leak test runs the snippet as ADOPTING.md has it (the review's three
|
|
4997
|
+
cases, a press held past the arming, then a press and a key that are taken); the old snippet
|
|
4998
|
+
fails it by the menu item's release.
|
|
4999
|
+
- **P2-B: a tap on a marker was never reported on WebKit** (since 0.9.0): WebKit made no click
|
|
5000
|
+
of a tap on the marker, whose only listener was the window's, though it did for a button.
|
|
5001
|
+
Each marker now has a click listener of its own, which never runs (the window's first
|
|
5002
|
+
listener stops every click on the layer): WebKit then clicks. A tap reports on all three
|
|
5003
|
+
engines, with a touch screen and in a phone's emulation (iPhone 13 on WebKit, Pixel 5 on
|
|
5004
|
+
Chromium; Firefox has none), after 6 s of nothing: the tap's own activation is what the host
|
|
5005
|
+
takes it by (measured: the host's page is active when the report arrives). The reference
|
|
5006
|
+
host's page now has a viewport meta, as a phone's page has: without it the emulation lays the
|
|
5007
|
+
page out 980 px wide at 0.4, and Playwright's taps land beside the frame. Control `marker-tap`
|
|
5008
|
+
(the listener out) fails the test on WebKit; Chromium and Firefox click a tap without it.
|
|
5009
|
+
- **P3-A: the label strip wasn't closed.** It kept P100's exceptions (the parts of emoji, a
|
|
5010
|
+
joiner between two shaped letters), and a Mongolian variation selector, itself a mark of a
|
|
5011
|
+
shaping script and default-ignorable, made a joiner beside it look shaped, then was taken out
|
|
5012
|
+
itself: a 107-character label kept 48 joiners, `rm -rf` in bits. Now every code point the rule
|
|
5013
|
+
names goes, no exceptions: an emoji in a label loses its joiners and selectors (its faces
|
|
5014
|
+
stay). Tested with that label, and 20,000 random ones from the review's pool, none of which
|
|
5015
|
+
leaves anything `unseen` refuses.
|
|
5016
|
+
- **P3-B:** THREAT_MODEL and point 2 said a page could no longer open the host's view at load, on
|
|
5017
|
+
a timer or on a scroll; within 5 s of any gesture anywhere on the page it can (the review's
|
|
5018
|
+
R7b). Both now say so, and that the guard is the defence.
|
|
5019
|
+
- **P3-C: placing markers after a change of the content was dear** (the longest task, 300
|
|
5020
|
+
paragraphs with counts: 44, 53 and 19 ms on Chromium, WebKit and Firefox; 200 marks in one
|
|
5021
|
+
3,000-line `<pre>`: 168, 163 and 102 ms). A line's end was read from the whole rest of its
|
|
5022
|
+
block, for each marker; each hit test walked every mark and marker the last draw left in the
|
|
5023
|
+
layer (0.13 ms a test, measured); a mark's block was found again on every change. Now the
|
|
5024
|
+
line's end is read 64 characters at a time, only until the text leaves the line; the layer's
|
|
5025
|
+
marks and markers are out of the hit tests while places are tested (hidden in one task, never
|
|
5026
|
+
taken out of the page); a marker whose line is out of view is placed without a measure or a
|
|
5027
|
+
test; a block is kept while it still holds the words. Measured again: 18, 22 and 16 ms; 24,
|
|
5028
|
+
48 and 40 ms (without counts: 5, 6 and 11; 13, 25 and 37). THREAT_MODEL and DESIGN say what it
|
|
5029
|
+
costs and that it is bounded.
|
|
5030
|
+
- **P3-D: nothing pinned #36.** A leak test now reads every word's glyph boxes against the points
|
|
5031
|
+
the layer takes (a 2 px grid) on the column page, all of its cases, and on the phone page's
|
|
5032
|
+
lines with one marker each: no marker covers a word, on all three engines. Control
|
|
5033
|
+
`marker-place` (the marker just past its words, centred on the line, as 0.9.0 placed it
|
|
5034
|
+
across) fails it. The press test's drag goes round the paragraph, so it holds wherever the
|
|
5035
|
+
marker is.
|
|
5036
|
+
- **P3-E:** CHANGELOG.md's Unreleased section says what a host sees change, what to act on first.
|
|
5037
|
+
- **CI's WebKit (PR #38):** `selection-follow` and `follow-throttle` failed nothing there: the
|
|
5038
|
+
honest session's verdict was a count of follow-ups over 140 wheel turns, and a slower runner
|
|
5039
|
+
settles fewer of them, so a shell without the clock stayed under it. The test now also
|
|
5040
|
+
scrolls eight times 300 ms apart from inside the frame, each a settle on any machine, and the
|
|
5041
|
+
host page notes when each follow-up arrives: the selection's re-reports, and the marks'
|
|
5042
|
+
follow-ups, must each come at least 700 ms apart (the clock keeps them 1 s apart; without it
|
|
5043
|
+
they come 300 ms apart). Both controls fail it on WebKit pinned to one CPU. That run also
|
|
5044
|
+
showed P104's settle test counting the script's steps, 30 ms apart, while a starved
|
|
5045
|
+
engine's scroll events bunched across a late frame: it counts the events now.
|
|
5046
|
+
- **P3-F:** THREAT_MODEL had P105 in §8 as merged and its status line naming it. As P104's own
|
|
5047
|
+
change did, it now describes what P105 does where it does it, without a §8 row; the release
|
|
5048
|
+
commit says what the document describes.
|
|
5049
|
+
|
|
5050
|
+
**API.** No signature changes. What a host may see change: `activated` is dropped while its page
|
|
5051
|
+
has no transient activation; the exported `parseAnchor` returns a label without invisible
|
|
5052
|
+
characters; `selected` comes again after a scroll only when its box moved, on the follow-ups'
|
|
5053
|
+
clock; text markers are elsewhere (`activated`'s box is the marker's, wherever it is drawn); a
|
|
5054
|
+
tap on a marker is reported on WebKit; ADOPTING.md's `guardPresses` takes `...parts` and returns
|
|
5055
|
+
`{ placed }` as before.
|
|
5056
|
+
|
|
5057
|
+
**Tested.** `test/annotate.test.ts`, on `createHost` over a stand-in platform: `activated` dropped
|
|
5058
|
+
where `userActivation()` answers false or throws, taken where it answers true or undefined; a
|
|
5059
|
+
`viewport()` answering null, a string, sizes as strings, throwing, or with a throwing getter: every
|
|
5060
|
+
box nothing at the corner, nothing thrown out of the listener; `clampRect(rect, null)`; a label's
|
|
5061
|
+
bidi override, zero-width, tag, soft hyphen and control characters taken out, emoji and a Persian
|
|
5062
|
+
joiner kept, a quote's soft hyphen kept, the host's own marks checked the same way.
|
|
5063
|
+
`leak/annotate.spec.ts`, on Chromium, WebKit and Firefox: the honest session in comment mode (its
|
|
5064
|
+
follow-ups, the selection's too, at most 45 in 28 s, nothing refused, the click after it taken;
|
|
5065
|
+
failed first with 120 on Chromium and Firefox); marks without counts told nothing after a scroll; a
|
|
5066
|
+
drag from a marker leaves the selection as it was; a page that patches
|
|
5067
|
+
`Event.prototype.stopImmediatePropagation` and `MouseEvent`'s `clientX` and `clientY` neither hears
|
|
5068
|
+
a marker's press nor stops its report; a page's `activated` posted 6.5 s after the marks arrived,
|
|
5069
|
+
with no gesture, not taken, and one on the person's own press in the content taken (the duty's
|
|
5070
|
+
case); the marker helpers find a marker where it is, by the points along its line where the layer
|
|
5071
|
+
takes the pointer. Negative controls, each alone, failing exactly their test on all three engines:
|
|
5072
|
+
`marker-prevent`, `marker-originals`, `follow-throttle`, `selection-follow`, `follow-count`,
|
|
5073
|
+
`annotation-activated-gesture`; and `marker-click` (now also failing the patched-prototypes case),
|
|
5074
|
+
`marker-trusted`, `annotation-activated`, `annotation-activated-count`, `annotation-checks` and
|
|
5075
|
+
`annotation-rect-clamp` again, as before.
|
|
5076
|
+
|
|
5077
|
+
**Tested, after the review of 3969ebc.** Unit: the review's label and the 20,000 random ones.
|
|
5078
|
+
Leak, on all three engines: the tap test (touch screen, iPhone 13, Pixel 5), the placement test,
|
|
5079
|
+
the guard test. Controls `marker-tap` and `marker-place`, and every control P105 added or touched,
|
|
5080
|
+
again.
|
|
5081
|
+
|
|
5082
|
+
**Threat it re-opens.** None: each point narrows what content can do or says what holds; no
|
|
5083
|
+
default, gate or policy loosens.
|
|
5084
|
+
|
|
5085
|
+
**Rejected.**
|
|
5086
|
+
- A budget of its own for `activated` (the review's other way for point 1): one clock keeps an
|
|
5087
|
+
honest page's follow-ups at half the shared rate, which leaves a click its room, without a second
|
|
5088
|
+
rate in the bridge (P104's reason). Two clocks, one a kind, would together be 120 a minute, the
|
|
5089
|
+
whole budget, on a session longer than a minute.
|
|
5090
|
+
- A token in each marker's report, so a host takes only the shell's: the content shares the
|
|
5091
|
+
shell's realm and would read it.
|
|
5092
|
+
- The marker at the line's last word everywhere: it covers nothing on the column either, but its
|
|
5093
|
+
place moves with each line's length and each reflow. It is the place in a cell or a card, where
|
|
5094
|
+
the gutter is someone else's.
|
|
5095
|
+
- #36's other way, a dot without a number by the words and the number on hover: there is no hover
|
|
5096
|
+
on a phone, and the number is what P104 is for. Compact keeps it.
|
|
5097
|
+
- Capturing `matches` and `querySelectorAll` for the insertion guards (R3): they run on every node
|
|
5098
|
+
the page inserts, through three prototypes; done right that is a change of its own to the
|
|
5099
|
+
shell's guards, for nothing secret.
|
|
5100
|
+
- Refusing a label with an invisible character, as P100 refuses an update: a label is only shown,
|
|
5101
|
+
and a selection with a soft hyphen is ordinary.
|
|
5102
|
+
|
|
5103
|
+
**Revisit when** a layout puts text beside a block that hit testing can't see (`pointer-events:
|
|
5104
|
+
none`), a host shows right-to-left text (the gutter is on the right), a host needs to place
|
|
5105
|
+
markers itself (then it draws them from `anchored`), an engine changes what gives a page
|
|
5106
|
+
activation, or MCP Apps defines annotations.
|