@botiverse/porthole 0.15.0 → 0.15.2

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/docs/DESIGN.md CHANGED
@@ -574,8 +574,9 @@ the system store for WebKit; Playwright's Firefox reads neither, so its project
574
574
  certificate errors). The suite (`packages/porthole/prod-shape`) runs the whole runner over https,
575
575
  then the sibling cases: Porthole's cookies host-only and `__Host-`; a sibling label (an app's
576
576
  preview) can't plant a cookie that opens content, or frame it; another site can't frame it; the
577
- clash. CI (`.github/workflows/ci.yml`) runs on every push: the checks, the loopback suites on
578
- each engine, and the prod-shape profile.
577
+ clash. CI (`.github/workflows/ci.yml`) runs the checks, the examples and the loopback suites on
578
+ Chromium on every push, and the loopback suites on each engine, the negative controls and the
579
+ prod-shape profile when started by hand, which a release requires on its commit (P146).
579
580
 
580
581
  **Compatibility.** Every 0.1.x export stays as it was; the kit wraps `createServer`. The npm
581
582
  package carries these docs (`docs/`), and `/server` exports the types an app's callbacks take
@@ -1012,7 +1013,7 @@ for that to lapse and click with raw input.
1012
1013
  | 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; outside `/server` too (P121), `createHost` refuses a nested page located on any other label, the shell runs on no other origin, and `nestedShellResponse` and `frameShellScript` refuse one; `nestedFileCsp` is the page's and its files' CSP for `/server` and a Worker of a host's own | `test/nested.test.ts`, `test/entry.test.ts` ("… (P114)"; `test/nested.test.ts` "… (P121)"); `leak/served/nested-siblings.spec.ts` (`[nested-siblings]`: a same-scope inline widget and artifact read each other, not the shell; `[nested-label]`: a nested page located on its scope's label is refused, no frame made) 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,nested-host-label,nested-shell-origin` (the shell on the scope's label, the host's and the shell's checks out) → `[nested-siblings]`, `[nested-label]` (all three); `nested-host-label` (the host's check out) → `[nested-label]` (all three) |
1013
1014
  | 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`) |
1014
1015
  | 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) | — |
