@botiverse/porthole 0.9.0 → 0.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/annotate/types.d.ts +21 -7
- package/dist/annotate/validate.d.ts +18 -3
- package/dist/annotate/validate.js +29 -5
- package/dist/bridge/bridge.js +1 -51
- package/dist/bridge/unseen.d.ts +18 -0
- package/dist/bridge/unseen.js +71 -0
- package/dist/check/files.d.ts +2 -0
- package/dist/check/files.js +67 -50
- package/dist/check/lint.d.ts +8 -1
- package/dist/check/lint.js +18 -0
- package/dist/check/markup.d.ts +7 -0
- package/dist/check/markup.js +49 -0
- package/dist/check/page-source.js +1 -1
- package/dist/check/scroll.d.ts +100 -0
- package/dist/check/scroll.js +1429 -0
- package/dist/conformance/behavior.js +107 -68
- package/dist/conformance/clipboard.js +16 -14
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/limits.js +117 -64
- package/dist/conformance/probes.js +66 -49
- package/dist/conformance/runtime.js +6 -0
- package/dist/conformance/served.js +66 -63
- package/dist/guide/guide.js +1 -1
- package/dist/guide/runtime.js +2 -2
- package/dist/host/create-host.js +46 -4
- package/dist/index.d.ts +1 -1
- package/dist/platform/types.d.ts +4 -2
- package/dist/react/frame.d.ts +2 -1
- package/dist/runtime/requests.d.ts +5 -0
- package/dist/runtime/requests.js +16 -1
- package/dist/runtime/types.generated.js +1 -1
- package/dist/shell/annotate.d.ts +6 -3
- package/dist/shell/annotate.js +474 -104
- package/dist/shell/use.js +9 -1
- package/docs/ADOPTING.md +99 -1
- package/docs/ARCHITECTURE.md +2 -1
- package/docs/DECISIONS.md +764 -14
- package/docs/DESIGN.md +192 -42
- package/docs/THREAT_MODEL.md +109 -27
- package/package.json +1 -1
- package/src/annotate/types.ts +22 -7
- package/src/annotate/validate.ts +32 -6
- package/src/bridge/bridge.ts +1 -60
- package/src/bridge/unseen.ts +82 -0
- package/src/check/files.ts +68 -54
- package/src/check/lint.ts +24 -0
- package/src/check/markup.ts +53 -0
- package/src/check/scroll.ts +1757 -0
- package/src/conformance/behavior.ts +221 -69
- package/src/conformance/clipboard.ts +44 -14
- package/src/conformance/limits.ts +169 -76
- package/src/conformance/probes.ts +97 -49
- package/src/conformance/runtime.ts +9 -0
- package/src/conformance/served.ts +112 -63
- package/src/guide/guide.ts +1 -0
- package/src/guide/runtime.ts +2 -2
- package/src/host/create-host.ts +50 -4
- package/src/index.ts +1 -0
- package/src/platform/types.ts +4 -2
- package/src/react/frame.tsx +2 -1
- package/src/runtime/requests.ts +23 -1
- package/src/runtime/types.generated.ts +1 -1
- package/src/shell/annotate.ts +474 -104
- package/src/shell/use.ts +9 -1
- package/types/runtime/v1/comments.d.ts +14 -4
package/docs/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;
|
|
@@ -3028,7 +3033,7 @@ store); `test/runtime.test.ts` (the CSP sources; upload limits and names).
|
|
|
3028
3033
|
the public suffix list (CORP becomes defense in depth), or a host needs assets shared across
|
|
3029
3034
|
artifacts (`copy_from`: a new id in the destination).
|
|
3030
3035
|
|
|
3031
|
-
## P090 · 2026-10-18 · Comments from the page: the host's composer at the page's anchor, write-only · Accepted; amended by P091
|
|
3036
|
+
## P090 · 2026-10-18 · Comments from the page: the host's composer at the page's anchor, write-only · Accepted; amended by P091, P108
|
|
3032
3037
|
|
|
3033
3038
|
**Decision.** `comments` is a built-in (P086) host function served by a handler: `open({ name,
|
|
3034
3039
|
label?, quote? })` (a name the page chose, ≤ 256 characters, `slide-3`, `refs/a.md#L12`; a label ≤
|
|
@@ -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, P107
|
|
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,741 @@ 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
|
+
Later (0.11.0, #46): a shard runs about 42 minutes, but a browser install that usually takes
|
|
4853
|
+
20 seconds took 21 (apt mirrors) and the 60-minute shard was cancelled with every control it
|
|
4854
|
+
reached passing. A shard now allows 90 minutes, and its install fails on its own past 25.
|
|
4855
|
+
|
|
4856
|
+
**Why.** PRINCIPLE 6: a wall never seen to fail proves nothing, and a check that says a wall was
|
|
4857
|
+
seen to fail when its run never happened is worse than no check. CI's "every control" was 7 of
|
|
4858
|
+
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,
|
|
4859
|
+
when someone remembered, and what DESIGN.md said they fail had drifted from what they do.
|
|
4860
|
+
**Rejected.**
|
|
4861
|
+
- Requiring exit 0, or exit 1, alone: either is what a broken run can give.
|
|
4862
|
+
- Counting any failure of a named test: a browser that can't launch fails every test, and a spec
|
|
4863
|
+
whose every test is named (permissions, authorize) would pass a run that never reached Porthole.
|
|
4864
|
+
- Retrying: a named test that fails only sometimes is not a wall seen to fail; a test that fails
|
|
4865
|
+
besides them is either a dependency the registry must name, or a flaky probe to fix.
|
|
4866
|
+
- Parsing the prose columns of DESIGN.md's tables for each control's probes: the prose explains
|
|
4867
|
+
why; the generated table is the exact claim, and the test holds the prose to naming only
|
|
4868
|
+
controls that exist.
|
|
4869
|
+
- Running controls with `kit.spec.ts` until the kit's app applies weakenings: its walls are the
|
|
4870
|
+
core's, whose controls run against the leak and served harnesses.
|
|
4871
|
+
**Threat it re-opens.** None: no default, gate or policy changes; four probes see more.
|
|
4872
|
+
**Revisit when** Playwright's JSON report changes shape (the judge's tests pin the fields it reads),
|
|
4873
|
+
a control's run makes a CI job too long (shard the controls across jobs), or the kit's app gains
|
|
4874
|
+
a weakening seam (then its controls join the registry).
|
|
4875
|
+
|
|
4876
|
+
## 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
|
|
4877
|
+
|
|
4878
|
+
Amends P104 (its points 1, 3, 5 and 7, and its Trust) and P053's Trust. From the independent
|
|
4879
|
+
review of P104 and 0.9.0 (botiverse/porthole#37: no P0 or P1, two P2s, six P3s) and from #36
|
|
4880
|
+
(Ferry, taking 0.9.0: a text marker covered the next word). Measured on Chromium 153, WebKit 26.6
|
|
4881
|
+
and Firefox 155.
|
|
4882
|
+
|
|
4883
|
+
**Decision**, by finding:
|
|
4884
|
+
1. **P2-2: the selection's re-report is a follow-up too.** After every settled scroll the shell
|
|
4885
|
+
sent the person's selection again (`selected`, since P053), whether its box had moved or not,
|
|
4886
|
+
outside P104's one-a-second clock. P104's own honest session (140 wheel turns 200 ms apart, a
|
|
4887
|
+
mark with a count) in comment mode (text selection on, one selection) sent 120 reports, the
|
|
4888
|
+
bridge's 120 a minute, and the marker's click after it was refused (`annotate:rate-limited`):
|
|
4889
|
+
the review's R5 on all three engines, and the extended test, failing first with 120 taken
|
|
4890
|
+
(Chromium, Firefox). Now the selection is told
|
|
4891
|
+
again only when its box moved more than 0.5 px since it was last told (or it changed, or went),
|
|
4892
|
+
and on the follow-ups' clock, which both kinds share: at most one report a second together, the
|
|
4893
|
+
latest (two in one tick leave the next second empty). The same session now gives 15 `anchored`
|
|
4894
|
+
and 15 `selected`, none refused, and the click is taken, on all three. A selection the person
|
|
4895
|
+
makes is told at once, as before; only the re-reports wait. A host without counts still hears
|
|
4896
|
+
the `anchored` reports 0.8 sent, and its selection again after a scroll only if it moved.
|
|
4897
|
+
2. **P2-1: the host's view of a mark is the host's to guard, and `activated` needs a gesture.** A
|
|
4898
|
+
page can post `activated` for a shown mark on its own `pointerdown`, with the pointer's
|
|
4899
|
+
coordinates; the host had it 9 to 121 ms into the press (R4), so a double click asked for on
|
|
4900
|
+
the content's own button lands its second click on the bubble's Resolve. THREAT_MODEL §6 asked a
|
|
4901
|
+
500 ms guard of confirmations only. Now it asks, of every host: a view that a frame's report
|
|
4902
|
+
opens or moves (`activated`, `anchored`, `selected`) takes no press for 500 ms after it appears
|
|
4903
|
+
or moves, ignores a press that began before that, opens beside the frame rather than over the
|
|
4904
|
+
report's box where the layout allows, takes no focus, and puts no destructive action one click
|
|
4905
|
+
away. ADOPTING.md § Annotations has the guard (`guardPresses`), P104's Trust says so.
|
|
4906
|
+
The narrowing, which holds: `createHost` takes `activated` only while `surface.userActivation()`
|
|
4907
|
+
isn't false (the gesture gate's reading: undefined, where a platform can't tell, passes; a
|
|
4908
|
+
throw drops it). A real marker click gives the host's page transient activation on all three
|
|
4909
|
+
engines, though the shell cancels the press (activation comes before the event is dispatched);
|
|
4910
|
+
a page's own post at load or on a timer has none (measured: a sandboxed frame's timer posts
|
|
4911
|
+
arrive with the host inactive; a click in it, its `mousedown` cancelled, activates the host).
|
|
4912
|
+
Playwright's `evaluate` is itself a gesture and activation lasts 5 s on all three, so the test
|
|
4913
|
+
asks nothing of either page for 7.5 s first. It stops a view opened with no gesture at all, and
|
|
4914
|
+
no more: activation lasts 5 s after any gesture anywhere on the page (a click on the host's own
|
|
4915
|
+
UI, typing in the content, the click that opened the display), and a fake posted then, on a
|
|
4916
|
+
timer or a scroll, is taken (point 9); one on the person's own press is R4. The host's duty
|
|
4917
|
+
above is the defence. A custom
|
|
4918
|
+
platform's `userActivation()` (already required) that answers false drops every marker click,
|
|
4919
|
+
as it refuses every gesture-gated call.
|
|
4920
|
+
3. **#36: a text marker beside its line, not over the next word.** P104 drew it at the words' end,
|
|
4921
|
+
raised (left at their right + 2, top 12 px above the line): its lower 6 px lay over the next
|
|
4922
|
+
word's first letters, and on a narrow page, when the words ended at a wrapped line's start,
|
|
4923
|
+
between two lines. Now it is centred on the anchor's last line, at the first of these places
|
|
4924
|
+
that is inside the frame, clear of that line's words, and over nothing of the content's but a
|
|
4925
|
+
box holding the anchor, with nothing else between the words and it (the shell hit-tests the
|
|
4926
|
+
place with `elementsFromPoint`, its own layer aside): the line's gutter, just past the right
|
|
4927
|
+
edge of the anchor's block (its content box); where the frame is too narrow for that, the
|
|
4928
|
+
frame's right edge; where something else is beside the block (a table's next cell, a card in a
|
|
4929
|
+
row), just past the line's last word. Markers ending on one line of one block go together, in
|
|
4930
|
+
the order their words end. Where the bubble with its glyph fits in none of these, its number
|
|
4931
|
+
alone does (compact: 18 px for one digit, inside a phone page's 20 px padding); where that fits
|
|
4932
|
+
nowhere either, the group goes as far right as nothing else stands in the way, over the line's
|
|
4933
|
+
end. The pointer on a marker lights its words as the active mark's are. A draw now measures
|
|
4934
|
+
every marker before it changes a node, and leaves each marker that stays where it is in the
|
|
4935
|
+
layer: one taken out and put back mid-press lost its click on WebKit (seen once the pointer's
|
|
4936
|
+
arrival lit a mark and redrew). Element markers are placed as they were.
|
|
4937
|
+
Judged on screen (16 px text, line height 1.6; a centred 640 px column, and a 390 px page with
|
|
4938
|
+
full-width text and 20 px padding; anchors ending mid-line, at a line's end, at a wrapped line's
|
|
4939
|
+
start, two and three on one line, in a card, in a table cell, and elements; Chromium, Firefox,
|
|
4940
|
+
WebKit): on the column, no marker covers a glyph (0.9.0's touched 14 words); on the phone none
|
|
4941
|
+
does but where two or three anchors end on one full line, which covers that line's last letters
|
|
4942
|
+
(0.9.0's touched 13 words there, and sat between lines). The gutter is worse than 0.9.0's place
|
|
4943
|
+
in one way: a marker for words that end mid-line, or on a short line, sits up to the column's
|
|
4944
|
+
width from them, tied to them by the line, its order and their highlight (and, with a pointer,
|
|
4945
|
+
by the light on hover). Taken for the column it gives: which lines have comments reads at a
|
|
4946
|
+
glance, and a marker doesn't move as the line's words reflow.
|
|
4947
|
+
4. **P3-1: the shell's guarantees say what they hold against.** The shell shares the content's
|
|
4948
|
+
realm and, at a marker's press, called the live prototypes: content that replaced
|
|
4949
|
+
`Event.prototype.stopImmediatePropagation` heard a real press (R1), one that redefined the
|
|
4950
|
+
`MouseEvent.prototype.clientX` getter made the shell miss the click (R2), and one that wrapped
|
|
4951
|
+
`Element.prototype.matches` got the closed shadow root from the shell's insertion guards and
|
|
4952
|
+
rewrote a marker (R3), on all three engines. Restated in THREAT_MODEL §7, P104's Trust, P053's
|
|
4953
|
+
Trust, DESIGN.md and the shell's comments: a press is unheard and can't be cancelled, and the
|
|
4954
|
+
layer is out of reach, against content that patches none of the built-ins (CHANGELOG 0.9.0's
|
|
4955
|
+
wording is the release's). The narrowing, small and a reading of the same functions: the
|
|
4956
|
+
marker's listener reads and stops a press through the platform's own functions and getters,
|
|
4957
|
+
kept before content runs, as the navigation guard does (`stopImmediatePropagation`;
|
|
4958
|
+
`preventDefault` as kept before a tab's shell locks its own; `target`, `type`, `button`,
|
|
4959
|
+
`clientX`, `clientY`; DOMRect's sides; `Reflect.apply`), and `tell` reads `window.parent` once
|
|
4960
|
+
(it is `[Replaceable]`). R1 and R2 no longer work (test and control `marker-originals`). R3
|
|
4961
|
+
still does, and picking's listeners still read the live prototypes. Nothing in the layer is
|
|
4962
|
+
secret.
|
|
4963
|
+
5. **P3-2: controls for what had none.** `marker-prevent` (the press's `preventDefault` out: focus
|
|
4964
|
+
moves, on every engine). Its selection probe was blind: a click on a marker never changes a
|
|
4965
|
+
selection, with or without the cancel, since markers aren't selectable. So it now also drags
|
|
4966
|
+
from the marker over the next line's words, which WebKit then selects; Chromium and Firefox
|
|
4967
|
+
don't, either way (measured). `follow-throttle` (`FOLLOW_EVERY` 0: the honest session's count,
|
|
4968
|
+
now a `probe:` verdict); `follow-count`, with a test of its own (marks without counts, a scroll:
|
|
4969
|
+
nothing after the settle); `selection-follow` (0.9.0's re-report after every settle). DESIGN.md
|
|
4970
|
+
said `marker-click` covered focus and selection: it covers the handlers, `marker-prevent` focus
|
|
4971
|
+
and the selection.
|
|
4972
|
+
6. **P3-3: a platform's `viewport()` that answers no size or throws** raised a TypeError out of the
|
|
4973
|
+
transport's listener (the report was dropped: closed, but out of the listener). Now
|
|
4974
|
+
`createHost` reads it in a `try` and takes only numbers, and `clampRect` takes null as unknown:
|
|
4975
|
+
every box is nothing at the frame's corner, and nothing throws.
|
|
4976
|
+
7. **P3-5: labels lose what the person can't see.** P104 named a wordless element by its `alt`,
|
|
4977
|
+
`aria-label` or `title`, text the person never sees on the page, which could carry bidi
|
|
4978
|
+
controls or zero-width characters into the host's UI, or a model's context through a host
|
|
4979
|
+
that forwards it. `parseAnchor` (so `parseReport` and `checkMarks`) takes out of every label
|
|
4980
|
+
every character P100's rule names, with none of its exceptions (point 9), now one definition in
|
|
4981
|
+
`src/bridge/unseen.ts`. Selectors keep theirs, to be found again; THREAT_MODEL says a quote
|
|
4982
|
+
handed to a model is the page's words.
|
|
4983
|
+
8. **P3-4 and P3-6: written down.** The frame's size is read for each report the host takes,
|
|
4984
|
+
before its rate: one forced layout of the host's page per message, which a repeated
|
|
4985
|
+
`ui/initialize` already causes (accepted; the clamp after the gate would sit in the bridge's
|
|
4986
|
+
delivery). A box is in the frame's own CSS px: a host that scales or transforms the frame maps
|
|
4987
|
+
it through that transform (THREAT_MODEL §7, ADOPTING.md, `AnnotationRect`).
|
|
4988
|
+
|
|
4989
|
+
9. **After the review of 3969ebc** (no P0 or P1; R5, R1 and R2 hold, every control fails exactly
|
|
4990
|
+
its probes):
|
|
4991
|
+
- **P2-A: the guard in ADOPTING.md let presses through.** It caught `click` alone, and let one
|
|
4992
|
+
with `detail` 0 pass: a menu item that clicks itself when a press that began elsewhere ends
|
|
4993
|
+
on it (Radix's pattern; Base UI's items click on `mouseup`), and a trigger that acts on
|
|
4994
|
+
`pointerdown`, fired within 500 ms (the review's R9). Now the guard makes the view `inert`
|
|
4995
|
+
(and `pointer-events: none`) while it arms, so nothing in it takes a press, a click or focus, and
|
|
4996
|
+
after that it drops the end of a press that didn't begin on it (`pointerup`, `mouseup`,
|
|
4997
|
+
`touchend`, `click`) until one does, or a key. Portaled menus and popovers are outside the
|
|
4998
|
+
view: they go in a container inside it, or are guarded too, and close when it moves. §6 says
|
|
4999
|
+
a press of any kind. A leak test runs the snippet as ADOPTING.md has it (the review's three
|
|
5000
|
+
cases, a press held past the arming, then a press and a key that are taken); the old snippet
|
|
5001
|
+
fails it by the menu item's release.
|
|
5002
|
+
- **P2-B: a tap on a marker was never reported on WebKit** (since 0.9.0): WebKit made no click
|
|
5003
|
+
of a tap on the marker, whose only listener was the window's, though it did for a button.
|
|
5004
|
+
Each marker now has a click listener of its own, which never runs (the window's first
|
|
5005
|
+
listener stops every click on the layer): WebKit then clicks. A tap reports on all three
|
|
5006
|
+
engines, with a touch screen and in a phone's emulation (iPhone 13 on WebKit, Pixel 5 on
|
|
5007
|
+
Chromium; Firefox has none), after 6 s of nothing: the tap's own activation is what the host
|
|
5008
|
+
takes it by (measured: the host's page is active when the report arrives). The reference
|
|
5009
|
+
host's page now has a viewport meta, as a phone's page has: without it the emulation lays the
|
|
5010
|
+
page out 980 px wide at 0.4, and Playwright's taps land beside the frame. Control `marker-tap`
|
|
5011
|
+
(the listener out) fails the test on WebKit; Chromium and Firefox click a tap without it.
|
|
5012
|
+
- **P3-A: the label strip wasn't closed.** It kept P100's exceptions (the parts of emoji, a
|
|
5013
|
+
joiner between two shaped letters), and a Mongolian variation selector, itself a mark of a
|
|
5014
|
+
shaping script and default-ignorable, made a joiner beside it look shaped, then was taken out
|
|
5015
|
+
itself: a 107-character label kept 48 joiners, `rm -rf` in bits. Now every code point the rule
|
|
5016
|
+
names goes, no exceptions: an emoji in a label loses its joiners and selectors (its faces
|
|
5017
|
+
stay). Tested with that label, and 20,000 random ones from the review's pool, none of which
|
|
5018
|
+
leaves anything `unseen` refuses.
|
|
5019
|
+
- **P3-B:** THREAT_MODEL and point 2 said a page could no longer open the host's view at load, on
|
|
5020
|
+
a timer or on a scroll; within 5 s of any gesture anywhere on the page it can (the review's
|
|
5021
|
+
R7b). Both now say so, and that the guard is the defence.
|
|
5022
|
+
- **P3-C: placing markers after a change of the content was dear** (the longest task, 300
|
|
5023
|
+
paragraphs with counts: 44, 53 and 19 ms on Chromium, WebKit and Firefox; 200 marks in one
|
|
5024
|
+
3,000-line `<pre>`: 168, 163 and 102 ms). A line's end was read from the whole rest of its
|
|
5025
|
+
block, for each marker; each hit test walked every mark and marker the last draw left in the
|
|
5026
|
+
layer (0.13 ms a test, measured); a mark's block was found again on every change. Now the
|
|
5027
|
+
line's end is read 64 characters at a time, only until the text leaves the line; the layer's
|
|
5028
|
+
marks and markers are out of the hit tests while places are tested (hidden in one task, never
|
|
5029
|
+
taken out of the page); a marker whose line is out of view is placed without a measure or a
|
|
5030
|
+
test; a block is kept while it still holds the words. Measured again: 18, 22 and 16 ms; 24,
|
|
5031
|
+
48 and 40 ms (without counts: 5, 6 and 11; 13, 25 and 37). THREAT_MODEL and DESIGN say what it
|
|
5032
|
+
costs and that it is bounded.
|
|
5033
|
+
- **P3-D: nothing pinned #36.** A leak test now reads every word's glyph boxes against the points
|
|
5034
|
+
the layer takes (a 2 px grid) on the column page, all of its cases, and on the phone page's
|
|
5035
|
+
lines with one marker each: no marker covers a word, on all three engines. Control
|
|
5036
|
+
`marker-place` (the marker just past its words, centred on the line, as 0.9.0 placed it
|
|
5037
|
+
across) fails it. The press test's drag goes round the paragraph, so it holds wherever the
|
|
5038
|
+
marker is.
|
|
5039
|
+
- **P3-E:** CHANGELOG.md's Unreleased section says what a host sees change, what to act on first.
|
|
5040
|
+
- **CI's WebKit (PR #38):** `selection-follow` and `follow-throttle` failed nothing there: the
|
|
5041
|
+
honest session's verdict was a count of follow-ups over 140 wheel turns, and a slower runner
|
|
5042
|
+
settles fewer of them, so a shell without the clock stayed under it. The test now also
|
|
5043
|
+
scrolls eight times 300 ms apart from inside the frame, each a settle on any machine, and the
|
|
5044
|
+
host page notes when each follow-up arrives: the selection's re-reports, and the marks'
|
|
5045
|
+
follow-ups, must each come at least 700 ms apart (the clock keeps them 1 s apart; without it
|
|
5046
|
+
they come 300 ms apart). Both controls fail it on WebKit pinned to one CPU. That run also
|
|
5047
|
+
showed P104's settle test counting the script's steps, 30 ms apart, while a starved
|
|
5048
|
+
engine's scroll events bunched across a late frame: it counts the events now.
|
|
5049
|
+
- **P3-F:** THREAT_MODEL had P105 in §8 as merged and its status line naming it. As P104's own
|
|
5050
|
+
change did, it now describes what P105 does where it does it, without a §8 row; the release
|
|
5051
|
+
commit says what the document describes.
|
|
5052
|
+
|
|
5053
|
+
**API.** No signature changes. What a host may see change: `activated` is dropped while its page
|
|
5054
|
+
has no transient activation; the exported `parseAnchor` returns a label without invisible
|
|
5055
|
+
characters; `selected` comes again after a scroll only when its box moved, on the follow-ups'
|
|
5056
|
+
clock; text markers are elsewhere (`activated`'s box is the marker's, wherever it is drawn); a
|
|
5057
|
+
tap on a marker is reported on WebKit; ADOPTING.md's `guardPresses` takes `...parts` and returns
|
|
5058
|
+
`{ placed }` as before.
|
|
5059
|
+
|
|
5060
|
+
**Tested.** `test/annotate.test.ts`, on `createHost` over a stand-in platform: `activated` dropped
|
|
5061
|
+
where `userActivation()` answers false or throws, taken where it answers true or undefined; a
|
|
5062
|
+
`viewport()` answering null, a string, sizes as strings, throwing, or with a throwing getter: every
|
|
5063
|
+
box nothing at the corner, nothing thrown out of the listener; `clampRect(rect, null)`; a label's
|
|
5064
|
+
bidi override, zero-width, tag, soft hyphen and control characters taken out, emoji and a Persian
|
|
5065
|
+
joiner kept, a quote's soft hyphen kept, the host's own marks checked the same way.
|
|
5066
|
+
`leak/annotate.spec.ts`, on Chromium, WebKit and Firefox: the honest session in comment mode (its
|
|
5067
|
+
follow-ups, the selection's too, at most 45 in 28 s, nothing refused, the click after it taken;
|
|
5068
|
+
failed first with 120 on Chromium and Firefox); marks without counts told nothing after a scroll; a
|
|
5069
|
+
drag from a marker leaves the selection as it was; a page that patches
|
|
5070
|
+
`Event.prototype.stopImmediatePropagation` and `MouseEvent`'s `clientX` and `clientY` neither hears
|
|
5071
|
+
a marker's press nor stops its report; a page's `activated` posted 6.5 s after the marks arrived,
|
|
5072
|
+
with no gesture, not taken, and one on the person's own press in the content taken (the duty's
|
|
5073
|
+
case); the marker helpers find a marker where it is, by the points along its line where the layer
|
|
5074
|
+
takes the pointer. Negative controls, each alone, failing exactly their test on all three engines:
|
|
5075
|
+
`marker-prevent`, `marker-originals`, `follow-throttle`, `selection-follow`, `follow-count`,
|
|
5076
|
+
`annotation-activated-gesture`; and `marker-click` (now also failing the patched-prototypes case),
|
|
5077
|
+
`marker-trusted`, `annotation-activated`, `annotation-activated-count`, `annotation-checks` and
|
|
5078
|
+
`annotation-rect-clamp` again, as before.
|
|
5079
|
+
|
|
5080
|
+
**Tested, after the review of 3969ebc.** Unit: the review's label and the 20,000 random ones.
|
|
5081
|
+
Leak, on all three engines: the tap test (touch screen, iPhone 13, Pixel 5), the placement test,
|
|
5082
|
+
the guard test. Controls `marker-tap` and `marker-place`, and every control P105 added or touched,
|
|
5083
|
+
again.
|
|
5084
|
+
|
|
5085
|
+
**Threat it re-opens.** None: each point narrows what content can do or says what holds; no
|
|
5086
|
+
default, gate or policy loosens.
|
|
5087
|
+
|
|
5088
|
+
**Rejected.**
|
|
5089
|
+
- A budget of its own for `activated` (the review's other way for point 1): one clock keeps an
|
|
5090
|
+
honest page's follow-ups at half the shared rate, which leaves a click its room, without a second
|
|
5091
|
+
rate in the bridge (P104's reason). Two clocks, one a kind, would together be 120 a minute, the
|
|
5092
|
+
whole budget, on a session longer than a minute.
|
|
5093
|
+
- A token in each marker's report, so a host takes only the shell's: the content shares the
|
|
5094
|
+
shell's realm and would read it.
|
|
5095
|
+
- The marker at the line's last word everywhere: it covers nothing on the column either, but its
|
|
5096
|
+
place moves with each line's length and each reflow. It is the place in a cell or a card, where
|
|
5097
|
+
the gutter is someone else's.
|
|
5098
|
+
- #36's other way, a dot without a number by the words and the number on hover: there is no hover
|
|
5099
|
+
on a phone, and the number is what P104 is for. Compact keeps it.
|
|
5100
|
+
- Capturing `matches` and `querySelectorAll` for the insertion guards (R3): they run on every node
|
|
5101
|
+
the page inserts, through three prototypes; done right that is a change of its own to the
|
|
5102
|
+
shell's guards, for nothing secret.
|
|
5103
|
+
- Refusing a label with an invisible character, as P100 refuses an update: a label is only shown,
|
|
5104
|
+
and a selection with a soft hyphen is ordinary.
|
|
5105
|
+
|
|
5106
|
+
**Revisit when** a layout puts text beside a block that hit testing can't see (`pointer-events:
|
|
5107
|
+
none`), a host shows right-to-left text (the gutter is on the right), a host needs to place
|
|
5108
|
+
markers itself (then it draws them from `anchored`), an engine changes what gives a page
|
|
5109
|
+
activation, or MCP Apps defines annotations.
|
|
5110
|
+
|
|
5111
|
+
## P106 · 2026-10-23 · A page held to one screen by its own styles is warned before it is published · Accepted
|
|
5112
|
+
|
|
5113
|
+
From Raft's triage of its Artifacts (task #71): agents' first versions of high-fidelity mockups,
|
|
5114
|
+
bundled from an app's own code, carry the app shell's global styles, `html, body { height: 100%;
|
|
5115
|
+
overflow: hidden }` and `#root { position: fixed; height: 100dvh; overflow: hidden }`, right for
|
|
5116
|
+
the app and wrong for a long page in a frame: it doesn't scroll. 2 of 50 artifacts on the server
|
|
5117
|
+
had it (the first version broken, the second fixing it by overriding the styles); one also had an
|
|
5118
|
+
inner box take the wheel. Nothing told the agent: the manual spoke only of sideways overflow, and
|
|
5119
|
+
`admitFiles` didn't look.
|
|
5120
|
+
|
|
5121
|
+
**Decision.**
|
|
5122
|
+
1. **`scroll-lock`, a warning** in `lintContent` (so `admitContent`) and `lintFiles` (so
|
|
5123
|
+
`admitFiles`), from `src/check/scroll.ts`: a cascade, read from the text, of the few
|
|
5124
|
+
properties that matter (overflow, height, max-height, position, top and bottom, with their
|
|
5125
|
+
shorthands) over the three elements that hold a document: html, body, and the body's one
|
|
5126
|
+
element of content (the root: `#root`, `#app`, a lone `div`; none where body has two). It
|
|
5127
|
+
warns where one of them holds the page and nothing below body scrolls itself:
|
|
5128
|
+
- html with overflow-y hidden or clip;
|
|
5129
|
+
- body with overflow-y hidden or clip, where html's overflow is visible or body is one screen;
|
|
5130
|
+
- the root with overflow-y hidden or clip, one screen tall;
|
|
5131
|
+
- any of them `position: fixed`, one screen tall.
|
|
5132
|
+
Nothing below body scrolls itself: no element in the page's own markup below body has
|
|
5133
|
+
`overflow` or `overflow-y` auto or scroll, by its `style=""`, by a Tailwind class (where
|
|
5134
|
+
Tailwind is loaded), or by a rule the check reads whose selector matches it (with the selectors
|
|
5135
|
+
the check can match; one it can't read, or that matches nothing in the markup, doesn't count).
|
|
5136
|
+
The root itself isn't such an element, by its `style=""`, its classes or a rule: it is in the
|
|
5137
|
+
cascade, so its own values decide. One screen tall with overflow-y auto or scroll, it scrolls
|
|
5138
|
+
the page (no warning); without a height it grows with what it holds and has nothing to scroll,
|
|
5139
|
+
so `html, body { height: 100%; overflow: hidden } #root { overflow-y: auto }`, or the same
|
|
5140
|
+
with `<div id="root" style="overflow: auto">`, is held. A root that scrolls in a height the
|
|
5141
|
+
check can't read is its own box, as an inner one is (no warning): under a flex or grid body
|
|
5142
|
+
(its `display`, or Tailwind's `flex`, `grid`; the root's height is the layout's: `flex-1`), or
|
|
5143
|
+
with a height of another shape (a length, `min()`, `var()`, a `calc()` other than below, an
|
|
5144
|
+
arbitrary `h-[…]`), where body itself is one screen tall. It is held where its height is the
|
|
5145
|
+
content's (unset, `auto`, `fit-content`, or 100% of a body that is) under a block body, and
|
|
5146
|
+
wherever body isn't one screen tall (a body that grows with the page holds a flex column that
|
|
5147
|
+
does too: `html { height: 100%; overflow: hidden } body { display: flex; flex-direction:
|
|
5148
|
+
column; overflow: hidden } #root { overflow: auto }` is held).
|
|
5149
|
+
Where one does, the page may scroll in that box (a dashboard's `main { flex: 1; overflow-y:
|
|
5150
|
+
auto }`), and the text can't tell which box holds the content: no warning; the manual's line on
|
|
5151
|
+
the wheel says the rest. Matched against at most 2,000 elements, 32 deep, 256 selectors and a
|
|
5152
|
+
million steps (each selector's compound and element tried once).
|
|
5153
|
+
**A page its script draws** (body holds at most one element of content, with no text, and the
|
|
5154
|
+
page has a script: `<div id="root"></div>`) has nothing to match: it is warned, but said as a
|
|
5155
|
+
page that looks held: "The page looks held to one screen in its frame: … If it is meant to fit
|
|
5156
|
+
one screen, or a box its script draws scrolls the content, ignore this; otherwise let it scroll
|
|
5157
|
+
as a document: …". A page with its content in the markup is told "The page won't scroll in its
|
|
5158
|
+
frame: … Unless it is meant to fit one screen, let it scroll as a document: …".
|
|
5159
|
+
One screen: height or max-height (or `block-size`, `max-block-size`) `100vh` (`dvh`, `svh`,
|
|
5160
|
+
`lvh`) or `calc(100vh - 4rem)` (the whole less one positive length: px, rem, em, %, vh),
|
|
5161
|
+
`100%` or `calc(100% - 56px)` of a one-screen parent (html's 100% is
|
|
5162
|
+
the frame's; Tailwind's arbitrary `h-[calc(100vh-4rem)]` read as Tailwind writes it, with
|
|
5163
|
+
spaces around `-` and `+`) or of the frame where it is fixed or absolute, or fixed or absolute with both top
|
|
5164
|
+
and bottom set (`inset: 0`). Measured with Playwright's Chromium and Firefox (a 3,000 px
|
|
5165
|
+
page, a 400 px frame, the wheel): each of these stops it; `body { overflow: hidden }` alone
|
|
5166
|
+
does (the viewport takes body's overflow), as does `#root { position: fixed; inset: 0 }`
|
|
5167
|
+
without any overflow; `#root { overflow: hidden }` without a height, `#root { height: 100% }`
|
|
5168
|
+
under a body as tall as its content, `html, body { height: 100% }` alone, and
|
|
5169
|
+
`overflow-x: hidden` alone don't; a one-screen `#root { overflow: auto }` under a held body
|
|
5170
|
+
scrolls in the root. WebKit couldn't run on the box; nothing here is engine-specific CSS.
|
|
5171
|
+
Why the markup: an app's whole stylesheet, bundled into a page, has scroll boxes of its own (a
|
|
5172
|
+
list, a sidebar) that a page may never draw; counting every such rule would leave the app
|
|
5173
|
+
shell's page, the case this is for, unwarned.
|
|
5174
|
+
2. **What it reads:** `<style>` and `<link rel=stylesheet>` in document order (not for print, not
|
|
5175
|
+
alternate), the linked sheets found in the version and their `@import`s, `style=""` on the
|
|
5176
|
+
three, rules whose selectors it can match (type, id, class, `*`, `:root`, `:only-child`,
|
|
5177
|
+
`:first-child`, descendant and child), and, where the page loads Tailwind (its CDN, or a
|
|
5178
|
+
Tailwind stylesheet), the utilities that hold a page (`h-screen`, `h-full`, `overflow-hidden`,
|
|
5179
|
+
`fixed`, `inset-0`…). Specificity, order, `!important` and cascade layers pick each value, so
|
|
5180
|
+
a later override, as the triage's second versions wrote, is seen. A layer's place is where it is
|
|
5181
|
+
first declared or its block opens, a sub-layer's rules below its parent's own, unlayered rules
|
|
5182
|
+
above all layers, reversed for `!important`; each value is picked once every sheet is read.
|
|
5183
|
+
**Bounded:** a page's stylesheets are each read once (a sheet linked or imported again is read
|
|
5184
|
+
where it first comes), at most 32 of them and 4 MiB in all, its own `<style>` elements
|
|
5185
|
+
included; past that, the rest isn't read (a later one that fits still is). Each
|
|
5186
|
+
is asked of the caller once per place it is named from. The check is then linear in what it
|
|
5187
|
+
reads: ten sheets each importing the next six times read ten sheets, not 6^10; each element
|
|
5188
|
+
keeps, per longhand, only each layer's winner so far (within a layer, and within `!important`
|
|
5189
|
+
or `style=""`, specificity and order decide; the layers' order picks among those once all is
|
|
5190
|
+
read), and the layers' tree is built in place, so a sheet of 80,000 declarations, or an `@layer`
|
|
5191
|
+
of 80,000 names, costs what sixteen of 5,000 do. A rule's selectors are read one at a time, and
|
|
5192
|
+
a scroll rule's kept only while there is room for them (a 2 MiB rule of 300,000 selectors ran
|
|
5193
|
+
out of memory at 128 MB before). An element's classes are a set, and a compound
|
|
5194
|
+
selector of more than 32 ids and classes matches nothing, so matching a compound against an
|
|
5195
|
+
element is bounded work, for html, body and the root as for the elements below body: the size
|
|
5196
|
+
of the sheets and the size of the page add, not multiply. A layer named more than 16 deep
|
|
5197
|
+
(`a.b.c…`, with the layers it is in) isn't read: its rules are dropped, but its first 16 parts
|
|
5198
|
+
are declared where it comes, as a browser declares them, so the layers' order holds. A page's
|
|
5199
|
+
sheets name at most 1,024 layers (each, parents included): a new one past them isn't declared
|
|
5200
|
+
and its rules aren't read, as a layer too deep (each layer kept every value its rules gave:
|
|
5201
|
+
2 MiB of anonymous layers needed 128 MB of heap, of layers 15 parts deep 256 MB, in 8daa075
|
|
5202
|
+
too). A layer's name with the layers it is in (`a.b.c`) is at most 256 characters: a longer
|
|
5203
|
+
one isn't declared, nor its rules or the layers in it read (each anonymous layer in a 1.9 MB
|
|
5204
|
+
one copied its name: out of memory at 1,024 MB; in a 1 MB one, past 300 s).
|
|
5205
|
+
**A version's pages** (`lintFiles`, so `admitFiles` at publish): the rule reads the pages an
|
|
5206
|
+
agent opens first, the entry and then the others in path order, at most 8 in all, each as a
|
|
5207
|
+
page alone (its sheets read as it streams them: nothing parsed is kept from one page to the
|
|
5208
|
+
next). Only the pages' paths are kept for it, and the eight it checks are decoded again there
|
|
5209
|
+
(keeping every page's text took 96 MB for 500 pages of 192 KB). The 8 share one budget: 8 MiB of stylesheet read, every sheet each page reads (one two
|
|
5210
|
+
pages link is read for each) and each page's own `<style>`, and two million steps of matching
|
|
5211
|
+
scroll rules against markup. A page that would spend more than is left isn't checked, nor are
|
|
5212
|
+
any after it, the cheap ones too. Where pages aren't checked (past 8, or past the budget), one
|
|
5213
|
+
warning says how many: "N pages not checked for scroll lock: the check reads the entry and at
|
|
5214
|
+
most 7 other pages, within one budget. If one of them holds html, body or its root to one
|
|
5215
|
+
screen (…), let it scroll as a document." A page over its size isn't read at all (its error
|
|
5216
|
+
says so) and isn't counted. A warning, so an unchecked page is a warning missed, never a
|
|
5217
|
+
refusal. Bounded: whatever a version holds, the rule reads at most 8 pages and 8 MiB of
|
|
5218
|
+
sheets (the review's 500 pages sharing a 250 KB sheet took 13.8 s; 999 pages sharing a 1 MB one
|
|
5219
|
+
now read 8). Why not read each sheet once for the version and replay it for each page (the
|
|
5220
|
+
fourth review's answer): its parsed rules took about 100 bytes a byte, kept for the version (a
|
|
5221
|
+
page with one 2 MiB sheet ran out of memory at 128 MB; eight with their own took 1.5 GB), for
|
|
5222
|
+
an advisory rule whose pages that matter are the ones an agent opens.
|
|
5223
|
+
3. **The warning says what to do:** what holds it, as the page wrote it, and the rule that undoes
|
|
5224
|
+
it under the page's own selectors (so it wins by coming later; `!important` where the hold
|
|
5225
|
+
was). The page's CSS goes into the agent's context, so only values of a known shape are echoed
|
|
5226
|
+
(lengths, percentages, viewport units, 0, auto, hidden, clip, fixed, static…; else the property
|
|
5227
|
+
and `…`), each declaration (its `!important` included) and selector at most 60 characters, and
|
|
5228
|
+
a selector with escapes, other than plain characters or longer is given as the element's own
|
|
5229
|
+
name: `#root` where the root's id is plain and `#id` at most 60 characters (the id is page text
|
|
5230
|
+
too), else `body > div`, or `body > *` for an element HTML doesn't have (a custom element's
|
|
5231
|
+
name is page text too). Where that name has less specificity than the selector it stands for
|
|
5232
|
+
(`body > div` for a 61-character `#id`, `#root` for `body > #\72 oot.x`), the fix is
|
|
5233
|
+
`!important`, or it couldn't win. So: `add html, body, #root { height: auto; overflow: visible; position: static } after
|
|
5234
|
+
those rules`, `take h-screen overflow-hidden off body's class`, or `take … out of html's style
|
|
5235
|
+
attribute`. In `lintFiles` it names the stylesheet and line the hold is in; a page's own
|
|
5236
|
+
`<style>` is reported once.
|
|
5237
|
+
4. **The manual** (the Pages section, every kind): "It scrolls as a document: unless it's meant to
|
|
5238
|
+
fit one screen (a game, a canvas), don't hold html, body or the element that holds it all to one
|
|
5239
|
+
screen (height: 100% or 100vh with overflow: hidden, or
|
|
5240
|
+
position: fixed), or what's below the first screen can't be reached. A box that scrolls by
|
|
5241
|
+
itself takes the wheel while the pointer is over it: keep those to parts of the page (a wide
|
|
5242
|
+
table, a long list), never the whole of it."
|
|
5243
|
+
|
|
5244
|
+
**Why.** The agent learns it at publish, with the fix in the words of its own CSS, instead of from
|
|
5245
|
+
a person who can't scroll. A warning and not a refusal: some pages are one-screen apps on purpose,
|
|
5246
|
+
and a text read can't be sure.
|
|
5247
|
+
|
|
5248
|
+
**Rejected.**
|
|
5249
|
+
- Overflow hidden on html or body only together with a one-screen height (the triage's first
|
|
5250
|
+
rule): body's overflow alone stops the viewport, measured above; requiring the height misses
|
|
5251
|
+
`body { overflow: hidden }`, which is the common way to stop a page's scroll.
|
|
5252
|
+
- Measuring it in a browser (`checkPage` comparing the document's scroll height with the frame):
|
|
5253
|
+
publish has no browser; a later check may add it, and then the wheel too.
|
|
5254
|
+
- Warning on an inner one-screen scroll box: it does scroll, and an app's sidebar is one; the
|
|
5255
|
+
manual says it instead.
|
|
5256
|
+
- Warning where a box below body scrolls, unless it is shown to hold the page: from the text, a
|
|
5257
|
+
box's height in a flex or grid layout can't be told, and the review's three cases (a flex
|
|
5258
|
+
`main`, Tailwind's dashboard, a `style="overflow: auto"`) were false warnings.
|
|
5259
|
+
- Any rule that gives something below body a scroll box silencing the warning (the first answer
|
|
5260
|
+
to that review): an app's bundled stylesheet always has one, and its pages went unwarned.
|
|
5261
|
+
|
|
5262
|
+
**Limits.** Not read: rules under `@media` (but `all` and `screen`), `@supports`, `@container`;
|
|
5263
|
+
`:is()`, `:where()`, `:not()`, attributes and sibling combinators (they match nothing); nested
|
|
5264
|
+
rules; values through `var()` or `calc()`; `@import … layer()` beyond a name; a layer named more
|
|
5265
|
+
than 16 deep; a sheet's second link or import; what scripts set; stylesheets from another origin;
|
|
5266
|
+
sheets past the budget. Each can miss a hold or an override (a warning then wrong, never
|
|
5267
|
+
a refusal). A body with stray unclosed tags may be taken as having one child. A root that scrolls
|
|
5268
|
+
under a flex or grid body, or with a height the check can't read, is taken as its own scroll box:
|
|
5269
|
+
where it is in fact as tall as its content (a flex column's item without `flex: 1`, a `min()`
|
|
5270
|
+
that comes to its content), the hold is missed. In a version, pages past the entry and 7 more,
|
|
5271
|
+
or past the budget (8 MiB of sheets, two million match steps), aren't checked: a warning says
|
|
5272
|
+
how many. A page's layers past 1,024, and a layer's name past 256 characters, aren't read: that
|
|
5273
|
+
misses a hold in them, and it can warn wrongly too, where the hold is in a layer read and what
|
|
5274
|
+
undoes it is in one that isn't (`html { overflow: hidden }` in layer `p0`, and `html { overflow:
|
|
5275
|
+
visible }` in a new layer past the cap). Known, to follow: the app shell's fix names
|
|
5276
|
+
only html (`add html { … }`), and body's overflow, which the viewport takes once html's is
|
|
5277
|
+
visible, is said by a second warning after it; an `!important` hold inside a layer can't be
|
|
5278
|
+
undone by the unlayered `!important` the fix suggests (a layer's `!important` beats it), so the
|
|
5279
|
+
same advice comes again; `display: -webkit-box` isn't taken as flex.
|
|
5280
|
+
|
|
5281
|
+
**Tested.** `test/check.test.ts` (a page held to one screen): the app shell's exact styles (the
|
|
5282
|
+
message and line), body or html hidden alone, the root by height, max-height and `inset: 0`, a
|
|
5283
|
+
lone `div` by `:only-child`, `style=""`, `!important`, a more specific hold over a later override,
|
|
5284
|
+
Tailwind's CDN utilities on body and a build's class rules; none for overflow hidden on the root
|
|
5285
|
+
without a height, a one-screen height without overflow hidden, `overflow-x: hidden`, an inner
|
|
5286
|
+
element, two body children, a one-screen scroll box in a held body, 100% of a content-tall body;
|
|
5287
|
+
later overrides (same `<style>`, a later one, `style=""`, unlayered over layered, a comment),
|
|
5288
|
+
part of an override not enough; the limits (`@media`, `@supports`, `var()`, `:is()`); the
|
|
5289
|
+
manual's line in the artifact, fill and inline manuals; after review: none where something below
|
|
5290
|
+
body scrolls in the markup (a flex `main`, Tailwind's dashboard, `style="overflow: auto"`), held
|
|
5291
|
+
where it only scrolls sideways; an app bundle (the shell's styles and `.message-list { overflow-y:
|
|
5292
|
+
auto }`, an empty `#root`) warned in the hedged words, silent with a `.message-list` in its markup
|
|
5293
|
+
(also through `#root > section .message-list`), held where the markup has no match, the selector
|
|
5294
|
+
can't be read (`:hover`) or doesn't match (`section > .message-list`); the shell's styles over
|
|
5295
|
+
content in the markup said flatly; a hostile `top:` value and a long one not echoed, an escaped
|
|
5296
|
+
selector given as `#root`; after the second review: a scroll rule on the root without a height
|
|
5297
|
+
held (`#root { overflow-y: auto }`, `body > div { overflow: auto }`), one screen tall not, a box in
|
|
5298
|
+
the root or one of two in body still a scroll box; a plain id of 1,400 characters given as `body >
|
|
5299
|
+
div` (in the rule, the fix and the style attribute's fix; the message 346 characters, 3,128
|
|
5300
|
+
before), one of 59 as `#id`; a layer 100,000 deep not read (it overflowed the stack), 16 deep read;
|
|
5301
|
+
80,000 declarations of body and an `@layer` of 80,000 names timed against sixteen times 5,000
|
|
5302
|
+
(under eight times as long, and each under 2 s: about 0.06 s and 0.14 s here, 36.6 s and 36.3 s
|
|
5303
|
+
before); after the third review: html, body, the root and 24 paragraphs with 4,000 classes each
|
|
5304
|
+
against two 2 MB `.a.a….b` rules, timed against sixteen sixteenths of both (under eight times,
|
|
5305
|
+
under 2 s: 0.1 s here, 178 s before; a sixteenth of both took 0.74 s, a quarter 11 s), a
|
|
5306
|
+
compound of 32 classes read and 33 not, a deep layer's parents declared where it comes (`theme`
|
|
5307
|
+
before `reset`), `!important` within the 60 characters, a custom element as `body > *`, the root
|
|
5308
|
+
by its own `style="overflow: auto"` and Tailwind class held without a height and not with
|
|
5309
|
+
`h-full`, by `block-size`, `max-block-size` and `calc(100vh - 56px)`, and a `style="overflow:
|
|
5310
|
+
auto"` below the root still a scroll box; after the fourth review: the four app shells (a
|
|
5311
|
+
Tailwind flex column with a `flex-1 overflow-y-auto` root, `display: flex` with an inline-styled
|
|
5312
|
+
root, Tailwind's grid with an `overflow-auto` main, an `h-[calc(100vh-4rem)]` root) and `min()`,
|
|
5313
|
+
a longer `calc()` and a length silent, the content's heights (none, `fit-content`, `auto`, a
|
|
5314
|
+
`display: block` body, 100% of a content-tall body) held; `calc()` read only as a whole less one
|
|
5315
|
+
positive length (`- 1px + 2000px`, `- -2000px`, `-10px`, `var()` not), `calc(100% - 4rem)` one
|
|
5316
|
+
screen under a one-screen body and not under a content-tall one; an `@import` into a layer 17
|
|
5317
|
+
deep declaring its first 16 parts; with no root, a body child's `style=""` still a scroll box;
|
|
5318
|
+
the fix `!important` where `#root` or `body > div` stands for a more specific selector, not where
|
|
5319
|
+
it is the selector; after the fifth review: `:root { overflow: hidden }` and `* { height: 100%;
|
|
5320
|
+
overflow: hidden }` held (the fix under their own selectors), `#\72 oot` as specific as `#root`
|
|
5321
|
+
so no `!important`, a flex column under a body that grows with the page held, and a root of
|
|
5322
|
+
`640px` under such a body too; a layer opened early with nothing for the page losing to a later one, a sub-layer below
|
|
5323
|
+
its parent's own rules either way round. `test/files.test.ts`: a linked sheet (its
|
|
5324
|
+
path and line), an `@import`ed one, each page by what it links, overrides across sheets in either
|
|
5325
|
+
order, print, alternate and missing sheets, and `admitFiles`'s note; ten sheets each importing the
|
|
5326
|
+
next six times (11 asks, well under 2 s; without the budget it ran past 60 s), a thousand links to
|
|
5327
|
+
one sheet (asked once), and a hold past 32 sheets unread; `lintFiles` on a page linking a 1.8 MB
|
|
5328
|
+
sheet of 230,000 declarations for body, under 3 s (0.2 s; 285 s before); 999 pages sharing a 1
|
|
5329
|
+
MB sheet (a version's most files) the entry and 7 more checked, in that order, and "991 pages
|
|
5330
|
+
not checked" said, under 10 s (41 s before) and under four times what 8 pages cost; eight
|
|
5331
|
+
pages or fewer, no note; eight pages, the first five linking a sheet just under 2 MiB, four
|
|
5332
|
+
checked and the fifth stopping the rest, the three cheap ones after it too ("4 pages not
|
|
5333
|
+
checked"); a page's own `<style>` charged (three of 3.5 MiB, the third not checked, nor a cheap
|
|
5334
|
+
one after); four pages each spending a page's million match steps, two checked; in a child
|
|
5335
|
+
process under a 48 MB heap, one page linking a 2 MiB sheet of each of six shapes: `.kN{top:0}`,
|
|
5336
|
+
`div{top:0}`, one rule's 300,000 selectors, anonymous layers, layers 15 parts deep and named
|
|
5337
|
+
layers of six declarations (each runs in 32 MB; the fourth review's code ran out at 128 MB on the
|
|
5338
|
+
first three, 8daa075 on the third; 11c422f on the last three at 64 MB, the layers 15 parts
|
|
5339
|
+
deep at 128 MB too), and 500
|
|
5340
|
+
pages of 192 KB as bytes (8 checked, "492 pages not checked"; 11c422f ran out at 96 MB). After
|
|
5341
|
+
the sixth review: 1,023 layers and a new one read, 1,024 and a new one not, `a.b` with one place
|
|
5342
|
+
left not, an unlayered rule and a layer already named still read, an `@import … layer(z)` past
|
|
5343
|
+
them not read; a layer's name of 256 characters read and of 257 not, nor one of 250 with a
|
|
5344
|
+
sub-layer of 6; an `@import … layer()` of 256 characters read and of 257 not; a statement's
|
|
5345
|
+
257-character name taking no place among the 1,024; a 1.9 MB layer name with 5,500 anonymous layers in it, under the 48 MB heap and
|
|
5346
|
+
5 s (out of memory at 1,024 MB before); a page's own `<style>` past
|
|
5347
|
+
4 MiB not read and the next one read; Tailwind's `h-[calc(100vh-4rem)] overflow-hidden` on the
|
|
5348
|
+
root held, `h-[calc(100vh--4rem)]` not one screen. The manual's examples and the
|
|
5349
|
+
Vite + React fixture still lint clean.
|
|
5350
|
+
|
|
5351
|
+
**Revisit when** `checkPage` measures scrolling in a browser (then this can defer to it), a host's
|
|
5352
|
+
viewer scrolls the frame itself (a page then can't be held), or the misses above show up in
|
|
5353
|
+
published pages.
|
|
5354
|
+
|
|
5355
|
+
## P107 · 2026-10-23 · Draft marks: a person's unposted comments, a dashed line and a hollow marker with no number · Accepted
|
|
5356
|
+
|
|
5357
|
+
A host adding batch comments (Raft Artifacts) shows a person's unsubmitted comments, drafts, in the
|
|
5358
|
+
page while they write more: at their anchors, in a style apart from posted comments, so that what
|
|
5359
|
+
others can already read and what only the author has written so far don't look alike. P104's marks
|
|
5360
|
+
have one look (a solid underline, a filled numbered marker, or neither), and P104 rejected a style
|
|
5361
|
+
knob per mark for want of a need. This is the need: one state, not a knob.
|
|
5362
|
+
|
|
5363
|
+
**Decision.**
|
|
5364
|
+
1. **`AnnotationMark.kind?: "posted" | "draft"`**, absent meaning posted. `checkMarks` checks it
|
|
5365
|
+
as it checks the other fields: any other value (a typo, another case, a number, null) throws,
|
|
5366
|
+
naming the mark. A posted mark is sent to the frame as 0.10.0 sent it (no `kind`, whether the host
|
|
5367
|
+
said `"posted"` or nothing), so nothing changes for a host that has no drafts, nor for the page.
|
|
5368
|
+
2. **A draft has a marker, never a number.** Its `count` is still checked (a bad one throws: it is
|
|
5369
|
+
the host's bug) and then dropped: the frame gets `{ id, anchor, kind: "draft" }`. The shell, too,
|
|
5370
|
+
draws no number for a draft and drops a mark of a kind it doesn't know. A draft gets a marker
|
|
5371
|
+
with or without a count (`hasMarker`), so everything P104 and P105 give a mark with a marker it
|
|
5372
|
+
gets the same way: `activated` taken for its id (within a gesture), `anchored` with the rest,
|
|
5373
|
+
following after a scroll or a change of the content (a host whose only markers are drafts is
|
|
5374
|
+
followed), placement in the gutter, compact where it must, stepping aside while picking.
|
|
5375
|
+
3. **Drawn apart.** A draft's text mark is a dashed 2 px underline (3 px when active) over a
|
|
5376
|
+
lighter fill than a posted mark's; an element's is P104's quiet outline, dashed. Its marker is
|
|
5377
|
+
hollow: a near-white bubble with a 1 px dashed amber edge and the bubble glyph's outline
|
|
5378
|
+
(stroked, not filled), no number, the same size as a posted marker without one (so placement is
|
|
5379
|
+
unchanged). Hover and active lighten it, as they do a posted one. The colors are the layer's own,
|
|
5380
|
+
as P104's are (the page's styles don't reach the layer), and read on light and dark pages. No
|
|
5381
|
+
new motion (the focus flash is the posted mark's). The shell has no forced-colors or
|
|
5382
|
+
high-contrast styles of its own; in forced colors a draft's dashed borders survive where the
|
|
5383
|
+
posted marks' box-shadow underline doesn't, which is the shell's gap, not this change's.
|
|
5384
|
+
|
|
5385
|
+
**Trust.** Unchanged in kind from P104; one thing more the page learns.
|
|
5386
|
+
- *What content can now learn:* which of its marks are drafts, that the person viewing it is
|
|
5387
|
+
writing a comment there before they post it. Accepted, and said in THREAT_MODEL §7: the host sends
|
|
5388
|
+
drafts only to their author's own frame (Porthole can't tell whose a frame is: it is the host's
|
|
5389
|
+
duty, said in ADOPTING.md); the page is the thing being commented on and already sees where that
|
|
5390
|
+
person selects (`selected`) and points; and closed egress keeps what it learns off the network.
|
|
5391
|
+
Not off the channels the host opens: with the runtime's `db` writes and `user`, a page can read
|
|
5392
|
+
who is viewing (`user.get()`) and which shown marks are drafts, and store "viewer A is drafting
|
|
5393
|
+
at section 3" where its author and other viewers read it before A posts, then tie A's posted
|
|
5394
|
+
comment to A by its anchor and time; origins a config declares for egress (an MCP App's
|
|
5395
|
+
`connectDomains`, an `egress` the host opened; the `liveWidget` preset has none, P103) carry it
|
|
5396
|
+
out the same way (THREAT_MODEL S4, S5, §7). So a draft's existence, place and timing are the page's to
|
|
5397
|
+
pass on wherever the host gave it a way, and ADOPTING.md says: don't send drafts to such a page,
|
|
5398
|
+
or accept that its author and other viewers can learn of them. Nothing else of a draft reaches
|
|
5399
|
+
it: not its count (dropped, control `draft-count`; a host that sends a mark per draft tells how
|
|
5400
|
+
many there are), and its id is the host's, which ADOPTING.md already asks to say nothing.
|
|
5401
|
+
- *What content can fake:* `activated` for a draft's id, as for any mark with a marker (P104,
|
|
5402
|
+
P105): the host's view of a draft opens on it, guarded as THREAT_MODEL §6 says, and never acts
|
|
5403
|
+
(no submit, no discard one click away).
|
|
5404
|
+
- *A shared frame:* a host that sends drafts into a frame several people see tells that page, and
|
|
5405
|
+
whatever it draws for them, what one of them hasn't posted. That is the host's choice to not make.
|
|
5406
|
+
|
|
5407
|
+
**API.** `AnnotationMark.kind`, `AnnotationMarkKind` (exported), `hasMarker` (internal to the host
|
|
5408
|
+
and its checks). `annotations.show` throws on a bad `kind` (React's `annotations` reports it
|
|
5409
|
+
through `onHostError`, kind `"annotations"`). No other change: posted marks, every report, the
|
|
5410
|
+
bridge's rate are as they were. The shell is the content server's: one from before P107, given a
|
|
5411
|
+
draft by a newer host, draws it as a posted mark without a marker (it ignores `kind` and has no
|
|
5412
|
+
count), so a host upgrades its content server's Porthole before sending drafts.
|
|
5413
|
+
|
|
5414
|
+
**Tested.** `test/annotate.test.ts`: `checkMarks` keeps a draft's kind and drops its count, sends
|
|
5415
|
+
`"posted"` as nothing, still refuses a draft's bad count, and throws on `"Draft"`, `"note"`, `""`,
|
|
5416
|
+
`"draft "`, 1, null, true and `{}`; on `createHost` over a stand-in platform, `activated` taken for a
|
|
5417
|
+
draft with and without a count, and dropped for a posted mark without one. `leak/annotate.spec.ts`,
|
|
5418
|
+
on Chromium, WebKit and Firefox: the same anchors as posted marks (count 0, so neither has a number)
|
|
5419
|
+
and then as drafts look different in the frame and on the words; on Chromium, every draft's marker
|
|
5420
|
+
and line carry the draft's style and the markers have no number though one draft was given 7; a
|
|
5421
|
+
draft and a posted mark together, each drawn its way, the draft's text and element markers' clicks
|
|
5422
|
+
and the posted one's reported for their ids, none reaching the content's listeners (control
|
|
5423
|
+
`marker-click`, the shell's stop out, fails it too); the page,
|
|
5424
|
+
listening to its own window, reads a draft as `{ id, anchor, kind }` and posted marks as before
|
|
5425
|
+
(control `draft-count`, the count left on drafts, fails exactly that test); a raw `show` posted to
|
|
5426
|
+
the frame from the host's page, past `checkMarks`, with a draft given a count and a mark of kind
|
|
5427
|
+
`"note"`: the draft's marker is a bubble without a number (by its clicked box on every engine, by
|
|
5428
|
+
its words on Chromium) and the unknown kind is neither anchored nor drawn (control
|
|
5429
|
+
`draft-shell-checks`, the shell's two checks out, fails exactly that test); drafts alone followed
|
|
5430
|
+
once a scroll settles. P104's and P105's marker tests and controls pass as before.
|
|
5431
|
+
|
|
5432
|
+
**Threat it re-opens.** None of Porthole's: no default, gate or policy loosens. The page learns one
|
|
5433
|
+
fact more (a mark is a draft), bounded by the host's duty above.
|
|
5434
|
+
|
|
5435
|
+
**Rejected.**
|
|
5436
|
+
- A style per mark (colors, dashes) for the host to choose: P104's reason; two states cover the
|
|
5437
|
+
need, and a style the host picks is one more thing the page reads.
|
|
5438
|
+
- Hiding that a mark is a draft from the page (drawing drafts the host's own way, over the frame):
|
|
5439
|
+
the host can't place over the frame what moves with the frame's scroll without the frame's
|
|
5440
|
+
reports, which is what markers are; and the author's own frame is the one place a draft goes.
|
|
5441
|
+
- A draft's count drawn as a number: a hollow marker with a number reads as posted; a host with
|
|
5442
|
+
several drafts at an anchor gives them one mark or several, as it likes.
|
|
5443
|
+
- A dot without the glyph: the bubble's outline reads as "a comment, not yet", and keeps the size,
|
|
5444
|
+
so a draft's marker sits where a posted one would.
|
|
5445
|
+
|
|
5446
|
+
**Revisit when** a host needs drafts in a frame others see (then the host draws them itself), a
|
|
5447
|
+
third state is asked for (resolved, private: then a state list, still not a style knob), the
|
|
5448
|
+
shell gets forced-colors styles, or MCP Apps defines annotations.
|
|
5449
|
+
|
|
5450
|
+
## P108 · 2026-10-26 · A comment's draft from the page: text the composer starts with, never posted by the page · Accepted
|
|
5451
|
+
|
|
5452
|
+
Amends P090. A page that asks for decisions (Raft's "decision sheet": a card per question with
|
|
5453
|
+
"Approve" and "Needs changes" buttons) opens the host's composer at the card with `comments.open`
|
|
5454
|
+
(P090), and the person then types the same words every time. xxchan asked for the button to carry
|
|
5455
|
+
them (#proj-workspace, 2026-10-26).
|
|
5456
|
+
|
|
5457
|
+
**Decision.**
|
|
5458
|
+
1. **`comments.open(anchor, { draft })`.** `draft` is text the composer starts with: a string, not
|
|
5459
|
+
blank, at most 2,000 characters (the quote's limit), well-formed, and nothing a person can't see
|
|
5460
|
+
(P100's `unseen`: no zero-width, bidi or tag characters, no controls but a new line and a tab,
|
|
5461
|
+
so a checklist is fine). Anything else refuses the call as `invalid` before any handler, as a
|
|
5462
|
+
draft that isn't a string does: the shell sends it as the page gave it (options that aren't an
|
|
5463
|
+
object send `null`), read after the click's check, so a getter that throws is a rejection. The
|
|
5464
|
+
handler gets `{ anchor, draft }`.
|
|
5465
|
+
2. **The rest is P090's.** From a click (`user-activation`, 30 a minute), view level; content hears
|
|
5466
|
+
only whether the composer opened; no method reads a thread; the page never posts.
|
|
5467
|
+
3. **The host's duties** (THREAT_MODEL §6 and §7, ADOPTING's example): show the draft whole, as the
|
|
5468
|
+
person's editable plain text, in its own composer; post it only on the person's Send; arm the
|
|
5469
|
+
composer as §6 arms a view the content brought: no press, and no Enter that sends, for 500 ms
|
|
5470
|
+
after it opens, Send not focused, beside the frame where the layout allows. Once posted the
|
|
5471
|
+
comment is the person's, mentions in it included: that is why they must see it all first.
|
|
5472
|
+
`defineRuntimeConformance` checks that the handler takes a draft (answers a boolean); that it
|
|
5473
|
+
never posts on its own can't be seen from a handler and is the host's.
|
|
5474
|
+
|
|
5475
|
+
**Why.** The comment is still the person's word: they see all of the text, can change or drop it,
|
|
5476
|
+
and post it themselves, as P090 requires. What the page saves them is typing.
|
|
5477
|
+
**Threats it opens, and their bounds.**
|
|
5478
|
+
- *Words the person didn't read:* a long draft hiding a line they wouldn't sign, or one an agent
|
|
5479
|
+
reading the comment later takes as their instruction. Bounded by visible text only (no hidden
|
|
5480
|
+
characters: the review found tags, U+200B and U+202E would otherwise pass), 2,000 characters, and
|
|
5481
|
+
the host showing it whole; reading it is the person's.
|
|
5482
|
+
- *Click-through:* before P108 a stray press on Send posted nothing; now the first click already
|
|
5483
|
+
loads a postable comment, and the page can place its button where Send will appear (the second
|
|
5484
|
+
click of a double click), or ask the person to press Enter. Bounded by the host's arming (above).
|
|
5485
|
+
**Rejected.** The page posting the comment (P090); a draft without a gesture; rich text or
|
|
5486
|
+
mentions resolved from the draft before posting (the host would be acting on the content's names);
|
|
5487
|
+
coercing what isn't text into text (`String(null)` is "null", which the person never meant).
|
|
5488
|
+
**Tested.** `test/runtime.test.ts` ("a draft (P108)": as given, a checklist too; past 2,000,
|
|
5489
|
+
blank, a number, null, a lone surrogate, tag characters, U+200B, U+202E, a bell: `invalid`, no
|
|
5490
|
+
handler); `leak/served/runtime.spec.ts` ("a comment's draft is the host's to check": from real
|
|
5491
|
+
clicks, a zero-width space, tags, 2,001 characters, a number and a string as options open nothing
|
|
5492
|
+
and reach no handler, a checklist reaches the composer; "comments are write-only": the draft beside
|
|
5493
|
+
the anchor). Negative control `comment-draft` (the draft taken as given) → the first case, every
|
|
5494
|
+
engine. `types/runtime/v1/check.ts` (the page-shaped call compiles); the runtime conformance's
|
|
5495
|
+
comments case sends a draft.
|