@botiverse/porthole 0.13.0 → 0.14.1
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/CHANGELOG.md +770 -0
- package/dist/annotate/types.d.ts +36 -4
- package/dist/annotate/types.js +6 -0
- package/dist/annotate/validate.d.ts +2 -1
- package/dist/annotate/validate.js +30 -6
- package/dist/check/page-source.js +1 -1
- package/dist/compile/policy.d.ts +7 -0
- package/dist/compile/policy.js +13 -1
- package/dist/config/schema.d.ts +11 -0
- package/dist/config/validate.js +19 -0
- package/dist/conformance/harness-source.js +1 -1
- package/dist/displays/displays.js +3 -1
- package/dist/guide/limits.js +1 -1
- package/dist/host/create-host.d.ts +2 -0
- package/dist/host/create-host.js +78 -3
- package/dist/host/pass-on.d.ts +15 -0
- package/dist/host/pass-on.js +65 -0
- package/dist/host/types.d.ts +29 -0
- package/dist/index.d.ts +4 -1
- package/dist/index.js +4 -1
- package/dist/isolation/types.d.ts +8 -0
- package/dist/isolation/types.js +8 -0
- package/dist/platform/focus-guard.d.ts +71 -2
- package/dist/platform/focus-guard.js +187 -12
- package/dist/platform/types.d.ts +8 -1
- package/dist/platform/web.js +60 -4
- package/dist/presets/presets.d.ts +2 -0
- package/dist/presets/presets.js +1 -0
- package/dist/react/frame.d.ts +4 -3
- package/dist/server/files.js +19 -3
- package/dist/server/index.d.ts +1 -0
- package/dist/server/index.js +5 -0
- package/dist/server/naming.js +4 -0
- package/dist/server/nested.d.ts +59 -0
- package/dist/server/nested.js +96 -0
- package/dist/server/server.js +193 -23
- package/dist/server/types.d.ts +5 -0
- package/dist/shell/annotate.d.ts +4 -3
- package/dist/shell/annotate.js +179 -9
- package/dist/shell/frame.d.ts +45 -0
- package/dist/shell/frame.js +250 -0
- package/dist/shell/plan.js +2 -1
- package/dist/shell/runtime.d.ts +6 -0
- package/dist/shell/runtime.js +60 -15
- package/docs/ADOPTING.md +85 -2
- package/docs/ARCHITECTURE.md +28 -0
- package/docs/DECISIONS.md +416 -1
- package/docs/DESIGN.md +21 -4
- package/docs/THREAT_MODEL.md +102 -5
- package/package.json +6 -5
- package/src/annotate/types.ts +32 -4
- package/src/annotate/validate.ts +34 -8
- package/src/compile/policy.ts +14 -1
- package/src/config/schema.ts +11 -0
- package/src/config/validate.ts +23 -0
- package/src/displays/displays.ts +3 -1
- package/src/guide/limits.ts +1 -1
- package/src/host/create-host.ts +81 -4
- package/src/host/pass-on.ts +73 -0
- package/src/host/types.ts +27 -0
- package/src/index.ts +4 -1
- package/src/isolation/types.ts +12 -0
- package/src/platform/focus-guard.ts +258 -15
- package/src/platform/types.ts +8 -1
- package/src/platform/web.ts +81 -9
- package/src/presets/presets.ts +3 -0
- package/src/react/frame.tsx +4 -3
- package/src/server/files.ts +19 -3
- package/src/server/index.ts +14 -0
- package/src/server/naming.ts +4 -0
- package/src/server/nested.ts +116 -0
- package/src/server/server.ts +224 -21
- package/src/server/types.ts +5 -0
- package/src/shell/annotate.ts +179 -9
- package/src/shell/frame.ts +268 -0
- package/src/shell/plan.ts +2 -1
- package/src/shell/runtime.ts +61 -15
package/docs/DECISIONS.md
CHANGED
|
@@ -4595,7 +4595,7 @@ second wall on a tab); a host needs a served page to open windows from a tab (th
|
|
|
4595
4595
|
`'self'` default (it joins `FRAME_DENIED_FEATURES`); or WebKit and Firefox apply
|
|
4596
4596
|
`Permissions-Policy` to these features (the shell's device locks become the second wall there too).
|
|
4597
4597
|
|
|
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
|
|
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, P116
|
|
4599
4599
|
|
|
4600
4600
|
A host that shows its comments beside an artifact page wants, at each comment's anchor in the page,
|
|
4601
4601
|
a small marker (a bubble and how many comments are there) that scrolls with the content; a click on
|
|
@@ -5843,3 +5843,418 @@ that throws gives the "wasn't checked" warning; `admitFiles` with `\ffffff` in a
|
|
|
5843
5843
|
|
|
5844
5844
|
**Revisit when** a page's own document is ever shown outside the shell (then quirks mode is real),
|
|
5845
5845
|
or an engine starts counting fixed boxes in what the viewport scrolls.
|
|
5846
|
+
|
|
5847
|
+
## P111 · 2026-10-28 · A nested page: Porthole's shell at the framed address, the page its opaque child, and the shell's own activation decides the keyboard and `comments.open` · Accepted
|
|
5848
|
+
|
|
5849
|
+
**Context.** P109's focus guard and `comments.open`'s gate ask whether the person, not the page,
|
|
5850
|
+
moved the keyboard into a frame or clicked in it. In full Chromium a cross-site frame is out of
|
|
5851
|
+
process, and the host's page sees nothing of a press in it: measured on Chromium 153 (2026-10-28,
|
|
5852
|
+
not the headless shell Playwright runs by default), no `:active`, no `:hover`, no pointer event past
|
|
5853
|
+
the frame's edge, only its window blurring with its own activation on, which a page's `focus()`
|
|
5854
|
+
after the person typed in the host also gives. So a person's real click into a page's field was
|
|
5855
|
+
taken back every time (the display stopped at the third), and `comments.open` from a real click was
|
|
5856
|
+
refused within 5 s of any input on the host's page (porthole#53). WebKit keeps these frames in
|
|
5857
|
+
process (`:active` holds there) and was right. Nothing in the page's realm can be asked instead:
|
|
5858
|
+
in every mode before this one, the shell's runtime and the page share a document (served, opaque,
|
|
5859
|
+
the MCP proxy), so whatever the shell would report, the page could post from the same window
|
|
5860
|
+
(ARCHITECTURE "Trust boundaries" 4, P053).
|
|
5861
|
+
|
|
5862
|
+
**Decision.** A config may nest its artifact pages (`nested: true`: domain isolation, artifact
|
|
5863
|
+
mode). The address the host frames (a ticket's answer, a cookie's reload, an entered address)
|
|
5864
|
+
answers Porthole's shell alone, a document with no content in it, on the content origin, its script
|
|
5865
|
+
the only one its CSP runs (by hash), framing and fetching only the origin's sealed files' prefix.
|
|
5866
|
+
The shell frames the page in a child `<iframe sandbox="allow-scripts">` at the page's sealed address
|
|
5867
|
+
(P083); the page's answer carries the same sandbox in its CSP, so on a tab of its own it is opaque
|
|
5868
|
+
too. The page is the served page as before (the shell's runtime and its document), but its origin
|
|
5869
|
+
is opaque, its storage the runtime's in-memory stand-in, and it hears its parent, the shell, on the
|
|
5870
|
+
content origin; it never fetches with a cookie. The shell:
|
|
5871
|
+
- passes every message between the host and the page unchanged, the page's trusted by
|
|
5872
|
+
`event.source` alone (its origin is "null"), and drops any the page sends in the shell's own
|
|
5873
|
+
namespace (`porthole/shell/`);
|
|
5874
|
+
- tells the host its own state (`porthole/shell/state`: its transient activation and how long ago
|
|
5875
|
+
it turned on, and whether focus is in it), read each animation frame, on its focus and blur, and
|
|
5876
|
+
before each message of the page's is passed on. Activation goes up to ancestors, never down: a
|
|
5877
|
+
press or key in the page turns the shell's on, and nothing on the host's page does;
|
|
5878
|
+
- renews the page's sealed address (`<base>__porthole/renew`, same-origin, as P083 asks) and gives
|
|
5879
|
+
the page the new one (`porthole/files-renewed`), which the page's own loads can't (an opaque
|
|
5880
|
+
origin's are never same-origin).
|
|
5881
|
+
The host knows a frame is nested from its config only, never from the frame. For such a frame the
|
|
5882
|
+
focus guard's rule is: the person moved focus in if the shell's activation turned on within the
|
|
5883
|
+
last second (`SHELL_GESTURE_MS`) and the host's page had no trusted pointerdown or keydown of its
|
|
5884
|
+
own since; or by Tab, or the host's own move, or (where the engine shows it) a press on the frame
|
|
5885
|
+
element. No pointer-over or host-wide activation cue counts for it. A move the shell hasn't spoken
|
|
5886
|
+
of yet waits for its word (it comes at the shell's next frame, after the host heard the move) at
|
|
5887
|
+
most `SHELL_WAIT_MS` (500 ms), then is taken back. The same signal opens `comments.open`: its
|
|
5888
|
+
gate's "person in this frame" holds while the shell saw that gesture, or focus is in the frame by
|
|
5889
|
+
the person's move. An engine whose shell has no `navigator.userActivation` keeps 0.13's rule. A
|
|
5890
|
+
`storage` event tells the host, once per run, whether the page touched `localStorage` or
|
|
5891
|
+
`sessionStorage` (the page's word; never a key or a value).
|
|
5892
|
+
|
|
5893
|
+
**Threat it re-opens.** (1) A nested page's files are served with
|
|
5894
|
+
`Cross-Origin-Resource-Policy: cross-origin` and `Access-Control-Allow-Origin: *`, where P081 had
|
|
5895
|
+
`same-origin`: an opaque page's own loads are cross-origin. Whoever holds the sealed address could
|
|
5896
|
+
embed or read the files from any page; they could already fetch them with it, and P083 bounds the
|
|
5897
|
+
address (one version, one viewer, an hour on its own). (2) The page's sealed address opens past its
|
|
5898
|
+
hour only through the shell's renewal: P083's grace for a running page's own loads (same-origin
|
|
5899
|
+
only) can't apply, so a module the page loaded keeps an address that ends within the hour (its later
|
|
5900
|
+
imports fail), where P083 served them till the session's end. (3) The page loses its origin's
|
|
5901
|
+
storage (an in-memory stand-in, as opaque frames have). (4) A press in the page within 5 s of the
|
|
5902
|
+
last one turns no activation on: the second move into the frame (after the person went back to the
|
|
5903
|
+
host's page) is taken back until the activation lapses, or they Tab in. Accepted by the CTO.
|
|
5904
|
+
|
|
5905
|
+
**Why.** The shell is a realm the page can't reach, above its frame: the page is a different origin
|
|
5906
|
+
(opaque), so it has nothing of the shell's (DOM, globals, the window the host hears), and it can
|
|
5907
|
+
neither navigate it nor post as it. Its activation is the person's gesture in this page and no other.
|
|
5908
|
+
|
|
5909
|
+
**Rejected.** A shared shell on one host for every artifact (the per-artifact host stays: decided
|
|
5910
|
+
with the CTO); the page's runtime reporting its own gestures (the page's word, in the page's realm);
|
|
5911
|
+
the host's own activation edge (refreshed by the person's typing, so a press in the frame within 5 s
|
|
5912
|
+
of it is invisible); the pointer's last position on the host's page (it stops at the frame's edge,
|
|
5913
|
+
measured); consuming activation to see a new edge (it consumes the whole page's, the host's
|
|
5914
|
+
included).
|
|
5915
|
+
|
|
5916
|
+
**Residual.** Assets (`/_blob/`) and Porthole's vendored libraries aren't served to a nested page
|
|
5917
|
+
yet (the config refuses them). Another page of the set opens in the frame (the shell's `frame-src`
|
|
5918
|
+
is the sealed prefix) without the navigate events a served page's guard uses (opaque documents get
|
|
5919
|
+
none): the shell's CSP is the wall, as `frame-src` is for opaque frames (P033). The host's page gets
|
|
5920
|
+
the keys a person types within the wait for the shell's word on a move it can't judge at once (on a
|
|
5921
|
+
slow machine, up to 500 ms; measured well under a frame's time on Chromium). A trace's snapshots in
|
|
5922
|
+
Playwright are evaluations in each frame, as gestures: the browser cases run untraced.
|
|
5923
|
+
|
|
5924
|
+
**Tested.** `test/nested.test.ts`: the config's bounds; the page's sandbox (scripts only) and a
|
|
5925
|
+
static check that `allow-same-origin` appears in no sandbox Porthole writes or serves but a frame's
|
|
5926
|
+
on an origin of its own, and that every sandbox attribute is written from those lists; the shell's
|
|
5927
|
+
CSP and document; `/server`: the framed address answers the shell, the page at its sealed address
|
|
5928
|
+
without a cookie is sandboxed and hears the shell alone, its files' resource policy and CORS, only
|
|
5929
|
+
the shell renews; the host's rule. `leak/served/nested.spec.ts` on full Chromium (out-of-process
|
|
5930
|
+
frames), the headless shell, WebKit and Firefox, real input only: the page is an opaque origin at its
|
|
5931
|
+
sealed address; a real click into its field keeps the keyboard there; its `focus()` as it loads, on a
|
|
5932
|
+
timer while the person types, right after a click on the host's own button, 1.2, 3 and 4.5 s after
|
|
5933
|
+
the person paused typing in the host's composer, and 700 ms after the person pressed it and went
|
|
5934
|
+
back to the composer, is taken back; a marker's click is heard; `comments.open` from a real click
|
|
5935
|
+
within a second of typing in the host is allowed, and without one refused; a page that says the
|
|
5936
|
+
shell's words to its parent or to the host's window moves nothing; the host hears storage used.
|
|
5937
|
+
Negative controls `shell-namespace` (the shell passes its namespace on) and `shell-host-input` (no
|
|
5938
|
+
quiet host needed) each fail their probe on Chromium, WebKit and Firefox.
|
|
5939
|
+
|
|
5940
|
+
**Revisit when** an engine shows the host's page a press in an out-of-process frame, or a page needs
|
|
5941
|
+
its own storage (then a capability for it, never the content origin's), assets, or libraries.
|
|
5942
|
+
|
|
5943
|
+
**Amended after the CTO's review (porthole#54): a stalled shell.** The shell's "since" is when it
|
|
5944
|
+
saw its activation turn on, not when the press was. Where the page shares the shell's thread
|
|
5945
|
+
(WebKit; Firefox and Chromium where the frames share a process), a page that holds the thread from
|
|
5946
|
+
its own click handler pushes that moment past the person's next press and keys on the host's page,
|
|
5947
|
+
which then pass the "no host input since" check: the page could take the keyboard, or open the
|
|
5948
|
+
composer, after the person went back to the host. Now the shell looks every 50 ms (an interval as
|
|
5949
|
+
well as each animation frame), beats to the host as often (`porthole/shell/beat`), and says in each
|
|
5950
|
+
report how long it went without a look (`gap`). An activation that turns on in a report after the
|
|
5951
|
+
shell went more than `SHELL_STALL_MS` (100 ms) without a look, or the host heard nothing from it
|
|
5952
|
+
for longer, is uncertain: no one's gesture (the focus guard takes the move back, `comments.open` is
|
|
5953
|
+
refused) until it goes off. **Cost:** a page that keeps its thread busy (or a machine that is), in
|
|
5954
|
+
an engine where it shares the thread with the shell, has a person's real click taken for
|
|
5955
|
+
uncertain; their next press once the page is idle, or a Tab, gets in (measured on a machine at load
|
|
5956
|
+
45: Firefox took back one of two rounds of a real click). Two messages a 50 ms per display. **Tested:**
|
|
5957
|
+
`leak/served/nested.spec.ts` "a shell's activation seen after a stall is no one's gesture until it
|
|
5958
|
+
goes off" (the host's rule, in the browser's own event loop, on every engine), and
|
|
5959
|
+
`leak/served/nested-stall.spec.ts` (the race end to end with real input: the page's handler holds
|
|
5960
|
+
the thread 1.5 s while the person goes back to the composer; on the headless shell it got through
|
|
5961
|
+
without the check, measured; elsewhere Playwright's input waits the stall out, so that case is no
|
|
5962
|
+
control's probe); negative control `shell-stall` (the gap ignored).
|
|
5963
|
+
|
|
5964
|
+
**Amended after the CTO's review (porthole#54): every file sandboxed.** A nested page's files are on
|
|
5965
|
+
its shell's origin, so a file a browser can run as a document, opened on a tab of its own (an SVG
|
|
5966
|
+
or an XML file with a script, "open image in new tab"), must not run there. Every answer below the
|
|
5967
|
+
sealed prefix carries a CSP sandbox, never `allow-same-origin`: a page's `sandbox allow-scripts`
|
|
5968
|
+
(opaque); every other file's `default-src 'none'; sandbox` (opaque, nothing runs: P081's inert CSP);
|
|
5969
|
+
and now a script's too (`sandbox`, where a served script had none). **Tested:**
|
|
5970
|
+
`test/nested.test.ts` (every type in Porthole's table, opened as a tab opens it: a sandbox, never
|
|
5971
|
+
`allow-same-origin`), and `leak/served/nested.spec.ts` "a page's SVG or XML file opened on a tab of
|
|
5972
|
+
its own is an opaque origin…" (each opaque; its script wrote nothing to the shell's origin's
|
|
5973
|
+
storage); negative control `file-sandbox` (a file without its sandbox).
|
|
5974
|
+
|
|
5975
|
+
**Workers in a nested page (the CTO's follow-up #85).** Whether the sandbox on a script's answer
|
|
5976
|
+
refuses a worker, measured on full Chromium, the headless shell, WebKit and Firefox
|
|
5977
|
+
(`leak/served/nested-workers.spec.ts`): it refuses none, every outcome the same with it taken out
|
|
5978
|
+
(the `file-sandbox` control). A worker from a script of the page's own set, classic or module, is
|
|
5979
|
+
refused on every engine, sandbox or not: a worker's script must be its creator's origin, and a
|
|
5980
|
+
nested page's is opaque (Chromium throws `SecurityError`, WebKit and Firefox fire `error`). A worker
|
|
5981
|
+
from a Blob URL starts and answers on every engine, and loads the set's scripts (`importScripts`,
|
|
5982
|
+
CORS-free) and, on WebKit and Firefox, its modules; Chromium refuses a module worker from a Blob URL
|
|
5983
|
+
in an opaque document, one that imports nothing included (no script's answer is involved). So no
|
|
5984
|
+
answer needs its sandbox taken off for a worker, and none is: the narrowest fix (no sandbox on a
|
|
5985
|
+
`Sec-Fetch-Dest: worker` answer) would fix nothing. The agent manual already teaches workers from
|
|
5986
|
+
`blob:` URLs only.
|
|
5987
|
+
|
|
5988
|
+
## P112 · 2026-10-28 · 0.14's comment UX: what annotations add for a host's comment modes · Accepted
|
|
5989
|
+
|
|
5990
|
+
**Context.** Raft's comment design (its modes A–C, a card that follows its mark, a list in document
|
|
5991
|
+
order, block selection on touch) needs more from `annotate` than 0.13 has. Each addition is the
|
|
5992
|
+
content's word, as every report is (P053): the host uses it as a hint, never as a permission, and
|
|
5993
|
+
takes it only while it asked for it. Each item below landed on its own, with its negative control.
|
|
5994
|
+
|
|
5995
|
+
- **Escape while selecting text** (P4). In text selection mode an Escape is reported as
|
|
5996
|
+
`cancelled`, as it is while picking an element; the key stays the page's (a page that closes its
|
|
5997
|
+
own dialog on Escape still does), and the host decides what ends (a pick ends with it, as
|
|
5998
|
+
before). The host takes `cancelled` only while it asked for a pick or for text: a page can send
|
|
5999
|
+
it, and then only gets the host out of a mode the person can enter again (Raft: mode B ends, its
|
|
6000
|
+
drafts kept). Tested: `leak/annotate.spec.ts` "Escape while selecting text is cancelled…";
|
|
6001
|
+
negative control `cancel-any-mode` (a cancel with no mode on is heard).
|
|
6002
|
+
- **Following a mark** (P1). `annotations.track(id | null)`: while the followed mark moves (a
|
|
6003
|
+
scroll, a layout change), the frame reports `{ type: "tracked", id, rect }` at most once per
|
|
6004
|
+
animation frame. One mark at a time, and only a shown one (`track` throws for another; a `show`
|
|
6005
|
+
without it, or `clear`, stops it). The host takes a `tracked` only for the mark it follows, at
|
|
6006
|
+
most 60 a second, its box clamped to the frame, outside the bridge's 120 reports a minute (which
|
|
6007
|
+
a card that follows its mark would spend in two seconds). It costs a message and a box read per
|
|
6008
|
+
frame, only while the host follows a mark. The box is where to put a card, nothing more: a page
|
|
6009
|
+
can move it within its frame, as it can draw anything there. Tested: `leak/annotate.spec.ts` "a
|
|
6010
|
+
followed mark's box comes as it moves…"; negative control `track-checks` (any mark, any rate).
|
|
6011
|
+
- **A mark's place** (P2). Each attached result in `anchored` carries `order`: its place among the
|
|
6012
|
+
found marks by where it starts in the document, from 0, offscreen marks included (orphans have
|
|
6013
|
+
none); a change of place is reported as a move is. The host takes a whole number below the most
|
|
6014
|
+
marks a show carries, or drops the report. The page knows where its anchors are anyway; the host
|
|
6015
|
+
sorts by it and takes it as nothing more. Tested: `leak/annotate.spec.ts` "every found mark's
|
|
6016
|
+
place in the document…"; negative control `order-check` (any number taken).
|
|
6017
|
+
- **Holding a block** (P3). `start({ text: true, elements: "hold" })`: a finger held still (within
|
|
6018
|
+
10 px) for 500 ms on a block selects it, reported as `selected` with an element anchor, as a pick
|
|
6019
|
+
is; the click its release makes (and a context menu) never reaches the page. Every other tap, a
|
|
6020
|
+
finger that moved, and any mouse are the page's, so the page stays usable while comments are on;
|
|
6021
|
+
the mode lasts until the host stops it (a pick ends after one). It makes nothing but `selected`,
|
|
6022
|
+
as `elements: true` does; a page can tell a long press happened, as it can tell a selection.
|
|
6023
|
+
Tested: `leak/annotate.spec.ts` "holding a block 500 ms selects it…" (the events as the browser
|
|
6024
|
+
dispatches them, sent in the frame: a page's realm can send them too, and what comes of them is a
|
|
6025
|
+
report, the page's word); negative control `hold-click` (the release's click reaches the page).
|
|
6026
|
+
- **Whether a page may pass a draft on** (P8). `mayPassOn(config, declaration)`, and
|
|
6027
|
+
`host.mayPassOn(declaration)`: true where the page can keep what it is given where others read
|
|
6028
|
+
it, knowing whose it is (`db` and `user`, both declared and offered), or reaches the network
|
|
6029
|
+
beyond the library CDNs (`anyHttps`, or any origin the config or a capability opens for any kind
|
|
6030
|
+
that isn't one of `LIBRARY_CDNS`'s for that kind: a CDN serves published packages by their path,
|
|
6031
|
+
and its logs are its operator's, not the page author's). ADOPTING's "no drafts to a page that can
|
|
6032
|
+
pass them on" as a function a host calls instead of reading the declaration itself. A pure
|
|
6033
|
+
function of the host's own records: `test/pass-on.test.ts` holds each channel alone, and none;
|
|
6034
|
+
there is no browser probe for it to fail.
|
|
6035
|
+
- **A draft-only composer may take focus** (P6). THREAT_MODEL §6 said every view a report opens
|
|
6036
|
+
takes no focus; ADOPTING's keyboard section opened a composer focused on `selected`. Now one
|
|
6037
|
+
rule in both: in a comment mode the person started themselves (the host's own control), a
|
|
6038
|
+
composer their selection opens may take focus with `focusField` if all it can do is save a draft
|
|
6039
|
+
(nothing posts, submits or sends from it), the rest of §6's guard holding; any other view a
|
|
6040
|
+
report opens takes none. What the page gains by choosing that moment is the person's next keys in
|
|
6041
|
+
a draft they see and can discard. As Raft's comment design proposes it (its mode B); Tenny's to
|
|
6042
|
+
confirm.
|
|
6043
|
+
*Amended after the CTO's review (porthole#54):* `db` alone was missed (a page can store the draft
|
|
6044
|
+
where its other readers see it, whoever wrote it), and so were `openLink` (the draft in a URL the
|
|
6045
|
+
person opens) and `artifact` (the draft in a new version). The whole vocabulary now: what carries
|
|
6046
|
+
what the page puts in it to someone other than the person viewing it counts, wherever the page
|
|
6047
|
+
can reach it (the config declares it, and under the runtime with a declaration through a built-in
|
|
6048
|
+
family or one the page declared): `db`, `artifact`, `assets`, `openLink`, `sendPrompt`,
|
|
6049
|
+
`setModelContext`, `callTool`, `readData`, `subscribeData` (their arguments go to the host's data
|
|
6050
|
+
services, which may be someone else's), and `reportError` where errors go to the agent. Not:
|
|
6051
|
+
`copyText` and `downloadFile` (the person's own clipboard and disk), `annotate`, `resize` and
|
|
6052
|
+
`comments` (the host's own UI; the composer is the person's, under the host's duties), and `user`
|
|
6053
|
+
(it only reads). Tested: `test/pass-on.test.ts`, each channel alone.
|
|
6054
|
+
|
|
6055
|
+
## P115 · 2026-10-28 · The host clears the page's selection: `annotations.clearSelection()` · Accepted
|
|
6056
|
+
|
|
6057
|
+
**Context.** In a comment mode (Raft's web app, Kirby) the person selects words, the host's
|
|
6058
|
+
composer opens beside them, and they post a comment or add a draft. The selection stays: the
|
|
6059
|
+
browser keeps drawing it (gray, since focus is in the host's composer) over words that now carry
|
|
6060
|
+
a mark, until the person clicks in the page. 0.13 and 0.14 give the host no way to clear it;
|
|
6061
|
+
Kirby asked for one (`selection.clear()`) to call once the selection is used.
|
|
6062
|
+
|
|
6063
|
+
**Decision.** `display.annotations.clearSelection()`, beside `start`, `stop`, `show`, `focus`,
|
|
6064
|
+
`track` and `clear` (a control of the display's annotations, named for what it clears: `clear`
|
|
6065
|
+
already means every mark). It sends `porthole/annotate.clearSelection` (no params) to the frame,
|
|
6066
|
+
only where the config declares `annotate` (else it throws, as the others do), and to no frame that
|
|
6067
|
+
runs later (nothing is kept: a new frame has no selection). The shell then:
|
|
6068
|
+
|
|
6069
|
+
- removes the page's selection with `Selection.prototype.removeAllRanges` as it was before content
|
|
6070
|
+
ran (taken with the DOM's other functions), on `Document.prototype.getSelection`'s answer, so a
|
|
6071
|
+
page that replaced either keeps nothing the host cleared;
|
|
6072
|
+
- forgets what it held of it: the report waiting for the selection to settle (250 ms), the one it
|
|
6073
|
+
last told and its box, and a scroll's follow-up of it. So nothing is told back: the
|
|
6074
|
+
`selectionchange` the clear makes finds nothing to report (no `unselected`: the host knows), and
|
|
6075
|
+
the same words selected again are a new selection, told as any is;
|
|
6076
|
+
- changes nothing else: marks (posted and drafts), the active and the followed mark, the mode,
|
|
6077
|
+
and an element picked. With nothing selected it is a no-op; it clears in any mode, text
|
|
6078
|
+
selection on or not (the host is trusted with the page's view, as it is with `focus`, which
|
|
6079
|
+
scrolls it).
|
|
6080
|
+
|
|
6081
|
+
There is no highlight of Porthole's own to remove: a settled selection is drawn by the browser
|
|
6082
|
+
(the shell draws marks, and an outline only while picking).
|
|
6083
|
+
|
|
6084
|
+
**Trust.** Host to frame only. The host takes no `clearSelection` from a frame (it is no report);
|
|
6085
|
+
the shell takes it only from its frame's parent and the host's origins, as every host message
|
|
6086
|
+
(a page that posts it to its own window is dropped). It gives the page nothing it hasn't: a page
|
|
6087
|
+
can clear or select its own text at any time, and can select the words again right after (the
|
|
6088
|
+
host hears that as a selection, while it asked for text). A report the shell posted just before
|
|
6089
|
+
the clear arrived (a selection that settled in the same moment) still reaches the host after its
|
|
6090
|
+
call; a host that cares drops a `selected` it gets right after clearing, as it would one it
|
|
6091
|
+
didn't ask for.
|
|
6092
|
+
|
|
6093
|
+
**Rejected.** A `selection` namespace (`display.selection.clear()`, as Kirby wrote it): the
|
|
6094
|
+
selection is the annotation runtime's (only `annotate` reports it), and one namespace for
|
|
6095
|
+
annotations is what hosts already hold. Clearing the selection inside `stop()` or `clear()`: a
|
|
6096
|
+
host stops the mode or redraws its marks for other reasons, with a selection the person still
|
|
6097
|
+
means to use. Telling the host `unselected` after a clear: it would arrive after the host's own
|
|
6098
|
+
call, as if the person did it, and a host that opens or closes UI on it would act twice.
|
|
6099
|
+
Clearing through the page's own `getSelection().removeAllRanges()`: a page (or a library it
|
|
6100
|
+
loads) that patched it would keep the highlight.
|
|
6101
|
+
|
|
6102
|
+
Tested: `test/annotate.test.ts` (sent as it is, after the handshake only, never replayed, throws
|
|
6103
|
+
without `annotate`; the shell uses the function it took); `leak/annotate.spec.ts` "clearSelection
|
|
6104
|
+
takes the page's selection away and tells nothing back; marks and drafts stay, the next selection
|
|
6105
|
+
is told (P115)", on a page that replaced `removeAllRanges`, with no selection, in text mode and with
|
|
6106
|
+
the mode stopped; `leak/served/nested.spec.ts` "the host's clearSelection reaches the nested page
|
|
6107
|
+
through its shell (P115)"; negative control `clear-selection` (the page's own `removeAllRanges`, and the
|
|
6108
|
+
told selection kept: each alone fails the probe, measured on Chromium).
|
|
6109
|
+
|
|
6110
|
+
**Revisit when** a host needs the element picked (`elements: true`) or a held block cleared too
|
|
6111
|
+
(they leave no highlight now), or the MCP Apps spec gains a host-to-view way to clear a selection.
|
|
6112
|
+
|
|
6113
|
+
## P114 · 2026-10-28 · A nested page's shell on a label of its own, where nothing else is ever served · Accepted
|
|
6114
|
+
|
|
6115
|
+
**Context.** porthole#56 (Ferry's audit of what merged after 0.13.0). P111 rests on the shell
|
|
6116
|
+
being a realm content can't reach (ARCHITECTURE "Trust boundaries" 4): the host trusts the shell's
|
|
6117
|
+
word (`porthole/shell/state`: the keyboard rule, `comments.open`), and the shell holds the page's
|
|
6118
|
+
sealed files' address, a bearer credential (P083). The opaque page can't reach it. But the shell
|
|
6119
|
+
was served on its scope's content origin, where every other domain-mode display of the scope (an
|
|
6120
|
+
inline widget, a live widget, an MCP app, an artifact that isn't nested) runs agent-made content
|
|
6121
|
+
with `allow-same-origin`. Such a display on the host's page is same-origin with the shell: from a
|
|
6122
|
+
plain artifact or an inline widget of the same scope, `parent.frames[0].document` was the shell,
|
|
6123
|
+
its page's frame inside it (measured by Ferry on the headless shell, full Chromium and Firefox). So
|
|
6124
|
+
it could make the shell's word say "the person pressed" (P109's threat back for nested pages) and
|
|
6125
|
+
take the sealed address. P0 for a host that maps several artifacts to one scope. Nothing refused
|
|
6126
|
+
the mix: `nested` can't have `storage`, `assets` or `egress.libraries`, so a nested kind beside
|
|
6127
|
+
other kinds of one scope is the expected layout. The nested suite missed it because each of its
|
|
6128
|
+
cases had a scope of its own.
|
|
6129
|
+
|
|
6130
|
+
**Decision.** The shell's origin hosts nothing but nested pages' shells, their opaque pages, those
|
|
6131
|
+
pages' files and Porthole's status pages. `/server` holds the rule; it isn't left to how a host
|
|
6132
|
+
lays out `defineDisplays` or names its scopes.
|
|
6133
|
+
|
|
6134
|
+
- **The label.** A nested page is served on `nestedLabelOf(label)`: `porthole-` and 24 base32
|
|
6135
|
+
characters (120 bits) of the SHA-256 of `porthole/nested/<the scope's label>`. One per scope:
|
|
6136
|
+
every nested page of the scope shares it, as they shared the scope's origin before (only
|
|
6137
|
+
Porthole's shell runs there with that origin, and each page is opaque and opens only with its
|
|
6138
|
+
own sealed address). Not keyed and not secret: it says nothing the scope's label doesn't, and a
|
|
6139
|
+
content Worker of a host's own works it out from the label alone. It is one label under the
|
|
6140
|
+
content domain, so its wildcard DNS name, its wildcard certificate and the hosts'
|
|
6141
|
+
`frame-src https://*.<domain>` already cover it.
|
|
6142
|
+
- **What it answers.** The frame's address (`/__porthole/d/<key>`: the shell), the sealed
|
|
6143
|
+
prefix (`/__porthole/f/<token>/…`: the page, its files, the renewal, each with a CSP sandbox
|
|
6144
|
+
without `allow-same-origin`, P111), and Porthole's status pages and their script. Anything else
|
|
6145
|
+
is a 404 there: no clean address, entry, asset (`/_blob/`), library, session check or url-mode
|
|
6146
|
+
app. A ticket, cookie or sealed address is good there only for a nested page whose shell's label
|
|
6147
|
+
it is; and on the scope's label never for a nested page (its ticket, cookie or sealed address is
|
|
6148
|
+
refused there: a 401).
|
|
6149
|
+
- **No content label is ever one.** The keyed default has no hyphen; every `porthole-` label is
|
|
6150
|
+
Porthole's own: `content.name` giving one throws (as a reserved label does), and
|
|
6151
|
+
`prefixedName("porthole-")` throws. A shell's label the host reserved (`content.reserved`)
|
|
6152
|
+
makes `issue` throw: the request would go to the host's routes.
|
|
6153
|
+
- **Where the frame is.** `issue` answers the shell's origin for a nested page
|
|
6154
|
+
(`FrameLocation.origin`, and its `url`); the host page's checks take it as they take any served
|
|
6155
|
+
origin (it matches the content source, it isn't the host's site). `originFor(scope)` and
|
|
6156
|
+
`urlOf(scope, path)` stay the scope's: they are where its other displays and its clean addresses
|
|
6157
|
+
are.
|
|
6158
|
+
- **A clean address** (P068) stays on the scope's label: the entry, its code and its session are
|
|
6159
|
+
there, as before. Opened for a nested page, the scope's label answers it with a `303` to the
|
|
6160
|
+
shell's label (`/__porthole/d/<key>?ticket=<one-time>`): a ticket of its own for the same access
|
|
6161
|
+
(viewer, subject, anonymous), good for 60 s, buying what is left of the session, with the path
|
|
6162
|
+
below the file set's base the address asked for (`TicketRecord.page`, checked: a relative path,
|
|
6163
|
+
no dot segment, no query). The shell's label sets its own session there, so a reload rides on
|
|
6164
|
+
it; the scope's label never answers the shell.
|
|
6165
|
+
- **An entry code is no ticket.** A document's address takes a ticket from `issue` (or a hop)
|
|
6166
|
+
only, never an entry code (`TicketRecord.entry`), which opens its entry alone with its own
|
|
6167
|
+
browser's nonce. Before, a code could stand in for a ticket at the scope's label's
|
|
6168
|
+
`/__porthole/d/`; at the shell's it would have skipped the nonce (an attacker's session planted
|
|
6169
|
+
in a victim's frame).
|
|
6170
|
+
- `configFor` checks that a nested config's `contentOrigins` match a shell's sample origin too.
|
|
6171
|
+
|
|
6172
|
+
**Threat it closes.** A same-scope display reading or driving the shell: the shell's word to the
|
|
6173
|
+
host, its focus and activation, the page's sealed address. A content display is now never
|
|
6174
|
+
same-origin with any shell (its label is never a `porthole-` one), whatever the host's scopes.
|
|
6175
|
+
|
|
6176
|
+
**Limits.** On a tab, a nested page's clean address ends at the shell's document address (with its
|
|
6177
|
+
spent ticket), not the clean one; a reload rides the shell's session, and after it ends that
|
|
6178
|
+
address says "This link has been used" where the clean one would sign in again. The hop's ticket is
|
|
6179
|
+
in a `Location`, as exposed as `issue`'s frame address (P020): one use, a minute. A host that frames
|
|
6180
|
+
a clean address itself (not `issue`'s location) gets the shell's origin after the hop; with
|
|
6181
|
+
`createHost` the frame's origin is the location's, so such a host frames `issue`'s location.
|
|
6182
|
+
|
|
6183
|
+
**Rejected.**
|
|
6184
|
+
- A label in the form IDNA reserves (`??--`), which no host's naming can make today (P047): ACME
|
|
6185
|
+
CAs (Let's Encrypt) refuse certificates for such names, so a host with a certificate per name
|
|
6186
|
+
couldn't serve it. The `porthole-` prefix narrows what a host may name instead (the kit's health
|
|
6187
|
+
gate already reserved `porthole-health`).
|
|
6188
|
+
- A deeper name (`<x>.n.<domain>`): a second wildcard certificate and DNS name for every host.
|
|
6189
|
+
- A keyed label: a host's own content Worker couldn't work it out without the server's secret, and
|
|
6190
|
+
it would hide nothing the scope's label shows.
|
|
6191
|
+
- A label per page instead of per scope: nothing runs on the shell's origin but the shell, so
|
|
6192
|
+
per scope is enough, and its sessions stay per scope as before.
|
|
6193
|
+
- Refusing other kinds of a nested kind's scope (in `defineDisplays`, or at `issue`): the layout is
|
|
6194
|
+
the expected one, and scopes are the host's, not the registry's.
|
|
6195
|
+
- The shell on the scope's label on a tab only (a clean address): a same-scope page could open it
|
|
6196
|
+
in a window it names and reach its realm.
|
|
6197
|
+
|
|
6198
|
+
**Adopters.** Every host on `/server` or the host kit: the shell's label is under the content
|
|
6199
|
+
domain's wildcard, so wildcard DNS and a wildcard certificate need nothing; an edge, a route or a
|
|
6200
|
+
firewall that matches labels by pattern (`a-*.<domain>`) must let `porthole-*` through to the
|
|
6201
|
+
content server too. A host whose naming makes `porthole-` labels must change it. A content Worker
|
|
6202
|
+
of a host's own (Raft's, on 0.13 today) that adopts nested pages serves the shell, the page and
|
|
6203
|
+
its files on `nestedLabelOf(label)` (`nestedAncestors(<that origin>, <host origins>)`, the shell's
|
|
6204
|
+
`origin` that origin), answers the frame location with it, serves nothing else there, and never
|
|
6205
|
+
answers a nested page on the scope's label (ADOPTING "Nested pages").
|
|
6206
|
+
|
|
6207
|
+
**Tested.** `test/nested.test.ts` "a nested page's shell on a label of its own (P114)" (the
|
|
6208
|
+
label, one per scope, under host naming and the keyed default; the scope's label answers no
|
|
6209
|
+
nested page; the shell's answers nothing else, another display's ticket or sealed address
|
|
6210
|
+
included; naming and reserved labels); `test/entry.test.ts` "a nested page's clean address
|
|
6211
|
+
(P114)" (the hop, the page it was entered at, the shell's own session; an attacker's entry code
|
|
6212
|
+
at the shell's document address opens nothing); `leak/served/nested-siblings.spec.ts`
|
|
6213
|
+
`[nested-siblings]`: a nested page beside an inline widget and a plain artifact of its scope, which
|
|
6214
|
+
read each other (the positive control) and nothing of the shell (not its document, no sealed
|
|
6215
|
+
address, not its page's address); `leak/served/nested.spec.ts`'s first case beside a widget of its
|
|
6216
|
+
scope; `leak/kit.spec.ts` (through `nodeHost`) and the prod-shape profile (through Caddy's TLS and
|
|
6217
|
+
CoreDNS): framed by `issue`'s location, and from a clean address. Negative control `shell-label`:
|
|
6218
|
+
the harness answers the shell's frame address and sealed files on the scope's label (from the
|
|
6219
|
+
shell's, every mention of its origin made the scope's), and `[nested-siblings]` fails, nothing
|
|
6220
|
+
else. Measured on the headless shell, full Chromium, WebKit and Firefox (the last two in the
|
|
6221
|
+
prod-shape profile's browser image).
|
|
6222
|
+
|
|
6223
|
+
**Revisit when** a nested page gets storage, assets or libraries (they would be served on the
|
|
6224
|
+
shell's label: the rule must say what may run there), or a host needs a nested page's shell per
|
|
6225
|
+
page.
|
|
6226
|
+
|
|
6227
|
+
## P116 · 2026-10-28 · A mark's count above the limit is clamped, not refused · Accepted
|
|
6228
|
+
|
|
6229
|
+
**Context.** P104 had `checkMarks` throw on a `count` above `ANNOTATION_LIMITS.count` (999), as on
|
|
6230
|
+
a bad anchor, so one mark refused the whole `show`. The count is a host's data that anyone can
|
|
6231
|
+
grow: in Ferry, one comment with 999 replies made `annotations.show` throw, the host got
|
|
6232
|
+
`onHostError({ kind: "annotations" })`, and treated it as fatal (porthole#40).
|
|
6233
|
+
|
|
6234
|
+
**Decision.** A whole number above the limit is clamped to it before the mark goes to the frame.
|
|
6235
|
+
The marker reads "99+" above 99 either way, so nothing a person sees changes, and the page is told
|
|
6236
|
+
no more than 999, as before. Anything that isn't a whole number from 0 (negative, a fraction,
|
|
6237
|
+
NaN, Infinity, not a number) still throws: that is a host's bug, not data that grew.
|
|
6238
|
+
|
|
6239
|
+
**Rejected (for now).** Dropping only a bad mark rather than refusing the list, and running
|
|
6240
|
+
`focus`/`start` after a refused `show` (porthole#40's other suggestions): they change what a host
|
|
6241
|
+
hears about its own bugs; left for their own decision.
|
|
6242
|
+
|
|
6243
|
+
Tested: `test/annotate.test.ts` (counts above the limit clamped, the rest refused as before).
|
|
6244
|
+
|
|
6245
|
+
## P117 · 2026-10-28 · A draft holds back a tag start it was cut in · Accepted
|
|
6246
|
+
|
|
6247
|
+
**Context.** While content streams, the shell draws each partial (`tool-input-partial`) inert as
|
|
6248
|
+
it has come so far. Cut right after `<` or `</`, the HTML tokenizer emits them as text, so the
|
|
6249
|
+
draft shows a stray `<` until the next fragment (porthole#16: Ferry's screenshot, a lone `<` under
|
|
6250
|
+
eight drawn rows, cut just before `<script>`). Agents cut their arguments at arbitrary points.
|
|
6251
|
+
|
|
6252
|
+
**Decision.** Before parsing a draft, the shell leaves out a trailing tag start: from the last
|
|
6253
|
+
`<`, if what follows is empty, `/`, or a letter and no `>` (a tag's name or attributes, which the
|
|
6254
|
+
tokenizer drops anyway). A `<` that starts no tag (`1 < 2`), a comment, and a `<` with a `>` after
|
|
6255
|
+
it are drawn as they are. The whole content (`tool-input`) is never trimmed; nothing runs
|
|
6256
|
+
differently, since a draft runs nothing.
|
|
6257
|
+
|
|
6258
|
+
Tested: `test/shell.test.ts` (`<`, `</`, `</di`, inside an attribute, and whole content
|
|
6259
|
+
unchanged); `leak/react.spec.ts` "content streams through props…" (a draft cut after `</` and
|
|
6260
|
+
after `<` draws neither).
|
package/docs/DESIGN.md
CHANGED
|
@@ -995,6 +995,8 @@ for that to lapse and click with raw input.
|
|
|
995
995
|
| The runtime: a draft is visible text, strictly; the anchor beside it cleaned (P109) | a draft with a joiner (U+200C, U+200D) anywhere but between two letters or marks (first, last, doubled, beside a space or punctuation, in an emoji sequence), a line or paragraph separator, blank-looking text, more than 32 blanks or two blank lines in a row is refused; the label and quote lose what a person can't see, refused if nothing visible is left | `test/runtime.test.ts`: "a draft is visible text, strictly (P109)" | — (unit-tested: the bridge's own check, behind `comment-draft`'s) |
|
|
996
996
|
| The keyboard: the focus guard (P109) | a move of the keyboard from one of the host page's text fields into a display's frame that the person didn't make (no press on the frame, `:active` on Chromium and WebKit, the pointer coming over it on Firefox; no Tab; no gesture the page's own events don't explain) is undone once the move is over; three while typing within 10 s, or five within 2 s, stop the display | `test/focus-guard.test.ts`; `leak/served/runtime.spec.ts`: "a page that takes the keyboard while the person types in the host's composer…", "a page that takes the keyboard back on its own blur keeps none of it…" (GK-1), "a composer the host focuses with focusField…", "the person's own moves into the frame keep the keyboard…" | `focus-guard` → the first (all three) and the next two (Firefox); `focus-guard-watch` (the watch after a take-back, the look at every frame) → those two (Firefox) |
|
|
997
997
|
| The runtime: `comments.open` from the frame the person is in (P109) | its `user-activation` gate also needs the host page's focus in the calling frame (`CapabilitySpec.inFrame`, `Surface.focused`), after the focus guard | `leak/served/runtime.spec.ts`: "comments.open while the person types in the host's composer reaches no handler…" | `comments-in-frame` → that case (all three) |
|
|
998
|
+
| A nested page: Porthole's shell above an opaque page (P111) | the framed address answers the shell alone (its own script by hash, framing and fetching only the sealed prefix); the page is its child, `sandbox="allow-scripts"` in the attribute and its CSP (never `allow-same-origin`: a static check over every sandbox Porthole writes), loaded without a cookie; the shell passes messages by `event.source`, never in its own namespace; the host takes a move into the frame, or a `comments.open`, for the person's only if the shell's activation turned on within the last second with no trusted press or key on the host's page since (or a Tab, the host's move, a press the engine shows) | `test/nested.test.ts`; `leak/served/nested.spec.ts` on full Chromium, the headless shell, WebKit and Firefox | `shell-namespace` → "the shell's words are the shell's alone…" (all three); `shell-host-input` → "a page's focus() just after the person pressed it and went back…" (all three) |
|
|
999
|
+
| A nested page's shell on a label of its own (P114, porthole#56) | the shell, its page and that page's files are served on `nestedLabelOf(<scope's label>)` (`porthole-<24 base32>`, one per scope), never on the scope's label, where the scope's other displays run content with `allow-same-origin`; that label answers only frame addresses of nested pages, their sealed prefix and status pages (no clean address, entry, asset, library, app, nor another instance's ticket, cookie or sealed address), the scope's label no nested page (a clean address goes on with a one-time ticket); no host's naming makes a `porthole-` label; an entry code is no document's ticket | `test/nested.test.ts`, `test/entry.test.ts` ("… (P114)"); `leak/served/nested-siblings.spec.ts` (`[nested-siblings]`: a same-scope inline widget and artifact read each other, not the shell) on full Chromium, the headless shell, WebKit and Firefox; `leak/kit.spec.ts` and the prod-shape profile (the label through `nodeHost`, and through a TLS edge and DNS) | `shell-label` (the shell on the scope's label) → `[nested-siblings]` (all three) |
|
|
998
1000
|
| The asset library (P089, P091) | `/_blob/<id>` (or the frame's `<sealed base>__porthole/blob/<id>`) for an access to its artifact (a cookie, a sealed `Referer`, the sealed path), then the host's check, the store asked with it; typed by name, never a page, code only where trusted and uploaded code may run (asked at each load; by id alone, every artifact config must, P103), inert CSP, CORP, revalidated; the page's CSP opens `<origin>/_blob/` for images, media, fonts and data, for scripts and styles only where uploads are the admins' | `test/assets.test.ts` (a forged same-origin claim: 401; another artifact's session: 404; revoked: 403; bearer mode; a stricter config turns trusted code into a download, bearer mode too); `leak/served/runtime.spec.ts`: an upload loads in its frame; a set's page loads it; static `/_blob/` in a frame by `Referer` (Chromium, Firefox; WebKit sends only the origin: measured); "a script asset runs as code only if an admin uploaded it"; "scripts load from /_blob/ only where uploads are the admins'"; "an asset reaches only its own artifact's pages"; "an asset opened on its own runs nothing" | `blob-trusted` → the trusted-code case; `blob-script,blob-trusted` (two walls) → that case and the tab's CSP case; `blob-inert` → the opened-on-its-own case (all three; `scripts/controls.ts`) |
|
|
999
1001
|
| Workers (P044, P045) | no Node module in `/server`; D1 tickets taken by one `DELETE … RETURNING` | `test/workers.test.ts` (workerd, no `nodejs_compat`, real D1: once per ticket, a race, anonymous, a revocation, flat names, reserved namespaces) | — |
|
|
1000
1002
|
|
|
@@ -1034,9 +1036,10 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1034
1036
|
|-----------|---------|--------|
|
|
1035
1037
|
| host → frame | `porthole/annotate.start` | `{ elements, text }`: picking elements (the one under the pointer or finger outlined with its name; a click or tap picks it, never reaching the content; Escape cancels; one pick), selecting text (each settled selection), or both (a click picks, a drag selects) |
|
|
1036
1038
|
| host → frame | `porthole/annotate.stop` | — |
|
|
1037
|
-
| host → frame | `porthole/annotate.show` | `{ marks: [{ id, anchor, count?, kind? }], active? }`: drawn over the content in the shell's own layer (a closed shadow root), found again whenever the content changes; a mark with a `count` (0 to 999) also gets a marker (P104); `kind: "draft"` (absent: posted) is drawn apart, with a marker and never a count (P107) |
|
|
1039
|
+
| host → frame | `porthole/annotate.show` | `{ marks: [{ id, anchor, count?, kind? }], active? }`: drawn over the content in the shell's own layer (a closed shadow root), found again whenever the content changes; a mark with a `count` (0 to 999; the host clamps a larger one, P116) also gets a marker (P104); `kind: "draft"` (absent: posted) is drawn apart, with a marker and never a count (P107) |
|
|
1038
1040
|
| host → frame | `porthole/annotate.focus` | `{ id }`: scrolled into view inside the frame, made the active mark, flashed |
|
|
1039
1041
|
| host → frame | `porthole/annotate.clear` | — |
|
|
1042
|
+
| host → frame | `porthole/annotate.clearSelection` | —: the page's text selection is taken away (the DOM's own `removeAllRanges`, taken before content runs) with what the shell held of it, and nothing is reported back; marks, drafts and the mode stay (P115) |
|
|
1040
1043
|
| frame → host | `porthole/annotate.selected` | `{ anchor, rect }`; after a scroll, the same selection again only if its box moved more than 0.5 px, on the follow-ups' clock (P105) |
|
|
1041
1044
|
| frame → host | `porthole/annotate.unselected` | — (the text selection went away) |
|
|
1042
1045
|
| frame → host | `porthole/annotate.cancelled` | — (Escape) |
|
|
@@ -1116,8 +1119,9 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1116
1119
|
see or do anything. A view a report opens or moves guards its presses
|
|
1117
1120
|
(THREAT_MODEL §6).
|
|
1118
1121
|
- **Host API.** `display.annotations.start(mode?)`, `stop()`, `show(marks)`,
|
|
1119
|
-
`focus(id)`, `clear()`,
|
|
1120
|
-
is given to every frame the display runs
|
|
1122
|
+
`focus(id)`, `track(id)`, `clear()`, `clearSelection()` (P115), and the `annotation`
|
|
1123
|
+
event (`AnnotationReport`); the state is given to every frame the display runs (not a
|
|
1124
|
+
`clearSelection`: a new frame has no selection). `parseAnchor` checks an anchor a host
|
|
1121
1125
|
stores (its server, before saving a comment).
|
|
1122
1126
|
|
|
1123
1127
|
Tests (`leak/annotate.spec.ts`, all three engines): a pick outlines and picks
|
|
@@ -1158,7 +1162,10 @@ page reading a draft's kind and never its count (`draft-count`), a raw `show` pa
|
|
|
1158
1162
|
an unknown kind (`draft-shell-checks`), and drafts alone followed after a scroll; and ADOPTING.md's `guardPresses`, as written
|
|
1159
1163
|
there, taking no press within 500 ms of its view opening (a release on a menu item,
|
|
1160
1164
|
a double click's second press on a button or a trigger, a press held past the
|
|
1161
|
-
arming) and the person's own press or key after.
|
|
1165
|
+
arming) and the person's own press or key after. The host's `clearSelection` (P115) takes
|
|
1166
|
+
a selection away from a page that patched `Selection.prototype.removeAllRanges`, tells
|
|
1167
|
+
nothing back, leaves marks and drafts found, and the same words selected again are told
|
|
1168
|
+
(`clear-selection`).
|
|
1162
1169
|
|
|
1163
1170
|
## The shell runtime
|
|
1164
1171
|
|
|
@@ -1466,6 +1473,16 @@ control the tables above name to the registry):
|
|
|
1466
1473
|
| `focus-guard` | `served/runtime.spec.ts` | `a page that takes the keyboard while the person types in the host's composer gets a key or two at most, and is stopped` | Firefox: `a page that takes the keyboard back on its own blur keeps none of it: the composer keeps its words, and comments.open reaches no handler`, `a composer the host focuses with focusField, beside a page with the person's gesture that takes focus back on its blur, gets their words` | — |
|
|
1467
1474
|
| `focus-guard-watch` | `served/runtime.spec.ts` | nothing | Firefox: `a page that takes the keyboard back on its own blur keeps none of it: the composer keeps its words, and comments.open reaches no handler`, `a composer the host focuses with focusField, beside a page with the person's gesture that takes focus back on its blur, gets their words` | no probe can see it on Chromium and WebKit: they blur the host's window on every move into a frame and a take-back lands, and a page can't take focus back from its own blur there (measured) |
|
|
1468
1475
|
| `comments-in-frame` | `served/runtime.spec.ts` | `comments.open while the person types in the host's composer reaches no handler, by the page's own call or the shell's; from a press in the frame it does` | — | — |
|
|
1476
|
+
| `cancel-any-mode` | `annotate.spec.ts` | `Escape while selecting text is cancelled, and stays the page's key; with no mode on, a page's own cancel isn't heard (P112)`, `a hostile page fakes reports: the host takes none it didn't ask for, nothing malformed, and not a flood` | — | — |
|
|
1477
|
+
| `track-checks` | `annotate.spec.ts` | `a followed mark's box comes as it moves, for that mark only, at most 60 a second, clamped to the frame, until the host stops (P112)` | — | — |
|
|
1478
|
+
| `order-check` | `annotate.spec.ts` | `every found mark's place in the document comes with its box, offscreen ones too; a place that isn't one is no report (P112)` | — | — |
|
|
1479
|
+
| `hold-click` | `annotate.spec.ts` | `holding a block 500 ms selects it and its release's click never reaches the page; a tap, a moving finger and a mouse are the page's (P112)` | — | — |
|
|
1480
|
+
| `clear-selection` | `annotate.spec.ts` | `clearSelection takes the page's selection away and tells nothing back; marks and drafts stay, the next selection is told (P115)` | — | — |
|
|
1481
|
+
| `shell-namespace` | `served/nested.spec.ts` | `the shell's words are the shell's alone: a page that says them, to its parent or to the host's window, moves nothing` | — | — |
|
|
1482
|
+
| `shell-label` | `served/nested-siblings.spec.ts` | `[nested-siblings]` | — | — |
|
|
1483
|
+
| `file-sandbox` | `served/nested.spec.ts` | `a page's SVG or XML file opened on a tab of its own is an opaque origin, and its script touches nothing of the shell's (P111, after its review)` | — | — |
|
|
1484
|
+
| `shell-stall` | `served/nested.spec.ts` | `a shell's activation seen after a stall is no one's gesture until it goes off (P111, after its review)` | — | — |
|
|
1485
|
+
| `shell-host-input` | `served/nested.spec.ts` | `a page's focus() just after the person pressed it and went back to the host's composer is taken back` | — | — |
|
|
1469
1486
|
| `comment-draft` | `served/runtime.spec.ts` | `a comment's draft is the host's to check: past the limit, holding what a person can't see, or not text, it opens no composer (P108)` | — | — |
|
|
1470
1487
|
| `blob-script` | `served/runtime.spec.ts` | nothing | — | an untrusted script asset is served as a download (`blob-script,blob-trusted`) |
|
|
1471
1488
|
| `blob-trusted` | `served/runtime.spec.ts` | `a script asset runs as code only if an admin uploaded it where uploads are the admins'` | — | — |
|