@botiverse/porthole 0.14.2 → 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,9 +1,18 @@
1
1
  import type { CompiledConfig } from "../compile/compile.ts";
2
- import { servedPermissionsPolicy, serializeCsp, type CspDirective } from "../compile/policy.ts";
2
+ import {
3
+ INERT_FILE_CSP,
4
+ PAGE_SANDBOX_TOKENS,
5
+ servedPermissionsPolicy,
6
+ serializeCsp,
7
+ type CspDirective,
8
+ } from "../compile/policy.ts";
3
9
  import { frameShellDocument, frameShellScript, type FrameShellOptions } from "../shell/frame.ts";
10
+ import { onNestedLabel, PORTHOLE_LABEL_PREFIX } from "../isolation/served.ts";
4
11
  import { sha256, utf8 } from "./crypto.ts";
5
12
  import { base32 } from "./keys.ts";
6
13
 
14
+ export { isNestedLabel, PORTHOLE_LABEL_PREFIX } from "../isolation/served.ts";
15
+
7
16
  /**
8
17
  * A nested page's serving (P111): what the address the host frames answers (Porthole's shell,
9
18
  * `nestedShellResponse`), and what changes on the page and its files below the sealed prefix
@@ -16,14 +25,6 @@ import { base32 } from "./keys.ts";
16
25
  * address.
17
26
  */
18
27
 
19
- /**
20
- * The start of every label Porthole serves for itself on a content domain (P114): no host's naming
21
- * may make one (`content.name` is refused one, and `prefixedName` won't take the prefix).
22
- */
23
- export const PORTHOLE_LABEL_PREFIX = "porthole-";
24
-
25
- const NESTED_LABEL = /^porthole-[a-z2-7]{24}$/u;
26
-
27
28
  /**
28
29
  * The label a nested page's shell is served on (P114), for its scope's label: `porthole-` and 24
29
30
  * base32 characters of the label's SHA-256, one per scope, the same for every nested page of it. No
@@ -37,9 +38,6 @@ export function nestedLabelOf(label: string): string {
37
38
  return `${PORTHOLE_LABEL_PREFIX}${base32(sha256(utf8(`porthole/nested/${label}`)).subarray(0, 15))}`;
38
39
  }
39
40
 
40
- /** Whether a label is a nested page's shell's own (`nestedLabelOf`'s form). */
41
- export const isNestedLabel = (label: string): boolean => NESTED_LABEL.test(label);
42
-
43
41
  /** Where every page and file of a nested page is, on its origin: its sealed files' prefix. */
44
42
  export const NESTED_FILES_PREFIX = "/__porthole/f/";
45
43
 
