@botiverse/porthole 0.15.1 → 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.
@@ -410,7 +410,37 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
410
410
  // The selection the host follows (P138) is drawn as what is picked is: an element in the
411
411
  // picking outline, a little lighter and without its name; words with a light fill and a line
412
412
  // under them, in the same blue, apart from the marks' yellow (no comment is there yet).
413
- 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}";
413
+ 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)))}}}";
414
+ // The marks ride the document's own scroll (P147). The layer stays fixed and clipped to the
415
+ // viewport, so it adds nothing to what the page can scroll; inside it one box holds every
416
+ // mark, marker and outline at its place in the document (its top plus how far the document
417
+ // is scrolled), and a scroll-driven animation moves that box up by the scroll. The engine
418
+ // runs it with the scroll itself, so a mark is where its words are in every frame, not a
419
+ // frame behind (a scroll event is heard after the frame it scrolled). Down the page only:
420
+ // sideways, and where the engine has no scroll timeline (ridden: 0), a mark is placed in the
421
+ // viewport and follows from the scroll event as before. Read with the DOM's own getters,
422
+ // taken before content runs; the range is what the timeline runs over (0: it is inactive,
423
+ // and nothing moves).
424
+ const rides = typeof CSS === "object" && CSS !== null && typeof CSS.supports === "function" && CSS.supports("animation-timeline: scroll()");
425
+ const scrollerOf = getterOf(Document.prototype, "scrollingElement");
426
+ const scrollTopOf = getterOf(Element.prototype, "scrollTop");
427
+ const scrollHeightOf = getterOf(Element.prototype, "scrollHeight");
428
+ const clientHeightOf = getterOf(Element.prototype, "clientHeight");
429
+ // How far down the document is scrolled as the marks are drawn, and how far it can be.
430
+ let ridden = 0;
431
+ const rideOf = () => {
432
+ const none = { by: 0, range: 0 };
433
+ if (!rides || scrollerOf === null || scrollTopOf === null || scrollHeightOf === null || clientHeightOf === null) {
434
+ return none;
435
+ }
436
+ const scroller = callOf(scrollerOf, document, []);
437
+ if (!scroller) {
438
+ return none;
439
+ }
440
+ const range = callOf(scrollHeightOf, scroller, []) - callOf(clientHeightOf, scroller, []);
441
+ const by = callOf(scrollTopOf, scroller, []);
442
+ return range > 0 && by >= 0 && by <= range + 1 ? { by, range } : none;
443
+ };
414
444
  // Inline and important: the content's own style sheets can't hide, shrink or move it by
415
445
  // accident. Set again at each draw, since its scripts can rewrite it (narrowing only: the
416
446
  // content can still cover the layer, or move it with its ancestors, P104). Clipped, where an
@@ -788,7 +818,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
788
818
  // button: Safari's Tab skips a button without one, unless the person asked otherwise.
789
819
  marker.tabIndex = mode.elements ? -1 : 0;
790
820
  marker.className = "marker" + (mark.draft ? " draft" : "") + (each.compact ? " compact" : "") + (mark.id === active ? " active" : "") + (mode.elements ? " inert" : "");
791
- marker.style.cssText = "left:" + each.left + "px;top:" + each.top + "px";
821
+ marker.style.cssText = "left:" + each.left + "px;top:" + (each.top + ridden) + "px";
792
822
  markers.push({ id: mark.id, element: marker });
793
823
  const name = nameOf(mark);
794
824
  const form = (mark.draft ? "draft:" : "") + (each.compact ? "compact:" : "full:") + label + ":" + name;
@@ -835,17 +865,19 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
835
865
  // the pointer's arrival on a marker lit its mark and redrew).
836
866
  let boxes = null;
