@botiverse/porthole 0.15.0 → 0.15.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +53 -5
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/isolation/served.d.ts +2 -1
- package/dist/isolation/served.js +33 -2
- package/dist/server/host.d.ts +12 -4
- package/dist/server/host.js +5 -0
- package/dist/shell/annotate.js +50 -9
- package/docs/ADOPTING.md +9 -2
- package/docs/DECISIONS.md +298 -4
- package/docs/DESIGN.md +4 -3
- package/docs/THREAT_MODEL.md +38 -15
- package/package.json +1 -1
- package/src/isolation/served.ts +33 -2
- package/src/server/host.ts +21 -4
- package/src/shell/annotate.ts +50 -9
|
@@ -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.
|
|
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
|
/**
|
package/dist/isolation/served.js
CHANGED
|
@@ -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
|
|
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.
|
|
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
|
/**
|
package/dist/server/host.d.ts
CHANGED
|
@@ -88,10 +88,14 @@ export interface ContentHostOptions<V> {
|
|
|
88
88
|
*/
|
|
89
89
|
readonly framedBy?: readonly string[];
|
|
90
90
|
/**
|
|
91
|
-
* Whether `
|
|
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.
|
|
94
|
-
*
|
|
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
|
-
/**
|
|
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>;
|
package/dist/server/host.js
CHANGED
|
@@ -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 });
|
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/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)
|
|
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.
|