@@ -77,6 +75,16 @@ export function nestedShellResponse(
77
75
  compiled: CompiledConfig,
78
76
  options: FrameShellOptions & { readonly origin: string; readonly method?: string },
79
77
  ): Response {
78
+ // On the shell's own label alone (P114), its page on that origin (P121): a content Worker of a
79
+ // host's own that would serve it beside other content is refused here, not left to its routes.
80
+ if (!onNestedLabel(options.origin)) {
81
+ throw new TypeError(
82
+ `nestedShellResponse: origin ${options.origin} isn't on a nested page's own label (${PORTHOLE_LABEL_PREFIX}<24 base32>, nestedLabelOf)`,
83
+ );
84
+ }
85
+ if (new URL(options.page).origin !== options.origin) {
86
+ throw new TypeError("nestedShellResponse: page is on the shell's own origin");
87
+ }
80
88
  const script = frameShellScript(options);
81
89
  const headers = new Headers({
82
90
  "content-type": "text/html; charset=utf-8",
@@ -104,6 +112,30 @@ export function nestedShellResponse(
104
112
  export const nestedAncestors = (origin: string, frameAncestors: string): string =>
105
113
  `${origin} ${frameAncestors}`;
106
114
 
115
+ /**
116
+ * A nested page's answer's CSP below its sealed prefix, by what it is (P111; the one source for
117
+ * `/server` and a content Worker of a host's own, P121): a page its directives and
118
+ * `sandbox allow-scripts`, so it is an opaque origin in the shell's child and on a tab of its own
119
+ * (never `allow-same-origin`, which would give it the shell's origin and realm); a script its
120
+ * directives and `sandbox` (a worker's policy is its script's; opened on its own it runs nothing on
121
+ * the shell's origin); any other file nothing at all. `directives` are the page's: the compiled
122
+ * config's, its files' prefix opened (`fileSetCspDirectives(compiled.cspDirectives, source)`) for
123
+ * a page of a file set. Then who may frame it: `frame-ancestors` (`nestedAncestors`).
124
+ */
125
+ export function nestedFileCsp(
126
+ role: "page" | "script" | "file",
127
+ directives: readonly CspDirective[],
128
+ ): string {
129
+ switch (role) {
130
+ case "page":
131
+ return serializeCsp([...directives, ["sandbox", ...PAGE_SANDBOX_TOKENS]]);
132
+ case "script":
133
+ return serializeCsp([...directives, ["sandbox"]]);
134
+ case "file":
135
+ return INERT_FILE_CSP;
136
+ }
137
+ }
138
+
107
139
  /**
108
140
  * What a nested page's files (not its pages) carry beyond a served file's (P111): its page's
109
141
  * origin is opaque, so a same-origin resource policy would refuse its own images and scripts, and
@@ -18,6 +18,7 @@ import {
18
18
  isNestedLabel,
19
19
  nestedAncestors,
20
20
  nestedLabelOf,
21
+ nestedFileCsp,
21
22
  nestedShellResponse,
22
23
  PORTHOLE_LABEL_PREFIX,
23
24
  } from "./nested.ts";
@@ -1199,11 +1200,11 @@ export function createServer(options: ServerOptions): PortholeServer {
1199
1200
  // A page that may use its artifact's assets loads them from its own origin (P089); every
1200
1201
  // served page carries its frame's sandbox, a tab of its own included (P099).
1201
1202
  const { config, cspDirectives } = served.compiled;
1203
+ const directives = served.assets
1204
+ ? assetCspDirectives(config, cspDirectives, access.origin)
1205
+ : cspDirectives;
1202
1206
  const headers = documentHeaders(
1203
- servedDocumentCsp(
1204
- config,
1205
- served.assets ? assetCspDirectives(config, cspDirectives, access.origin) : cspDirectives,
1206
- ),
1207
+ nested ? nestedFileCsp("page", directives) : servedDocumentCsp(config, directives),
1207
1208
  servedPermissionsPolicy(config),
1208
1209
  ancestors,
1209
1210
  );
@@ -1,3 +1,37 @@
1
+ /**
2
+ * Which marker a press on the shell's layer is for (P119), spliced into the runtime: the index of
3
+ * `count` boxes (`boxAt(i)`, the markers' own boxes in the viewport, the last drawn on top), or -1.
4
+ * A point on a marker's own box is that marker's (the topmost, as before). With `touch` (the last
5
+ * pointer a finger or a pen), a marker also takes the points of a 44 by 44 CSS px box centred on
6
+ * its own (its own size where it is larger): where those overlap, the marker whose own box's
7
+ * centre is nearest the point. No built-in is called (content may have patched them).
8
+ */
9
+ export const MARKER_HIT = String.raw`(count, boxAt, x, y, touch) => {
10
+ const TARGET = 44;
11
+ let best = -1;
12
+ let nearest = 0;
13
+ for (let i = count - 1; i >= 0; i -= 1) {
14
+ const rect = boxAt(i);
15
+ if (x >= rect.x && x <= rect.x + rect.width && y >= rect.y && y <= rect.y + rect.height) {
16
+ return i;
17
+ }
18
+ if (touch) {
19
+ const dx = x - (rect.x + rect.width / 2);
20
+ const dy = y - (rect.y + rect.height / 2);
21
+ const halfWidth = (rect.width > TARGET ? rect.width : TARGET) / 2;
22
+ const halfHeight = (rect.height > TARGET ? rect.height : TARGET) / 2;
23
+ if (dx >= -halfWidth && dx <= halfWidth && dy >= -halfHeight && dy <= halfHeight) {
24
+ const distance = dx * dx + dy * dy;
25
+ if (best === -1 || distance < nearest) {
26
+ best = i;
27
+ nearest = distance;
28
+ }
29
+ }
30
+ }
31
+ }
32
+ return best;
33
+ }`;
34
+
1
35
  /**
2
36
  * The shell's annotation runtime (P053), spliced into the shell's runtime (`__ANNOTATE__`) when
3
37
  * the config declares `annotate`, so it runs before any content does, with the DOM's own
@@ -376,7 +410,10 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
376
410
  // layer inherits from the page could reach it, so each of those is set here). A draft
377
411
  // (P107) is a comment not yet posted: its line is dashed (an element's outline too) and its
378
412
  // marker hollow, a light bubble with a dashed edge and the glyph's outline, no number.
379
- 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}.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{pointer-events:none}.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)}.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
+ // While the last pointer was a finger or a pen (P119), each marker takes the pointer in a
414
+ // box of at least 44 by 44 px centred on its own (an invisible ::before; 100% is its padding
415
+ // box, its border 1 px), so a tap a few px off still lands on the shell's layer.
416
+ 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}.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{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)}.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}";
380
417
  // Inline and important: the content's own style sheets can't hide, shrink or move it by
381
418
  // accident. Set again at each draw, since its scripts can rewrite it (narrowing only: the
382
419
  // content can still cover the layer, or move it with its ancestors, P104).
@@ -404,6 +441,13 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
404
441
  // marker's node across draws, so a press that spans a redraw ends on the node it began on.
405
442
  let markers = [];
406
443
  const markerNodes = new Map();
444
+ // Whether the last pointer was a finger or a pen (P119): then each marker takes the pointer
445
+ // in a 44 px box around it (the markers' box has the class "touch"). Until a pointer is
446
+ // seen, whether the device has a coarse pointer at all (a phone, a tablet, a laptop with a
447
+ // touch screen): a mouse moves before it presses, and its first move turns it off.
448
+ const coarseQuery = typeof window.matchMedia === "function" ? window.matchMedia("(any-pointer: coarse)") : null;
449
+ let touch = coarseQuery !== null && coarseQuery.matches === true;
450
+ const markerHit = ${MARKER_HIT};
407
451
  const MARKER_HEIGHT = 18;
408
452
  const SVG = "http://www.w3.org/2000/svg";
409
453
  const labelOf = (count) => (count === 0 ? "" : count > 99 ? "99+" : String(count));
@@ -714,6 +758,9 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
714
758
  if (boxes.style.textContent !== STYLE) {
715
759
  boxes.style.textContent = STYLE;
716
760
  }
761
+ if (boxes.markers.className !== (touch ? "touch" : "")) {
762
+ boxes.markers.className = touch ? "touch" : "";
763
+ }
717
764
  return boxes;
718
765
  };
719
766
  const draw = () => {
@@ -1118,14 +1165,11 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1118
1165
  const rect = callOf(elementRect, element, []);
1119
1166
  return { x: callOf(leftOf, rect, []), y: callOf(topOf, rect, []), width: callOf(widthOf, rect, []), height: callOf(heightOf, rect, []) };
1120
1167
  };
1168
+ // The marker a press at (x, y) is for: on a marker's own box, that one; after a finger or a
1169
+ // pen, also within the 44 px box around one, the nearest (P119).
1121
1170
  const markerAt = (x, y) => {
1122
- for (let i = markers.length - 1; i >= 0; i -= 1) {
1123
- const rect = markerBox(markers[i].element);
1124
- if (x >= rect.x && x <= rect.x + rect.width && y >= rect.y && y <= rect.y + rect.height) {
1125
- return markers[i];
1126
- }
1127
- }
1128
- return null;
1171
+ const at = markerHit(markers.length, (i) => markerBox(markers[i].element), x, y, touch);
1172
+ return at < 0 ? null : markers[at];
1129
1173
  };
1130
1174
  const isShown = (id) => {
1131
1175
  for (let i = 0; i < marks.length; i += 1) {
@@ -1170,6 +1214,28 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1170
1214
  const CANCELLED = { mousedown: 1, mouseup: 1, click: 1, dblclick: 1, auxclick: 1, contextmenu: 1 };
1171
1215
  // The pointer on a marker (1), or leaving the layer for the content (0).
1172
1216
  const HOVERS = { pointerover: 1, pointermove: 1, pointerout: 0, pointerleave: 0 };
1217
+ // Which pointer the person uses (P119), from each real one that goes down or moves, before
1218
+ // the marker's listener (which stops a press on the layer): a finger or a pen gives every
1219
+ // marker its 44 px box, a mouse takes it away. A mouse moves before it presses, so its press
1220
+ // is hit-tested on the markers' own boxes. Read through the platform's getter, kept now; an
1221
+ // event the page makes up (isTrusted is false) changes nothing.
1222
+ const pointerTypeOf = getterOf(typeof PointerEvent === "function" ? PointerEvent.prototype : null, "pointerType");
1223
+ const onPointer = (event) => {
1224
+ if (!event.isTrusted || pointerTypeOf === null) {
1225
+ return;
1226
+ }
1227
+ const kind = callOf(pointerTypeOf, event, []);
1228
+ const next = kind === "touch" || kind === "pen";
1229
+ if (next !== touch) {
1230
+ touch = next;
1231
+ if (boxes !== null) {
1232
+ boxes.markers.className = touch ? "touch" : "";
1233
+ }
1234
+ }
1235
+ };
1236
+ for (const type of ["pointerdown", "pointermove"]) {
1237
+ window.addEventListener(type, onPointer, true);
1238
+ }
1173
1239
  for (const type of ["pointerdown", "pointerup", "pointercancel", "mousedown", "mouseup", "click", "dblclick", "auxclick", "contextmenu", "touchstart", "touchend", "touchcancel", "pointerover", "pointerout", "pointerenter", "pointerleave", "pointermove", "mouseover", "mouseout", "mouseenter", "mouseleave", "mousemove"]) {
1174
1240
  window.addEventListener(type, onMarker, true);
1175
1241
  }
@@ -1,5 +1,5 @@
1
1
  import { PAGE_SANDBOX_TOKENS } from "../compile/policy.ts";
2
- import { hostOriginProblem } from "../isolation/served.ts";
2
+ import { hostOriginProblem, onNestedLabel } from "../isolation/served.ts";
3
3
 
4
4
  /**
5
5
  * Porthole's shell for a nested page (P111): the whole document at the address the host frames,
@@ -18,8 +18,11 @@ import { hostOriginProblem } from "../isolation/served.ts";
18
18
  * shell (activation goes up, never down), so the shell's activation turning on is a press or
19
19
  * key of the person's in this page. It is read at every animation frame, on its window's focus
20
20
  * and blur, and before each message of the page's is passed on (a call made in a click's handler
21
- * arrives after the state that says so). What it can't see: a gesture while its activation is
22
- * already on (within 5 s of the last one) turns nothing on;
21
+ * arrives after the state that says so), and at once when the host asks (`porthole/shell/look`,
22
+ * P120: the host heard focus move into the frame, and a key the person types into the page
23
+ * before the shell's next frame would turn its activation on as a press does). What it can't
24
+ * see: a gesture while its activation is already on (within 5 s of the last one) turns nothing
25
+ * on;
23
26
  * - renews the page's sealed files' address before it ends, and gives the page the new one
24
27
  * (`porthole/files-renewed`): the page's own loads aren't its origin's (an opaque origin's never
25
28
  * are), so only the shell, on that origin, may renew it (P083);
@@ -32,6 +35,12 @@ export const FRAME_SHELL_RUNTIME = String.raw`(() => {
32
35
  const plan = __PLAN__;
33
36
  const PREFIX = "porthole/shell/";
34
37
  const own = location.origin;
38
+ // A nested page's shell runs on a label of its own alone (P114, P121): on any other origin (its
39
+ // scope's, where other displays run content with allow-same-origin) it frames nothing and says
40
+ // nothing.
41
+ if (!/^porthole-[a-z2-7]{24}\./.test(location.hostname + ".")) {
42
+ return;
43
+ }
35
44
  let page = null;
36
45
  try {
37
46
  page = new URL(plan.page);
@@ -96,21 +105,22 @@ export const FRAME_SHELL_RUNTIME = String.raw`(() => {
96
105
  let focused = false;
97
106
  let lookedAt = performance.now();
98
107
  let toldAt = 0;
99
- const tell = (gap) => {
108
+ const tell = (gap, asked) => {
100
109
  toldAt = performance.now();
101
- toHost({
102
- jsonrpc: "2.0",
103
- method: PREFIX + "state",
104
- params: {
105
- supported: activation !== undefined,
106
- active,
107
- ago: active ? Math.max(0, Math.round(performance.now() - since)) : null,
108
- focused,
109
- gap: Math.max(0, Math.round(gap)),
110
- },
111
- });
110
+ const params = {
111
+ supported: activation !== undefined,
112
+ active,
113
+ ago: active ? Math.max(0, Math.round(performance.now() - since)) : null,
114
+ focused,
115
+ gap: Math.max(0, Math.round(gap)),
116
+ };
117
+ // The answer to the host's ask (P120), by its number.
118
+ if (asked !== undefined) {
119
+ params.asked = asked;
120
+ }
121
+ toHost({ jsonrpc: "2.0", method: PREFIX + "state", params });
112
122
  };
113
- const look = () => {
123
+ const look = (asked) => {
114
124
  const now = performance.now();
115
125
  const gap = now - lookedAt;
116
126
  lookedAt = now;
@@ -128,8 +138,8 @@ export const FRAME_SHELL_RUNTIME = String.raw`(() => {
128
138
  focused = inside;
129
139
  changed = true;
130
140
  }
131
- if (changed) {
132
- tell(gap);
141
+ if (changed || typeof asked === "number") {
142
+ tell(gap, typeof asked === "number" ? asked : undefined);
133
143
  } else if (now - toldAt >= 50) {
134
144
  // The heartbeat: the host knows the shell was looking, every 50 ms.
135
145
  toldAt = now;
@@ -167,6 +177,15 @@ export const FRAME_SHELL_RUNTIME = String.raw`(() => {
167
177
  return;
168
178
  }
169
179
  if (framed && source === window.parent && plan.origins.indexOf(event.origin) !== -1) {
180
+ const data = event.data;
181
+ // The host's words to the shell are never the page's to hear (P120): its ask to look now.
182
+ if (data !== null && typeof data === "object" && typeof data.method === "string" && data.method.indexOf(PREFIX) === 0) {
183
+ const n = data.params !== null && typeof data.params === "object" ? data.params.n : undefined;
184
+ if (data.method === PREFIX + "look" && typeof n === "number" && n >= 0 && Math.floor(n) === n) {
185
+ look(n);
186
+ }
187
+ return;
188
+ }
170
189
  const child = frame.contentWindow;
171
190
  if (child !== null) {
172
191
  child.postMessage(event.data, "*");
@@ -237,6 +256,12 @@ export function frameShellScript(options: FrameShellOptions): string {
237
256
  if (!page.pathname.startsWith("/__porthole/f/") || page.hash !== "") {
238
257
  throw new TypeError("frameShellScript: page is under /__porthole/f/, with no fragment");
239
258
  }
259
+ // The shell runs on a nested page's own label alone (P114), and its page is on its origin.
260
+ if (!onNestedLabel(page.origin)) {
261
+ throw new TypeError(
262
+ "frameShellScript: page is on a nested page's own label (porthole-<24 base32>, nestedLabelOf)",
263
+ );
264
+ }
240
265
  return FRAME_SHELL_RUNTIME.replace("__PLAN__", () =>
241
266
  scriptJson({
242
267
  origins: options.origins,