@botiverse/porthole 0.14.3 → 0.14.4

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.
@@ -1,4 +1,4 @@
1
- import { FRAME_STATUS_METHOD, SHELL_BEAT_METHOD, SHELL_METHOD_PREFIX, SHELL_STATE_METHOD, } from "../isolation/types.js";
1
+ import { FRAME_STATUS_METHOD, SHELL_BEAT_METHOD, SHELL_LOOK_METHOD, SHELL_METHOD_PREFIX, SHELL_STATE_METHOD, } from "../isolation/types.js";
2
2
  import { postMessageTransport } from "../transport/post-message.js";
3
3
  import { focusGuard } from "./focus-guard.js";
4
4
  /** A frame-status message (`porthole/notifications/frame-status`), by its method alone. */
@@ -28,7 +28,7 @@ function shellWords(opened, frame, guard) {
28
28
  if (params === null || typeof params !== "object") {
29
29
  return;
30
30
  }
31
- const { supported, ago, focused, gap } = params;
31
+ const { supported, ago, focused, gap, asked } = params;
32
32
  const span = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0;
33
33
  if (message.method === SHELL_BEAT_METHOD) {
34
34
  if (span(gap)) {
@@ -40,10 +40,17 @@ function shellWords(opened, frame, guard) {
40
40
  typeof supported !== "boolean" ||
41
41
  typeof focused !== "boolean" ||
42
42
  !(ago === null || span(ago)) ||
43
- !span(gap)) {
43
+ !span(gap) ||
44
+ !(asked === undefined || (Number.isSafeInteger(asked) && asked >= 0))) {
44
45
  return;
45
46
  }
46
- guard.shell(frame, { supported, ago: ago, focused, gap: gap });
47
+ guard.shell(frame, {
48
+ supported,
49
+ ago: ago,
50
+ focused,
51
+ gap: gap,
52
+ ...(asked === undefined ? {} : { asked: asked }),
53
+ });
47
54
  });
48
55
  return {
49
56
  send: (message) => opened.send(message),
@@ -113,17 +120,25 @@ export const webPlatform = {
113
120
  const guard = focusGuard(view);
114
121
  const taken = new Set();
115
122
  const nested = spec.nested === true && spec.source.kind === "url";
116
- const unguard = guard.add(frame, (take) => {
117
- for (const listener of taken) {
118
- listener(take);
119
- }
120
- }, { nested });
121
123
  // A served frame may pass through the host's own pages (a redirect entry's, P068): what they
122
124
  // say of the frame's status is heard too, and nothing else from there.
123
125
  const own = view.origin;
124
126
  const opened = postMessageTransport(() => frame.contentWindow, origin, view, origin === "null" || own === "null" || own === origin
125
127
  ? undefined
126
128
  : { origin: own, accept: isFrameStatus });
129
+ const unguard = guard.add(frame, (take) => {
130
+ for (const listener of taken) {
131
+ listener(take);
132
+ }
133
+ }, {
134
+ nested,
135
+ // A nested page's shell is asked to look as the guard hears a move into its frame (P120).
136
+ ...(nested
137
+ ? {
138
+ ask: (n) => opened.send({ jsonrpc: "2.0", method: SHELL_LOOK_METHOD, params: { n } }),
139
+ }
140
+ : {}),
141
+ });
127
142
  // A nested page's shell (P111): its own words go to the guard, by the frame's window and the
128
143
  // content origin (the transport's checks); the page's pass on. The shell drops any page
129
144
  // message in its namespace, so there none is the page's.
@@ -3,7 +3,7 @@ import { DEFAULT_ENTRY, lookupFile, requestFilePath } from "../files/paths.js";
3
3
  import { fileTypeOf } from "../files/types.js";
4
4
  import { isCodeAsset } from "../runtime/requests.js";
5
5
  import { sha256, utf8 } from "./crypto.js";
6
- import { NESTED_FILE_HEADERS } from "./nested.js";
6
+ import { NESTED_FILE_HEADERS, nestedFileCsp } from "./nested.js";
7
7
  const HEX = /^[0-9a-f]{64}$/u;
8
8
  const YEAR = 31_536_000;
9
9
  const hex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
@@ -174,12 +174,12 @@ export async function serveFile(serving) {
174
174
  // sandbox, so none opened as a document on its own (a tab, "open image in new tab") runs on that
175
175
  // origin. Pages run their scripts, opaque; anything else runs nothing (a file's is inert already,
176
176
  // a script's gets one too).
177
- const csp = role === "file"
178
- ? INERT_FILE_CSP
179
- : role === "page"
180
- ? servedDocumentCsp(serving.compiled.config, directives)
181
- : nested
182
- ? `${serializeCsp(directives)}; sandbox`
177
+ const csp = nested
178
+ ? nestedFileCsp(role, directives)
179
+ : role === "file"
180
+ ? INERT_FILE_CSP
181
+ : role === "page"
182
+ ? servedDocumentCsp(serving.compiled.config, directives)
183
183
  : serializeCsp(directives);
184
184
  const headers = new Headers({
185
185
  "content-type": type,
@@ -37,7 +37,7 @@ export { createContentHost, HEALTH_PATH, ISSUE_BODY_BYTES, type ContentHealthVie
37
37
  export { clashOf, contentDomain, ContentDomainError, hostnameOf, type ContentDomainInfo, type ContentDomainProblem, } from "./domain.ts";
38
38
  export { d1TicketSchema, d1TicketStore, memoryTicketStore, type D1Like, type D1StatementLike, } from "./tickets.ts";
39
39
  export { FRAME_STATUS_METHOD } from "../isolation/types.ts";
40
- export { isNestedLabel, NESTED_FILE_HEADERS, NESTED_FILES_PREFIX, nestedAncestors, nestedLabelOf, nestedShellCsp, nestedShellResponse, PORTHOLE_LABEL_PREFIX, } from "./nested.ts";
40
+ export { isNestedLabel, NESTED_FILE_HEADERS, NESTED_FILES_PREFIX, nestedAncestors, nestedFileCsp, nestedLabelOf, nestedShellCsp, nestedShellResponse, PORTHOLE_LABEL_PREFIX, } from "./nested.ts";
41
41
  export { isHostLabel, prefixedName, type Naming } from "./naming.ts";
42
42
  export { conformancePage } from "../conformance/page.ts";
43
43
  export type { PortholeConfig } from "../config/schema.ts";
@@ -41,7 +41,7 @@ export { FRAME_STATUS_METHOD } from "../isolation/types.js";
41
41
  // sealed prefix, all on the shell's own label (P114, `nestedLabelOf`). `/server` serves them for a
42
42
  // config with `nested`; a content Worker of its own answers the same (docs/ADOPTING.md, "Nested
43
43
  // pages").
44
- export { isNestedLabel, NESTED_FILE_HEADERS, NESTED_FILES_PREFIX, nestedAncestors, nestedLabelOf, nestedShellCsp, nestedShellResponse, PORTHOLE_LABEL_PREFIX, } from "./nested.js";
44
+ export { isNestedLabel, NESTED_FILE_HEADERS, NESTED_FILES_PREFIX, nestedAncestors, nestedFileCsp, nestedLabelOf, nestedShellCsp, nestedShellResponse, PORTHOLE_LABEL_PREFIX, } from "./nested.js";
45
45
  export { isHostLabel, prefixedName } from "./naming.js";
46
46
  // The page an app serves in conformance test mode (P071).
47
47
  export { conformancePage } from "../conformance/page.js";
@@ -1,5 +1,7 @@
1
1
  import type { CompiledConfig } from "../compile/compile.ts";
2
+ import { type CspDirective } from "../compile/policy.ts";
2
3
  import { type FrameShellOptions } from "../shell/frame.ts";
4
+ export { isNestedLabel, PORTHOLE_LABEL_PREFIX } from "../isolation/served.ts";
3
5
  /**
4
6
  * A nested page's serving (P111): what the address the host frames answers (Porthole's shell,
5
7
  * `nestedShellResponse`), and what changes on the page and its files below the sealed prefix
@@ -11,11 +13,6 @@ import { type FrameShellOptions } from "../shell/frame.ts";
11
13
  * `allow-same-origin`, which would be same-origin with the shell, its realm and the page's sealed
12
14
  * address.
13
15
  */
14
- /**
15
- * The start of every label Porthole serves for itself on a content domain (P114): no host's naming
16
- * may make one (`content.name` is refused one, and `prefixedName` won't take the prefix).
17
- */
18
- export declare const PORTHOLE_LABEL_PREFIX = "porthole-";
19
16
  /**
20
17
  * The label a nested page's shell is served on (P114), for its scope's label: `porthole-` and 24
21
18
  * base32 characters of the label's SHA-256, one per scope, the same for every nested page of it. No
@@ -26,8 +23,6 @@ export declare const PORTHOLE_LABEL_PREFIX = "porthole-";
26
23
  * serves its nested pages on it too.
27
24
  */
28
25
  export declare function nestedLabelOf(label: string): string;
29
- /** Whether a label is a nested page's shell's own (`nestedLabelOf`'s form). */
30
- export declare const isNestedLabel: (label: string) => boolean;
31
26
  /** Where every page and file of a nested page is, on its origin: its sealed files' prefix. */
32
27
  export declare const NESTED_FILES_PREFIX = "/__porthole/f/";
33
28
  /**
@@ -50,6 +45,17 @@ export declare function nestedShellResponse(compiled: CompiledConfig, options: F
50
45
  * above it, the host origins (`frame-ancestors` names every ancestor).
51
46
  */
52
47
  export declare const nestedAncestors: (origin: string, frameAncestors: string) => string;
48
+ /**
49
+ * A nested page's answer's CSP below its sealed prefix, by what it is (P111; the one source for
50
+ * `/server` and a content Worker of a host's own, P121): a page its directives and
51
+ * `sandbox allow-scripts`, so it is an opaque origin in the shell's child and on a tab of its own
52
+ * (never `allow-same-origin`, which would give it the shell's origin and realm); a script its
53
+ * directives and `sandbox` (a worker's policy is its script's; opened on its own it runs nothing on
54
+ * the shell's origin); any other file nothing at all. `directives` are the page's: the compiled
55
+ * config's, its files' prefix opened (`fileSetCspDirectives(compiled.cspDirectives, source)`) for
56
+ * a page of a file set. Then who may frame it: `frame-ancestors` (`nestedAncestors`).
57
+ */
58
+ export declare function nestedFileCsp(role: "page" | "script" | "file", directives: readonly CspDirective[]): string;
53
59
  /**
54
60
  * What a nested page's files (not its pages) carry beyond a served file's (P111): its page's
55
61
  * origin is opaque, so a same-origin resource policy would refuse its own images and scripts, and
@@ -1,7 +1,9 @@
1
- import { servedPermissionsPolicy, serializeCsp } from "../compile/policy.js";
1
+ import { INERT_FILE_CSP, PAGE_SANDBOX_TOKENS, servedPermissionsPolicy, serializeCsp, } from "../compile/policy.js";
2
2
  import { frameShellDocument, frameShellScript } from "../shell/frame.js";
3
+ import { onNestedLabel, PORTHOLE_LABEL_PREFIX } from "../isolation/served.js";
3
4
  import { sha256, utf8 } from "./crypto.js";
4
5
  import { base32 } from "./keys.js";
6
+ export { isNestedLabel, PORTHOLE_LABEL_PREFIX } from "../isolation/served.js";
5
7
  /**
6
8
  * A nested page's serving (P111): what the address the host frames answers (Porthole's shell,
7
9
  * `nestedShellResponse`), and what changes on the page and its files below the sealed prefix
@@ -13,12 +15,6 @@ import { base32 } from "./keys.js";
13
15
  * `allow-same-origin`, which would be same-origin with the shell, its realm and the page's sealed
14
16
  * address.
15
17
  */
16
- /**
17
- * The start of every label Porthole serves for itself on a content domain (P114): no host's naming
18
- * may make one (`content.name` is refused one, and `prefixedName` won't take the prefix).
19
- */
20
- export const PORTHOLE_LABEL_PREFIX = "porthole-";
21
- const NESTED_LABEL = /^porthole-[a-z2-7]{24}$/u;
22
18
  /**
23
19
  * The label a nested page's shell is served on (P114), for its scope's label: `porthole-` and 24
24
20
  * base32 characters of the label's SHA-256, one per scope, the same for every nested page of it. No
@@ -31,8 +27,6 @@ const NESTED_LABEL = /^porthole-[a-z2-7]{24}$/u;
31
27
  export function nestedLabelOf(label) {
32
28
  return `${PORTHOLE_LABEL_PREFIX}${base32(sha256(utf8(`porthole/nested/${label}`)).subarray(0, 15))}`;
33
29
  }
34
- /** Whether a label is a nested page's shell's own (`nestedLabelOf`'s form). */
35
- export const isNestedLabel = (label) => NESTED_LABEL.test(label);
36
30
  /** Where every page and file of a nested page is, on its origin: its sealed files' prefix. */
37
31
  export const NESTED_FILES_PREFIX = "/__porthole/f/";
38
32
  const base64 = (bytes) => btoa(String.fromCharCode(...bytes));
@@ -60,6 +54,14 @@ export function nestedShellCsp(script, origin, hostOrigins) {
60
54
  * stored (it carries the page's sealed address), its page at `options.page`.
61
55
  */
62
56
  export function nestedShellResponse(compiled, options) {
57
+ // On the shell's own label alone (P114), its page on that origin (P121): a content Worker of a
58
+ // host's own that would serve it beside other content is refused here, not left to its routes.
59
+ if (!onNestedLabel(options.origin)) {
60
+ throw new TypeError(`nestedShellResponse: origin ${options.origin} isn't on a nested page's own label (${PORTHOLE_LABEL_PREFIX}<24 base32>, nestedLabelOf)`);
61
+ }
62
+ if (new URL(options.page).origin !== options.origin) {
63
+ throw new TypeError("nestedShellResponse: page is on the shell's own origin");
64
+ }
63
65
  const script = frameShellScript(options);
64
66
  const headers = new Headers({
65
67
  "content-type": "text/html; charset=utf-8",
@@ -84,6 +86,26 @@ export function nestedShellResponse(compiled, options) {
84
86
  * above it, the host origins (`frame-ancestors` names every ancestor).
85
87
  */
86
88
  export const nestedAncestors = (origin, frameAncestors) => `${origin} ${frameAncestors}`;
89
+ /**
90
+ * A nested page's answer's CSP below its sealed prefix, by what it is (P111; the one source for
91
+ * `/server` and a content Worker of a host's own, P121): a page its directives and
92
+ * `sandbox allow-scripts`, so it is an opaque origin in the shell's child and on a tab of its own
93
+ * (never `allow-same-origin`, which would give it the shell's origin and realm); a script its
94
+ * directives and `sandbox` (a worker's policy is its script's; opened on its own it runs nothing on
95
+ * the shell's origin); any other file nothing at all. `directives` are the page's: the compiled
96
+ * config's, its files' prefix opened (`fileSetCspDirectives(compiled.cspDirectives, source)`) for
97
+ * a page of a file set. Then who may frame it: `frame-ancestors` (`nestedAncestors`).
98
+ */
99
+ export function nestedFileCsp(role, directives) {
100
+ switch (role) {
101
+ case "page":
102
+ return serializeCsp([...directives, ["sandbox", ...PAGE_SANDBOX_TOKENS]]);
103
+ case "script":
104
+ return serializeCsp([...directives, ["sandbox"]]);
105
+ case "file":
106
+ return INERT_FILE_CSP;
107
+ }
108
+ }
87
109
  /**
88
110
  * What a nested page's files (not its pages) carry beyond a served file's (P111): its page's
89
111
  * origin is opaque, so a same-origin resource policy would refuse its own images and scripts, and
@@ -7,7 +7,7 @@ import { isHostLabel, reservedLabels } from "./naming.js";
7
7
  import { enterPage, pageScript, SESSION_PATH, statusPage } from "./pages.js";
8
8
  import { libraryFile } from "./libraries.js";
9
9
  import { isNavigation, ownLoad, serveAsset, serveFile } from "./files.js";
10
- import { isNestedLabel, nestedAncestors, nestedLabelOf, nestedShellResponse, PORTHOLE_LABEL_PREFIX, } from "./nested.js";
10
+ import { isNestedLabel, nestedAncestors, nestedLabelOf, nestedFileCsp, nestedShellResponse, PORTHOLE_LABEL_PREFIX, } from "./nested.js";
11
11
  import { DEFAULT_ENTRY } from "../files/paths.js";
12
12
  import { isPortholeCookie, setsPortholeCookie } from "./proxy.js";
13
13
  import { assetCodeRuns, assetCspDirectives, INERT_FILE_CSP, servedDocumentCsp, servedPermissionsPolicy, } from "../compile/policy.js";
@@ -966,7 +966,10 @@ export function createServer(options) {
966
966
  // A page that may use its artifact's assets loads them from its own origin (P089); every
967
967
  // served page carries its frame's sandbox, a tab of its own included (P099).
968
968
  const { config, cspDirectives } = served.compiled;
969
- const headers = documentHeaders(servedDocumentCsp(config, served.assets ? assetCspDirectives(config, cspDirectives, access.origin) : cspDirectives), servedPermissionsPolicy(config), ancestors);
969
+ const directives = served.assets
970
+ ? assetCspDirectives(config, cspDirectives, access.origin)
971
+ : cspDirectives;
972
+ const headers = documentHeaders(nested ? nestedFileCsp("page", directives) : servedDocumentCsp(config, directives), servedPermissionsPolicy(config), ancestors);
970
973
  if (cookie !== null) {
971
974
  headers.set("set-cookie", cookie);
972
975
  }
@@ -15,8 +15,11 @@
15
15
  * shell (activation goes up, never down), so the shell's activation turning on is a press or
16
16
  * key of the person's in this page. It is read at every animation frame, on its window's focus
17
17
  * and blur, and before each message of the page's is passed on (a call made in a click's handler
18
- * arrives after the state that says so). What it can't see: a gesture while its activation is
19
- * already on (within 5 s of the last one) turns nothing on;
18
+ * arrives after the state that says so), and at once when the host asks (`porthole/shell/look`,
19
+ * P120: the host heard focus move into the frame, and a key the person types into the page
20
+ * before the shell's next frame would turn its activation on as a press does). What it can't
21
+ * see: a gesture while its activation is already on (within 5 s of the last one) turns nothing
22
+ * on;
20
23
  * - renews the page's sealed files' address before it ends, and gives the page the new one
21
24
  * (`porthole/files-renewed`): the page's own loads aren't its origin's (an opaque origin's never
22
25
  * are), so only the shell, on that origin, may renew it (P083);
@@ -1,5 +1,5 @@
1
1
  import { PAGE_SANDBOX_TOKENS } from "../compile/policy.js";
2
- import { hostOriginProblem } from "../isolation/served.js";
2
+ import { hostOriginProblem, onNestedLabel } from "../isolation/served.js";
3
3
  /**
4
4
  * Porthole's shell for a nested page (P111): the whole document at the address the host frames,
5
5
  * with no content in it. It frames the page (the same origin's sealed files' address) in a child
@@ -17,8 +17,11 @@ import { hostOriginProblem } from "../isolation/served.js";
17
17
  * shell (activation goes up, never down), so the shell's activation turning on is a press or
18
18
  * key of the person's in this page. It is read at every animation frame, on its window's focus
19
19
  * and blur, and before each message of the page's is passed on (a call made in a click's handler
20
- * arrives after the state that says so). What it can't see: a gesture while its activation is
21
- * already on (within 5 s of the last one) turns nothing on;
20
+ * arrives after the state that says so), and at once when the host asks (`porthole/shell/look`,
21
+ * P120: the host heard focus move into the frame, and a key the person types into the page
22
+ * before the shell's next frame would turn its activation on as a press does). What it can't
23
+ * see: a gesture while its activation is already on (within 5 s of the last one) turns nothing
24
+ * on;
22
25
  * - renews the page's sealed files' address before it ends, and gives the page the new one
23
26
  * (`porthole/files-renewed`): the page's own loads aren't its origin's (an opaque origin's never
24
27
  * are), so only the shell, on that origin, may renew it (P083);
@@ -31,6 +34,12 @@ export const FRAME_SHELL_RUNTIME = String.raw `(() => {
31
34
  const plan = __PLAN__;
32
35
  const PREFIX = "porthole/shell/";
33
36
  const own = location.origin;
37
+ // A nested page's shell runs on a label of its own alone (P114, P121): on any other origin (its
38
+ // scope's, where other displays run content with allow-same-origin) it frames nothing and says
39
+ // nothing.
40
+ if (!/^porthole-[a-z2-7]{24}\./.test(location.hostname + ".")) {
41
+ return;
42
+ }
34
43
  let page = null;
35
44
  try {
36
45
  page = new URL(plan.page);
@@ -95,21 +104,22 @@ export const FRAME_SHELL_RUNTIME = String.raw `(() => {
95
104
  let focused = false;
96
105
  let lookedAt = performance.now();
97
106
  let toldAt = 0;
98
- const tell = (gap) => {
107
+ const tell = (gap, asked) => {
99
108
  toldAt = performance.now();
100
- toHost({
101
- jsonrpc: "2.0",
102
- method: PREFIX + "state",
103
- params: {
104
- supported: activation !== undefined,
105
- active,
106
- ago: active ? Math.max(0, Math.round(performance.now() - since)) : null,
107
- focused,
108
- gap: Math.max(0, Math.round(gap)),
109
- },
110
- });
109
+ const params = {
110
+ supported: activation !== undefined,
111
+ active,
112
+ ago: active ? Math.max(0, Math.round(performance.now() - since)) : null,
113
+ focused,
114
+ gap: Math.max(0, Math.round(gap)),
115
+ };
116
+ // The answer to the host's ask (P120), by its number.
117
+ if (asked !== undefined) {
118
+ params.asked = asked;
119
+ }
120
+ toHost({ jsonrpc: "2.0", method: PREFIX + "state", params });
111
121
  };
112
- const look = () => {
122
+ const look = (asked) => {
113
123
  const now = performance.now();
114
124
  const gap = now - lookedAt;
115
125
  lookedAt = now;
@@ -127,8 +137,8 @@ export const FRAME_SHELL_RUNTIME = String.raw `(() => {
127
137
  focused = inside;
128
138
  changed = true;
129
139
  }
130
- if (changed) {
131
- tell(gap);
140
+ if (changed || typeof asked === "number") {
141
+ tell(gap, typeof asked === "number" ? asked : undefined);
132
142
  } else if (now - toldAt >= 50) {
133
143
  // The heartbeat: the host knows the shell was looking, every 50 ms.
134
144
  toldAt = now;
@@ -166,6 +176,15 @@ export const FRAME_SHELL_RUNTIME = String.raw `(() => {
166
176
  return;
167
177
  }
168
178
  if (framed && source === window.parent && plan.origins.indexOf(event.origin) !== -1) {
179
+ const data = event.data;
180
+ // The host's words to the shell are never the page's to hear (P120): its ask to look now.
181
+ if (data !== null && typeof data === "object" && typeof data.method === "string" && data.method.indexOf(PREFIX) === 0) {
182
+ const n = data.params !== null && typeof data.params === "object" ? data.params.n : undefined;
183
+ if (data.method === PREFIX + "look" && typeof n === "number" && n >= 0 && Math.floor(n) === n) {
184
+ look(n);
185
+ }
186
+ return;
187
+ }
169
188
  const child = frame.contentWindow;
170
189
  if (child !== null) {
171
190
  child.postMessage(event.data, "*");
@@ -222,6 +241,10 @@ export function frameShellScript(options) {
222
241
  if (!page.pathname.startsWith("/__porthole/f/") || page.hash !== "") {
223
242
  throw new TypeError("frameShellScript: page is under /__porthole/f/, with no fragment");
224
243
  }
244
+ // The shell runs on a nested page's own label alone (P114), and its page is on its origin.
245
+ if (!onNestedLabel(page.origin)) {
246
+ throw new TypeError("frameShellScript: page is on a nested page's own label (porthole-<24 base32>, nestedLabelOf)");
247
+ }
225
248
  return FRAME_SHELL_RUNTIME.replace("__PLAN__", () => scriptJson({
226
249
  origins: options.origins,
227
250
  page: page.href,
package/docs/ADOPTING.md CHANGED
@@ -267,14 +267,20 @@ display.on("annotation", (report) => {
267
267
  if (report.type === "activated") bubble.openBeside(frame, report.rect, report.id);
268
268
  if (report.type === "anchored") bubble.follow(report.results);
269
269
  });
270
- // The selection was used (a comment posted, a draft added): take it, and its highlight, away.
271
- composer.onDone(() => display.annotations.clearSelection());
270
+ // The composer closed, whatever came of it (posted, a draft added, dismissed): take the selection,
271
+ // and its highlight, away. The page sees the clear: never clear only when a draft is added.
272
+ composer.onClose(() => display.annotations.clearSelection());
272
273
  ```
273
274
 
274
- - **Clear the selection once you used it** (`annotations.clearSelection()`, P115): the page's text
275
- selection, and the highlight the browser leaves on it (gray while focus is in your composer),
276
- stay until something clears them; the person's next click in the page would, and this does it
277
- when your composer is done with it. No `unselected` follows it (you know), and nothing else
275
+ - **Clear the selection when the composer closes, every time** (`annotations.clearSelection()`,
276
+ P115): the page's text selection, and the highlight the browser leaves on it (gray while focus
277
+ is in your composer), stay until something clears them; the person's next click in the page
278
+ would, and this does it when your composer is done with it. The page sees the clear (the
279
+ message, and a `selectionchange` with no press of its own), so it learns when the person was
280
+ done with its words (P121): clear on every close, kept or dismissed, or as the composer opens
281
+ (which tells it nothing `selected` and its blur didn't), or leave it to their next click; never
282
+ only when a draft is added, which tells the page that a draft exists there, and when. Above all
283
+ for a page `mayPassOn` says to keep drafts from (below). No `unselected` follows it (you know), and nothing else
278
284
  changes: your marks and drafts, the mode (`start`) and a followed mark stay. With nothing
279
285
  selected it does nothing; it is never sent to a frame that runs later (a reload has no selection
280
286
  to clear). Like `start` and `show`, only where the config declares `annotate`. The shell is your
@@ -293,10 +299,12 @@ composer.onDone(() => display.annotations.clearSelection());
293
299
  annotating={commenting ? { elements: false, text: true } : null}
294
300
  annotations={marks} trackedAnnotation={openCard?.markId ?? null}
295
301
  onAnnotation={(report) => {
296
- if (report.type === "tracked") card.moveBeside(report.rect);
302
+ // The page moves its mark, and so the card, at will: armed again as it moves (§6, P121).
303
+ if (report.type === "tracked" && card.moveBeside(report.rect) > 4) cardGuard.placed();
297
304
  if (report.type === "selected") composer.openBeside(report.rect, report.anchor);
298
305
  }} />
299
- composer.onDone(() => frame.current?.clearSelection());
306
+ // cardGuard = guardPresses(card.element) (below); moveBeside answers how far it moved, in px.
307
+ composer.onClose(() => frame.current?.clearSelection()); // every close, kept or dismissed
300
308
  ```
301
309
 
302
310
  - **Ids say nothing, and a count only where the page may know it**: the content reads every
@@ -323,7 +331,9 @@ composer.onDone(() => display.annotations.clearSelection());
323
331
  library CDNs (whose paths only their operators read); show such a page no draft marks.
324
332
  - **The content chooses when your view opens and where** (it can post `activated` for a mark you
325
333
  show on the person's own press in the content, under their pointer, P105), so a view that a
326
- report opens or moves takes no press of any kind for 500 ms after it appears or moves (no
334
+ report opens or moves (a card that follows a `tracked` mark included, each time it moves more
335
+ than a few px: the page moves it at will, up to 60 times a second) takes no press of any kind
336
+ for 500 ms after it appears or moves (no
327
337
  `pointerdown`, `pointerup`, `click` or key: menu triggers act on a press, and menu items click
328
338
  themselves on a release), ignores a press that began before that, opens beside the frame rather
329
339
  than over `rect` where the layout allows, takes no focus, and has nothing one click away that
@@ -417,7 +427,12 @@ focusField(composer.textarea); // Firefox ignores a plain focus() while a fighti
417
427
  page's field is taken back. A nested page's shell sees it: a move into the frame is the
418
428
  person's if the shell's activation turned on within the last second and you saw no press or key
419
429
  of your own since. A second press in the page within 5 s of the last turns nothing on: after the
420
- person went back to your composer, their next move in is taken back until then, or a Tab.
430
+ person went back to your composer, their next move in is taken back until then, or a Tab. A
431
+ nested page that takes the keyboard back as the guard returns it is fought as any page is, and
432
+ stopped (P120). A move into the page within 250 ms of the person's key on your page is taken
433
+ back on every engine (no hand presses that fast after typing, P122); on full Chromium a key the
434
+ person types into the page just as it takes the keyboard, slower than that, can still pass for a
435
+ press (THREAT_MODEL §7).
421
436
 
422
437
  ## 4. Served pages: the host kit
423
438
 
@@ -611,7 +626,7 @@ and Porthole's libraries (`egress.libraries`); the config refuses them.
611
626
 
612
627
  What a content origin serves for a nested page (`/server` does all of it; a content Worker of your
613
628
  own answers the same, with the helpers `/server` exports: `nestedLabelOf`, `nestedShellResponse`,
614
- `NESTED_FILE_HEADERS`, `nestedAncestors`). `<origin>` is the shell's own,
629
+ `nestedFileCsp`, `NESTED_FILE_HEADERS`, `nestedAncestors`). `<origin>` is the shell's own,
615
630
  `https://<nestedLabelOf(label)>.<content domain>`, where `label` is the scope's label (the one its
616
631
  other displays are served on); `<token>` is the access in the path (Porthole's sealed session, or a
617
632
  signed token of your own: the shell only needs addresses under the prefix). Your frame location
@@ -620,13 +635,16 @@ for a nested page is on `<origin>`.
620
635
  **The rule** (P114): `<origin>` answers the four rows below and Porthole's status pages, nothing
621
636
  else (no other display, no clean address, no asset, no app), and the scope's label never answers a
622
637
  nested page's shell, page or files. That is what keeps the shell's realm (its word to your page,
623
- the page's sealed address) out of every other display's reach.
638
+ the page's sealed address) out of every other display's reach. Porthole holds the shell to that
639
+ label (P121): `createHost` refuses a nested page located anywhere else (a host error, `locate`, and
640
+ no frame), `nestedShellResponse` throws for another origin, and the shell runs nowhere else. That
641
+ `<origin>` answers nothing but these is yours to hold: Porthole can't see your Worker's routes.
624
642
 
625
643
  | Request | Answer |
626
644
  | --- | --- |
627
645
  | `<origin>/__porthole/d/<key>`, the framed address (a ticket's, a cookie's reload; an entered clean address on the scope's label answers a `303` here with a one-time ticket), a navigation | 200, `text/html`: Porthole's shell, `nestedShellResponse(compiled, { origin, origins: hostOrigins, page: "<origin>/__porthole/f/<token>/<entry>", renew: { url: "<origin>/__porthole/f/<token>/__porthole/renew", expires } })`. Headers: `Content-Security-Policy: default-src 'none'; script-src 'sha256-<its script>'; frame-src <origin>/__porthole/f/; connect-src <origin>/__porthole/f/; base-uri 'none'; form-action 'none'; frame-ancestors <host origins>`; `Cache-Control: no-store`; `Referrer-Policy: no-referrer`; `X-Content-Type-Options: nosniff`; the served `Permissions-Policy`. No content in it. Any other request there: 404. |
628
- | `<origin>/__porthole/f/<token>/<page>` (the shell's child, or a tab) | The page as served before (the shell's runtime and the page), its plan's `origins` the content origin alone (`[<origin>]`) and its storage `memory`. `Content-Security-Policy: <the page's directives, its files' prefix opened>; sandbox allow-scripts; frame-ancestors <origin> <host origins>` (never `allow-same-origin`). Access from `<token>` alone: no cookie is sent (the page's origin is opaque), and never decide by `Origin` (it is `null`) or `Sec-Fetch-Site` (`cross-site`). |
629
- | `<origin>/__porthole/f/<token>/<file>` (the page's loads) | As served files are, plus `Cross-Origin-Resource-Policy: cross-origin` and `Access-Control-Allow-Origin: *` (`NESTED_FILE_HEADERS`): the opaque page's images, scripts, modules, fonts and fetches are cross-origin. Every one carries a CSP sandbox, never `allow-same-origin`: a non-page file `default-src 'none'; sandbox`, a script its directives plus `sandbox`, so none opened on a tab of its own (an SVG, an XML file) runs on the shell's origin. |
646
+ | `<origin>/__porthole/f/<token>/<page>` (the shell's child, or a tab) | The page as served before (the shell's runtime and the page), its plan's `origins` the content origin alone (`[<origin>]`) and its storage `memory`. `Content-Security-Policy`: `nestedFileCsp("page", fileSetCspDirectives(compiled.cspDirectives, "<origin>/__porthole/f/"))` then `; frame-ancestors ` and `nestedAncestors("<origin>", "<host origins>")`: the page's directives, its files' prefix opened, and `sandbox allow-scripts` (never `allow-same-origin`). Access from `<token>` alone: no cookie is sent (the page's origin is opaque), and never decide by `Origin` (it is `null`) or `Sec-Fetch-Site` (`cross-site`). |
647
+ | `<origin>/__porthole/f/<token>/<file>` (the page's loads) | As served files are, plus `Cross-Origin-Resource-Policy: cross-origin` and `Access-Control-Allow-Origin: *` (`NESTED_FILE_HEADERS`): the opaque page's images, scripts, modules, fonts and fetches are cross-origin. Every one carries a CSP sandbox, never `allow-same-origin` (`nestedFileCsp(fileTypeOf(path).role, directives)`, then the `frame-ancestors` above): a non-page file `default-src 'none'; sandbox`, a script its directives plus `sandbox`, so none opened on a tab of its own (an SVG, an XML file) runs on the shell's origin. |
630
648
  | `<origin>/__porthole/f/<token>/__porthole/renew` | Only the shell's own fetch (`Sec-Fetch-Site: same-origin`, not a navigation): `{ "base": "<origin>/__porthole/f/<new token>/", "expires": <epoch ms> }`, `no-store`; anything else 403. The shell renews 5 minutes before `expires` and moves the page to the new base. |
631
649
  | A token that ended, under the prefix | Porthole's status page (`401`, reason `session`), `frame-ancestors <origin> <host origins>`: it tells the shell, which tells your page (`outcome` blocked). |
632
650
 
@@ -214,6 +214,7 @@ Host app Shell (its own origin) Page (opaque child)
214
214
  │◄── the page's messages ──────│◄── postMessage (by source) ───│
215
215
  │── the host's messages ──────►│── postMessage ───────────────►│
216
216
  │◄── porthole/shell/state ─────│ its own activation, its focus │
217
+ │── porthole/shell/look ──────►│ look now (as a move is heard) │
217
218
  ```
218
219
 
219
220
  ### URL frame
@@ -292,7 +293,10 @@ several displays on one page are in [THREAT_MODEL.md](THREAT_MODEL.md).
292
293
  transient activation, which only a press or key in the page turns on, and whether
293
294
  focus is in it), and the host, which knows the frame is nested from its config
294
295
  only, uses it to tell the person's gesture from the page's (the focus guard,
295
- `comments.open`). Everything else the page says is still the content's word.
296
+ `comments.open`). The host's own words in that namespace (its ask to look, P120)
297
+ go to the shell alone. A key and a press look the same in that word, so the host
298
+ doesn't ask it while it fights a frame for the keyboard (P120). Everything else
299
+ the page says is still the content's word.
296
300
 
297
301
  5. **Host's decision ↔ content domain.** Authentication and authorization
298
302
  *policy* are the host's; carrying the host's decision safely onto the content