@botiverse/porthole 0.15.1 → 0.15.3

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.
@@ -22,6 +22,15 @@ import { framedByProblem, hostOriginProblem, includesOrigin, onNestedLabel, } fr
22
22
  * before the shell's next frame would turn its activation on as a press does). What it can't
23
23
  * see: a gesture while its activation is already on (within 5 s of the last one) turns nothing
24
24
  * on;
25
+ * - hears each real press in the page from the page's runtime (P148), over a `MessagePort` it makes
26
+ * at each load of the page's frame and sends down (`porthole/shell/press-port`): the runtime
27
+ * takes it before any content runs, and no content holds it. A message on it says only that
28
+ * there was a press; the shell notes when it heard it, on its own clock, tells the host in its
29
+ * state (how long ago, and how many it has heard), and then answers on the port, so what the
30
+ * page says next arrives after the state that says so. Only the port of the frame's last load is
31
+ * heard, and what was said of a press before it is forgotten; the port before is heard again
32
+ * only if the runtime that holds it says, on it, that its document is still there (WebKit fires
33
+ * a load for a navigation within the document, P142);
25
34
  * - renews the page's sealed files' address before it ends, and gives the page the new one
26
35
  * (`porthole/files-renewed`): the page's own loads aren't its origin's (an opaque origin's never
27
36
  * are), so only the shell, on that origin, may renew it (P083);
