@botiverse/porthole 0.14.15 → 0.14.16
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 +31 -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/react/frame.d.ts +9 -1
- package/dist/react/frame.js +23 -3
- package/dist/shell/annotate.d.ts +5 -3
- package/dist/shell/annotate.js +36 -16
- package/dist/shell/runtime.d.ts +10 -0
- package/dist/shell/runtime.js +72 -26
- package/docs/ADOPTING.md +28 -19
- package/docs/DECISIONS.md +206 -3
- package/docs/DESIGN.md +19 -10
- package/docs/THREAT_MODEL.md +23 -5
- 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/react/frame.tsx +36 -5
- package/src/shell/annotate.ts +36 -16
- package/src/shell/runtime.ts +73 -26
package/src/react/frame.tsx
CHANGED
|
@@ -680,7 +680,8 @@ export interface PortholeFrameProps {
|
|
|
680
680
|
/**
|
|
681
681
|
* Annotations, where the config declares `annotate` (P053): what the person may point at now
|
|
682
682
|
* (elements, text, or both), or null to stop. A picked element ends element picking: set it
|
|
683
|
-
* again to pick again.
|
|
683
|
+
* again to pick again. `keepSelection` is set for you on a start made while `trackedSelection` is
|
|
684
|
+
* given (P140).
|
|
684
685
|
*/
|
|
685
686
|
readonly annotating?: AnnotateMode | null;
|
|
686
687
|
/**
|
|
@@ -716,6 +717,13 @@ export interface PortholeFrameProps {
|
|
|
716
717
|
* thing at a time); false, or leaving it out, ends it and its highlight (the comment posted, the
|
|
717
718
|
* composer dismissed, Escape in it), and `trackedAnnotation`'s mark is followed again. Until a
|
|
718
719
|
* `selectionTracked` comes, place by `selected`'s boxes: an older shell sends none.
|
|
720
|
+
*
|
|
721
|
+
* Give it from the first render, `false` until the composer opens (P140): each start of
|
|
722
|
+
* `annotating` made while it is given carries `keepSelection`, so the frame keeps what is picked
|
|
723
|
+
* or selected (and the picked element outlined) for the follow. It is read as a mode starts:
|
|
724
|
+
* giving it, or leaving it out, later restarts nothing, and counts from the next start. Left out
|
|
725
|
+
* when the mode started, the frame keeps nothing, and a follow asked after the pick has nothing
|
|
726
|
+
* to follow (`orphaned`).
|
|
719
727
|
*/
|
|
720
728
|
readonly trackedSelection?: boolean;
|
|
721
729
|
/** The display's imperative calls (`PortholeFrameHandle`, P118): React 19's `ref` prop. */
|
|
@@ -1292,10 +1300,18 @@ function Mount({
|
|
|
1292
1300
|
: JSON.stringify([focusedAnnotation]);
|
|
1293
1301
|
// By value: the same marks given again don't mark them again.
|
|
1294
1302
|
const annotations = useByValue(frame.annotations);
|
|
1303
|
+
// The mode, by value: what the person may point at, and the host's own `keepSelection`. Not
|
|
1304
|
+
// whether `trackedSelection` is given (P140, Ferryman's review): that is read at each start, so
|
|
1305
|
+
// a composer's prop that appears or goes restarts no mode (which would turn a pick that ended
|
|
1306
|
+
// back on, for the person's next click to pick again).
|
|
1295
1307
|
const mode =
|
|
1296
1308
|
annotating === undefined || annotating === null
|
|
1297
1309
|
? ""
|
|
1298
|
-
: JSON.stringify([
|
|
1310
|
+
: JSON.stringify([
|
|
1311
|
+
annotating.elements ?? true,
|
|
1312
|
+
annotating.text ?? true,
|
|
1313
|
+
annotating.keepSelection === true,
|
|
1314
|
+
]);
|
|
1299
1315
|
useEffect(() => {
|
|
1300
1316
|
const display = handle.current;
|
|
1301
1317
|
if (annotates && display !== null) {
|
|
@@ -1337,12 +1353,16 @@ function Mount({
|
|
|
1337
1353
|
if (!annotates || display === null) {
|
|
1338
1354
|
return;
|
|
1339
1355
|
}
|
|
1340
|
-
const wanted = mode === "" ? null : (JSON.parse(mode) as [boolean, boolean]);
|
|
1356
|
+
const wanted = mode === "" ? null : (JSON.parse(mode) as [boolean | "hold", boolean, boolean]);
|
|
1341
1357
|
attempt(
|
|
1342
1358
|
() =>
|
|
1343
1359
|
wanted === null
|
|
1344
1360
|
? display.annotations.stop()
|
|
1345
|
-
: display.annotations.start({
|
|
1361
|
+
: display.annotations.start({
|
|
1362
|
+
elements: wanted[0],
|
|
1363
|
+
text: wanted[1],
|
|
1364
|
+
...(wanted[2] || keepsSelection(latest()) ? { keepSelection: true } : {}),
|
|
1365
|
+
}),
|
|
1346
1366
|
latest(),
|
|
1347
1367
|
);
|
|
1348
1368
|
}, [annotates, mode]);
|
|
@@ -1442,7 +1462,9 @@ function applyAnnotations(display: DisplayHandle, frame: PortholeFrameProps): vo
|
|
|
1442
1462
|
display.annotations.focus(focused);
|
|
1443
1463
|
}
|
|
1444
1464
|
if (frame.annotating !== undefined && frame.annotating !== null) {
|
|
1445
|
-
display.annotations.start(
|
|
1465
|
+
display.annotations.start(
|
|
1466
|
+
keepsSelection(frame) ? { ...frame.annotating, keepSelection: true } : frame.annotating,
|
|
1467
|
+
);
|
|
1446
1468
|
}
|
|
1447
1469
|
}, frame);
|
|
1448
1470
|
}
|
|
@@ -1457,6 +1479,15 @@ function useByValue<T>(value: T): T {
|
|
|
1457
1479
|
return useMemo(() => (key === "" ? undefined : JSON.parse(key)) as T, [key]);
|
|
1458
1480
|
}
|
|
1459
1481
|
|
|
1482
|
+
/**
|
|
1483
|
+
* Whether a start keeps what is selected for a follow (P140): while `trackedSelection` is given
|
|
1484
|
+
* (true or false), or the host's own `keepSelection` says so. Read at each start, never a reason
|
|
1485
|
+
* for one.
|
|
1486
|
+
*/
|
|
1487
|
+
function keepsSelection(frame: PortholeFrameProps): boolean {
|
|
1488
|
+
return frame.annotating?.keepSelection === true || frame.trackedSelection !== undefined;
|
|
1489
|
+
}
|
|
1490
|
+
|
|
1460
1491
|
/** What a display follows (P118, P138): a mark's id, the selection (this one object), or nothing. */
|
|
1461
1492
|
const SELECTION = Object.freeze({ selection: true } as const);
|
|
1462
1493
|
type Followed = string | typeof SELECTION | null;
|
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/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
|
})();`;
|