@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/dist/host/create-host.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { ANNOTATE_METHODS
|
|
1
|
+
import { ANNOTATE_METHODS } from "../annotate/types.js";
|
|
2
2
|
import { annotateMode, checkMarks, clampRect, followsSelection, hasMarker, inViewport, parseReport, } from "../annotate/validate.js";
|
|
3
3
|
import { FIND_LIMITS, FIND_METHODS } from "../find/types.js";
|
|
4
4
|
import { blankQuery, checkFindQuery, parseFindReport, parseFindResult } from "../find/validate.js";
|
|
@@ -370,6 +370,12 @@ export function createHost(config, options = {}) {
|
|
|
370
370
|
if (type === undefined) {
|
|
371
371
|
return;
|
|
372
372
|
}
|
|
373
|
+
// The followed selection (P138) only while the host follows it, and dropped unread
|
|
374
|
+
// otherwise (P140): a host that doesn't follow it takes it as 0.14.14 took a method it
|
|
375
|
+
// didn't know, so a malformed one is no refusal either.
|
|
376
|
+
if (type === "selectionTracked" && !trackingSelection) {
|
|
377
|
+
return;
|
|
378
|
+
}
|
|
373
379
|
let report = parseReport({ ...(isRecord(raw.params) ? raw.params : {}), type });
|
|
374
380
|
if (report === null) {
|
|
375
381
|
void through.call("annotate", null);
|
|
@@ -394,12 +400,9 @@ export function createHost(config, options = {}) {
|
|
|
394
400
|
emit("annotation", withinFrame(report));
|
|
395
401
|
return;
|
|
396
402
|
}
|
|
397
|
-
// The followed selection (P138): only while the host follows it, on the same 60 a
|
|
398
|
-
// (one followed thing at a time), past the bridge's rate as the followed mark's.
|
|
403
|
+
// The followed selection (P138): only while the host follows it (above), on the same 60 a
|
|
404
|
+
// second (one followed thing at a time), past the bridge's rate as the followed mark's.
|
|
399
405
|
if (report.type === "selectionTracked") {
|
|
400
|
-
if (!trackingSelection) {
|
|
401
|
-
return;
|
|
402
|
-
}
|
|
403
406
|
const at = Date.now();
|
|
404
407
|
while (trackedTimes.length > 0 && at - trackedTimes[0] >= 1_000) {
|
|
405
408
|
trackedTimes.shift();
|
|
@@ -420,7 +423,7 @@ export function createHost(config, options = {}) {
|
|
|
420
423
|
}
|
|
421
424
|
// A pick ends with it; holding a block (P112) lasts until the host stops it.
|
|
422
425
|
if (kind === "element" && annotating.elements === true) {
|
|
423
|
-
annotating = annotating.text ? { elements: false
|
|
426
|
+
annotating = annotating.text ? { ...annotating, elements: false } : null;
|
|
424
427
|
}
|
|
425
428
|
break;
|
|
426
429
|
}
|
|
@@ -436,7 +439,7 @@ export function createHost(config, options = {}) {
|
|
|
436
439
|
return;
|
|
437
440
|
}
|
|
438
441
|
if (annotating.elements === true) {
|
|
439
|
-
annotating = annotating.text ? { elements: false
|
|
442
|
+
annotating = annotating.text ? { ...annotating, elements: false } : null;
|
|
440
443
|
}
|
|
441
444
|
break;
|
|
442
445
|
case "anchored": {
|
package/dist/host/types.d.ts
CHANGED
|
@@ -301,7 +301,11 @@ export interface FindControls {
|
|
|
301
301
|
* given to every frame the display runs (a reload, a navigation recovered from).
|
|
302
302
|
*/
|
|
303
303
|
export interface AnnotationControls {
|
|
304
|
-
/**
|
|
304
|
+
/**
|
|
305
|
+
* Lets the person point at elements, select text, or both (default both). With
|
|
306
|
+
* `keepSelection: true` (P140) the frame keeps what is selected for `track({ selection: true })`;
|
|
307
|
+
* without it, nothing is kept and a pick's outline goes with the pick.
|
|
308
|
+
*/
|
|
305
309
|
start(mode?: AnnotateMode): void;
|
|
306
310
|
stop(): void;
|
|
307
311
|
/** Marks these anchors (replacing the marks before); the frame reports where they are. */
|
|
@@ -321,14 +325,17 @@ export interface AnnotationControls {
|
|
|
321
325
|
* highlights it while it is followed (an element in the outline it had while it was picked) and
|
|
322
326
|
* reports `{ type: "selectionTracked", ... }` with the same boxes as `tracked` and `inView`, or
|
|
323
327
|
* `state: "orphaned"` while it isn't in the page; at most 60 a second together with `tracked`.
|
|
324
|
-
*
|
|
328
|
+
* The frame keeps a selection to follow only for a host that said so at `start`
|
|
329
|
+
* (`keepSelection`, P140), or one that already follows the selection as it is made: without
|
|
330
|
+
* either, a follow asked after `selected` has nothing to follow and answers `orphaned`. A `show`
|
|
331
|
+
* leaves it, and `stop` (or a pick ending) too: it ends with `track(null)`, `track(id)`
|
|
325
332
|
* or `clear` (comment posted, composer dismissed, Escape in it), and the highlight with it. A
|
|
326
333
|
* newer shell answers at its next animation frame; an older one sends nothing (it reads the
|
|
327
334
|
* message as `track(null)`), so until a `selectionTracked` comes, place by `selected`'s boxes.
|
|
328
|
-
* Kept for a frame that runs later, which has no selection: it answers `orphaned`.
|
|
329
|
-
* just picked stays outlined until then, so call it before a `start`
|
|
330
|
-
* stop ends that outline); while followed, `selected` isn't re-sent
|
|
331
|
-
* review).
|
|
335
|
+
* Kept for a frame that runs later, which has no selection: it answers `orphaned`. Under
|
|
336
|
+
* `keepSelection` the element just picked stays outlined until then, so call it before a `start`
|
|
337
|
+
* or `stop` sent with it (a stop ends that outline); while followed, `selected` isn't re-sent
|
|
338
|
+
* after a scroll (Tenny's review).
|
|
332
339
|
*/
|
|
333
340
|
track(target: AnnotationTrackTarget): void;
|
|
334
341
|
/** Removes every mark. */
|
package/dist/react/frame.d.ts
CHANGED
|
@@ -311,7 +311,8 @@ export interface PortholeFrameProps {
|
|
|
311
311
|
/**
|
|
312
312
|
* Annotations, where the config declares `annotate` (P053): what the person may point at now
|
|
313
313
|
* (elements, text, or both), or null to stop. A picked element ends element picking: set it
|
|
314
|
-
* again to pick again.
|
|
314
|
+
* again to pick again. `keepSelection` is set for you on a start made while `trackedSelection` is
|
|
315
|
+
* given (P140).
|
|
315
316
|
*/
|
|
316
317
|
readonly annotating?: AnnotateMode | null;
|
|
317
318
|
/**
|
|
@@ -347,6 +348,13 @@ export interface PortholeFrameProps {
|
|
|
347
348
|
* thing at a time); false, or leaving it out, ends it and its highlight (the comment posted, the
|
|
348
349
|
* composer dismissed, Escape in it), and `trackedAnnotation`'s mark is followed again. Until a
|
|
349
350
|
* `selectionTracked` comes, place by `selected`'s boxes: an older shell sends none.
|
|
351
|
+
*
|
|
352
|
+
* Give it from the first render, `false` until the composer opens (P140): each start of
|
|
353
|
+
* `annotating` made while it is given carries `keepSelection`, so the frame keeps what is picked
|
|
354
|
+
* or selected (and the picked element outlined) for the follow. It is read as a mode starts:
|
|
355
|
+
* giving it, or leaving it out, later restarts nothing, and counts from the next start. Left out
|
|
356
|
+
* when the mode started, the frame keeps nothing, and a follow asked after the pick has nothing
|
|
357
|
+
* to follow (`orphaned`).
|
|
350
358
|
*/
|
|
351
359
|
readonly trackedSelection?: boolean;
|
|
352
360
|
/** The display's imperative calls (`PortholeFrameHandle`, P118): React 19's `ref` prop. */
|
package/dist/react/frame.js
CHANGED
|
@@ -729,9 +729,17 @@ function Mount({ frame, page, running, findFor, initialHeightPx, placeholder, ru
|
|
|
729
729
|
: JSON.stringify([focusedAnnotation]);
|
|
730
730
|
// By value: the same marks given again don't mark them again.
|
|
731
731
|
const annotations = useByValue(frame.annotations);
|
|
732
|
+
// The mode, by value: what the person may point at, and the host's own `keepSelection`. Not
|
|
733
|
+
// whether `trackedSelection` is given (P140, Ferryman's review): that is read at each start, so
|
|
734
|
+
// a composer's prop that appears or goes restarts no mode (which would turn a pick that ended
|
|
735
|
+
// back on, for the person's next click to pick again).
|
|
732
736
|
const mode = annotating === undefined || annotating === null
|
|
733
737
|
? ""
|
|
734
|
-
: JSON.stringify([
|
|
738
|
+
: JSON.stringify([
|
|
739
|
+
annotating.elements ?? true,
|
|
740
|
+
annotating.text ?? true,
|
|
741
|
+
annotating.keepSelection === true,
|
|
742
|
+
]);
|
|
735
743
|
useEffect(() => {
|
|
736
744
|
const display = handle.current;
|
|
737
745
|
if (annotates && display !== null) {
|
|
@@ -776,7 +784,11 @@ function Mount({ frame, page, running, findFor, initialHeightPx, placeholder, ru
|
|
|
776
784
|
const wanted = mode === "" ? null : JSON.parse(mode);
|
|
777
785
|
attempt(() => wanted === null
|
|
778
786
|
? display.annotations.stop()
|
|
779
|
-
: display.annotations.start({
|
|
787
|
+
: display.annotations.start({
|
|
788
|
+
elements: wanted[0],
|
|
789
|
+
text: wanted[1],
|
|
790
|
+
...(wanted[2] || keepsSelection(latest()) ? { keepSelection: true } : {}),
|
|
791
|
+
}), latest());
|
|
780
792
|
}, [annotates, mode]);
|
|
781
793
|
useEffect(() => {
|
|
782
794
|
const display = handle.current;
|
|
@@ -859,7 +871,7 @@ function applyAnnotations(display, frame) {
|
|
|
859
871
|
display.annotations.focus(focused);
|
|
860
872
|
}
|
|
861
873
|
if (frame.annotating !== undefined && frame.annotating !== null) {
|
|
862
|
-
display.annotations.start(frame.annotating);
|
|
874
|
+
display.annotations.start(keepsSelection(frame) ? { ...frame.annotating, keepSelection: true } : frame.annotating);
|
|
863
875
|
}
|
|
864
876
|
}, frame);
|
|
865
877
|
}
|
|
@@ -872,6 +884,14 @@ function useByValue(value) {
|
|
|
872
884
|
const key = value === undefined ? "" : JSON.stringify(value);
|
|
873
885
|
return useMemo(() => (key === "" ? undefined : JSON.parse(key)), [key]);
|
|
874
886
|
}
|
|
887
|
+
/**
|
|
888
|
+
* Whether a start keeps what is selected for a follow (P140): while `trackedSelection` is given
|
|
889
|
+
* (true or false), or the host's own `keepSelection` says so. Read at each start, never a reason
|
|
890
|
+
* for one.
|
|
891
|
+
*/
|
|
892
|
+
function keepsSelection(frame) {
|
|
893
|
+
return frame.annotating?.keepSelection === true || frame.trackedSelection !== undefined;
|
|
894
|
+
}
|
|
875
895
|
/** What a display follows (P118, P138): a mark's id, the selection (this one object), or nothing. */
|
|
876
896
|
const SELECTION = Object.freeze({ selection: true });
|
|
877
897
|
/** What the props ask to follow: the selection while `trackedSelection`, else the mark, if any. */
|
package/dist/shell/annotate.d.ts
CHANGED
|
@@ -61,9 +61,11 @@ export declare const WORD_LATE: string;
|
|
|
61
61
|
* - the last line (P133): where a selection or a mark's words end, in the document's coordinates
|
|
62
62
|
* too (`lastLineDocumentRect`), so a host places its UI after them;
|
|
63
63
|
* - the selection followed (P138): what the last `selected` reported (the element picked, or the
|
|
64
|
-
* words selected) is kept
|
|
65
|
-
*
|
|
66
|
-
*
|
|
64
|
+
* words selected) is kept while the host follows the selection (`track` with `selection`) or said
|
|
65
|
+
* at `start` that it will (`keepSelection`, P140), and nothing is kept otherwise; while followed
|
|
66
|
+
* it is drawn in the layer and its boxes are reported as a followed mark's are
|
|
67
|
+
* (`selectionTracked`), with whether it is in view, or that it is gone; it takes no pointer, no
|
|
68
|
+
* focus and no key.
|
|
67
69
|
*
|
|
68
70
|
* It shares the realm with the content, which can interfere with all of it: the host takes its
|
|
69
71
|
* reports as UI hints only.
|
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/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
|