837
867
  const boxesOf = (root) => {
838
- if (boxes === null || boxes.style.parentNode !== root || boxes.marks.parentNode !== root || boxes.markers.parentNode !== root || boxes.hover.parentNode !== root) {
868
+ 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) {
839
869
  const style = createElement.call(document, "style");
840
870
  if (nonce !== "") {
841
871
  style.nonce = nonce;
842
872
  }
843
- boxes = { style, marks: createElement.call(document, "div"), markers: createElement.call(document, "div"), hover: createElement.call(document, "div") };
873
+ boxes = { style, ride: createElement.call(document, "div"), marks: createElement.call(document, "div"), markers: createElement.call(document, "div"), hover: createElement.call(document, "div") };
874
+ boxes.ride.className = "ride";
844
875
  // Only the markers are for assistive technology (P133): the rest draws what the page
845
876
  // already says.
846
877
  boxes.marks.setAttribute("aria-hidden", "true");
847
878
  boxes.hover.setAttribute("aria-hidden", "true");
848
- root.replaceChildren(boxes.style, boxes.marks, boxes.markers, boxes.hover);
879
+ boxes.ride.replaceChildren(boxes.marks, boxes.markers, boxes.hover);
880
+ root.replaceChildren(boxes.style, boxes.ride);
849
881
  }
850
882
  if (boxes.style.textContent !== STYLE) {
851
883
  boxes.style.textContent = STYLE;
@@ -863,6 +895,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
863
895
  const into = boxesOf(root);
864
896
  const parts = [];
865
897
  const flashOn = Date.now() < flashUntil;
898
+ // Read with the boxes, in this one task: a place in the document is a box's top in the
899
+ // viewport plus this.
900
+ const ride = rideOf();
901
+ ridden = ride.by;
866
902
  // What is measured first, then drawn: no node of the layer changes while the page is read.
867
903
  const corners = [];
868
904
  const wanted = [];
@@ -879,7 +915,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
879
915
  }
880
916
  const each = createElement.call(document, "div");
881
917
  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" : "");
882
- each.style.cssText = "left:" + rect.left + "px;top:" + rect.top + "px;width:" + rect.width + "px;height:" + rect.height + "px";
918
+ each.style.cssText = "left:" + rect.left + "px;top:" + (rect.top + ridden) + "px;width:" + rect.width + "px;height:" + rect.height + "px";
883
919
  parts.push(each);
884
920
  }
885
921
  if (mark.marker) {
@@ -965,7 +1001,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
965
1001
  }
966
1002
  const each = createElement.call(document, "div");
967
1003
  each.className = lit.range ? "held text" : "held";
968
- each.style.cssText = "left:" + rect.left + "px;top:" + rect.top + "px;width:" + rect.width + "px;height:" + rect.height + "px";
1004
+ each.style.cssText = "left:" + rect.left + "px;top:" + (rect.top + ridden) + "px;width:" + rect.width + "px;height:" + rect.height + "px";
969
1005
  outlines.push(each);
970
1006
  }
971
1007
  }
@@ -973,13 +1009,18 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
973
1009
  const rect = elementRect.call(hover);
974
1010
  const outline = createElement.call(document, "div");
975
1011
  outline.className = "hover";
976
- outline.style.cssText = "left:" + rect.left + "px;top:" + rect.top + "px;width:" + rect.width + "px;height:" + rect.height + "px";
1012
+ outline.style.cssText = "left:" + rect.left + "px;top:" + (rect.top + ridden) + "px;width:" + rect.width + "px;height:" + rect.height + "px";
977
1013
  const tag = createElement.call(document, "div");
978
1014
  tag.className = "tag";
979
1015
  tag.textContent = describe(hover).slice(0, 80);
980
- tag.style.cssText = "left:" + Math.max(4, rect.left) + "px;top:" + (rect.top >= 24 ? rect.top - 22 : Math.max(4, rect.bottom + 4)) + "px";
1016
+ 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";
981
1017
  outlines.push(outline, tag);
982
1018
  }
1019
+ // How far the ride goes, for the animation; set only when it changed.
1020
+ const range = String(ride.range);
1021
+ if (into.ride.style.getPropertyValue("--ride") !== range) {
1022
+ into.ride.style.setProperty("--ride", range);
1023
+ }
983
1024
  into.marks.replaceChildren(...parts);
984
1025
  for (const child of Array.from(into.markers.childNodes)) {
985
1026
  if (badges.indexOf(child) === -1) {
package/docs/DECISIONS.md CHANGED
@@ -3149,7 +3149,7 @@ a page's updates heard by the next page, code a viewer uploaded made runnable by
3149
3149
  keeps partitioned cookies there (then `/_blob/<id>` loads everywhere and `assets.url` is a
3150
3150
  convenience); or a host needs per-collection levels beyond a batch's.
3151
3151
 
3152
- ## P097 · 2026-10-19 · A release is a commit of main that passed all of CI; the open-source materials · Accepted
3152
+ ## P097 · 2026-10-19 · A release is a commit of main that passed all of CI; the open-source materials · Accepted; amended by P146
3153
3153
 
3154
3154
  The 2026-10-19 audit's V03 and its licenses-and-materials findings (baseline 264b12fa). Before,
3155
3155
  a pushed `v*` tag published from one job that ran `check`, the build and the Chromium bundle test,
@@ -4757,7 +4757,7 @@ the content can't steal, likely the host's own overlay), a bubble must follow du
4757
4757
  coarser report, or the host drawing markers itself from `anchored`), or MCP Apps defines
