@botiverse/porthole 0.14.15 → 0.14.17
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 +50 -0
- package/dist/annotate/types.d.ts +10 -1
- package/dist/annotate/validate.d.ts +9 -2
- package/dist/annotate/validate.js +9 -2
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +11 -8
- package/dist/host/types.d.ts +13 -6
- package/dist/isolation/served.d.ts +8 -0
- package/dist/isolation/served.js +16 -0
- package/dist/react/frame.d.ts +9 -1
- package/dist/react/frame.js +23 -3
- package/dist/server/host.d.ts +14 -1
- package/dist/server/host.js +8 -3
- package/dist/server/nested.d.ts +5 -4
- package/dist/server/nested.js +8 -6
- package/dist/server/pages.d.ts +16 -2
- package/dist/server/pages.js +51 -16
- package/dist/server/server.js +26 -2
- package/dist/server/types.d.ts +8 -0
- package/dist/shell/annotate.d.ts +5 -3
- package/dist/shell/annotate.js +36 -16
- package/dist/shell/frame.d.ts +6 -0
- package/dist/shell/frame.js +16 -3
- package/dist/shell/runtime.d.ts +10 -0
- package/dist/shell/runtime.js +72 -26
- package/docs/ADOPTING.md +40 -22
- package/docs/DECISIONS.md +318 -3
- package/docs/DESIGN.md +19 -10
- package/docs/THREAT_MODEL.md +39 -7
- package/package.json +1 -1
- package/src/annotate/types.ts +10 -1
- package/src/annotate/validate.ts +15 -3
- package/src/host/create-host.ts +13 -14
- package/src/host/types.ts +13 -6
- package/src/isolation/served.ts +21 -0
- package/src/react/frame.tsx +36 -5
- package/src/server/host.ts +22 -4
- package/src/server/nested.ts +13 -5
- package/src/server/pages.ts +72 -18
- package/src/server/server.ts +32 -1
- package/src/server/types.ts +8 -0
- package/src/shell/annotate.ts +36 -16
- package/src/shell/frame.ts +22 -3
- package/src/shell/runtime.ts +73 -26
package/src/shell/annotate.ts
CHANGED
|
@@ -109,9 +109,11 @@ export const WORD_LATE = String.raw`(at, now) => {
|
|
|
109
109
|
* - the last line (P133): where a selection or a mark's words end, in the document's coordinates
|
|
110
110
|
* too (`lastLineDocumentRect`), so a host places its UI after them;
|
|
111
111
|
* - the selection followed (P138): what the last `selected` reported (the element picked, or the
|
|
112
|
-
* words selected) is kept
|
|
113
|
-
*
|
|
114
|
-
*
|
|
112
|
+
* words selected) is kept while the host follows the selection (`track` with `selection`) or said
|
|
113
|
+
* at `start` that it will (`keepSelection`, P140), and nothing is kept otherwise; while followed
|
|
114
|
+
* it is drawn in the layer and its boxes are reported as a followed mark's are
|
|
115
|
+
* (`selectionTracked`), with whether it is in view, or that it is gone; it takes no pointer, no
|
|
116
|
+
* focus and no key.
|
|
115
117
|
*
|
|
116
118
|
* It shares the realm with the content, which can interfere with all of it: the host takes its
|
|
117
119
|
* reports as UI hints only.
|
|
@@ -440,20 +442,25 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
440
442
|
// The selection last reported as selected (P138): its anchor, and what it is in the page (the
|
|
441
443
|
// element picked, or a copy of the selection's range, which the page's changes keep up to
|
|
442
444
|
// date and which stays when the page's own selection goes). Followed while the host asks
|
|
443
|
-
// (track with selection), and drawn then. Each new selected replaces it.
|
|
445
|
+
// (track with selection), and drawn then. Each new selected replaces it. Kept only while the
|
|
446
|
+
// host follows the selection, or said at its last start that it will (keepSelection, P140):
|
|
447
|
+
// for any other host nothing is kept, as before P138.
|
|
444
448
|
let held = null;
|
|
445
449
|
let followingSelection = false;
|
|
450
|
+
let keeping = false;
|
|
451
|
+
const keeps = () => followingSelection || keeping;
|
|
446
452
|
// What the host was last told of it: "attached", "orphaned", or null (nothing yet).
|
|
447
453
|
let heldTold = null;
|
|
448
454
|
const heldGone = (found) => (found.range ? found.range.collapsed || !found.range.startContainer.isConnected : !found.element.isConnected);
|
|
449
455
|
const heldShown = () => followingSelection && held !== null && heldTold !== "orphaned" && !heldGone(held.found);
|
|
450
|
-
// The element just picked (P138, Tenny's review):
|
|
451
|
-
//
|
|
452
|
-
//
|
|
453
|
-
//
|
|
454
|
-
//
|
|
455
|
-
//
|
|
456
|
-
// the pick
|
|
456
|
+
// The element just picked (P138, Tenny's review): for a host that will follow it
|
|
457
|
+
// (keepSelection, P140), it keeps its outline after selected, so there is no gap before the
|
|
458
|
+
// host follows it, and the follow's highlight takes over where it does. For any other host
|
|
459
|
+
// the outline goes with the pick, as before P138. Until the follow comes it ends as a
|
|
460
|
+
// selection does: the next pick or selection, the host's clearSelection, a mode started or
|
|
461
|
+
// stopped, clear, Escape, or the element leaving the page. Not unselected: a selection made
|
|
462
|
+
// after the pick has already ended it as it was reported, so the one unselected can clear is
|
|
463
|
+
// one from before, which the pick's own click takes away when text is selected too.
|
|
457
464
|
let picked = null;
|
|
458
465
|
const endPick = () => {
|
|
459
466
|
if (picked !== null) {
|
|
@@ -1094,6 +1101,10 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
1094
1101
|
if (followingSelection) {
|
|
1095
1102
|
picked = null;
|
|
1096
1103
|
}
|
|
1104
|
+
// Its end lets the selection go, unless the host said it follows it again (P140).
|
|
1105
|
+
if (!keeps()) {
|
|
1106
|
+
held = null;
|
|
1107
|
+
}
|
|
1097
1108
|
trackedBox = null;
|
|
1098
1109
|
trackedView = null;
|
|
1099
1110
|
heldTold = null;
|
|
@@ -1104,9 +1115,10 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
1104
1115
|
draw();
|
|
1105
1116
|
}
|
|
1106
1117
|
};
|
|
1107
|
-
// A new selected (P138): what is followed, if the selection is, from the next frame on
|
|
1118
|
+
// A new selected (P138): what is followed, if the selection is, from the next frame on; kept
|
|
1119
|
+
// only for a host that follows it or will (P140).
|
|
1108
1120
|
const holdSelected = (anchor, found) => {
|
|
1109
|
-
held = { anchor, found, tried: 0 };
|
|
1121
|
+
held = keeps() ? { anchor, found, tried: 0 } : null;
|
|
1110
1122
|
if (followingSelection) {
|
|
1111
1123
|
trackedBox = null;
|
|
1112
1124
|
heldTold = null;
|
|
@@ -1657,7 +1669,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
1657
1669
|
}
|
|
1658
1670
|
swallowUntil = performance.now() + 2000;
|
|
1659
1671
|
holdSelected(anchor, { element });
|
|
1660
|
-
picked = followingSelection ?
|
|
1672
|
+
picked = keeping && !followingSelection ? element : null;
|
|
1661
1673
|
redraw();
|
|
1662
1674
|
tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element })));
|
|
1663
1675
|
}, HOLD_MS),
|
|
@@ -1707,8 +1719,9 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
1707
1719
|
hover = null;
|
|
1708
1720
|
setCursor(false);
|
|
1709
1721
|
holdSelected(anchor, { element });
|
|
1710
|
-
// Its outline stays (P138), now without its name, until the host follows it or it ends
|
|
1711
|
-
|
|
1722
|
+
// Its outline stays (P138), now without its name, until the host follows it or it ends;
|
|
1723
|
+
// only for a host that will follow it (P140): for any other it goes with the pick.
|
|
1724
|
+
picked = keeping && !followingSelection ? element : null;
|
|
1712
1725
|
draw();
|
|
1713
1726
|
tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element })));
|
|
1714
1727
|
}, true);
|
|
@@ -1805,6 +1818,13 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
|
|
|
1805
1818
|
switch (data.method) {
|
|
1806
1819
|
case M.start:
|
|
1807
1820
|
mode = { elements: params.elements === true, text: params.text === true, hold: params.elements === "hold" };
|
|
1821
|
+
// Whether the host will follow what is selected (P140): only then is it kept before
|
|
1822
|
+
// the host follows it. A stop leaves it, so a stop sent as the composer opens doesn't
|
|
1823
|
+
// take the selection away before the follow comes.
|
|
1824
|
+
keeping = params.keepSelection === true;
|
|
1825
|
+
if (!keeps()) {
|
|
1826
|
+
held = null;
|
|
1827
|
+
}
|
|
1808
1828
|
hover = null;
|
|
1809
1829
|
picked = null;
|
|
1810
1830
|
reported = null;
|
package/src/shell/frame.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { PAGE_SANDBOX_TOKENS } from "../compile/policy.ts";
|
|
2
|
-
import { hostOriginProblem, onNestedLabel } from "../isolation/served.ts";
|
|
2
|
+
import { framedByProblem, 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,
|
|
@@ -81,7 +81,9 @@ export const FRAME_SHELL_RUNTIME = String.raw`(() => {
|
|
|
81
81
|
const web = plan.origins.filter((origin) => origin.indexOf("https://") === 0 || origin.indexOf("http://") === 0);
|
|
82
82
|
// To the host: each web host origin (only the parent's is delivered); a desktop app's own scheme
|
|
83
83
|
// is no target a browser takes, so where one is listed and the parent isn't a known web origin,
|
|
84
|
-
// "*" (frame-ancestors holds the parent to the host origins; nothing said here is secret).
|
|
84
|
+
// "*" (frame-ancestors holds the parent to the host origins; nothing said here is secret). Where
|
|
85
|
+
// it names an outer page above them too (the host's framedBy, P141: plan.strictParent), the parent
|
|
86
|
+
// may be the outer page: "*" then goes only to a parent the engine names as a host origin.
|
|
85
87
|
const toHost = (message) => {
|
|
86
88
|
if (!framed) {
|
|
87
89
|
return;
|
|
@@ -92,7 +94,11 @@ export const FRAME_SHELL_RUNTIME = String.raw`(() => {
|
|
|
92
94
|
} catch (_) {}
|
|
93
95
|
}
|
|
94
96
|
const parent = location.ancestorOrigins && location.ancestorOrigins.length > 0 ? location.ancestorOrigins[0] : null;
|
|
95
|
-
if (
|
|
97
|
+
if (
|
|
98
|
+
web.length < plan.origins.length &&
|
|
99
|
+
(parent === null || web.indexOf(parent) === -1) &&
|
|
100
|
+
(plan.strictParent !== true || (parent !== null && plan.origins.indexOf(parent) !== -1))
|
|
101
|
+
) {
|
|
96
102
|
try {
|
|
97
103
|
window.parent.postMessage(message, "*");
|
|
98
104
|
} catch (_) {}
|
|
@@ -264,6 +270,12 @@ export { SHELL_METHOD_PREFIX, SHELL_STATE_METHOD } from "../isolation/types.ts";
|
|
|
264
270
|
export interface FrameShellOptions {
|
|
265
271
|
/** The host origins: the shell takes messages from its parent only from these. */
|
|
266
272
|
readonly origins: readonly string[];
|
|
273
|
+
/**
|
|
274
|
+
* Origins of an outer page that may be an ancestor above a host origin's page (P141): in the
|
|
275
|
+
* shell's `frame-ancestors` after `origins` (`nestedShellResponse`), never heard or told. Where
|
|
276
|
+
* there are any, the shell says `*` only to a parent the engine names as a host origin.
|
|
277
|
+
*/
|
|
278
|
+
readonly framedBy?: readonly string[];
|
|
267
279
|
/** The page's address: absolute, on the shell's own origin, under `/__porthole/f/`. */
|
|
268
280
|
readonly page: string;
|
|
269
281
|
/** The page frame's accessible name. */
|
|
@@ -287,6 +299,12 @@ export function frameShellScript(options: FrameShellOptions): string {
|
|
|
287
299
|
throw new TypeError(`frameShellScript: ${problem}`);
|
|
288
300
|
}
|
|
289
301
|
}
|
|
302
|
+
for (const origin of options.framedBy ?? []) {
|
|
303
|
+
const problem = framedByProblem(origin);
|
|
304
|
+
if (problem !== null || options.origins.includes(origin)) {
|
|
305
|
+
throw new TypeError(`frameShellScript: framedBy: ${problem ?? `${origin} is a host origin`}`);
|
|
306
|
+
}
|
|
307
|
+
}
|
|
290
308
|
let page: URL;
|
|
291
309
|
try {
|
|
292
310
|
page = new URL(options.page);
|
|
@@ -305,6 +323,7 @@ export function frameShellScript(options: FrameShellOptions): string {
|
|
|
305
323
|
return FRAME_SHELL_RUNTIME.replace("__PLAN__", () =>
|
|
306
324
|
scriptJson({
|
|
307
325
|
origins: options.origins,
|
|
326
|
+
...((options.framedBy ?? []).length === 0 ? {} : { strictParent: true }),
|
|
308
327
|
page: page.href,
|
|
309
328
|
sandbox: PAGE_SANDBOX_TOKENS.join(" "),
|
|
310
329
|
...(options.title === undefined ? {} : { title: options.title }),
|
package/src/shell/runtime.ts
CHANGED
|
@@ -92,6 +92,43 @@ export const ONCE = String.raw`(passesAsIs, toText) => (value) => {
|
|
|
92
92
|
return text;
|
|
93
93
|
}`;
|
|
94
94
|
|
|
95
|
+
/**
|
|
96
|
+
* The shell's handshake with its host (P085, P139), spliced into the runtime as
|
|
97
|
+
* `HANDSHAKE(topLevel, ask, answered, none, later)`. On a tab of its own (`topLevel`: the window is
|
|
98
|
+
* its own top, so its parent is itself and no host can hear it) there is no host to ask: `none()`
|
|
99
|
+
* at once, and nothing is asked. In a frame it asks (`ask()`, a promise of the host's answer) up to
|
|
100
|
+
* 40 times, 250 ms apart (`later(run, ms)`), since the host may start listening after the shell
|
|
101
|
+
* runs; the first answer is taken (`answered(result)`), once. After the 40th try with no answer,
|
|
102
|
+
* `none()`; an answer that comes later still is taken.
|
|
103
|
+
*/
|
|
104
|
+
export const HANDSHAKE = String.raw`(topLevel, ask, answered, none, later) => {
|
|
105
|
+
if (topLevel === true) {
|
|
106
|
+
none();
|
|
107
|
+
return;
|
|
108
|
+
}
|
|
109
|
+
let initialized = false;
|
|
110
|
+
let tries = 0;
|
|
111
|
+
const initialize = () => {
|
|
112
|
+
if (initialized) {
|
|
113
|
+
return;
|
|
114
|
+
}
|
|
115
|
+
if (tries >= 40) {
|
|
116
|
+
none();
|
|
117
|
+
return;
|
|
118
|
+
}
|
|
119
|
+
tries += 1;
|
|
120
|
+
ask().then((result) => {
|
|
121
|
+
if (initialized) {
|
|
122
|
+
return;
|
|
123
|
+
}
|
|
124
|
+
initialized = true;
|
|
125
|
+
answered(result);
|
|
126
|
+
}, () => {});
|
|
127
|
+
later(initialize, 250);
|
|
128
|
+
};
|
|
129
|
+
initialize();
|
|
130
|
+
}`;
|
|
131
|
+
|
|
95
132
|
/**
|
|
96
133
|
* The shell's runtime: the code that runs first in the frame, before any content. Plain ES2020,
|
|
97
134
|
* no imports and no build step, so every engine (a browser frame now, a native web view later)
|
|
@@ -155,6 +192,9 @@ export const SHELL_RUNTIME = String.raw`(() => {
|
|
|
155
192
|
// such name goes on the shell's own script element (data-porthole-unfixed, for a test or a
|
|
156
193
|
// person to see) and, once the shell can speak, to the host as an error report.
|
|
157
194
|
const shellScript = document.currentScript;
|
|
195
|
+
// The platform's own, kept before the shell's guards wrap it: the shell marks the document's root
|
|
196
|
+
// with it (data-porthole-host, P139).
|
|
197
|
+
const setAttributeOfShell = Element.prototype.setAttribute;
|
|
158
198
|
const unfixed = [];
|
|
159
199
|
let tellUnfixed = (_name) => {};
|
|
160
200
|
const lock = (target, name, value) => {
|
|
@@ -2232,36 +2272,43 @@ export const SHELL_RUNTIME = String.raw`(() => {
|
|
|
2232
2272
|
whenLoaded(() => void render({ html: plan.document }));
|
|
2233
2273
|
}
|
|
2234
2274
|
|
|
2235
|
-
//
|
|
2236
|
-
|
|
2237
|
-
|
|
2238
|
-
|
|
2239
|
-
|
|
2240
|
-
|
|
2241
|
-
|
|
2242
|
-
|
|
2243
|
-
|
|
2244
|
-
|
|
2245
|
-
|
|
2246
|
-
|
|
2247
|
-
|
|
2248
|
-
|
|
2249
|
-
|
|
2250
|
-
|
|
2251
|
-
|
|
2252
|
-
|
|
2253
|
-
|
|
2254
|
-
|
|
2255
|
-
|
|
2256
|
-
|
|
2275
|
+
// The handshake (HANDSHAKE, P085): asked until answered, since the host may start listening
|
|
2276
|
+
// after this runs; on a tab of its own, not asked at all (P139): its parent is itself, so no host
|
|
2277
|
+
// hears it, and the runtime has nothing to offer from the start. How it ended goes on the
|
|
2278
|
+
// document's root element (data-porthole-host: "answered", or "none" where no host answered), for
|
|
2279
|
+
// a test, a person or a tool that shoots the page to see (P139): not on the shell's own script,
|
|
2280
|
+
// which a whole document's render takes out with the body it replaces, while the root stays (the
|
|
2281
|
+
// render adds the page's own attributes to it and removes none). The page's own word, never a
|
|
2282
|
+
// gate, set through the platform's setAttribute kept before the guards (setAttributeOfShell).
|
|
2283
|
+
const shellRoot = document.documentElement;
|
|
2284
|
+
const settled = (how) => {
|
|
2285
|
+
try {
|
|
2286
|
+
callOf(setAttributeOfShell, shellRoot, ["data-porthole-host", how]);
|
|
2287
|
+
} catch (_) {}
|
|
2288
|
+
};
|
|
2289
|
+
const handshake = ${HANDSHAKE};
|
|
2290
|
+
handshake(
|
|
2291
|
+
window.top === window,
|
|
2292
|
+
() =>
|
|
2293
|
+
request("ui/initialize", {
|
|
2294
|
+
protocolVersion: plan.protocolVersion,
|
|
2295
|
+
appInfo: { name: "porthole-shell", version: "1" },
|
|
2296
|
+
appCapabilities: {},
|
|
2297
|
+
}),
|
|
2298
|
+
(result) => {
|
|
2299
|
+
settled("answered");
|
|
2257
2300
|
const capabilities = result && result.hostCapabilities;
|
|
2258
2301
|
const experimental = capabilities && capabilities.experimental;
|
|
2259
2302
|
runtimeOffer(experimental && typeof experimental === "object" ? experimental["porthole/runtime"] : null);
|
|
2260
2303
|
applyTheme(result && result.hostContext);
|
|
2261
2304
|
notify("ui/notifications/initialized", {});
|
|
2262
2305
|
schedule();
|
|
2263
|
-
},
|
|
2264
|
-
|
|
2265
|
-
|
|
2266
|
-
|
|
2306
|
+
},
|
|
2307
|
+
() => {
|
|
2308
|
+
// No host answered (or none can): the runtime has nothing to offer.
|
|
2309
|
+
settled("none");
|
|
2310
|
+
runtimeOffer(null);
|
|
2311
|
+
},
|
|
2312
|
+
(run, ms) => setTimeout(run, ms),
|
|
2313
|
+
);
|
|
2267
2314
|
})();`;
|