@@ -76,6 +85,63 @@ const frameShellRuntime = (strict) => String.raw `(() => {
76
85
  frame.style.width = "100%";
77
86
  frame.style.height = "100%";
78
87
  frame.style.background = "transparent";
88
+ // The page's real presses (P148): when the last one was heard (null: none since the frame's last
89
+ // load), how many were heard in all, and the one port listened to.
90
+ let pressedAt = null;
91
+ let presses = 0;
92
+ let pressPort = null;
93
+ // The port a load set aside, until the next one: its document may still be there (below).
94
+ let asidePort = null;
95
+ const shut = (port) => {
96
+ if (port !== null) {
97
+ port.onmessage = null;
98
+ port.close();
99
+ }
100
+ };
101
+ const hear = (port) => {
102
+ port.onmessage = (event) => {
103
+ if (pressPort !== port || event.data !== 0) {
104
+ return;
105
+ }
106
+ pressedAt = performance.now();
107
+ presses += 1;
108
+ // To the host first, then the answer: what the page held back follows the state.
109
+ look(undefined, true);
110
+ port.postMessage(0);
111
+ };
112
+ };
113
+ frame.addEventListener("load", () => {
114
+ shut(asidePort);
115
+ const before = pressPort;
116
+ asidePort = before;
117
+ pressedAt = null;
118
+ const child = frame.contentWindow;
119
+ if (child === null || typeof MessageChannel !== "function") {
120
+ shut(before);
121
+ asidePort = null;
122
+ pressPort = null;
123
+ return;
124
+ }
125
+ const channel = new MessageChannel();
126
+ const port = channel.port1;
127
+ pressPort = port;
128
+ hear(port);
129
+ if (before !== null) {
130
+ // A load is a new document, whose runtime takes this port, and the one before is heard no
131
+ // more. But not every load is one: WebKit fires it for a navigation within the document
132
+ // (P142), whose runtime is still there and takes no second port. It says so (1) on the port
133
+ // it holds, which no one else can: that port is then the one again, and the new one is shut.
134
+ before.onmessage = (event) => {
135
+ if (event.data === 1 && pressPort === port && asidePort === before) {
136
+ shut(port);
137
+ asidePort = null;
138
+ pressPort = before;
139
+ hear(before);
140
+ }
141
+ };
142
+ }
143
+ child.postMessage({ jsonrpc: "2.0", method: PREFIX + "press-port" }, "*", [channel.port2]);
144
+ });
79
145
  frame.src = page.href;
80
146
  document.body.append(frame);
81
147
 
@@ -120,6 +186,9 @@ const frameShellRuntime = (strict) => String.raw `(() => {
120
186
  ago: active ? Math.max(0, Math.round(performance.now() - since)) : null,
121
187
  focused,
122
188
  gap: Math.max(0, Math.round(gap)),
189
+ // The page's last real press (P148): how long ago the shell heard it, and how many so far.
190
+ pressed: pressedAt === null ? null : Math.max(0, Math.round(performance.now() - pressedAt)),
191
+ presses,
123
192
  };
124
193
  // The answer to the host's ask (P120), by its number.
125
194
  if (asked !== undefined) {
@@ -127,7 +196,7 @@ const frameShellRuntime = (strict) => String.raw `(() => {
127
196
  }
128
197
  toHost({ jsonrpc: "2.0", method: PREFIX + "state", params });
129
198
  };
130
- const look = (asked) => {
199
+ const look = (asked, pressed) => {
131
200
  const now = performance.now();
132
201
  const gap = now - lookedAt;
133
202
  lookedAt = now;
@@ -145,7 +214,7 @@ const frameShellRuntime = (strict) => String.raw `(() => {
145
214
  focused = inside;
146
215
  changed = true;
147
216
  }
148
- if (changed || typeof asked === "number") {
217
+ if (changed || pressed === true || typeof asked === "number") {
149
218
  tell(gap, typeof asked === "number" ? asked : undefined);
150
219
  } else if (now - toldAt >= 50) {
151
220
  // The heartbeat: the host knows the shell was looking, every 50 ms.
@@ -274,7 +343,7 @@ const STRICT_CONDITION = `
274
343
  export const FRAME_SHELL_RUNTIME = frameShellRuntime(false);
275
344
  /** A strict shell's runtime (P141): its parent may be an outer page. */
276
345
  export const STRICT_FRAME_SHELL_RUNTIME = frameShellRuntime(true);
277
- export { SHELL_METHOD_PREFIX, SHELL_STATE_METHOD } from "../isolation/types.js";
346
+ export { SHELL_METHOD_PREFIX, SHELL_PRESS_PORT_METHOD, SHELL_STATE_METHOD, } from "../isolation/types.js";
278
347
  /** JSON that is safe inside a `<script>`. */
279
348
  const scriptJson = (value) => JSON.stringify(value)
280
349
  .replace(/</gu, "\\u003c")
@@ -56,5 +56,10 @@ export interface ShellPlan {
56
56
  * those iframes and removes every other frame-like element. Absent: it removes them all.
57
57
  */
58
58
  readonly nestedFrames?: "own";
59
+ /**
60
+ * A nested page's (P148): its runtime tells its shell each real press, over the port the shell
61
+ * sends it. Absent for every other plan: their runtime listens for no port and tells no press.
62
+ */
63
+ readonly press?: true;
59
64
  }
60
65
  export declare function shellPlan(config: PortholeConfig): ShellPlan | null;
@@ -46,5 +46,7 @@ export function shellPlan(config) {
46
46
  protocolVersion: MCP_APPS_PROTOCOL_VERSION,
47
47
  // Only where opted into (P128): every other plan is the same as before it.
48
48
  ...(config.nestedFrames === "own" ? { nestedFrames: "own" } : {}),
49
+ // A nested page's alone (P148): every other plan is the same as before it.
50
+ ...(config.nested === true ? { press: true } : {}),
49
51
  };
50
52
  }
@@ -926,9 +926,14 @@ export const SHELL_RUNTIME = String.raw `(() => {
926
926
  const noRewrite = function () {
927
927
  throw new Error("document.open and document.write aren't available here: build the page with DOM methods");
928
928
  };
929
+ const unfixedBeforeRewrite = unfixed.length;
929
930
  for (const name of ["open", "write", "writeln"]) {
930
931
  lock(Document.prototype, name, noRewrite);
931
932
  }
933
+ // Whether all three are fixed in place. The press port rests on it (P148): document.open() takes
934
+ // every listener off the window, the runtime's among them, and a document opened and closed
935
+ // again loads again, so content that could call it would hear a port before the runtime did.
936
+ const rewriteFixed = unfixed.length === unfixedBeforeRewrite;
932
937
 
933
938
  // Some engines act on a hint the moment its element is connected or changed (WebKit opens a
934
939
  // preconnect then, outside the CSP), before the observer's microtask. So every way to connect a
@@ -1392,6 +1397,254 @@ export const SHELL_RUNTIME = String.raw `(() => {
1392
1397
  ]);
1393
1398
  }
1394
1399
 
1400
+ // A nested page's real presses, told to its shell (P148). The shell sees a press in the page only
1401
+ // as its own activation turning on, and a press within 5 s of the last gesture turns nothing on
1402
+ // (P111): to the host that reads as a button that does nothing. So the runtime, which runs before
1403
+ // any content and hears the browser's own events first, tells the shell each one, over a
1404
+ // MessagePort the shell sends at each load of the page's frame. What keeps that the runtime's
1405
+ // word and never the content's:
1406
+ // - the port: taken here, by the first listener there is (on window, capturing), from the first
1407
+ // message that is the browser's own (isTrusted), from the parent read now, that names the
1408
+ // method and carries exactly one port. The event goes no further. Every other event of that
1409
+ // name is stopped too, so content never hears one, and one that fails a check doesn't use up
1410
+ // the one port. The port is in this closure alone: no content holds it or can post on it. No
1411
+ // second port is taken: the shell's next one (it sends one at every load of the frame, and
1412
+ // WebKit fires a load for a navigation within the document) is answered on the first, that
1413
+ // this document is still here;
1414
+ // - the press: only the browser's own events (isTrusted), read through the platform's getters
1415
+ // kept now. A mouse on its way down; a finger or a pen on its way up (one that scrolls ends in
1416
+ // pointercancel: HTML's own rule for what activates); Enter or Space, not held down, on a
1417
+ // native control that isn't editable (a link takes Enter alone), by its tag and type, never
1418
+ // its role, which is the content's word; a click on such a control (an assistive technology's
1419
+ // activation is a click alone), but not the click a form gives its submit button when Enter is
1420
+ // pressed in another of its fields, which is typing, nor any click while a key is down;
1421
+ // - what is told: nothing but that there was one. No place, no target, no time.
1422
+ // After a press is told, what the page's calls say to its host (send, below) waits for the
1423
+ // shell's word that it has the press (it tells the host before it answers), so a call made in
1424
+ // the press's own handler never arrives ahead of it; a shell that doesn't answer in 250 ms
1425
+ // holds nothing back.
1426
+ // None of it is installed unless all of it can be (a built-in missing, or document.open, write
1427
+ // or writeln not fixed in place above): the page then tells no press, and the host has the
1428
+ // shell's activation alone, as before.
1429
+ let pressHeld = null;
1430
+ const pressParent = window.parent;
1431
+ if (plan.press === true && !hostless && pressParent !== window && rewriteFixed) {
1432
+ const messageProto = typeof MessageEvent === "function" ? MessageEvent.prototype : null;
1433
+ const messageSourceOf = getterOf(messageProto, "source");
1434
+ const messageDataOf = getterOf(messageProto, "data");
1435
+ const messagePortsOf = getterOf(messageProto, "ports");
1436
+ const stopNow = Event.prototype.stopImmediatePropagation;
1437
+ const portProto = typeof MessagePort === "function" ? MessagePort.prototype : null;
1438
+ const portPost = portProto === null ? null : portProto.postMessage;
1439
+ const portStart = portProto === null ? null : portProto.start;
1440
+ const eventTargetOf = getterOf(Event.prototype, "target");
1441
+ const pointerTypeOf = getterOf(typeof PointerEvent === "function" ? PointerEvent.prototype : null, "pointerType");
1442
+ const keyProto = typeof KeyboardEvent === "function" ? KeyboardEvent.prototype : null;
1443
+ const keyOf = getterOf(keyProto, "key");
1444
+ const repeatOf = getterOf(keyProto, "repeat");
1445
+ const editableOf = getterOf(HTMLElement.prototype, "isContentEditable");
1446
+ const designModeOf = getterOf(Document.prototype, "designMode");
1447
+ const activeOf = getterOf(Document.prototype, "activeElement");
1448
+ const controlTypeOf = getterOf(HTMLInputElement.prototype, "type");
1449
+ // Each control's form through its own getter: a field tied to a form by its form attribute is
1450
+ // not inside that form's element.
1451
+ const formGetters = bare(null);
1452
+ formGetters.button = getterOf(HTMLButtonElement.prototype, "form");
1453
+ formGetters.input = getterOf(HTMLInputElement.prototype, "form");
1454
+ formGetters.select = getterOf(HTMLSelectElement.prototype, "form");
1455
+ formGetters.textarea = getterOf(HTMLTextAreaElement.prototype, "form");
1456
+ const pressLater = setTimeout;
1457
+ const pressNoLater = clearTimeout;
1458
+ const pressListen = EventTarget.prototype.addEventListener;
1459
+ const all =
1460
+ messageSourceOf !== null && messageDataOf !== null && messagePortsOf !== null &&
1461
+ typeof stopNow === "function" && typeof portPost === "function" && typeof portStart === "function" &&
1462
+ eventTargetOf !== null && pointerTypeOf !== null && keyOf !== null && repeatOf !== null &&
1463
+ editableOf !== null && designModeOf !== null && activeOf !== null && controlTypeOf !== null &&
1464
+ formGetters.button !== null && formGetters.input !== null && formGetters.select !== null && formGetters.textarea !== null &&
1465
+ localNameOf !== null && namespaceOf !== null && nodeTypeOf !== null;
1466
+ if (all) {
1467
+ let port = null;
1468
+ // How many presses the shell hasn't answered yet, and the timer that stops waiting for it.
1469
+ let unanswered = 0;
1470
+ let giveUp = 0;
1471
+ const release = () => {
1472
+ unanswered = 0;
1473
+ callOf(pressNoLater, window, [giveUp]);
1474
+ const held = pressHeld;
1475
+ pressHeld = null;
1476
+ if (held !== null) {
1477
+ for (let i = 0; i < held.length; i += 1) {
1478
+ post(held[i]);
1479
+ }
1480
+ }
1481
+ };
1482
+ const tellPress = () => {
1483
+ if (port === null) {
1484
+ return;
1485
+ }
1486
+ try {
1487
+ callOf(portPost, port, [0]);
1488
+ } catch (_) {
1489
+ return;
1490
+ }
1491
+ unanswered += 1;
1492
+ if (pressHeld === null) {
1493
+ pressHeld = [];
1494
+ }
1495
+ callOf(pressNoLater, window, [giveUp]);
1496
+ giveUp = callOf(pressLater, window, [release, 250]);
1497
+ };
1498
+ callOf(pressListen, window, [
1499
+ "message",
1500
+ (event) => {
1501
+ let named = false;
1502
+ try {
1503
+ const data = callOf(messageDataOf, event, []);
1504
+ named = data !== null && typeof data === "object" && data.method === "porthole/shell/press-port";
1505
+ } catch (_) {}
1506
+ if (!named) {
1507
+ return;
1508
+ }
1509
+ callOf(stopNow, event, []);
1510
+ if (event.isTrusted !== true) {
1511
+ return;
1512
+ }
1513
+ try {
1514
+ const ports = callOf(messagePortsOf, event, []);
1515
+ if (callOf(messageSourceOf, event, []) !== pressParent || ports === null || ports.length !== 1) {
1516
+ return;
1517
+ }
1518
+ // Only the first is ever taken. A later one is the shell's for a load that left this
1519
+ // document where it was (WebKit's, for a navigation within it, P142): told, on the
1520
+ // port held, that this document is still here, so the shell goes on hearing that one.
1521
+ if (port !== null) {
1522
+ callOf(portPost, port, [1]);
1523
+ return;
1524
+ }
1525
+ const taken = ports[0];
1526
+ // The shell's answer to a press: it has it, and has told the host.
1527
+ callOf(pressListen, taken, [
1528
+ "message",
1529
+ () => {
1530
+ unanswered -= 1;
1531
+ if (unanswered <= 0) {
1532
+ release();
1533
+ }
1534
+ },
1535
+ ]);
1536
+ callOf(portStart, taken, []);
1537
+ port = taken;
1538
+ } catch (_) {}
1539
+ },
1540
+ true,
1541
+ ]);
1542
+ // A native control a key or a click presses: "both" (Enter and Space), "enter" (a link), or
1543
+ // "" for anything else, an editable one included. By the kept getters: the tag and the type,
1544
+ // never an attribute the content writes to say what it is.
1545
+ const controlOf = (node) => {
1546
+ if (typeOf(node) !== 1 || callOf(namespaceOf, node, []) !== XHTML) {
1547
+ return "";
1548
+ }
1549
+ const name = callOf(localNameOf, node, []);
1550
+ let kind = "";
1551
+ if (name === "button" || name === "summary") {
1552
+ kind = "both";
1553
+ } else if (name === "input") {
1554
+ const type = callOf(controlTypeOf, node, []);
1555
+ kind = type === "button" || type === "submit" || type === "reset" ? "both" : "";
1556
+ } else if (name === "a") {
1557
+ kind = callOf(hasAttributeIn, node, ["href"]) === true ? "enter" : "";
1558
+ }
1559
+ return kind !== "" && callOf(editableOf, node, []) !== true ? kind : "";
1560
+ };
1561
+ const formOf = (node) => {
1562
+ if (typeOf(node) !== 1 || callOf(namespaceOf, node, []) !== XHTML) {
1563
+ return null;
1564
+ }
1565
+ const getter = formGetters[callOf(localNameOf, node, [])];
1566
+ return typeof getter === "function" ? callOf(getter, node, []) : null;
1567
+ };
1568
+ // The browser's own event: nothing a page dispatches is a press.
1569
+ const real = (event) => event.isTrusted === true;
1570
+ // Whether a key is down: from the browser's own keydown to its keyup, or the next press of
1571
+ // a pointer. No click in that time is a press. The key's own press was judged as it went
1572
+ // down, where it went down: content that moves the focus to its button inside the keydown
1573
+ // of an Enter typed in a text field gets that button a click of the browser's own, and a
1574
+ // held key's repeats give a button one each. An assistive technology's click comes with no
1575
+ // key down.
1576
+ let keyDown = false;
1577
+ const pointed = (down) => (event) => {
1578
+ if (!real(event)) {
1579
+ return;
1580
+ }
1581
+ keyDown = false;
1582
+ try {
1583
+ if ((callOf(pointerTypeOf, event, []) === "mouse") === down) {
1584
+ tellPress();
1585
+ }
1586
+ } catch (_) {}
1587
+ };
1588
+ callOf(pressListen, window, ["pointerdown", pointed(true), true]);
1589
+ callOf(pressListen, window, ["pointerup", pointed(false), true]);
1590
+ callOf(pressListen, window, [
1591
+ "keyup",
1592
+ (event) => {
1593
+ if (real(event)) {
1594
+ keyDown = false;
1595
+ }
1596
+ },
1597
+ true,
1598
+ ]);
1599
+ callOf(pressListen, window, [
1600
+ "keydown",
1601
+ (event) => {
1602
+ if (!real(event)) {
1603
+ return;
1604
+ }
1605
+ keyDown = true;
1606
+ try {
1607
+ // A key held down goes on being the key it was when it went down, wherever the focus
1608
+ // has moved since: its repeats are no press.
1609
+ const key = callOf(keyOf, event, []);
1610
+ if ((key !== "Enter" && key !== " ") || callOf(repeatOf, event, []) === true || callOf(designModeOf, document, []) === "on") {
1611
+ return;
1612
+ }
1613
+ const kind = controlOf(callOf(eventTargetOf, event, []));
1614
+ if (kind === "both" || (kind === "enter" && key === "Enter")) {
1615
+ tellPress();
1616
+ }
1617
+ } catch (_) {}
1618
+ },
1619
+ true,
1620
+ ]);
1621
+ callOf(pressListen, window, [
1622
+ "click",
1623
+ (event) => {
1624
+ if (!real(event)) {
1625
+ return;
1626
+ }
1627
+ try {
1628
+ const target = callOf(eventTargetOf, event, []);
1629
+ if (keyDown || controlOf(target) === "") {
1630
+ return;
1631
+ }
1632
+ // A form's own click on its submit button, for Enter in another of its fields.
1633
+ const active = callOf(activeOf, document, []);
1634
+ if (active !== null && active !== target) {
1635
+ const form = formOf(target);
1636
+ if (form !== null && form === formOf(active)) {
1637
+ return;
1638
+ }
1639
+ }
1640
+ tellPress();
1641
+ } catch (_) {}
1642
+ },
1643
+ true,
1644
+ ]);
1645
+ }
1646
+ }
1647
+
1395
1648
  // The clipboard is the host's to write (P051): content can neither write nor read it. A copy
1396
1649
  // the person makes (their keys, their menu) copies their selection as the browser makes it: no
1397
1650
  // copy or cut listener of the content's runs, so none can swap what goes on the clipboard.
@@ -1610,8 +1863,14 @@ export const SHELL_RUNTIME = String.raw `(() => {
1610
1863
  window.parent.postMessage(Object.assign({ jsonrpc: "2.0" }, message), "*");
1611
1864
  }
1612
1865
  };
1866
+ // After a press was told to the shell (P148), what the shell's protocol says next (a call, an
1867
+ // answer) waits for the shell to have the press: posted by the release above, through post.
1613
1868
  const send = (message) => {
1614
1869
  if (plan.protocol === "shell") {
1870
+ if (pressHeld !== null) {
1871
+ pressHeld[pressHeld.length] = message;
1872
+ return;
1873
+ }
1615
1874
  post(message);
1616
1875
  }
1617
1876
  };
package/docs/ADOPTING.md CHANGED
@@ -683,8 +683,11 @@ focusField(composer.textarea); // Firefox ignores a plain focus() while a fighti
683
683
  frame there is out of process: your page sees no press in it, so a person's click into the
684
684
  page's field is taken back. A nested page's shell sees it: a move into the frame is the
685
685
  person's if the shell's activation turned on within the last second and you saw no press or key
686
- of your own since. A second press in the page within 5 s of the last turns nothing on: after the
687
- person went back to your composer, their next move in is taken back until then, or a Tab. A
686
+ of your own since. A second press in the page within 5 s of the last turns nothing on; from
687
+ 0.15.3 the page's runtime tells its shell each real press (P148), so the person's next press in
688
+ the page counts as the first did, after they went back to your composer too. Nothing for you to
689
+ do but run 0.15.3 on both sides (your page, and whatever serves the content origins): an older
690
+ side ignores what the newer says, and the 5 s stay until both are new. A
688
691
  nested page that takes the keyboard back as the guard returns it is fought as any page is, and
689
692
  stopped (P120). A move into the page within 250 ms of the person's key on your page is taken
690
693
  back on every engine (no hand presses that fast after typing, P122); on full Chromium a key the