@botiverse/porthole 0.15.0 → 0.15.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -39,7 +39,8 @@ export declare const includesOrigin: (origins: readonly string[], origin: string
39
39
  * ancestor of every frame the host shows, above the host's own page, and never a host origin. An
40
40
  * exact web origin, `https://host[:port]` (lowercase, no path, no wildcard), or `http://` on
41
41
  * loopback alone (`localhost`, `*.localhost`, `127.0.0.1`, `[::1]`) for development: never a
42
- * desktop scheme, `"null"`, a CSP keyword or a list. Null if it can be.
42
+ * desktop scheme, `"null"`, a CSP keyword or a list. Its port, where it names one, is 1 to 65535
43
+ * in plain decimal, and its host is as the URL parser gives it back (P145). Null if it can be.
43
44
  */
44
45
  export declare function framedByProblem(origin: unknown): string | null;
45
46
  /**
@@ -48,10 +48,37 @@ const HOST_ORIGIN = /^[a-z][a-z0-9+.-]*:\/\/([a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-
48
48
  export function isHostOrigin(origin) {
49
49
  return typeof origin === "string" && origin.length <= 300 && HOST_ORIGIN.test(origin);
50
50
  }
51
+ /**
52
+ * Whether an origin that matched `HOST_ORIGIN` is one a browser can serialize as it is written
53
+ * (P145): a port, where it names one, is 1 to 65535 in plain decimal (never `:0`, `:99999` or
54
+ * `:0443`), and an `http`/`https` host is as the URL parser gives it back (never `0x7f.0.0.1` for
55
+ * `127.0.0.1`). A default port (`:443`) is still taken: browsers drop it, and `normalOrigin`
56
+ * compares it so (P144). Such an origin matches no frame and no message, so refusing it only says
57
+ * so early.
58
+ */
59
+ function serializable(origin) {
60
+ const port = /:(\d+)$/u.exec(origin)?.[1];
61
+ if (port !== undefined && !(/^[1-9]\d{0,4}$/u.test(port) && Number(port) <= 65_535)) {
62
+ return false;
63
+ }
64
+ const scheme = origin.slice(0, origin.indexOf(":"));
65
+ if (scheme !== "http" && scheme !== "https") {
66
+ return true;
67
+ }
68
+ try {
69
+ const url = new URL(origin);
70
+ return url.hostname === origin.slice(scheme.length + 3).replace(/:\d+$/u, "");
71
+ }
72
+ catch {
73
+ return false;
74
+ }
75
+ }
51
76
  /** Why `origin` can't be a host origin, in words a host's developer can act on; null if it can. */
52
77
  export function hostOriginProblem(origin) {
53
78
  if (isHostOrigin(origin)) {
54
- return null;
79
+ return serializable(origin)
80
+ ? null
81
+ : `${JSON.stringify(origin)} is not an origin a browser serializes so (a port is 1 to 65535, no leading zero; a host as the URL parser gives it)`;
55
82
  }
56
83
  if (origin === "null") {
57
84
  return 'the host page\'s origin is opaque ("null"): serve it from a real origin (an Electron custom protocol must be registered as standard, and file: pages have none)';
@@ -87,7 +114,8 @@ const LOOPBACK_HOST = (host) => host === "localhost" || host.endsWith(".localhos
87
114
  * ancestor of every frame the host shows, above the host's own page, and never a host origin. An
88
115
  * exact web origin, `https://host[:port]` (lowercase, no path, no wildcard), or `http://` on
89
116
  * loopback alone (`localhost`, `*.localhost`, `127.0.0.1`, `[::1]`) for development: never a
90
- * desktop scheme, `"null"`, a CSP keyword or a list. Null if it can be.
117
+ * desktop scheme, `"null"`, a CSP keyword or a list. Its port, where it names one, is 1 to 65535
118
+ * in plain decimal, and its host is as the URL parser gives it back (P145). Null if it can be.
91
119
  */
92
120
  export function framedByProblem(origin) {
93
121
  const parsed = typeof origin === "string" && isHostOrigin(origin) ? parseOrigin(origin) : null;
@@ -95,6 +123,9 @@ export function framedByProblem(origin) {
95
123
  !(parsed.scheme === "https" || (parsed.scheme === "http" && LOOPBACK_HOST(parsed.host)))) {
96
124
  return `${JSON.stringify(origin)} is not an exact https origin (https://host[:port], lowercase, no path; http only on loopback)`;
97
125
  }
126
+ if (!serializable(origin)) {
127
+ return `${JSON.stringify(origin)} is not an origin a browser serializes so (a port is 1 to 65535, no leading zero; a host as the URL parser gives it)`;
128
+ }
98
129
  return null;
99
130
  }
100
131
  /**
@@ -88,10 +88,14 @@ export interface ContentHostOptions<V> {
88
88
  */
89
89
  readonly framedBy?: readonly string[];
90
90
  /**
91
- * Whether `access` may answer an embed grant (P143, `Grant.embed`): a public artifact page that
91
+ * Whether `server.issue` takes an embed grant (P143, `Grant.embed`): a public artifact page that
92
92
  * any site may frame, with no host (`ServerOptions.embeds`). Default false: an embed grant is
93
- * refused at issue. Only an embed session's answers say `frame-ancestors *`; every other answer
94
- * is as without it.
93
+ * refused at issue. Mint one from a route of your own that decides the page is public
94
+ * (`host.server.issue(instance, { anonymous: true, embed: true })`), never from `access`: `access`
95
+ * answers your readers (the issue endpoint, a clean address), and the kit refuses an `access`
96
+ * answer with `embed` (409 at the issue endpoint and a clean address's resolve; a clean address's
97
+ * tab gets its 409 page, as `enterBy` refuses it) (P145). Only an embed session's answers say
98
+ * `frame-ancestors *`; every other answer is as without it.
95
99
  */
96
100
  readonly embeds?: boolean;
97
101
  /** At least 32 random bytes (or a string of at least 32 bytes). */
@@ -128,7 +132,11 @@ export interface ContentHostOptions<V> {
128
132
  * version), check its fields, refuse the rest. The client never chooses an origin.
129
133
  */
130
134
  readonly instance: (proposal: InstanceRef, viewer: V | null, request: Request) => Awaitable<InstanceRef | null>;
131
- /** Policy 2, access at issue: may this viewer see it, and with what grant (null: 401/403). */
135
+ /**
136
+ * Policy 2, access at issue: may this viewer see it, and with what grant (null: 401/403). It
137
+ * answers readers, so never with `embed` (refused, P145): an embed grant is minted from a route
138
+ * of your own through `host.server.issue`.
139
+ */
132
140
  readonly access: (instance: InstanceRef, viewer: V | null, request: Request) => Awaitable<Grant | null>;
133
141
  /** Policy 3, on every request after (P050): may this cookie still see it. */
134
142
  readonly authorize?: (request: AuthorizeRequest) => Awaitable<AuthorizeAnswer>;
@@ -669,6 +669,11 @@ export function createContentHost(options) {
669
669
  };
670
670
  /** A location issued for what the host's access granted, with its clean address. */
671
671
  async function issuedFor(instance, grant, request, more = {}) {
672
+ // `access` answers readers, here and at a clean address: an embed grant (P143) is never
673
+ // theirs, whatever `embeds` says (P145). A host mints it from a route of its own.
674
+ if (grant.embed !== undefined) {
675
+ return refusal(409, "refused", "access never answers an embed grant: mint it from a route of your own with host.server.issue (P145)");
676
+ }
672
677
  let location;
673
678
  try {
674
679
  location = await server.issue(instance, grant, more.page === undefined ? undefined : { page: more.page });
@@ -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/ADOPTING.md CHANGED
@@ -761,13 +761,20 @@ nodeServer({ content, app: async (request) => (await routes(request)) ?? app(req
761
761
  - **`embeds`** (P143): to let any site embed a public artifact page, set `embeds: true` and, from
762
762
  one route of your own that decides the page is public (never your reader's issue endpoint),
763
763
  issue it with `{ anonymous: true, embed: true }` (no `level`, no `user`; an artifact's page that
764
- isn't nested). That session's answers say `frame-ancestors *`, and nothing else's do. It has no
764
+ isn't nested): `host.server.issue(instance, { anonymous: true, embed: true })`. Never answer
765
+ `embed` from `access`: it answers your readers, and the kit refuses it there (409 from the issue
766
+ endpoint and a clean address's resolve, its 409 page at a clean address's tab; P145). That
767
+ session's answers say `frame-ancestors *`, and nothing else's do. It has no
765
768
  host: frame it from an outer page of your own that listens to nothing (its `frame-src` the one
766
769
  label), which any site may frame; the shell asks no host and says nothing to any parent, links out
767
770
  of the page go nowhere (give the outer page your own "Open" link), and there is no door.
768
771
  `authorize.check` gets `embed: true` for it, so your check can hold an embed subject to embed
769
772
  sessions. A content Worker of your own answers its refusals before a session exists with
770
- `statusPage({ embed: true, … })` or `doorStatusResponse({ embed: true, … })`.
773
+ `statusPage({ embed: true, … })` or `doorStatusResponse({ embed: true, … })`. The page learns
774
+ where it is embedded: its request's `Referer` and `document.referrer` name your outer page, and
775
+ `location.ancestorOrigins` names every ancestor, the embedding site included (Chromium, Firefox
776
+ and WebKit), so a page with any egress can report where it is shown
777
+ ([THREAT_MODEL.md S4](THREAT_MODEL.md#s4-public-links-and-pages-that-are-apps)).
771
778
  - **No content domain** (self-hosted without one): still make the host, with `domain: null` (or
772
779
  `""`). That is the supported setup: no secret is needed, `GET /porthole/meta` answers
773
780
  `{ served: false }`, and pages show every kind opaque (a url kind, its fallback) instead of
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).
@@ -8863,7 +8863,7 @@ cases, whose second page is opened by a link.
8863
8863
  (the `same` notice then has no load to explain), single-document served artifacts need it (give
8864
8864
  their notices the version), or hosts need Safari before 26 on a tab (P099's limit stands).
8865
8865
 
8866
- ## P143 · 2026-11-10 · An embedded document: a public grant with no host, framed by any page (`embed`) · Accepted
8866
+ ## P143 · 2026-11-10 · An embedded document: a public grant with no host, framed by any page (`embed`) · Accepted; amended by P145
8867
8867
 
8868
8868
  From Raft (Tenny): public artifacts embedded on any site, as a video is. The host's own outer page
8869
8869
  (its code, no author code, and no host: it hears and tells nothing) frames the content frame, and
@@ -8975,7 +8975,7 @@ plan) fails `[embed.unheard]`; each exactly that probe on Chromium.
8975
8975
  its own entry), auto-height needs a word to the embedding site, or browsers give a policy for the
8976
8976
  parent alone.
8977
8977
 
8978
- ## P144 · 2026-11-10 · After the audit of 0.14.17 and 0.14.18: `framedBy`'s default path byte for byte, the nesting it is for, origins compared as browsers serialize them · Accepted
8978
+ ## P144 · 2026-11-10 · After the audit of 0.14.17 and 0.14.18: `framedBy`'s default path byte for byte, the nesting it is for, origins compared as browsers serialize them · Accepted; amended by P145
8979
8979
 
8980
8980
  Amends P141 (its decision 1's "byte for byte", its decision 3 and its "What it re-opens"). From
8981
8981
  Ferryman's audit of 0.14.17 (P141) and 0.14.18 (P142): no P0 and no new egress; four findings, all
@@ -9048,3 +9048,297 @@ the nested shell pass unchanged on Chromium.
9048
9048
 
9049
9049
  **Revisit when** a host needs a strict page's script at the old address, or browsers give a policy
9050
9050
  for the parent alone.
9051
+
9052
+ ## P145 · 2026-11-10 · After the audit of 0.15.0: "byte for byte" said as it holds, embeds never from `access`, what an embed page learns, origins' ports · Accepted
9053
+
9054
+ Amends P143 (its decision 3's "as before, byte for byte", and its host duties) and P144 (its
9055
+ decision 1's "every response is 0.14.16's again", and its decision 3's "P141's exact forms"). From
9056
+ Ferryman's audit of 0.15.0 (P143, P144): no P0, no escape, no new egress, and no way found for an
9057
+ embed session's `*` to reach another session; one P1 (by the rule that any default-path byte change
9058
+ is at least P1; P3 on its own) and three P3s, all fixed here.
9059
+
9060
+ **Context.**
9061
+ 1. *(P1 by rule, P3 on its own) "Byte for byte".* P144 #1 ended "without `framedBy` every response
9062
+ is 0.14.16's again, byte for byte"; 0.15.0's CHANGELOG said "the default path is 0.14.16's
9063
+ again", and P143 #3 and its CHANGELOG line "every other session's answers are as before, byte
9064
+ for byte". Every header held (every CSP, `frame-ancestors`, `script-src` hash, cookie and cache
9065
+ header) and so did the four scripts P144 pinned. The bodies of the documents that inline the
9066
+ shell runtime did not: a served shell, an artifact page, a file set's pages, the MCP Apps proxy
9067
+ and the nested page carry P142's changes (0.14.18) and P143's `hostless` branches (0.15.0). Those
9068
+ branches are inert where a plan names a host (`createServer` refuses empty `hostOrigins`), and no
9069
+ hash covers the runtime (`'unsafe-inline'`), so nothing a browser does changed; the claim did.
9070
+ P143's bound test compares with a 0.15.0 server without `embeds`, which carries the same runtime,
9071
+ so it could not see this.
9072
+ 2. *(P3) The kit's `embeds` said "whether `access` may answer an embed grant".* `access` answers
9073
+ the kit's reader issue endpoint and a clean address's resolve, which ADOPTING and THREAT_MODEL
9074
+ say must never mint `embed`, and the kit's test minted it there. A host that followed the kit's
9075
+ doc made signed-out readers' frames hostless and frameable by any site (nothing signed-in rode
9076
+ along: `checkGrant` refuses a viewer, level or user with `embed`).
9077
+ 3. *(P3) An embed page learns where it is embedded*, which P143 didn't say beside "the embedding
9078
+ site sees the page load".
9079
+ 4. *(P3) Ports.* `framedByProblem` (and `hostOriginProblem`) took `:0`, `:99999` and `:0443`, and a
9080
+ host the URL parser rewrites (`https://0x7f.0.0.1` is `https://127.0.0.1`). Each failed closed (a
9081
+ source that matches nothing, or a stricter page), but P144 said inputs are held to exact forms.
9082
+ 5. *(P3) A control's probe failed at an unmarked step.* Under `embed-origins`, `[embed.unheard]`
9083
+ once failed at "the embedded page shows" instead of its verdict (Chromium, a loaded box), so the
9084
+ runner counted it as not failing by its probe. The cause: the shell draws one document
9085
+ (`render` runs once), and the hostile outer page says a document every 100 ms. A weakened shell
9086
+ that hears that word before its own document has loaded draws the word instead of the page
9087
+ (`#taken`, no `#content`), and the step before the verdict waited 5 s for `#content`. Reproduced
9088
+ on Chromium and Firefox by delivering the document in two parts: both failed "unmarked: Error:
9089
+ the embedded page shows".
9090
+
9091
+ **Decision.**
9092
+ 1. **Said as it holds.** Without `framedBy` and an embed, every header and the status, entry and
9093
+ door pages' scripts and the nested page's shell are 0.14.16's, byte for byte; the shell runtime
9094
+ that served documents inline is 0.15.0's: P142's changes and P143's `hostless` branches, inert
9095
+ where a plan names a host. Every other session's answers are, byte for byte, what the same server
9096
+ without `embeds` answers. THREAT_MODEL's status line, S4 and 0.15.0's CHANGELOG lines say so.
9097
+ The runtime is not moved again: splicing `hostless` into embed documents alone (as P144 did for
9098
+ `strict`) would make the claim true against 0.14.18 only, not 0.14.16, for a third runtime
9099
+ variant. Instead **its bytes are pinned** (`SHELL_RUNTIME`, `ANNOTATE_RUNTIME`, `FIND_RUNTIME`,
9100
+ `USE_RUNTIME`, `LEGACY_GLOBALS_RUNTIME` by sha256): a change to them fails a test, so the next
9101
+ release says it rather than asserting it away.
9102
+ 2. **Embeds never from `access`.** The host kit refuses an `access` answer that carries `embed`,
9103
+ whatever `embeds` says: 409 `refused` from its issue endpoint and a clean address's resolve, and
9104
+ a clean address's tab gets the kit's 409 page (`enterBy` refuses it, as before). A host mints an
9105
+ embed session from a route of its own with `host.server.issue(instance, { anonymous: true,
9106
+ embed: true })`, which needs `embeds: true`. `ContentHostOptions.embeds` and `access` say so.
9107
+ 3. **What an embed page learns, said** (THREAT_MODEL S4, ADOPTING `embeds`). Measured in Chromium,
9108
+ Firefox (155) and WebKit: the content document's request carries the outer page's address as
9109
+ `Referer` (its origin, under the default referrer policy; Firefox 155 also sends it as `Origin`, Chromium
9110
+ and WebKit send no `Origin`; Ferryman's recheck of #129),
9111
+ `document.referrer` is the same, and `location.ancestorOrigins` lists the outer page and the
9112
+ embedding site. A page with any egress can send that out. Porthole's served documents send no
9113
+ `Referer` of their own (`no-referrer`), which doesn't hide what the page reads.
9114
+ 4. **A port is 1 to 65535, in plain decimal; an `http`/`https` host is as the URL parser gives
9115
+ it.** `hostOriginProblem` and `framedByProblem` refuse `:0`, `:00`, `:65536`, `:99999`, `:0443`,
9116
+ and a host like `0x7f.0.0.1`, `0177.0.0.1` or `127.1`; so `createServer`, the host kit and every
9117
+ helper that takes host origins or `framedBy` throw on them. A default port (`:443`) is still
9118
+ taken: browsers drop it and P144 compares it so; refusing it in a patch release would break a
9119
+ working config.
9120
+ 5. **The probe judges, not the step before it.** `[embed.unheard]` waits for the page to have
9121
+ loaded, its own `#content` or a word's `#taken`, and leaves which one to its verdict. Its
9122
+ documents now arrive in two parts (the shell's script, then the rest 1.5 s later), so the words
9123
+ reach the shell before its document loads every time, not only on a loaded box: the probe covers
9124
+ the early words too, and `embed-origins` fails it with the page taken over (`taken: true`,
9125
+ `content: false`), on every engine.
9126
+
9127
+ **Rejected.**
9128
+ - *Requiring `new URL(origin).origin === origin`* (the audit's suggestion): it refuses `:443` too,
9129
+ which 0.15.0 takes for host origins and `framedBy` alike (P144's tests); a patch should not break
9130
+ a working config. The rule above refuses everything else it would.
9131
+ - *The kit dropping `embed` from an `access` answer and issuing a public session*: a host that
9132
+ meant an embed would get a reader's frame without a word; a refusal says it.
9133
+ - *Running `embed.spec` on Firefox and WebKit through a workflow change*: CI's `loopback` job runs
9134
+ every spec (`testMatch: **/*.spec.ts`) on `chromium`, `chromium-oopif`, `webkit` and `firefox`,
9135
+ and `controls-shard` runs every control on `chromium`, `webkit` and `firefox`; 0.15.0's CI ran
9136
+ `embed.spec` on all three. Only P143's local run was Chromium alone.
9137
+
9138
+ **Tested.** `test/framed-by.test.ts`: the served shell runtime's five parts pinned to 0.15.0's
9139
+ sha256, three of them shown not 0.14.16's (and `use`, `legacy` the same), and on a server without
9140
+ `framedBy` or `embeds` an artifact page carries the `hostless` line with a plan naming its host
9141
+ origins; Ferryman's edges probe: thirteen origins (`:0`, `:00`, `:65536`, `:99999`, `:0443`,
9142
+ `:08443`, a host origin with `:0443`, `http://localhost:0`, `http://127.0.0.1:65536`,
9143
+ `0x7f.0.0.1`, `0177.0.0.1`, `127.1`, `203.0.113.07`) refused by `createServer`, the host kit,
9144
+ `statusPage`, `doorResponse`, `doorStatusResponse`, `nestedShellCsp` and `frameShellScript`; the
9145
+ audit's refused forms (a host origin with or without `:443`, a trailing dot, userinfo, Unicode, case,
9146
+ a path, `http:` off loopback, `ferry://App`) still refused; ports 1, 8443, 65535, a default port, an
9147
+ IPv4 address and loopback http taken; a host origin's port held the same; `embeds: "true"` throws.
9148
+ `test/origins.test.ts`: `hostOriginProblem` on the same ports and hosts, custom schemes included.
9149
+ `test/embed.test.ts`: the kit refuses `access` answering `embed` at its issue endpoint, a clean
9150
+ address's resolve (409 `refused`) and its tab (409, no redirect), with `embeds` absent, false and
9151
+ true, and issues a public grant from the same routes; `host.server.issue` mints the embed only with
9152
+ `embeds: true`. Taking the kit's check out fails the refusal test. `leak/served/embed.spec.ts`
9153
+ passes on Chromium, Firefox and WebKit, and `embed-ancestors`, `embed-handshake` and `embed-origins`
9154
+ each fail exactly their probe on all three. The old spec with its document in two parts failed
9155
+ `embed-origins` unmarked on Chromium and Firefox; this one fails it by the probe.
9156
+
9157
+ **Revisit when** the runtime pin changes (say what changed), a host needs `embed` from a reader's
9158
+ route (then it needs its own entry, never `access`), or a browser stops exposing
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.