1015
- | An embedded document (P143) | grant `embed` (only with the server's `embeds: true`, anonymous, no level or user, an artifact's page that isn't nested; signed into the session as `m` and into the sealed address) → `frame-ancestors *` for that session's answers alone (its document, a file set's pages and files and own frames, assets, renewals, its status and ended-access pages); an embed session's cookie has a name of its own (`e-<key>`) and never stands in for another session; the plan names no host (`origins: []`): the shell asks no host, ends its handshake at once (`"none"`), says nothing to any parent (no `*` notices, no annotation or find report) and hears no one; no door; `statusPage` and `doorStatusResponse` take `embed` (`*`, `data-porthole-hosts="[]"`) | `test/embed.test.ts` (refused without `embeds`, with a viewer, a level or a user, for url mode, a nested display, a served shell or the proxy, at a clean address and at the door; the flag can't be added or stripped, nor a session moved to the other name; **the bound**: 23 kinds of answer under an embed session say `*` and name no host, and the same under a public and a viewer's session are byte for byte what a server without `embeds` answers, on the same server while an embed session of the same artifact exists, and with both cookies sent; the host's check is told `embed`; cookies host-only, never `Domain=`); `test/shell.test.ts` (P143's handshake); `leak/served/embed.spec.ts`: `[embed.loads]`, `[embed.unheard]`, `[embed.untold]`, `[embed.no-escape]`, `[embed.reader-unframeable]` | `embed-ancestors` → `[embed.reader-unframeable]`; `embed-handshake` → `[embed.untold]`; `embed-origins` → `[embed.unheard]` (all three) |
1016
+ | An embedded document (P143) | grant `embed` (only with the server's `embeds: true`, anonymous, no level or user, an artifact's page that isn't nested; signed into the session as `m` and into the sealed address) → `frame-ancestors *` for that session's answers alone (its document, a file set's pages and files and own frames, assets, renewals, its status and ended-access pages); an embed session's cookie has a name of its own (`e-<key>`) and never stands in for another session; the plan names no host (`origins: []`): the shell asks no host, ends its handshake at once (`"none"`), says nothing to any parent (no `*` notices, no annotation or find report) and hears no one; no door; `statusPage` and `doorStatusResponse` take `embed` (`*`, `data-porthole-hosts="[]"`); the host kit refuses an `access` answer with `embed` (P145: minted through `host.server.issue` alone) | `test/embed.test.ts` (refused without `embeds`, with a viewer, a level or a user, for url mode, a nested display, a served shell or the proxy, at a clean address and at the door; the host kit refuses it from `access` at its issue endpoint, a clean address's resolve and its tab, with `embeds` or without; the flag can't be added or stripped, nor a session moved to the other name; **the bound**: 23 kinds of answer under an embed session say `*` and name no host, and the same under a public and a viewer's session are byte for byte what a server without `embeds` answers, on the same server while an embed session of the same artifact exists, and with both cookies sent; the host's check is told `embed`; cookies host-only, never `Domain=`); `test/shell.test.ts` (P143's handshake); `leak/served/embed.spec.ts`: `[embed.loads]`, `[embed.unheard]` (the words before the document loads too, P145), `[embed.untold]`, `[embed.no-escape]`, `[embed.reader-unframeable]` | `embed-ancestors` → `[embed.reader-unframeable]`; `embed-handshake` → `[embed.untold]`; `embed-origins` → `[embed.unheard]` (all three) |
1016
1017
 
1017
1018
  ### The clipboard, and copy buttons
1018
1019
 
@@ -5,7 +5,7 @@ What Porthole protects, from whom, and where that protection ends. For each way
5
5
  guaranteed. [ADOPTING.md](ADOPTING.md) says how to set each one up, and
6
6
  [DESIGN.md](DESIGN.md) lists every defense with the test that proves it.
7
7
 
8
- **Status.** This describes Porthole 0.15.0 (2026-11-10). A review on 2026-10-19 found gaps, and every decision it led to
8
+ **Status.** This describes Porthole 0.15.2 (2026-11-11). A review on 2026-10-19 found gaps, and every decision it led to
9
9
  has merged ([§8](#8-fixes-in-flight) lists them). P096 changed the negative-control runner and CI,
10
10
  and the shipped conformance probes' messages and timing, not what they check. P104 (0.9.0's
11
11
  annotation markers) had a review of its own, and P105, in 0.10.0, is what it led to. 0.11.0 was
@@ -55,12 +55,25 @@ lets a host that opts in (`embeds`) mint an embed grant: a public artifact page'
55
55
  `frame-ancestors *` for that session alone, and the page has no host: it hears no one, tells no
56
56
  parent anything, and no capability, runtime host function or door is there (S4, §8). P144, after
57
57
  Ferryman's audit of 0.14.17 and 0.14.18 (no P0, no new egress), amends P141: without `framedBy`
58
- the status, entry and door pages' scripts and the nested page's shell are 0.14.16's again, byte for
59
- byte (0.14.17 had changed their hashes, not what they do); in the nesting P141 is for (the outer
60
- page, then the app's page, then content), content can message the outer page and every frame in
61
- its tree and learn its origin, so the outer page must check every message it takes, and S7's
62
- egress rule covers its frames (§6 "What every host must do", S7); and `framedBy` is compared with
63
- the host origins as browsers serialize origins (`https://a.example:443` is `https://a.example`).
58
+ every header (every `frame-ancestors` and `script-src` hash) and the status, entry and door pages'
59
+ scripts and the nested page's shell are 0.14.16's again, byte for byte (0.14.17 had changed their
60
+ hashes, not what they do); the shell runtime every served document inlines is not (P142's
61
+ changes, and P143's `hostless` branches, inert where a plan names a host; no hash covers it: P145);
62
+ in the nesting P141 is for (the outer page, then the app's page, then content), content can message
63
+ the outer page and every frame in its tree and learn its origin, so the outer page must check every
64
+ message it takes, and S7's egress rule covers its frames (§6 "What every host must do", S7); and
65
+ `framedBy` is compared with the host origins as browsers serialize origins (`https://a.example:443`
66
+ is `https://a.example`).
67
+ 0.15.1: P145, after Ferryman's audit of 0.15.0 (no P0, no escape, no new egress), amends P143 and
68
+ P144: their "byte for byte" is said as it holds (above); the host kit refuses an `access` answer
69
+ with `embed`, so a reader's issue endpoint never mints an embed session (S4); an embed page learns
70
+ where it is embedded (S4); and a host origin's or `framedBy`'s port is 1 to 65535, without a
71
+ leading zero, and its host as the URL parser gives it. No wall moves.
72
+ 0.15.2: P147, annotations' marks ride the document's scroll: the boxes of the shell's layer are
73
+ placed down the document and moved by a scroll-driven animation in the layer's closed shadow root,
74
+ so they no longer trail the text for the frames before the scroll event is heard. No message and
75
+ no reading is added (the scroll offset was read already, P132), and the layer still adds nothing to
76
+ what a page can scroll. No wall moves.
64
77
 
65
78
  ## 1. Two layers
66
79
 
@@ -139,8 +152,9 @@ viewer and any declaration.
139
152
  The leak suite attempts each channel in DESIGN.md's table from inside the content, on Chromium,
140
153
  WebKit and Firefox, and most defenses have a negative control that takes the defense out to show
141
154
  its probes then fail (DESIGN.md § "Egress hardening, each with its test"). CI runs every negative
142
- control on all three engines, and a control passes only when its marked probes failed by their own
143
- assertion (P096).
155
+ control on all three engines on the commit of every release (P146: the release's gate requires
156
+ that run; a pull request's CI runs the suite on Chromium, with no control), and a control passes
157
+ only when its marked probes failed by their own assertion (P096).
144
158
 
145
159
  ## 5. Out of scope
146
160
 
@@ -572,8 +586,10 @@ the attacker (c), and its readers are strangers.
572
586
  `frame-ancestors *` for that session alone, never a reader's; it is anonymous, with no level or
573
587
  user, an artifact's page that isn't nested; its plan names no host, so it hears no one, Porthole
574
588
  tells no parent anything, no capability or runtime host function runs, and no door is minted. The
575
- flag is signed into the session and the sealed address. Every other session is unchanged, byte
576
- for byte, while an embed session of the same artifact exists; cookies stay host-only.
589
+ flag is signed into the session and the sealed address. Every other session's answers are, byte
590
+ for byte, what the same server without `embeds` answers, while an embed session of the same
591
+ artifact exists; cookies stay host-only. The host kit never mints one from `access` (its reader's
592
+ issue endpoint and clean addresses refuse an `embed` answer, P145).
577
593
  - A page opened in a tab of its own has its frame's powers and no more (P099): its CSP header
578
594
  carries the frame's sandbox (scripts on its own origin; no popups, forms, downloads, browser
579
595
  dialogs, or navigation of another window, its opener's included), and its `Permissions-Policy`
@@ -607,10 +623,17 @@ the attacker (c), and its readers are strangers.
607
623
  - Check pages for secrets before publishing them: `lintContent` has no rule for credentials.
608
624
  - Pass Porthole's `Content-Security-Policy` and `Permissions-Policy` headers on as they are,
609
625
  through any edge or proxy: on a tab they are the page's sandbox.
610
- - For embeds (P143): mint `embed` from one route of yours alone (never a reader's ticket or door),
611
- keep that route from widening grants, and blank a takedown within a bound you state (your
612
- `authorize` answers, cached or not). The embedding site sees the page load and hears what the
613
- page itself posts to its parent or top.
626
+ - For embeds (P143): mint `embed` from one route of yours alone (never a reader's ticket or door;
627
+ with the host kit, `host.server.issue`, never `access`, which it refuses, P145), keep that route
628
+ from widening grants, and blank a takedown within a bound you state (your `authorize` answers,
629
+ cached or not). The embedding site sees the page load and hears what the page itself posts to its
630
+ parent or top. The page learns where it is embedded (P145, measured in Chromium, Firefox and
631
+ WebKit): its document's request carries your outer page's address as `Referer` (its origin, under
632
+ the default referrer policy; Firefox also sends it as `Origin`, Chromium and WebKit don't),
633
+ `document.referrer` says the same,
634
+ and `location.ancestorOrigins` names every ancestor, the embedding site's origin included. A page
635
+ with any egress (a `connect-src`, an image source) can send that out; one with none can't. Treat
636
+ where an embed is shown as known to its author.
614
637
  - Treat a public link's clean address as a tab's (P125): to show what one names in a frame, resolve
615
638
  it through your issue endpoint (`client.resolve`, `<PortholeView address>`). Its refusals (signed
616
639
  out, denied, not found) are your backend's word, drawn as the fallback with no frame built: keep
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@botiverse/porthole",
3
- "version": "0.15.0",
3
+ "version": "0.15.2",
4
4
  "description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
5
5
  "homepage": "https://github.com/botiverse/porthole#readme",
6
6
  "bugs": {
@@ -67,10 +67,37 @@ export function isHostOrigin(origin: unknown): origin is string {
67
67
  return typeof origin === "string" && origin.length <= 300 && HOST_ORIGIN.test(origin);
68
68
  }
69
69
 
70
+ /**
71
+ * Whether an origin that matched `HOST_ORIGIN` is one a browser can serialize as it is written
72
+ * (P145): a port, where it names one, is 1 to 65535 in plain decimal (never `:0`, `:99999` or
73
+ * `:0443`), and an `http`/`https` host is as the URL parser gives it back (never `0x7f.0.0.1` for
74
+ * `127.0.0.1`). A default port (`:443`) is still taken: browsers drop it, and `normalOrigin`
75
+ * compares it so (P144). Such an origin matches no frame and no message, so refusing it only says
76
+ * so early.
77
+ */
78
+ function serializable(origin: string): boolean {
79
+ const port = /:(\d+)$/u.exec(origin)?.[1];
80
+ if (port !== undefined && !(/^[1-9]\d{0,4}$/u.test(port) && Number(port) <= 65_535)) {
81
+ return false;
82
+ }
83
+ const scheme = origin.slice(0, origin.indexOf(":"));
84
+ if (scheme !== "http" && scheme !== "https") {
85
+ return true;
86
+ }
87
+ try {
88
+ const url = new URL(origin);
89
+ return url.hostname === origin.slice(scheme.length + 3).replace(/:\d+$/u, "");
90
+ } catch {
91
+ return false;
92
+ }
93
+ }
94
+
70
95
  /** Why `origin` can't be a host origin, in words a host's developer can act on; null if it can. */
71
96
  export function hostOriginProblem(origin: unknown): string | null {
72
97
  if (isHostOrigin(origin)) {
73
- return null;
98
+ return serializable(origin)
99
+ ? null
100
+ : `${JSON.stringify(origin)} is not an origin a browser serializes so (a port is 1 to 65535, no leading zero; a host as the URL parser gives it)`;
74
101
  }
75
102
  if (origin === "null") {
76
103
  return 'the host page\'s origin is opaque ("null"): serve it from a real origin (an Electron custom protocol must be registered as standard, and file: pages have none)';
@@ -111,7 +138,8 @@ const LOOPBACK_HOST = (host: string): boolean =>
111
138
  * ancestor of every frame the host shows, above the host's own page, and never a host origin. An
112
139
  * exact web origin, `https://host[:port]` (lowercase, no path, no wildcard), or `http://` on
113
140
  * loopback alone (`localhost`, `*.localhost`, `127.0.0.1`, `[::1]`) for development: never a
114
- * desktop scheme, `"null"`, a CSP keyword or a list. Null if it can be.
141
+ * desktop scheme, `"null"`, a CSP keyword or a list. Its port, where it names one, is 1 to 65535
142
+ * in plain decimal, and its host is as the URL parser gives it back (P145). Null if it can be.
115
143
  */
116
144
  export function framedByProblem(origin: unknown): string | null {
117
145
  const parsed = typeof origin === "string" && isHostOrigin(origin) ? parseOrigin(origin) : null;
@@ -121,6 +149,9 @@ export function framedByProblem(origin: unknown): string | null {
121
149
  ) {
122
150
  return `${JSON.stringify(origin)} is not an exact https origin (https://host[:port], lowercase, no path; http only on loopback)`;
123
151
  }
152
+ if (!serializable(origin as string)) {
153
+ return `${JSON.stringify(origin)} is not an origin a browser serializes so (a port is 1 to 65535, no leading zero; a host as the URL parser gives it)`;
154
+ }
124
155
  return null;
125
156
  }
126
157
 
@@ -121,10 +121,14 @@ export interface ContentHostOptions<V> {
121
121
  */
122
122
  readonly framedBy?: readonly string[];
123
123
  /**
124
- * Whether `access` may answer an embed grant (P143, `Grant.embed`): a public artifact page that
124
+ * Whether `server.issue` takes an embed grant (P143, `Grant.embed`): a public artifact page that
125
125
  * any site may frame, with no host (`ServerOptions.embeds`). Default false: an embed grant is
126
- * refused at issue. Only an embed session's answers say `frame-ancestors *`; every other answer
127
- * is as without it.
126
+ * refused at issue. Mint one from a route of your own that decides the page is public
127
+ * (`host.server.issue(instance, { anonymous: true, embed: true })`), never from `access`: `access`
128
+ * answers your readers (the issue endpoint, a clean address), and the kit refuses an `access`
129
+ * answer with `embed` (409 at the issue endpoint and a clean address's resolve; a clean address's
130
+ * tab gets its 409 page, as `enterBy` refuses it) (P145). Only an embed session's answers say
131
+ * `frame-ancestors *`; every other answer is as without it.
128
132
  */
129
133
  readonly embeds?: boolean;
130
134
  /** At least 32 random bytes (or a string of at least 32 bytes). */
@@ -167,7 +171,11 @@ export interface ContentHostOptions<V> {
167
171
  viewer: V | null,
168
172
  request: Request,
169
173
  ) => Awaitable<InstanceRef | null>;
170
- /** Policy 2, access at issue: may this viewer see it, and with what grant (null: 401/403). */
174
+ /**
175
+ * Policy 2, access at issue: may this viewer see it, and with what grant (null: 401/403). It
176
+ * answers readers, so never with `embed` (refused, P145): an embed grant is minted from a route
177
+ * of your own through `host.server.issue`.
178
+ */
171
179
  readonly access: (
172
180
  instance: InstanceRef,
173
181
  viewer: V | null,
@@ -1129,6 +1137,15 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
1129
1137
  request: Request,
1130
1138
  more: { readonly page?: string; readonly resolved?: boolean } = {},
1131
1139
  ): Promise<Response> {
1140
+ // `access` answers readers, here and at a clean address: an embed grant (P143) is never
1141
+ // theirs, whatever `embeds` says (P145). A host mints it from a route of its own.
1142
+ if ((grant as { readonly embed?: unknown }).embed !== undefined) {
1143
+ return refusal(
1144
+ 409,
1145
+ "refused",
1146
+ "access never answers an embed grant: mint it from a route of your own with host.server.issue (P145)",
1147
+ );
1148
+ }
1132
1149
  let location: FrameLocation;
1133
1150
  try {
1134
1151
  location = await server!.issue(
@@ -414,7 +414,37 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
414
414
  // The selection the host follows (P138) is drawn as what is picked is: an element in the
415
415
  // picking outline, a little lighter and without its name; words with a light fill and a line
416
416
  // under them, in the same blue, apart from the marks' yellow (no comment is there yet).
417
- const STYLE = ".mark{position:absolute;border-radius:2px;background:rgba(250,204,21,.18);box-shadow:inset 0 -2px 0 rgba(234,179,8,.95)}.mark.element{background:rgba(250,204,21,.07);box-shadow:none;outline:2px solid rgba(234,179,8,.9);outline-offset:1px}.mark.active{background:rgba(250,204,21,.26);box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 2px rgba(234,179,8,.45)}.mark.element.active{background:rgba(250,204,21,.12);box-shadow:none;outline-width:3px}.mark.element.quiet{background:rgba(250,204,21,.05);outline:1px solid rgba(234,179,8,.6);outline-offset:2px}.mark.element.quiet.active{background:rgba(250,204,21,.1);outline:2px solid rgba(234,179,8,.9)}.mark.draft{box-sizing:border-box;background:rgba(250,204,21,.08);box-shadow:none;border-bottom:2px dashed rgba(202,138,4,.95)}.mark.draft.active{background:rgba(250,204,21,.16);box-shadow:0 0 0 2px rgba(234,179,8,.45);border-bottom-width:3px}.mark.element.draft{background:rgba(250,204,21,.04);border-bottom:0;outline-style:dashed}.mark.element.draft.active{background:rgba(250,204,21,.08);box-shadow:none;outline-style:dashed}.marker{position:absolute;box-sizing:border-box;height:18px;min-width:18px;display:flex;align-items:center;justify-content:center;gap:3px;margin:0;padding:0 5px;border:1px solid rgba(161,98,7,.6);border-radius:9px 9px 9px 2px;background:#fde68a;color:#422006;box-shadow:0 1px 2px rgba(0,0,0,.3);font:600 11px/16px system-ui,-apple-system,Segoe UI,Roboto,sans-serif;font-style:normal;letter-spacing:0;word-spacing:0;text-transform:none;text-indent:0;text-shadow:none;direction:ltr;writing-mode:horizontal-tb;white-space:nowrap;user-select:none;-webkit-user-select:none;cursor:pointer;pointer-events:auto;appearance:none;-webkit-appearance:none}.marker:focus-visible{outline:2px solid #2563eb;outline-offset:1px}.marker:hover{background:#fcd34d}.marker.active{background:#facc15;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.3)}.marker.compact{padding:0 4px}.marker.draft{border:1px dashed rgb(202,138,4);background:#fffdf5;color:#a16207;box-shadow:0 1px 2px rgba(0,0,0,.2)}.marker.draft:hover{background:#fef9e7}.marker.draft.active{background:#fef3c7;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.2)}.marker.inert,[data-placing]>.marker{pointer-events:none}.touch>.marker::before{content:'';position:absolute;left:50%;top:50%;width:max(100% + 2px,44px);height:max(100% + 2px,44px);transform:translate(-50%,-50%)}.marker svg{display:block;width:11px;height:11px;flex:none}.mark.flash{animation:flash 1.8s ease-out}@keyframes flash{from{box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 6px rgba(250,204,21,.6)}}.hover{position:absolute;outline:2px solid #2563eb;outline-offset:1px;background:rgba(37,99,235,.12)}.held{position:absolute;outline:2px solid #2563eb;outline-offset:1px;background:rgba(37,99,235,.06)}.held.text{outline:0;border-radius:2px;background:rgba(37,99,235,.12);box-shadow:inset 0 -2px 0 #2563eb}.tag{position:absolute;max-width:70vw;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font:12px/18px ui-monospace,SFMono-Regular,Menlo,monospace;padding:0 6px;border-radius:4px;background:#1e293b;color:#fff}";
417
+ const STYLE = ".mark{position:absolute;border-radius:2px;background:rgba(250,204,21,.18);box-shadow:inset 0 -2px 0 rgba(234,179,8,.95)}.mark.element{background:rgba(250,204,21,.07);box-shadow:none;outline:2px solid rgba(234,179,8,.9);outline-offset:1px}.mark.active{background:rgba(250,204,21,.26);box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 2px rgba(234,179,8,.45)}.mark.element.active{background:rgba(250,204,21,.12);box-shadow:none;outline-width:3px}.mark.element.quiet{background:rgba(250,204,21,.05);outline:1px solid rgba(234,179,8,.6);outline-offset:2px}.mark.element.quiet.active{background:rgba(250,204,21,.1);outline:2px solid rgba(234,179,8,.9)}.mark.draft{box-sizing:border-box;background:rgba(250,204,21,.08);box-shadow:none;border-bottom:2px dashed rgba(202,138,4,.95)}.mark.draft.active{background:rgba(250,204,21,.16);box-shadow:0 0 0 2px rgba(234,179,8,.45);border-bottom-width:3px}.mark.element.draft{background:rgba(250,204,21,.04);border-bottom:0;outline-style:dashed}.mark.element.draft.active{background:rgba(250,204,21,.08);box-shadow:none;outline-style:dashed}.marker{position:absolute;box-sizing:border-box;height:18px;min-width:18px;display:flex;align-items:center;justify-content:center;gap:3px;margin:0;padding:0 5px;border:1px solid rgba(161,98,7,.6);border-radius:9px 9px 9px 2px;background:#fde68a;color:#422006;box-shadow:0 1px 2px rgba(0,0,0,.3);font:600 11px/16px system-ui,-apple-system,Segoe UI,Roboto,sans-serif;font-style:normal;letter-spacing:0;word-spacing:0;text-transform:none;text-indent:0;text-shadow:none;direction:ltr;writing-mode:horizontal-tb;white-space:nowrap;user-select:none;-webkit-user-select:none;cursor:pointer;pointer-events:auto;appearance:none;-webkit-appearance:none}.marker:focus-visible{outline:2px solid #2563eb;outline-offset:1px}.marker:hover{background:#fcd34d}.marker.active{background:#facc15;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.3)}.marker.compact{padding:0 4px}.marker.draft{border:1px dashed rgb(202,138,4);background:#fffdf5;color:#a16207;box-shadow:0 1px 2px rgba(0,0,0,.2)}.marker.draft:hover{background:#fef9e7}.marker.draft.active{background:#fef3c7;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.2)}.marker.inert,[data-placing]>.marker{pointer-events:none}.touch>.marker::before{content:'';position:absolute;left:50%;top:50%;width:max(100% + 2px,44px);height:max(100% + 2px,44px);transform:translate(-50%,-50%)}.marker svg{display:block;width:11px;height:11px;flex:none}.mark.flash{animation:flash 1.8s ease-out}@keyframes flash{from{box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 6px rgba(250,204,21,.6)}}.hover{position:absolute;outline:2px solid #2563eb;outline-offset:1px;background:rgba(37,99,235,.12)}.held{position:absolute;outline:2px solid #2563eb;outline-offset:1px;background:rgba(37,99,235,.06)}.held.text{outline:0;border-radius:2px;background:rgba(37,99,235,.12);box-shadow:inset 0 -2px 0 #2563eb}.tag{position:absolute;max-width:70vw;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font:12px/18px ui-monospace,SFMono-Regular,Menlo,monospace;padding:0 6px;border-radius:4px;background:#1e293b;color:#fff}.ride{position:absolute;left:0;top:0;width:0;height:0}@supports (animation-timeline:scroll()){.ride{animation:ride 1ms linear both;animation-timeline:scroll(root y)}@keyframes ride{to{transform:translateY(calc(-1px*var(--ride)))}}}";
418
+ // The marks ride the document's own scroll (P147). The layer stays fixed and clipped to the
419
+ // viewport, so it adds nothing to what the page can scroll; inside it one box holds every
420
+ // mark, marker and outline at its place in the document (its top plus how far the document
421
+ // is scrolled), and a scroll-driven animation moves that box up by the scroll. The engine
422
+ // runs it with the scroll itself, so a mark is where its words are in every frame, not a
423
+ // frame behind (a scroll event is heard after the frame it scrolled). Down the page only:
424
+ // sideways, and where the engine has no scroll timeline (ridden: 0), a mark is placed in the
425
+ // viewport and follows from the scroll event as before. Read with the DOM's own getters,
426
+ // taken before content runs; the range is what the timeline runs over (0: it is inactive,
427
+ // and nothing moves).
428
+ const rides = typeof CSS === "object" && CSS !== null && typeof CSS.supports === "function" && CSS.supports("animation-timeline: scroll()");
429
+ const scrollerOf = getterOf(Document.prototype, "scrollingElement");
430
+ const scrollTopOf = getterOf(Element.prototype, "scrollTop");
431
+ const scrollHeightOf = getterOf(Element.prototype, "scrollHeight");
432
+ const clientHeightOf = getterOf(Element.prototype, "clientHeight");
433
+ // How far down the document is scrolled as the marks are drawn, and how far it can be.
434
+ let ridden = 0;
435
+ const rideOf = () => {
436
+ const none = { by: 0, range: 0 };
437
+ if (!rides || scrollerOf === null || scrollTopOf === null || scrollHeightOf === null || clientHeightOf === null) {
438
+ return none;
439
+ }
440
+ const scroller = callOf(scrollerOf, document, []);
441
+ if (!scroller) {
442
+ return none;
443
+ }
444
+ const range = callOf(scrollHeightOf, scroller, []) - callOf(clientHeightOf, scroller, []);
445
+ const by = callOf(scrollTopOf, scroller, []);
446
+ return range > 0 && by >= 0 && by <= range + 1 ? { by, range } : none;
447
+ };
418
448
  // Inline and important: the content's own style sheets can't hide, shrink or move it by
419
449
  // accident. Set again at each draw, since its scripts can rewrite it (narrowing only: the
420
450
  // content can still cover the layer, or move it with its ancestors, P104). Clipped, where an
@@ -792,7 +822,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
792
822
  // button: Safari's Tab skips a button without one, unless the person asked otherwise.
793
823
  marker.tabIndex = mode.elements ? -1 : 0;
794
824
  marker.className = "marker" + (mark.draft ? " draft" : "") + (each.compact ? " compact" : "") + (mark.id === active ? " active" : "") + (mode.elements ? " inert" : "");
795
- marker.style.cssText = "left:" + each.left + "px;top:" + each.top + "px";
825
+ marker.style.cssText = "left:" + each.left + "px;top:" + (each.top + ridden) + "px";
796
826
  markers.push({ id: mark.id, element: marker });
797
827
  const name = nameOf(mark);
798
828
  const form = (mark.draft ? "draft:" : "") + (each.compact ? "compact:" : "full:") + label + ":" + name;
@@ -839,17 +869,19 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
839
869
  // the pointer's arrival on a marker lit its mark and redrew).
840
870
  let boxes = null;
841
871
  const boxesOf = (root) => {
842
- if (boxes === null || boxes.style.parentNode !== root || boxes.marks.parentNode !== root || boxes.markers.parentNode !== root || boxes.hover.parentNode !== root) {
872
+ if (boxes === null || boxes.style.parentNode !== root || boxes.ride.parentNode !== root || boxes.marks.parentNode !== boxes.ride || boxes.markers.parentNode !== boxes.ride || boxes.hover.parentNode !== boxes.ride) {
843
873
  const style = createElement.call(document, "style");
844
874
  if (nonce !== "") {
845
875
  style.nonce = nonce;
846
876
  }
847
- boxes = { style, marks: createElement.call(document, "div"), markers: createElement.call(document, "div"), hover: createElement.call(document, "div") };
877
+ boxes = { style, ride: createElement.call(document, "div"), marks: createElement.call(document, "div"), markers: createElement.call(document, "div"), hover: createElement.call(document, "div") };
878
+ boxes.ride.className = "ride";
848
879
  // Only the markers are for assistive technology (P133): the rest draws what the page
849
880
  // already says.
850
881
  boxes.marks.setAttribute("aria-hidden", "true");
851
882
  boxes.hover.setAttribute("aria-hidden", "true");
852
- root.replaceChildren(boxes.style, boxes.marks, boxes.markers, boxes.hover);
883
+ boxes.ride.replaceChildren(boxes.marks, boxes.markers, boxes.hover);
884
+ root.replaceChildren(boxes.style, boxes.ride);
853
885
  }
854
886
  if (boxes.style.textContent !== STYLE) {
855
887
  boxes.style.textContent = STYLE;
@@ -867,6 +899,10 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
867
899
  const into = boxesOf(root);
868
900
  const parts = [];
869
901
  const flashOn = Date.now() < flashUntil;
902
+ // Read with the boxes, in this one task: a place in the document is a box's top in the
903
+ // viewport plus this.
904
+ const ride = rideOf();
905
+ ridden = ride.by;
870
906
  // What is measured first, then drawn: no node of the layer changes while the page is read.
871
907
  const corners = [];
872
908
  const wanted = [];
@@ -883,7 +919,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
883
919
  }
884
920
  const each = createElement.call(document, "div");
885
921
  each.className = "mark " + (mark.found.range ? "text" : "element") + (mark.marker ? " quiet" : "") + (mark.draft ? " draft" : "") + (mark.id === active || mark.id === hot ? " active" : "") + (flashOn && mark.id === flashing ? " flash" : "");
886
- each.style.cssText = "left:" + rect.left + "px;top:" + rect.top + "px;width:" + rect.width + "px;height:" + rect.height + "px";
922
+ each.style.cssText = "left:" + rect.left + "px;top:" + (rect.top + ridden) + "px;width:" + rect.width + "px;height:" + rect.height + "px";
887
923
  parts.push(each);
888
924
  }
889
925
  if (mark.marker) {
@@ -969,7 +1005,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
969
1005
  }
970
1006
  const each = createElement.call(document, "div");
971
1007
  each.className = lit.range ? "held text" : "held";
972
- each.style.cssText = "left:" + rect.left + "px;top:" + rect.top + "px;width:" + rect.width + "px;height:" + rect.height + "px";
1008
+ each.style.cssText = "left:" + rect.left + "px;top:" + (rect.top + ridden) + "px;width:" + rect.width + "px;height:" + rect.height + "px";
973
1009
  outlines.push(each);
974
1010
  }
975
1011
  }
@@ -977,13 +1013,18 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
977
1013
  const rect = elementRect.call(hover);
978
1014
  const outline = createElement.call(document, "div");
979
1015
  outline.className = "hover";
980
- outline.style.cssText = "left:" + rect.left + "px;top:" + rect.top + "px;width:" + rect.width + "px;height:" + rect.height + "px";
1016
+ outline.style.cssText = "left:" + rect.left + "px;top:" + (rect.top + ridden) + "px;width:" + rect.width + "px;height:" + rect.height + "px";
981
1017
  const tag = createElement.call(document, "div");
982
1018
  tag.className = "tag";
983
1019
  tag.textContent = describe(hover).slice(0, 80);
984
- tag.style.cssText = "left:" + Math.max(4, rect.left) + "px;top:" + (rect.top >= 24 ? rect.top - 22 : Math.max(4, rect.bottom + 4)) + "px";
1020
+ tag.style.cssText = "left:" + Math.max(4, rect.left) + "px;top:" + ((rect.top >= 24 ? rect.top - 22 : Math.max(4, rect.bottom + 4)) + ridden) + "px";
985
1021
  outlines.push(outline, tag);
986
1022
  }
1023
+ // How far the ride goes, for the animation; set only when it changed.
1024
+ const range = String(ride.range);
1025
+ if (into.ride.style.getPropertyValue("--ride") !== range) {
1026
+ into.ride.style.setProperty("--ride", range);
1027
+ }
987
1028
  into.marks.replaceChildren(...parts);
988
1029
  for (const child of Array.from(into.markers.childNodes)) {
989
1030
  if (badges.indexOf(child) === -1) {