@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.
- package/CHANGELOG.md +11 -0
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/shell/annotate.js +50 -9
- package/docs/DECISIONS.md +187 -2
- package/docs/DESIGN.md +3 -2
- package/docs/THREAT_MODEL.md +9 -3
- package/package.json +1 -1
- package/src/shell/annotate.ts +50 -9
package/dist/shell/annotate.js
CHANGED
|
@@ -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.
|
|
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
|
-
|
|
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
|
|
578
|
-
each engine, and the
|
|
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
|
package/docs/THREAT_MODEL.md
CHANGED
|
@@ -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.
|
|
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
|
|
151
|
-
|
|
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.
|
|
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": {
|
package/src/shell/annotate.ts
CHANGED
|
@@ -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.
|
|
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
|
-
|
|
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) {
|