@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/dist/shell/annotate.js
CHANGED
|
@@ -105,9 +105,11 @@ export const WORD_LATE = String.raw `(at, now) => {
|
|
|
105
105
|
* - the last line (P133): where a selection or a mark's words end, in the document's coordinates
|
|
106
106
|
* too (`lastLineDocumentRect`), so a host places its UI after them;
|
|
107
107
|
* - the selection followed (P138): what the last `selected` reported (the element picked, or the
|
|
108
|
-
* words selected) is kept
|
|
109
|
-
*
|
|
110
|
-
*
|
|
108
|
+
* words selected) is kept while the host follows the selection (`track` with `selection`) or said
|
|
109
|
+
* at `start` that it will (`keepSelection`, P140), and nothing is kept otherwise; while followed
|
|
110
|
+
* it is drawn in the layer and its boxes are reported as a followed mark's are
|
|
111
|
+
* (`selectionTracked`), with whether it is in view, or that it is gone; it takes no pointer, no
|
|
112
|
+
* focus and no key.
|
|
111
113
|
*
|
|
112
114
|
* It shares the realm with the content, which can interfere with all of it: the host takes its
|
|
113
115
|
* reports as UI hints only.
|
|
@@ -436,20 +438,25 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
436
438
|
// The selection last reported as selected (P138): its anchor, and what it is in the page (the
|
|
437
439
|
// element picked, or a copy of the selection's range, which the page's changes keep up to
|
|
438
440
|
// date and which stays when the page's own selection goes). Followed while the host asks
|
|
439
|
-
// (track with selection), and drawn then. Each new selected replaces it.
|
|
441
|
+
// (track with selection), and drawn then. Each new selected replaces it. Kept only while the
|
|
442
|
+
// host follows the selection, or said at its last start that it will (keepSelection, P140):
|
|
443
|
+
// for any other host nothing is kept, as before P138.
|
|
440
444
|
let held = null;
|
|
441
445
|
let followingSelection = false;
|
|
446
|
+
let keeping = false;
|
|
447
|
+
const keeps = () => followingSelection || keeping;
|
|
442
448
|
// What the host was last told of it: "attached", "orphaned", or null (nothing yet).
|
|
443
449
|
let heldTold = null;
|
|
444
450
|
const heldGone = (found) => (found.range ? found.range.collapsed || !found.range.startContainer.isConnected : !found.element.isConnected);
|
|
445
451
|
const heldShown = () => followingSelection && held !== null && heldTold !== "orphaned" && !heldGone(held.found);
|
|
446
|
-
// The element just picked (P138, Tenny's review):
|
|
447
|
-
//
|
|
448
|
-
//
|
|
449
|
-
//
|
|
450
|
-
//
|
|
451
|
-
//
|
|
452
|
-
// the pick
|
|
452
|
+
// The element just picked (P138, Tenny's review): for a host that will follow it
|
|
453
|
+
// (keepSelection, P140), it keeps its outline after selected, so there is no gap before the
|
|
454
|
+
// host follows it, and the follow's highlight takes over where it does. For any other host
|
|
455
|
+
// the outline goes with the pick, as before P138. Until the follow comes it ends as a
|
|
456
|
+
// selection does: the next pick or selection, the host's clearSelection, a mode started or
|
|
457
|
+
// stopped, clear, Escape, or the element leaving the page. Not unselected: a selection made
|
|
458
|
+
// after the pick has already ended it as it was reported, so the one unselected can clear is
|
|
459
|
+
// one from before, which the pick's own click takes away when text is selected too.
|
|
453
460
|
let picked = null;
|
|
454
461
|
const endPick = () => {
|
|
455
462
|
if (picked !== null) {
|
|
@@ -1090,6 +1097,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1090
1097
|
if (followingSelection) {
|
|
1091
1098
|
picked = null;
|
|
1092
1099
|
}
|
|
1100
|
+
// Its end lets the selection go, unless the host said it follows it again (P140).
|
|
1101
|
+
if (!keeps()) {
|
|
1102
|
+
held = null;
|
|
1103
|
+
}
|
|
1093
1104
|
trackedBox = null;
|
|
1094
1105
|
trackedView = null;
|
|
1095
1106
|
heldTold = null;
|
|
@@ -1100,9 +1111,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1100
1111
|
draw();
|
|
1101
1112
|
}
|
|
1102
1113
|
};
|
|
1103
|
-
// A new selected (P138): what is followed, if the selection is, from the next frame on
|
|
1114
|
+
// A new selected (P138): what is followed, if the selection is, from the next frame on; kept
|
|
1115
|
+
// only for a host that follows it or will (P140).
|
|
1104
1116
|
const holdSelected = (anchor, found) => {
|
|
1105
|
-
held = { anchor, found, tried: 0 };
|
|
1117
|
+
held = keeps() ? { anchor, found, tried: 0 } : null;
|
|
1106
1118
|
if (followingSelection) {
|
|
1107
1119
|
trackedBox = null;
|
|
1108
1120
|
heldTold = null;
|
|
@@ -1653,7 +1665,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1653
1665
|
}
|
|
1654
1666
|
swallowUntil = performance.now() + 2000;
|
|
1655
1667
|
holdSelected(anchor, { element });
|
|
1656
|
-
picked = followingSelection ?
|
|
1668
|
+
picked = keeping && !followingSelection ? element : null;
|
|
1657
1669
|
redraw();
|
|
1658
1670
|
tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element })));
|
|
1659
1671
|
}, HOLD_MS),
|
|
@@ -1703,8 +1715,9 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1703
1715
|
hover = null;
|
|
1704
1716
|
setCursor(false);
|
|
1705
1717
|
holdSelected(anchor, { element });
|
|
1706
|
-
// Its outline stays (P138), now without its name, until the host follows it or it ends
|
|
1707
|
-
|
|
1718
|
+
// Its outline stays (P138), now without its name, until the host follows it or it ends;
|
|
1719
|
+
// only for a host that will follow it (P140): for any other it goes with the pick.
|
|
1720
|
+
picked = keeping && !followingSelection ? element : null;
|
|
1708
1721
|
draw();
|
|
1709
1722
|
tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element })));
|
|
1710
1723
|
}, true);
|
|
@@ -1801,6 +1814,13 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1801
1814
|
switch (data.method) {
|
|
1802
1815
|
case M.start:
|
|
1803
1816
|
mode = { elements: params.elements === true, text: params.text === true, hold: params.elements === "hold" };
|
|
1817
|
+
// Whether the host will follow what is selected (P140): only then is it kept before
|
|
1818
|
+
// the host follows it. A stop leaves it, so a stop sent as the composer opens doesn't
|
|
1819
|
+
// take the selection away before the follow comes.
|
|
1820
|
+
keeping = params.keepSelection === true;
|
|
1821
|
+
if (!keeps()) {
|
|
1822
|
+
held = null;
|
|
1823
|
+
}
|
|
1804
1824
|
hover = null;
|
|
1805
1825
|
picked = null;
|
|
1806
1826
|
reported = null;
|
package/dist/shell/frame.d.ts
CHANGED
|
@@ -37,6 +37,12 @@ export { SHELL_METHOD_PREFIX, SHELL_STATE_METHOD } from "../isolation/types.ts";
|
|
|
37
37
|
export interface FrameShellOptions {
|
|
38
38
|
/** The host origins: the shell takes messages from its parent only from these. */
|
|
39
39
|
readonly origins: readonly string[];
|
|
40
|
+
/**
|
|
41
|
+
* Origins of an outer page that may be an ancestor above a host origin's page (P141): in the
|
|
42
|
+
* shell's `frame-ancestors` after `origins` (`nestedShellResponse`), never heard or told. Where
|
|
43
|
+
* there are any, the shell says `*` only to a parent the engine names as a host origin.
|
|
44
|
+
*/
|
|
45
|
+
readonly framedBy?: readonly string[];
|
|
40
46
|
/** The page's address: absolute, on the shell's own origin, under `/__porthole/f/`. */
|
|
41
47
|
readonly page: string;
|
|
42
48
|
/** The page frame's accessible name. */
|
package/dist/shell/frame.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { PAGE_SANDBOX_TOKENS } from "../compile/policy.js";
|
|
2
|
-
import { hostOriginProblem, onNestedLabel } from "../isolation/served.js";
|
|
2
|
+
import { framedByProblem, 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
|
|
@@ -80,7 +80,9 @@ export const FRAME_SHELL_RUNTIME = String.raw `(() => {
|
|
|
80
80
|
const web = plan.origins.filter((origin) => origin.indexOf("https://") === 0 || origin.indexOf("http://") === 0);
|
|
81
81
|
// To the host: each web host origin (only the parent's is delivered); a desktop app's own scheme
|
|
82
82
|
// is no target a browser takes, so where one is listed and the parent isn't a known web origin,
|
|
83
|
-
// "*" (frame-ancestors holds the parent to the host origins; nothing said here is secret).
|
|
83
|
+
// "*" (frame-ancestors holds the parent to the host origins; nothing said here is secret). Where
|
|
84
|
+
// it names an outer page above them too (the host's framedBy, P141: plan.strictParent), the parent
|
|
85
|
+
// may be the outer page: "*" then goes only to a parent the engine names as a host origin.
|
|
84
86
|
const toHost = (message) => {
|
|
85
87
|
if (!framed) {
|
|
86
88
|
return;
|
|
@@ -91,7 +93,11 @@ export const FRAME_SHELL_RUNTIME = String.raw `(() => {
|
|
|
91
93
|
} catch (_) {}
|
|
92
94
|
}
|
|
93
95
|
const parent = location.ancestorOrigins && location.ancestorOrigins.length > 0 ? location.ancestorOrigins[0] : null;
|
|
94
|
-
if (
|
|
96
|
+
if (
|
|
97
|
+
web.length < plan.origins.length &&
|
|
98
|
+
(parent === null || web.indexOf(parent) === -1) &&
|
|
99
|
+
(plan.strictParent !== true || (parent !== null && plan.origins.indexOf(parent) !== -1))
|
|
100
|
+
) {
|
|
95
101
|
try {
|
|
96
102
|
window.parent.postMessage(message, "*");
|
|
97
103
|
} catch (_) {}
|
|
@@ -271,6 +277,12 @@ export function frameShellScript(options) {
|
|
|
271
277
|
throw new TypeError(`frameShellScript: ${problem}`);
|
|
272
278
|
}
|
|
273
279
|
}
|
|
280
|
+
for (const origin of options.framedBy ?? []) {
|
|
281
|
+
const problem = framedByProblem(origin);
|
|
282
|
+
if (problem !== null || options.origins.includes(origin)) {
|
|
283
|
+
throw new TypeError(`frameShellScript: framedBy: ${problem ?? `${origin} is a host origin`}`);
|
|
284
|
+
}
|
|
285
|
+
}
|
|
274
286
|
let page;
|
|
275
287
|
try {
|
|
276
288
|
page = new URL(options.page);
|
|
@@ -287,6 +299,7 @@ export function frameShellScript(options) {
|
|
|
287
299
|
}
|
|
288
300
|
return FRAME_SHELL_RUNTIME.replace("__PLAN__", () => scriptJson({
|
|
289
301
|
origins: options.origins,
|
|
302
|
+
...((options.framedBy ?? []).length === 0 ? {} : { strictParent: true }),
|
|
290
303
|
page: page.href,
|
|
291
304
|
sandbox: PAGE_SANDBOX_TOKENS.join(" "),
|
|
292
305
|
...(options.title === undefined ? {} : { title: options.title }),
|
package/dist/shell/runtime.d.ts
CHANGED
|
@@ -29,6 +29,16 @@ export declare const PASSES_AS_IS: string;
|
|
|
29
29
|
* and nothing is forwarded): fail closed.
|
|
30
30
|
*/
|
|
31
31
|
export declare const ONCE: string;
|
|
32
|
+
/**
|
|
33
|
+
* The shell's handshake with its host (P085, P139), spliced into the runtime as
|
|
34
|
+
* `HANDSHAKE(topLevel, ask, answered, none, later)`. On a tab of its own (`topLevel`: the window is
|
|
35
|
+
* its own top, so its parent is itself and no host can hear it) there is no host to ask: `none()`
|
|
36
|
+
* at once, and nothing is asked. In a frame it asks (`ask()`, a promise of the host's answer) up to
|
|
37
|
+
* 40 times, 250 ms apart (`later(run, ms)`), since the host may start listening after the shell
|
|
38
|
+
* runs; the first answer is taken (`answered(result)`), once. After the 40th try with no answer,
|
|
39
|
+
* `none()`; an answer that comes later still is taken.
|
|
40
|
+
*/
|
|
41
|
+
export declare const HANDSHAKE: string;
|
|
32
42
|
/**
|
|
33
43
|
* The shell's runtime: the code that runs first in the frame, before any content. Plain ES2020,
|
|
34
44
|
* no imports and no build step, so every engine (a browser frame now, a native web view later)
|
package/dist/shell/runtime.js
CHANGED
|
@@ -88,6 +88,42 @@ export const ONCE = String.raw `(passesAsIs, toText) => (value) => {
|
|
|
88
88
|
}
|
|
89
89
|
return text;
|
|
90
90
|
}`;
|
|
91
|
+
/**
|
|
92
|
+
* The shell's handshake with its host (P085, P139), spliced into the runtime as
|
|
93
|
+
* `HANDSHAKE(topLevel, ask, answered, none, later)`. On a tab of its own (`topLevel`: the window is
|
|
94
|
+
* its own top, so its parent is itself and no host can hear it) there is no host to ask: `none()`
|
|
95
|
+
* at once, and nothing is asked. In a frame it asks (`ask()`, a promise of the host's answer) up to
|
|
96
|
+
* 40 times, 250 ms apart (`later(run, ms)`), since the host may start listening after the shell
|
|
97
|
+
* runs; the first answer is taken (`answered(result)`), once. After the 40th try with no answer,
|
|
98
|
+
* `none()`; an answer that comes later still is taken.
|
|
99
|
+
*/
|
|
100
|
+
export const HANDSHAKE = String.raw `(topLevel, ask, answered, none, later) => {
|
|
101
|
+
if (topLevel === true) {
|
|
102
|
+
none();
|
|
103
|
+
return;
|
|
104
|
+
}
|
|
105
|
+
let initialized = false;
|
|
106
|
+
let tries = 0;
|
|
107
|
+
const initialize = () => {
|
|
108
|
+
if (initialized) {
|
|
109
|
+
return;
|
|
110
|
+
}
|
|
111
|
+
if (tries >= 40) {
|
|
112
|
+
none();
|
|
113
|
+
return;
|
|
114
|
+
}
|
|
115
|
+
tries += 1;
|
|
116
|
+
ask().then((result) => {
|
|
117
|
+
if (initialized) {
|
|
118
|
+
return;
|
|
119
|
+
}
|
|
120
|
+
initialized = true;
|
|
121
|
+
answered(result);
|
|
122
|
+
}, () => {});
|
|
123
|
+
later(initialize, 250);
|
|
124
|
+
};
|
|
125
|
+
initialize();
|
|
126
|
+
}`;
|
|
91
127
|
/**
|
|
92
128
|
* The shell's runtime: the code that runs first in the frame, before any content. Plain ES2020,
|
|
93
129
|
* no imports and no build step, so every engine (a browser frame now, a native web view later)
|
|
@@ -151,6 +187,9 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
151
187
|
// such name goes on the shell's own script element (data-porthole-unfixed, for a test or a
|
|
152
188
|
// person to see) and, once the shell can speak, to the host as an error report.
|
|
153
189
|
const shellScript = document.currentScript;
|
|
190
|
+
// The platform's own, kept before the shell's guards wrap it: the shell marks the document's root
|
|
191
|
+
// with it (data-porthole-host, P139).
|
|
192
|
+
const setAttributeOfShell = Element.prototype.setAttribute;
|
|
154
193
|
const unfixed = [];
|
|
155
194
|
let tellUnfixed = (_name) => {};
|
|
156
195
|
const lock = (target, name, value) => {
|
|
@@ -2228,36 +2267,43 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
2228
2267
|
whenLoaded(() => void render({ html: plan.document }));
|
|
2229
2268
|
}
|
|
2230
2269
|
|
|
2231
|
-
//
|
|
2232
|
-
|
|
2233
|
-
|
|
2234
|
-
|
|
2235
|
-
|
|
2236
|
-
|
|
2237
|
-
|
|
2238
|
-
|
|
2239
|
-
|
|
2240
|
-
|
|
2241
|
-
|
|
2242
|
-
|
|
2243
|
-
|
|
2244
|
-
|
|
2245
|
-
|
|
2246
|
-
|
|
2247
|
-
|
|
2248
|
-
|
|
2249
|
-
|
|
2250
|
-
|
|
2251
|
-
|
|
2252
|
-
|
|
2270
|
+
// The handshake (HANDSHAKE, P085): asked until answered, since the host may start listening
|
|
2271
|
+
// after this runs; on a tab of its own, not asked at all (P139): its parent is itself, so no host
|
|
2272
|
+
// hears it, and the runtime has nothing to offer from the start. How it ended goes on the
|
|
2273
|
+
// document's root element (data-porthole-host: "answered", or "none" where no host answered), for
|
|
2274
|
+
// a test, a person or a tool that shoots the page to see (P139): not on the shell's own script,
|
|
2275
|
+
// which a whole document's render takes out with the body it replaces, while the root stays (the
|
|
2276
|
+
// render adds the page's own attributes to it and removes none). The page's own word, never a
|
|
2277
|
+
// gate, set through the platform's setAttribute kept before the guards (setAttributeOfShell).
|
|
2278
|
+
const shellRoot = document.documentElement;
|
|
2279
|
+
const settled = (how) => {
|
|
2280
|
+
try {
|
|
2281
|
+
callOf(setAttributeOfShell, shellRoot, ["data-porthole-host", how]);
|
|
2282
|
+
} catch (_) {}
|
|
2283
|
+
};
|
|
2284
|
+
const handshake = ${HANDSHAKE};
|
|
2285
|
+
handshake(
|
|
2286
|
+
window.top === window,
|
|
2287
|
+
() =>
|
|
2288
|
+
request("ui/initialize", {
|
|
2289
|
+
protocolVersion: plan.protocolVersion,
|
|
2290
|
+
appInfo: { name: "porthole-shell", version: "1" },
|
|
2291
|
+
appCapabilities: {},
|
|
2292
|
+
}),
|
|
2293
|
+
(result) => {
|
|
2294
|
+
settled("answered");
|
|
2253
2295
|
const capabilities = result && result.hostCapabilities;
|
|
2254
2296
|
const experimental = capabilities && capabilities.experimental;
|
|
2255
2297
|
runtimeOffer(experimental && typeof experimental === "object" ? experimental["porthole/runtime"] : null);
|
|
2256
2298
|
applyTheme(result && result.hostContext);
|
|
2257
2299
|
notify("ui/notifications/initialized", {});
|
|
2258
2300
|
schedule();
|
|
2259
|
-
},
|
|
2260
|
-
|
|
2261
|
-
|
|
2262
|
-
|
|
2301
|
+
},
|
|
2302
|
+
() => {
|
|
2303
|
+
// No host answered (or none can): the runtime has nothing to offer.
|
|
2304
|
+
settled("none");
|
|
2305
|
+
runtimeOffer(null);
|
|
2306
|
+
},
|
|
2307
|
+
(run, ms) => setTimeout(run, ms),
|
|
2308
|
+
);
|
|
2263
2309
|
})();`;
|
package/docs/ADOPTING.md
CHANGED
|
@@ -290,7 +290,8 @@ composer.onClose(() => display.annotations.clearSelection());
|
|
|
290
290
|
- **React** (P118): `PortholeFrame` and `PortholeView` take the same as props: `annotating`,
|
|
291
291
|
`annotations`, `focusedAnnotation` and `trackedAnnotation` (the mark to follow, by value; `null`
|
|
292
292
|
stops), `trackedSelection` (true while your composer is open: the selection is followed in the
|
|
293
|
-
mark's place, P138
|
|
293
|
+
mark's place, P138; give it from the first render, `false` until then, so the mode starts with
|
|
294
|
+
`keepSelection`, P140: it is read as the mode starts, and giving it later restarts nothing), every report through `onAnnotation` (`tracked` and `selectionTracked` too). The selection is cleared through a
|
|
294
295
|
ref, which holds `clearSelection()` only (a `PortholeFrameHandle`; never the display, whose life
|
|
295
296
|
is the binding's); with no display running it does nothing. Errors the core's calls throw (an id
|
|
296
297
|
no shown mark has, a config without `annotate`) reach `onHostError`, kind `"annotations"`.
|
|
@@ -437,30 +438,38 @@ composer.onClose(() => display.annotations.clearSelection());
|
|
|
437
438
|
composer.openAt(frame, clipToFrame(at), report.anchor); // the frame's px: clip them, then add its position
|
|
438
439
|
});
|
|
439
440
|
```
|
|
440
|
-
- **A composer that stays beside what it is for** (P138): `selected` comes once for a pick
|
|
441
|
-
for words again only once a scroll settles), and a pick's outline goes with it
|
|
442
|
-
|
|
443
|
-
`
|
|
441
|
+
- **A composer that stays beside what it is for** (P138, P140): `selected` comes once for a pick
|
|
442
|
+
(and for words again only once a scroll settles), and by default a pick's outline goes with it
|
|
443
|
+
and the frame keeps nothing of it. To follow it, start with `keepSelection: true`
|
|
444
|
+
(`annotations.start({ elements: true, keepSelection: true })`; React does it while you give
|
|
445
|
+
`trackedSelection`), so the frame keeps what is picked or selected, then follow the selection
|
|
446
|
+
while your composer is open, `annotations.track({ selection: true })` (React:
|
|
447
|
+
`trackedSelection`). The frame highlights it (a picked element in the picking outline) and
|
|
444
448
|
reports `selectionTracked` as `tracked` reports a mark: at most 60 a second, its `rect` clamped,
|
|
445
449
|
`documentRect`, `lastLineDocumentRect` and `scroll` as above, and `inView`, so you hide the
|
|
446
450
|
composer (and show your own marker at the frame's edge, from `documentRect` and `scroll`, clipped)
|
|
447
451
|
while it is out of view. `state: "orphaned"`: it isn't in the page now (a re-render took it out;
|
|
448
|
-
a reload); keep the person's words, it may be found again.
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
452
|
+
a reload); keep the person's words, it may be found again. Without `keepSelection`, a follow
|
|
453
|
+
asked after `selected` has nothing to follow and answers `orphaned`; one asked before the pick
|
|
454
|
+
follows each selection made while it lasts. It follows the latest `selected`, so a new pick or
|
|
455
|
+
selection moves it. One thing is followed at a time: it takes a followed mark's place, and
|
|
456
|
+
`track(null)`, a mark's id or `clear` ends it, the highlight with it. End it on every close
|
|
457
|
+
(posted, dismissed, Escape in your composer: the frame's own Escape doesn't end it), as you
|
|
458
|
+
clear the selection: the page reads when it starts and ends, so an end on every close says
|
|
459
|
+
nothing of what came of it. The composer moves at the page's word: guard it as below, armed
|
|
460
|
+
again each time it moves or shows again. An older shell sends nothing (and draws nothing): place
|
|
461
|
+
by `selected` until the first `selectionTracked`, which a newer one sends at its next animation
|
|
462
|
+
frame. Under `keepSelection` a newer shell keeps the picked element outlined from the pick on,
|
|
463
|
+
so there is no gap before the follow's highlight; ask for the follow before a `start` or `stop`
|
|
464
|
+
you send as the composer opens (React orders them so), or the stop ends that outline a moment
|
|
465
|
+
before the follow draws it again. Until the follow comes, the outline ends as a selection does
|
|
466
|
+
(the next pick, Escape, `clearSelection`, `start`, `stop`, `clear`). Without `keepSelection` the
|
|
467
|
+
outline goes with the pick, as before 0.14.15. While you follow the selection, `selected` isn't
|
|
468
|
+
re-sent after a scroll: read where it is from `selectionTracked`; and while you don't, a
|
|
469
|
+
`selectionTracked` from the page is dropped unread.
|
|
462
470
|
|
|
463
471
|
```js
|
|
472
|
+
display.annotations.start({ elements: true, text: true, keepSelection: true });
|
|
464
473
|
display.on("annotation", (report) => {
|
|
465
474
|
if (report.type === "selected") {
|
|
466
475
|
composer.openBeside(frame, report.rect, report.anchor); // as before: an older shell stops here
|
|
@@ -736,6 +745,15 @@ nodeServer({ content, app: async (request) => (await routes(request)) ?? app(req
|
|
|
736
745
|
- **`Response.redirect` needs an absolute URL** outside a browser (Node throws on `/login`).
|
|
737
746
|
- **`reserved`** is only for labels your app itself serves on the content domain (previews of a
|
|
738
747
|
dev server, `p-*`). Labels nothing serves need nothing: they are a 404 there.
|
|
748
|
+
- **`framedBy`** (P141): where another app frames yours (a dashboard that embeds your app in an
|
|
749
|
+
iframe), its origins: `framedBy: ["https://dashboard.example.com"]`. `frame-ancestors` names every
|
|
750
|
+
ancestor, so without it each of your frames is blank inside that app. Each may then be an
|
|
751
|
+
ancestor of every frame Porthole serves, after `appOrigins`, and is never a host: no frame hears
|
|
752
|
+
or tells it, it isn't in `data-porthole-hosts`, and redirect entry and the handoff stay
|
|
753
|
+
`appOrigins`' alone. Exact https origins (`http://` on loopback), none an app origin. Your own
|
|
754
|
+
page between them is still the frame's parent, and its `frame-ancestors` is yours to set. A
|
|
755
|
+
content Worker of your own passes the same list to `statusPage`, `doorResponse`,
|
|
756
|
+
`doorStatusResponse` and `nestedShellResponse` (`framedBy`).
|
|
739
757
|
- **No content domain** (self-hosted without one): still make the host, with `domain: null` (or
|
|
740
758
|
`""`). That is the supported setup: no secret is needed, `GET /porthole/meta` answers
|
|
741
759
|
`{ served: false }`, and pages show every kind opaque (a url kind, its fallback) instead of
|
|
@@ -910,7 +928,7 @@ no frame), `nestedShellResponse` throws for another origin, and the shell runs n
|
|
|
910
928
|
|
|
911
929
|
| Request | Answer |
|
|
912
930
|
| --- | --- |
|
|
913
|
-
| `<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. |
|
|
931
|
+
| `<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, framedBy, 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> <framedBy>`; `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. |
|
|
914
932
|
| `<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`). |
|
|
915
933
|
| `<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. |
|
|
916
934
|
| `<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. |
|
|
@@ -1136,8 +1154,8 @@ A **content Worker of your own** (one that answers the content origins itself, i
|
|
|
1136
1154
|
`/server`) serves the door too: `issue` mints the door ticket and returns `door: { url }`, and the
|
|
1137
1155
|
Worker routes `DOOR_PATH + <key>` (`/__porthole/door/<key>`) on every label — take the door ticket
|
|
1138
1156
|
(`TicketRecord.door === true`, bound to the label and key), run the same access, document and entry
|
|
1139
|
-
checks the content route runs for that grant, then answer `doorResponse({ hostOrigins })` (open) or
|
|
1140
|
-
`doorStatusResponse({ status, reason, code?, hostOrigins })` (401 `session` / 403 `denied` / 404
|
|
1157
|
+
checks the content route runs for that grant, then answer `doorResponse({ hostOrigins, framedBy })` (open) or
|
|
1158
|
+
`doorStatusResponse({ status, reason, code?, hostOrigins, framedBy })` (401 `session` / 403 `denied` / 404
|
|
1141
1159
|
`not-found` / 500 `error`). Refuse a door ticket at `/__porthole/d/`, and serve no door on a nested
|
|
1142
1160
|
page's shell label. `DOOR_PATH`, `doorResponse` and `doorStatusResponse` are exported from
|
|
1143
1161
|
`@botiverse/porthole/server`.
|