4758
4758
  annotations.
4759
4759
 
4760
- ## P096 · 2026-10-19 · The negative controls: one registry, every control run, and a run that proves nothing fails · Accepted
4760
+ ## P096 · 2026-10-19 · The negative controls: one registry, every control run, and a run that proves nothing fails · Accepted; amended by P146
4761
4761
 
4762
4762
  Amends P032 (what DESIGN.md records per control), P091's harness item (`scripts/controls.ts`) and
4763
4763
  P097's CI triggers. From the audit of 2026-10-19 (V01, V02).
@@ -9157,3 +9157,188 @@ each fail exactly their probe on all three. The old spec with its document in tw
9157
9157
  **Revisit when** the runtime pin changes (say what changed), a host needs `embed` from a reader's
9158
9158
  route (then it needs its own entry, never `access`), or a browser stops exposing
9159
9159
  `ancestorOrigins` to a framed page.
9160
+
9161
+ ## P146 · 2026-11-10 · CI's full set runs before a release, not on every push · Accepted
9162
+
9163
+ Amends P096 (its decision 4: what a push runs; its decision 6: the shards run by hand) and P097
9164
+ (its decision 1: which run the gate takes). From the owner's direction (xxchan, 2026-11-10:
9165
+ Porthole's tests cut to what is needed or made cheaper; Raft's Artifacts are the real-world check;
9166
+ the security tests are worth keeping; the heavy suites only at a release is fine) and the CI cost
9167
+ review that moved CI to GitHub's runners (#130).
9168
+
9169
+ **Context**, measured on 2026-11-03T16:00Z to 11-10T16:00Z (Blacksmith's 4-vCPU runners, each job
9170
+ rounded up to a minute):
9171
+ - 94 ci.yml runs (57 pull requests', 35 pushes to main, 2 by hand) and 14 releases: 36,789 runner
9172
+ minutes. The controls were 31,760 of them (86%), the loopback suites 3,756, prod-shape 830, the
9173
+ examples 324, the checks 119.
9174
+ - One whole run is about 420 minutes: the controls 370 (12 shards of 25 to 35), loopback 36 (the
9175
+ headless shell 11, full Chromium 2, WebKit 12, Firefox 12), prod-shape 8, the examples 3, the
9176
+ checks 1 (types, lint, format and the unit tests together are 15 seconds of it).
9177
+ - The registry has 105 controls. Each is one Playwright run of its specs with one wall out, on one
9178
+ engine: 7 seconds (`url-permissions`) to 14 minutes (`nonce`), about two hours an engine (116,
9179
+ 121 and 124 minutes). 46 of them run the whole of `annotate.spec.ts` or `leak.spec.ts` (226 of
9180
+ the 361 minutes), `nonce` 43.
9181
+ - Every pull request's push and every merge paid all of it; a release needs it once, on the commit
9182
+ it publishes.
9183
+
9184
+ **Decision.**
9185
+ 1. **ci.yml has two sets of jobs.** The quick set runs on every pull request's push, every push to
9186
+ main and by hand: `check`, `examples`, `loopback (chromium)` and `loopback (chromium-oopif)`
9187
+ (every spec on Chromium, and the nested page's cases on full Chromium, frames out of process:
9188
+ P111). The full set runs only in a run started by hand (`workflow_dispatch`): `loopback
9189
+ (webkit)`, `loopback (firefox)`, the twelve `controls (<engine>, k/4)` shards, `controls` and
9190
+ `prod-shape`. Each job of the full set carries `if: github.event_name == 'workflow_dispatch'`,
9191
+ the one condition a job of ci.yml may carry (P097 had none), and no step that runs the
9192
+ project's code is conditional. The two loopback jobs (`loopback`, and `loopback-engines` under
9193
+ the same names) have the same steps; a test holds them equal. A run started by hand skips
9194
+ nothing, so it is the whole of ci.yml, as every run was before.
9195
+ 2. **A release needs the full run on its commit, as before, and now asks for it.** release.yml's
9196
+ gate takes the newest ci.yml run on `main` for the released commit that was started by hand,
9197
+ and no other: a push's run (its full set skipped) is no run to it, as a pull request's never
9198
+ was. `REQUIRED_CI_JOBS` is unchanged, all twenty jobs by name, and each must have passed in its
9199
+ latest attempt, so a run whose full set was skipped fails on each skipped job even if it were
9200
+ taken. A release is two commands: `stamp workflow run ci.yml --repo botiverse/porthole` (main's
9201
+ head), then `stamp workflow run release.yml --repo botiverse/porthole -f version=X.Y.Z`. The
9202
+ gate waits for a full run that is still going (`CI_WAIT_MINUTES`) and, after ten minutes with
9203
+ none, says to start one. The gate's permissions stay `contents: read`, `actions: read`: it
9204
+ starts nothing itself.
9205
+ 3. **Nothing cancels a run started by hand.** ci.yml's concurrency group is
9206
+ `ci-<event>-<ref>-push` for a push (was `ci-<ref>`) and `ci-<event>-<ref>-<run id>` for a run
9207
+ started by hand: a newer push still replaces an older push's run on its ref, but neither a
9208
+ merge to main nor a second full run started for a newer commit cancels the full run a release
9209
+ is waiting for (before, a merge cancelled main's run, and the release of the earlier commit
9210
+ with it; Tenny's review of #131 for the second case).
9211
+ 4. **A change to a wall asks for the full set before it merges** (AGENTS.md): a pull request that
9212
+ touches isolation, egress, the shell, the focus guard, a probe or a control starts the full
9213
+ run on its branch (`--ref <branch>`), since its own CI shows Chromium and no control.
9214
+ 5. **No test was removed.** Looked at for this: the unit tests are seconds for all 60 files, and
9215
+ the whole loopback suite is 10 to 12 minutes an engine (652 tests), now run on Chromium per
9216
+ push and on the others per release, so removing behaviour tests would save a minute or two of
9217
+ a run that is no longer the cost. The behaviour cases share their specs with the probes
9218
+ (`annotate.spec.ts`: a hostile page's faked reports beside the markers' placing), and every
9219
+ control judges the other tests of its specs too (P096), so a case cut from one changes what 23
9220
+ controls check; none was clearly redundant enough to cut without running the suites. The
9221
+ candidates, measured on Chromium, are for a change that can run them: `check.spec.ts`'s ten
9222
+ presets over every manual example (124 of the suite's 1,240 test-seconds), and the shipped
9223
+ probes run again against the strict page, the kit's app, the example app and prod-shape (the
9224
+ same walls in each deployment's shape: security, kept).
9225
+
9226
+ **Expected**, for the same week's activity: the quick set's four jobs were 1,739 of the minutes
9227
+ above; 14 full runs are about 5,900; about 7,600 in all, a fifth of 36,789. Full runs on branches
9228
+ (decision 4) add 420 each. On GitHub's runners the minutes cost nothing; what they save there is
9229
+ the queue (a full run is 19 jobs at once, a quick one 4).
9230
+
9231
+ **Why.** The controls test the tests (PRINCIPLE 6: a wall never seen to fail proves nothing): they
9232
+ change when a wall, a probe or the registry changes, and what must never happen is a release
9233
+ whose walls were not seen to fail. That is a property of the released commit, and the gate holds
9234
+ it there, with the same twenty jobs, by name. Running it 94 times a week to publish 14 commits
9235
+ bought an earlier answer for the pull requests that touch a wall, at five times the price; those can
9236
+ ask for it (decision 4). The quick set keeps what a pull request most often breaks in front of its
9237
+ author: types, lint, the unit tests, the built package, the example app through the adopter's
9238
+ suite, and every browser spec on one engine in both its builds: about 18 runner minutes, and 12
9239
+ of waiting.
9240
+
9241
+ **Accepted limits.**
9242
+ - A regression only WebKit or Firefox shows, or only a control sees (a probe gone blind), or only
9243
+ prod-shape, is found at the release's full run, or at a branch's, not at every pull request. The
9244
+ cost is a fix and another full run; nothing unverified is published.
9245
+ - The pull request's checks list the full set's jobs as skipped (a matrix job once, under its
9246
+ name's template). Skipped is not passed: the gate reads each job's conclusion.
9247
+ - As P097: the gate is in the file it guards, and stops mistakes, not someone who can push.
9248
+
9249
+ **Rejected.**
9250
+ - *The full set on pushes to main, the quick set on pull requests*: 35 merges a week at 420
9251
+ minutes is still 14,700, for commits most of which are never published, and the release's
9252
+ answer then arrives after the merge either way.
9253
+ - *The controls on one engine per push*: a third of 86% is still most of the cost, and the
9254
+ controls' per-engine entries (`fails` per engine, `holds`, `measured`) are what the other two
9255
+ engines check.
9256
+ - *A second workflow file for the full set*: two lists of required jobs (or the quick jobs written
9257
+ twice), and a gate that reads two workflows' runs; one file with one condition keeps
9258
+ `REQUIRED_CI_JOBS` the one list.
9259
+ - *release.yml running the suites itself* (a called workflow before `build`): the release's run
9260
+ would execute the project's browser suites for an hour, a flake would fail the release rather
9261
+ than a run one can start again, and the suites could no longer be run without releasing.
9262
+ - *The gate starting the full run* (`actions: write`): more than the gate needs to read a verdict.
9263
+ - *A weekly scheduled full run*: with two releases a day it adds nothing; see Revisit.
9264
+ - *Each control run with its named probes alone* (`--grep`): the controls' cost would fall
9265
+ several times over, but P096's "and nothing else" (a control that fails more is a probe that
9266
+ depends on something else) would go unchecked. A design question of its own, not a trim.
9267
+ - *Removing behaviour tests now* (decision 5).
9268
+
9269
+ **Tested.** `test/release.test.ts`: the quick set is exactly `check`, `examples`, `loopback
9270
+ (chromium)`, `loopback (chromium-oopif)`, and the full set the other sixteen; a job's only
9271
+ condition is the one above, whole; a job that needs one of the full set is of it; the two sets
9272
+ together are `REQUIRED_CI_JOBS`, each once; the two loopback jobs' steps are equal; no step that
9273
+ runs code is conditional, none may fail; the concurrency group; the gate's script selects
9274
+ `workflow_dispatch` and names no other event. `test/release-scripts.test.ts`, against the
9275
+ simulated API: a run by hand that passed is let through, whatever the commit's push run said; a
9276
+ push's run alone is "no full ci.yml run", and the jobs are never read; a run whose full set was
9277
+ skipped names each of the sixteen and stops; the newest run by hand decides; a pull request's is
9278
+ ignored; a pending one is waited for. `test/controls.test.ts`: the shards and their summary are of
9279
+ the full set. With the gate taking pushes again, a job's condition removed, or the old concurrency
9280
+ group, five of these fail.
9281
+
9282
+ **Revisit when** releases come less than weekly (add a scheduled full run on main, and let the
9283
+ gate take it); a release's full run fails on what the quick set could have shown more than now and
9284
+ then (move that suite or engine into the quick set); GitHub's runners queue a full run for long
9285
+ (the shard count, `MEASURED`); or the controls are redesigned to run less (the rejected `--grep`).
9286
+
9287
+ ## P147 · 2026-11-11 · Marks ride the document's scroll: a scroll timeline moves them, not the scroll event · Accepted
9288
+
9289
+ Amends P104 (how a mark follows a scroll) and P132. From Raft (xxchan, 2026-11-10, a screen
9290
+ recording): scrolling a page with comments, the highlight on the commented words and the marker
9291
+ beside them trail the text and catch up a moment later.
9292
+
9293
+ **Context.** The layer is fixed and covers the viewport (P104), and every box in it is placed in
9294
+ the viewport. A scroll moved the page and not the layer; the runtime heard the scroll event, drew
9295
+ again in that frame's animation callback, and the boxes were right again. That is as early as a
9296
+ script can be, and it is late: a browser scrolls on its compositor, and puts frames on the screen
9297
+ at the new scroll offset before the main thread has run the scroll event for it. In those frames
9298
+ the words have moved and the boxes have not. No ordering of the script fixes it; only something the
9299
+ compositor moves with the scroll does.
9300
+
9301
+ **Decision.**
9302
+ 1. **One box in the layer holds everything drawn** (marks, markers, the held selection, the
9303
+ picking outline and its tag): `.ride`, a child of the layer's shadow root. The layer itself is
9304
+ unchanged: fixed, the viewport's size, clipped, its inline style reset at each draw (P104), so
9305
+ it still adds nothing to what the page can scroll and nothing of the page's sizes it.
9306
+ 2. **Each box's top is its place in the document down the page**: its top in the viewport plus how
9307
+ far the document is scrolled, both read in the one task that draws (`scrollTop` of
9308
+ `document.scrollingElement`, through getters taken before content runs, P129). `.ride` is moved
9309
+ up by the scroll by a scroll-driven animation: `animation-timeline: scroll(root y)`, one
9310
+ keyframe at `translateY(-range)`, where the range (`scrollHeight - clientHeight`, set as
9311
+ `--ride` at each draw) is what that timeline runs over. The engine runs it with the scroll, so
9312
+ in every frame a box is where its words are.
9313
+ 3. **The scroll event still draws**, as before. For a page scrolled down by its root, that draw
9314
+ now writes the places the boxes already have. It is what still moves a mark in a scroller of
9315
+ the page's own (an `overflow: auto` element), which no root timeline follows: there a mark
9316
+ catches up from the event, as it did everywhere before.
9317
+ 4. **Down the page only.** Sideways a box stays placed in the viewport and follows from the event:
9318
+ a document scrolled sideways is rare, its scroll runs the other way where the text does (a
9319
+ right-to-left page), and one axis keeps the arithmetic to one number.
9320
+ 5. **Where there is no scroll timeline** (`CSS.supports("animation-timeline: scroll()")`, asked
9321
+ once before content runs: Firefox today), and where the root does not scroll (the range is 0,
9322
+ the timeline is inactive and moves nothing), every top is the viewport's and the event draws,
9323
+ exactly as before this decision.
9324
+ 6. **A mark on something the page keeps in place** (`position: fixed`, or `sticky` while stuck)
9325
+ now does the opposite of what the others did: it rides with the document for the frames before
9326
+ the event's draw puts it back. Accepted for now: comments on a fixed header are few beside
9327
+ comments on the text, and telling them apart costs a computed style up the tree for every mark
9328
+ at every draw. **Revisit** with a second, unridden box for such marks if a host reports it.
9329
+
9330
+ **What a page can do with it.** Nothing it could not: the layer was always in the page's own
9331
+ document, where the page can cover it or move it with its ancestors (P104). The animation and its
9332
+ keyframes are in the closed shadow root's sheet; `--ride` is set on `.ride` there, where no page
9333
+ style reaches (a custom property inherits into a shadow tree from its host, and `.ride` sets its
9334
+ own). A page that changes how tall it is between two draws shifts the boxes by the difference
9335
+ times how far it is scrolled, until the next draw (a mutation, a resize or a scroll): the marks of
9336
+ its own content, drawn a little off, for a moment.
9337
+
9338
+ **Threat.** None opened. No new message, no new reading: the scroll offset was already read for
9339
+ P132's reports (through the root's box; here through `scrollTop`, the number the timeline uses).
9340
+
9341
+ **Revisit when** an engine ships scroll timelines without running them on the compositor (the ride
9342
+ would then be no better than the event, and no worse); a host needs marks in the page's own
9343
+ scrollers to ride too (a timeline per scroller, named from the mark's nearest one); or decision 6's
9344
+ case is reported.
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
@@ -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.1 (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
@@ -69,6 +69,11 @@ P144: their "byte for byte" is said as it holds (above); the host kit refuses an
69
69
  with `embed`, so a reader's issue endpoint never mints an embed session (S4); an embed page learns
70
70
  where it is embedded (S4); and a host origin's or `framedBy`'s port is 1 to 65535, without a
71
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.
72
77
 
73
78
  ## 1. Two layers
74
79
 
@@ -147,8 +152,9 @@ viewer and any declaration.
147
152
  The leak suite attempts each channel in DESIGN.md's table from inside the content, on Chromium,
148
153
  WebKit and Firefox, and most defenses have a negative control that takes the defense out to show
149
154
  its probes then fail (DESIGN.md § "Egress hardening, each with its test"). CI runs every negative
150
- control on all three engines, and a control passes only when its marked probes failed by their own
151
- 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).
152
158
 
153
159
  ## 5. Out of scope
154
160
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@botiverse/porthole",
3
- "version": "0.15.1",
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": {
@@ -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) {