@botiverse/porthole 0.14.1 → 0.14.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +28 -0
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/react/frame.d.ts +26 -1
- package/dist/react/frame.js +69 -5
- package/dist/react/index.d.ts +1 -1
- package/dist/react/view.js +10 -4
- package/dist/shell/annotate.d.ts +9 -0
- package/dist/shell/annotate.js +73 -8
- package/docs/ADOPTING.md +19 -0
- package/docs/DECISIONS.md +114 -0
- package/docs/DESIGN.md +16 -6
- package/docs/THREAT_MODEL.md +7 -2
- package/package.json +1 -1
- package/src/react/frame.tsx +110 -3
- package/src/react/index.ts +1 -0
- package/src/react/view.tsx +20 -2
- package/src/shell/annotate.ts +74 -8
package/dist/react/frame.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import type { PageDeclaration } from "../runtime/declaration.ts";
|
|
2
2
|
import type { ViewerInfo } from "../runtime/levels.ts";
|
|
3
|
-
import { type CSSProperties, type ReactElement, type ReactNode } from "react";
|
|
3
|
+
import { type CSSProperties, type ReactElement, type ReactNode, type Ref } from "react";
|
|
4
4
|
import type { AnnotateMode, AnnotationMark, AnnotationReport } from "../annotate/types.ts";
|
|
5
5
|
import type { CapabilityHandler, CapabilityHandlers, Confirm, ConfirmRequest, Consent, DataCache, Refusal, Show } from "../bridge/types.ts";
|
|
6
6
|
import { Refused, type RefusalReason } from "../bridge/refusal.ts";
|
|
@@ -140,6 +140,20 @@ export interface PlaceholderProps {
|
|
|
140
140
|
/** Runs the display again (a stopped one), stopping another if the page is at its most. */
|
|
141
141
|
readonly run: () => void;
|
|
142
142
|
}
|
|
143
|
+
/**
|
|
144
|
+
* What a `ref` on `PortholeFrame` or `PortholeView` holds (P118): the display's few imperative
|
|
145
|
+
* calls, never the display itself. The same handle for the frame's whole life: its calls do
|
|
146
|
+
* nothing while no display runs (waiting to near the screen, stopped, a fallback drawn).
|
|
147
|
+
*/
|
|
148
|
+
export interface PortholeFrameHandle {
|
|
149
|
+
/**
|
|
150
|
+
* Takes the page's text selection away, and its highlight (`annotations.clearSelection()`,
|
|
151
|
+
* P115), once the host has used it (a comment posted, a draft added). No `unselected` follows.
|
|
152
|
+
* Nothing runs: nothing happens. A config without `annotate`: `onHostError`, kind
|
|
153
|
+
* `"annotations"` (the core's call throws; this never does).
|
|
154
|
+
*/
|
|
155
|
+
clearSelection(): void;
|
|
156
|
+
}
|
|
143
157
|
export interface PortholeFrameProps {
|
|
144
158
|
/** A preset's config. Keep it stable (module scope or memoized): a new one remounts the frame. */
|
|
145
159
|
readonly config: PortholeConfig;
|
|
@@ -273,6 +287,17 @@ export interface PortholeFrameProps {
|
|
|
273
287
|
readonly id: string;
|
|
274
288
|
readonly key: string | number;
|
|
275
289
|
} | null;
|
|
290
|
+
/**
|
|
291
|
+
* The mark to follow (`annotations.track`, P112, P118): while it moves, `onAnnotation` gets
|
|
292
|
+
* `{ type: "tracked", id, rect }` at most once per animation frame, for it alone. `null` (or
|
|
293
|
+
* leaving it out once set) stops. By value: given when it changes, and when the display is made.
|
|
294
|
+
* Only a shown mark (`annotations`) is followed: another id, or a config without `annotate`, is
|
|
295
|
+
* `onHostError` (kind `"annotations"`), as the core's call throws. `annotations` without it
|
|
296
|
+
* stop the following, as the core's `show` does; it starts again once they have it back.
|
|
297
|
+
*/
|
|
298
|
+
readonly trackedAnnotation?: string | null;
|
|
299
|
+
/** The display's imperative calls (`PortholeFrameHandle`, P118): React 19's `ref` prop. */
|
|
300
|
+
readonly ref?: Ref<PortholeFrameHandle>;
|
|
276
301
|
/**
|
|
277
302
|
* What the frame reported: a selection (an anchor and where it is), its clearing, a cancelled
|
|
278
303
|
* pick, where marks are (again once a scroll settles: those that moved), a marker clicked
|
package/dist/react/frame.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
|
|
2
|
-
import { createContext, useCallback, useContext, useEffect, useEffectEvent, useId, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
|
|
2
|
+
import { createContext, useCallback, useContext, useEffect, useEffectEvent, useId, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
|
|
3
3
|
import { isRefused, reasonOf, Refused } from "../bridge/refusal.js";
|
|
4
4
|
import { writeClipboard } from "../host/clipboard.js";
|
|
5
5
|
import { createHost } from "../host/create-host.js";
|
|
@@ -292,7 +292,25 @@ export function PortholeFrame(props) {
|
|
|
292
292
|
const box = useRef(null);
|
|
293
293
|
const max = props.config.limits.maxLiveFrames;
|
|
294
294
|
const state = useSyncExternalStore((listener) => live.subscribe(listener), () => live.state(key), () => "waiting");
|
|
295
|
-
const { eager } = props;
|
|
295
|
+
const { eager, ref: handleRef } = props;
|
|
296
|
+
// The running display (the Mount's), for the handle's calls; null while none runs.
|
|
297
|
+
const display = useRef(null);
|
|
298
|
+
const running = useCallback((each) => {
|
|
299
|
+
display.current = each;
|
|
300
|
+
}, []);
|
|
301
|
+
// The props as of the last render, read when the handle is called (never during render).
|
|
302
|
+
const own = useRef(props);
|
|
303
|
+
useLayoutEffect(() => {
|
|
304
|
+
own.current = props;
|
|
305
|
+
});
|
|
306
|
+
useImperativeHandle(handleRef, () => ({
|
|
307
|
+
clearSelection() {
|
|
308
|
+
const now = display.current;
|
|
309
|
+
if (now !== null) {
|
|
310
|
+
attempt(() => now.annotations.clearSelection(), own.current);
|
|
311
|
+
}
|
|
312
|
+
},
|
|
313
|
+
}), []);
|
|
296
314
|
useEffect(() => {
|
|
297
315
|
const element = box.current;
|
|
298
316
|
if (element === null) {
|
|
@@ -343,12 +361,15 @@ export function PortholeFrame(props) {
|
|
|
343
361
|
: {}),
|
|
344
362
|
...(state === "running" ? {} : { minHeight: Math.max(height, PLACEHOLDER_HEIGHT_PX) }),
|
|
345
363
|
...props.style,
|
|
346
|
-
}, children: state === "running" ? (_jsx(Mount, { frame: props, page: page, initialHeightPx: height, placeholder: placeholder, run: run }, String(props.generation ?? 0))) : (placeholder({ state, title: props.title, run })) }));
|
|
364
|
+
}, children: state === "running" ? (_jsx(Mount, { frame: props, page: page, running: running, initialHeightPx: height, placeholder: placeholder, run: run }, String(props.generation ?? 0))) : (placeholder({ state, title: props.title, run })) }));
|
|
347
365
|
}
|
|
348
366
|
/** One running display: created when mounted, torn down when unmounted, fed as props change. */
|
|
349
|
-
function Mount({ frame, page, initialHeightPx, placeholder, run }) {
|
|
367
|
+
function Mount({ frame, page, running, initialHeightPx, placeholder, run, }) {
|
|
350
368
|
const holder = useRef(null);
|
|
351
369
|
const handle = useRef(null);
|
|
370
|
+
// The mark the display follows now, as the core keeps it (P118), and the prop as last seen.
|
|
371
|
+
const following = useRef(null);
|
|
372
|
+
const asked = useRef(null);
|
|
352
373
|
const [ready, setReady] = useState(false);
|
|
353
374
|
// The height this display started at: later reports don't make it start again.
|
|
354
375
|
const [startHeight] = useState(initialHeightPx);
|
|
@@ -527,6 +548,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
|
|
|
527
548
|
return;
|
|
528
549
|
}
|
|
529
550
|
handle.current = display;
|
|
551
|
+
running(display);
|
|
530
552
|
const events = [
|
|
531
553
|
"initialized",
|
|
532
554
|
"resize",
|
|
@@ -547,12 +569,24 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
|
|
|
547
569
|
if (config.capabilities.annotate !== undefined) {
|
|
548
570
|
applyAnnotations(display, first);
|
|
549
571
|
}
|
|
572
|
+
// The followed mark, once the marks are shown; without `annotate`, the core's error.
|
|
573
|
+
following.current = null;
|
|
574
|
+
const wanted = first.trackedAnnotation ?? null;
|
|
575
|
+
asked.current = wanted;
|
|
576
|
+
if (wanted !== null) {
|
|
577
|
+
attempt(() => {
|
|
578
|
+
display.annotations.track(wanted);
|
|
579
|
+
following.current = wanted;
|
|
580
|
+
}, first);
|
|
581
|
+
}
|
|
550
582
|
if (first.content !== undefined) {
|
|
551
583
|
display.setContent(first.content, { partial: first.partial === true });
|
|
552
584
|
}
|
|
553
585
|
return () => {
|
|
554
586
|
display.destroy();
|
|
555
587
|
handle.current = null;
|
|
588
|
+
running(null);
|
|
589
|
+
following.current = null;
|
|
556
590
|
};
|
|
557
591
|
// A new display only for a new config, document or instance, or what the provider makes
|
|
558
592
|
// displays with (its nonce, hostInfo by value, whether it locates or confirms; generation, by
|
|
@@ -575,6 +609,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
|
|
|
575
609
|
hostInfo,
|
|
576
610
|
locate,
|
|
577
611
|
nonce,
|
|
612
|
+
running,
|
|
578
613
|
]);
|
|
579
614
|
useEffect(() => {
|
|
580
615
|
if (content !== undefined) {
|
|
@@ -608,9 +643,34 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
|
|
|
608
643
|
useEffect(() => {
|
|
609
644
|
const display = handle.current;
|
|
610
645
|
if (annotates && display !== null) {
|
|
611
|
-
attempt(() =>
|
|
646
|
+
attempt(() => {
|
|
647
|
+
display.annotations.show(annotations ?? []);
|
|
648
|
+
// A show without the followed mark stops the following (the core's own).
|
|
649
|
+
if (following.current !== null && !shown(annotations, following.current)) {
|
|
650
|
+
following.current = null;
|
|
651
|
+
}
|
|
652
|
+
}, latest());
|
|
612
653
|
}
|
|
613
654
|
}, [annotates, annotations]);
|
|
655
|
+
// The followed mark follows its prop (after the marks above, so the two can change together).
|
|
656
|
+
const trackedAnnotation = frame.trackedAnnotation ?? null;
|
|
657
|
+
useEffect(() => {
|
|
658
|
+
const display = handle.current;
|
|
659
|
+
const changed = trackedAnnotation !== asked.current;
|
|
660
|
+
asked.current = trackedAnnotation;
|
|
661
|
+
if (display === null || trackedAnnotation === following.current) {
|
|
662
|
+
return;
|
|
663
|
+
}
|
|
664
|
+
// Its mark was taken off (the error, if any, was told when the prop said it): followed again
|
|
665
|
+
// once the marks have it back.
|
|
666
|
+
if (!changed && trackedAnnotation !== null && !shown(annotations, trackedAnnotation)) {
|
|
667
|
+
return;
|
|
668
|
+
}
|
|
669
|
+
attempt(() => {
|
|
670
|
+
display.annotations.track(trackedAnnotation);
|
|
671
|
+
following.current = trackedAnnotation;
|
|
672
|
+
}, latest());
|
|
673
|
+
}, [trackedAnnotation, annotations]);
|
|
614
674
|
useEffect(() => {
|
|
615
675
|
const display = handle.current;
|
|
616
676
|
const id = focusOf(latest().focusedAnnotation);
|
|
@@ -695,6 +755,10 @@ function useByValue(value) {
|
|
|
695
755
|
const key = value === undefined ? "" : JSON.stringify(value);
|
|
696
756
|
return useMemo(() => (key === "" ? undefined : JSON.parse(key)), [key]);
|
|
697
757
|
}
|
|
758
|
+
/** Whether `marks` has a mark `id`. */
|
|
759
|
+
function shown(marks, id) {
|
|
760
|
+
return (marks ?? []).some((mark) => mark.id === id);
|
|
761
|
+
}
|
|
698
762
|
/** The id `focusedAnnotation` names, if any. */
|
|
699
763
|
function focusOf(value) {
|
|
700
764
|
return typeof value === "string"
|
package/dist/react/index.d.ts
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
* theme={tokensFor} onError={report} />
|
|
9
9
|
* </PortholeProvider>
|
|
10
10
|
*/
|
|
11
|
-
export { PLACEHOLDER_HEIGHT_PX, PortholeFrame, PortholeProvider, type PlaceholderProps, type PortholeFrameProps, type ConfirmActions, type PortholeProviderProps, } from "./frame.tsx";
|
|
11
|
+
export { PLACEHOLDER_HEIGHT_PX, PortholeFrame, PortholeProvider, type PlaceholderProps, type PortholeFrameHandle, type PortholeFrameProps, type ConfirmActions, type PortholeProviderProps, } from "./frame.tsx";
|
|
12
12
|
export { ARM_DELAY_MS, ConfirmDialog, type ConfirmDialogProps } from "./dialog.tsx";
|
|
13
13
|
export { ContextNotice, contextSize, contextText, type ContextNoticeProps, type ContextUpdate, } from "./context-notice.tsx";
|
|
14
14
|
export { cssVariableTheme, PortholeView, usePortholeLink, useRunAgain, type PortholeFallbackProps, type PortholeViewProps, } from "./view.tsx";
|
package/dist/react/view.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
|
|
2
|
-
import { useCallback, useContext, useEffect, useState, useSyncExternalStore, } from "react";
|
|
2
|
+
import { useCallback, useContext, useEffect, useImperativeHandle, useRef, useState, useSyncExternalStore, } from "react";
|
|
3
3
|
import { frameFallback } from "../host/client.js";
|
|
4
|
-
import { PortholeFrame, PortholeContext } from "./frame.js";
|
|
4
|
+
import { PortholeFrame, PortholeContext, } from "./frame.js";
|
|
5
5
|
function useClient() {
|
|
6
6
|
const client = useContext(PortholeContext).client;
|
|
7
7
|
if (client === undefined) {
|
|
@@ -24,7 +24,13 @@ function DefaultFallback({ title, message, link }) {
|
|
|
24
24
|
export function PortholeView(props) {
|
|
25
25
|
const client = useClient();
|
|
26
26
|
const meta = useMeta(client);
|
|
27
|
-
const { display, instance, content, fallback, pending, onOutcome, ...frame } = props;
|
|
27
|
+
const { display, instance, content, fallback, pending, onOutcome, ref, ...frame } = props;
|
|
28
|
+
// The view's handle (P118) is there while the view is, a fallback drawn or not: its calls reach
|
|
29
|
+
// the frame's display when one runs, and do nothing otherwise.
|
|
30
|
+
const shown = useRef(null);
|
|
31
|
+
useImperativeHandle(ref, () => ({
|
|
32
|
+
clearSelection: () => shown.current?.clearSelection(),
|
|
33
|
+
}), []);
|
|
28
34
|
const [failed, setFailed] = useState(null);
|
|
29
35
|
const [generation, setGeneration] = useState(0);
|
|
30
36
|
const [link, setLink] = useState(null);
|
|
@@ -73,7 +79,7 @@ export function PortholeView(props) {
|
|
|
73
79
|
if (failed !== null) {
|
|
74
80
|
return _jsx(_Fragment, { children: (fallback ?? DefaultFallback)({ ...failed, link, retry }) });
|
|
75
81
|
}
|
|
76
|
-
return (_jsx(PortholeFrame, { ...frame, config: config, generation: (frame.generation ?? 0) + generation, ...(instance === undefined ? {} : { instance }), ...(content === undefined ? {} : { content }), onOutcome: (outcome) => {
|
|
82
|
+
return (_jsx(PortholeFrame, { ...frame, ref: shown, config: config, generation: (frame.generation ?? 0) + generation, ...(instance === undefined ? {} : { instance }), ...(content === undefined ? {} : { content }), onOutcome: (outcome) => {
|
|
77
83
|
onOutcome?.(outcome);
|
|
78
84
|
const said = frameFallback(outcome, { url });
|
|
79
85
|
if (said !== null) {
|
package/dist/shell/annotate.d.ts
CHANGED
|
@@ -1,3 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which marker a press on the shell's layer is for (P119), spliced into the runtime: the index of
|
|
3
|
+
* `count` boxes (`boxAt(i)`, the markers' own boxes in the viewport, the last drawn on top), or -1.
|
|
4
|
+
* A point on a marker's own box is that marker's (the topmost, as before). With `touch` (the last
|
|
5
|
+
* pointer a finger or a pen), a marker also takes the points of a 44 by 44 CSS px box centred on
|
|
6
|
+
* its own (its own size where it is larger): where those overlap, the marker whose own box's
|
|
7
|
+
* centre is nearest the point. No built-in is called (content may have patched them).
|
|
8
|
+
*/
|
|
9
|
+
export declare const MARKER_HIT: string;
|
|
1
10
|
/**
|
|
2
11
|
* The shell's annotation runtime (P053), spliced into the shell's runtime (`__ANNOTATE__`) when
|
|
3
12
|
* the config declares `annotate`, so it runs before any content does, with the DOM's own
|
package/dist/shell/annotate.js
CHANGED
|
@@ -1,3 +1,36 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which marker a press on the shell's layer is for (P119), spliced into the runtime: the index of
|
|
3
|
+
* `count` boxes (`boxAt(i)`, the markers' own boxes in the viewport, the last drawn on top), or -1.
|
|
4
|
+
* A point on a marker's own box is that marker's (the topmost, as before). With `touch` (the last
|
|
5
|
+
* pointer a finger or a pen), a marker also takes the points of a 44 by 44 CSS px box centred on
|
|
6
|
+
* its own (its own size where it is larger): where those overlap, the marker whose own box's
|
|
7
|
+
* centre is nearest the point. No built-in is called (content may have patched them).
|
|
8
|
+
*/
|
|
9
|
+
export const MARKER_HIT = String.raw `(count, boxAt, x, y, touch) => {
|
|
10
|
+
const TARGET = 44;
|
|
11
|
+
let best = -1;
|
|
12
|
+
let nearest = 0;
|
|
13
|
+
for (let i = count - 1; i >= 0; i -= 1) {
|
|
14
|
+
const rect = boxAt(i);
|
|
15
|
+
if (x >= rect.x && x <= rect.x + rect.width && y >= rect.y && y <= rect.y + rect.height) {
|
|
16
|
+
return i;
|
|
17
|
+
}
|
|
18
|
+
if (touch) {
|
|
19
|
+
const dx = x - (rect.x + rect.width / 2);
|
|
20
|
+
const dy = y - (rect.y + rect.height / 2);
|
|
21
|
+
const halfWidth = (rect.width > TARGET ? rect.width : TARGET) / 2;
|
|
22
|
+
const halfHeight = (rect.height > TARGET ? rect.height : TARGET) / 2;
|
|
23
|
+
if (dx >= -halfWidth && dx <= halfWidth && dy >= -halfHeight && dy <= halfHeight) {
|
|
24
|
+
const distance = dx * dx + dy * dy;
|
|
25
|
+
if (best === -1 || distance < nearest) {
|
|
26
|
+
best = i;
|
|
27
|
+
nearest = distance;
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
return best;
|
|
33
|
+
}`;
|
|
1
34
|
/**
|
|
2
35
|
* The shell's annotation runtime (P053), spliced into the shell's runtime (`__ANNOTATE__`) when
|
|
3
36
|
* the config declares `annotate`, so it runs before any content does, with the DOM's own
|
|
@@ -376,7 +409,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
376
409
|
// layer inherits from the page could reach it, so each of those is set here). A draft
|
|
377
410
|
// (P107) is a comment not yet posted: its line is dashed (an element's outline too) and its
|
|
378
411
|
// marker hollow, a light bubble with a dashed edge and the glyph's outline, no number.
|
|
379
|
-
|
|
412
|
+
// While the last pointer was a finger or a pen (P119), each marker takes the pointer in a
|
|
413
|
+
// box of at least 44 by 44 px centred on its own (an invisible ::before; 100% is its padding
|
|
414
|
+
// box, its border 1 px), so a tap a few px off still lands on the shell's layer.
|
|
415
|
+
const STYLE = ".mark{position:absolute;border-radius:2px;background:rgba(250,204,21,.18);box-shadow:inset 0 -2px 0 rgba(234,179,8,.95)}.mark.element{background:rgba(250,204,21,.07);box-shadow:none;outline:2px solid rgba(234,179,8,.9);outline-offset:1px}.mark.active{background:rgba(250,204,21,.26);box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 2px rgba(234,179,8,.45)}.mark.element.active{background:rgba(250,204,21,.12);box-shadow:none;outline-width:3px}.mark.element.quiet{background:rgba(250,204,21,.05);outline:1px solid rgba(234,179,8,.6);outline-offset:2px}.mark.element.quiet.active{background:rgba(250,204,21,.1);outline:2px solid rgba(234,179,8,.9)}.mark.draft{box-sizing:border-box;background:rgba(250,204,21,.08);box-shadow:none;border-bottom:2px dashed rgba(202,138,4,.95)}.mark.draft.active{background:rgba(250,204,21,.16);box-shadow:0 0 0 2px rgba(234,179,8,.45);border-bottom-width:3px}.mark.element.draft{background:rgba(250,204,21,.04);border-bottom:0;outline-style:dashed}.mark.element.draft.active{background:rgba(250,204,21,.08);box-shadow:none;outline-style:dashed}.marker{position:absolute;box-sizing:border-box;height:18px;min-width:18px;display:flex;align-items:center;justify-content:center;gap:3px;margin:0;padding:0 5px;border:1px solid rgba(161,98,7,.6);border-radius:9px 9px 9px 2px;background:#fde68a;color:#422006;box-shadow:0 1px 2px rgba(0,0,0,.3);font:600 11px/16px system-ui,-apple-system,Segoe UI,Roboto,sans-serif;font-style:normal;letter-spacing:0;word-spacing:0;text-transform:none;text-indent:0;text-shadow:none;direction:ltr;writing-mode:horizontal-tb;white-space:nowrap;user-select:none;-webkit-user-select:none;cursor:pointer;pointer-events:auto}.marker:hover{background:#fcd34d}.marker.active{background:#facc15;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.3)}.marker.compact{padding:0 4px}.marker.draft{border:1px dashed rgb(202,138,4);background:#fffdf5;color:#a16207;box-shadow:0 1px 2px rgba(0,0,0,.2)}.marker.draft:hover{background:#fef9e7}.marker.draft.active{background:#fef3c7;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.2)}.marker.inert{pointer-events:none}.touch>.marker::before{content:'';position:absolute;left:50%;top:50%;width:max(100% + 2px,44px);height:max(100% + 2px,44px);transform:translate(-50%,-50%)}.marker svg{display:block;width:11px;height:11px;flex:none}.mark.flash{animation:flash 1.8s ease-out}@keyframes flash{from{box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 6px rgba(250,204,21,.6)}}.hover{position:absolute;outline:2px solid #2563eb;outline-offset:1px;background:rgba(37,99,235,.12)}.tag{position:absolute;max-width:70vw;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font:12px/18px ui-monospace,SFMono-Regular,Menlo,monospace;padding:0 6px;border-radius:4px;background:#1e293b;color:#fff}";
|
|
380
416
|
// Inline and important: the content's own style sheets can't hide, shrink or move it by
|
|
381
417
|
// accident. Set again at each draw, since its scripts can rewrite it (narrowing only: the
|
|
382
418
|
// content can still cover the layer, or move it with its ancestors, P104).
|
|
@@ -404,6 +440,13 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
404
440
|
// marker's node across draws, so a press that spans a redraw ends on the node it began on.
|
|
405
441
|
let markers = [];
|
|
406
442
|
const markerNodes = new Map();
|
|
443
|
+
// Whether the last pointer was a finger or a pen (P119): then each marker takes the pointer
|
|
444
|
+
// in a 44 px box around it (the markers' box has the class "touch"). Until a pointer is
|
|
445
|
+
// seen, whether the device has a coarse pointer at all (a phone, a tablet, a laptop with a
|
|
446
|
+
// touch screen): a mouse moves before it presses, and its first move turns it off.
|
|
447
|
+
const coarseQuery = typeof window.matchMedia === "function" ? window.matchMedia("(any-pointer: coarse)") : null;
|
|
448
|
+
let touch = coarseQuery !== null && coarseQuery.matches === true;
|
|
449
|
+
const markerHit = ${MARKER_HIT};
|
|
407
450
|
const MARKER_HEIGHT = 18;
|
|
408
451
|
const SVG = "http://www.w3.org/2000/svg";
|
|
409
452
|
const labelOf = (count) => (count === 0 ? "" : count > 99 ? "99+" : String(count));
|
|
@@ -714,6 +757,9 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
714
757
|
if (boxes.style.textContent !== STYLE) {
|
|
715
758
|
boxes.style.textContent = STYLE;
|
|
716
759
|
}
|
|
760
|
+
if (boxes.markers.className !== (touch ? "touch" : "")) {
|
|
761
|
+
boxes.markers.className = touch ? "touch" : "";
|
|
762
|
+
}
|
|
717
763
|
return boxes;
|
|
718
764
|
};
|
|
719
765
|
const draw = () => {
|
|
@@ -1118,14 +1164,11 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1118
1164
|
const rect = callOf(elementRect, element, []);
|
|
1119
1165
|
return { x: callOf(leftOf, rect, []), y: callOf(topOf, rect, []), width: callOf(widthOf, rect, []), height: callOf(heightOf, rect, []) };
|
|
1120
1166
|
};
|
|
1167
|
+
// The marker a press at (x, y) is for: on a marker's own box, that one; after a finger or a
|
|
1168
|
+
// pen, also within the 44 px box around one, the nearest (P119).
|
|
1121
1169
|
const markerAt = (x, y) => {
|
|
1122
|
-
|
|
1123
|
-
|
|
1124
|
-
if (x >= rect.x && x <= rect.x + rect.width && y >= rect.y && y <= rect.y + rect.height) {
|
|
1125
|
-
return markers[i];
|
|
1126
|
-
}
|
|
1127
|
-
}
|
|
1128
|
-
return null;
|
|
1170
|
+
const at = markerHit(markers.length, (i) => markerBox(markers[i].element), x, y, touch);
|
|
1171
|
+
return at < 0 ? null : markers[at];
|
|
1129
1172
|
};
|
|
1130
1173
|
const isShown = (id) => {
|
|
1131
1174
|
for (let i = 0; i < marks.length; i += 1) {
|
|
@@ -1170,6 +1213,28 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
|
|
|
1170
1213
|
const CANCELLED = { mousedown: 1, mouseup: 1, click: 1, dblclick: 1, auxclick: 1, contextmenu: 1 };
|
|
1171
1214
|
// The pointer on a marker (1), or leaving the layer for the content (0).
|
|
1172
1215
|
const HOVERS = { pointerover: 1, pointermove: 1, pointerout: 0, pointerleave: 0 };
|
|
1216
|
+
// Which pointer the person uses (P119), from each real one that goes down or moves, before
|
|
1217
|
+
// the marker's listener (which stops a press on the layer): a finger or a pen gives every
|
|
1218
|
+
// marker its 44 px box, a mouse takes it away. A mouse moves before it presses, so its press
|
|
1219
|
+
// is hit-tested on the markers' own boxes. Read through the platform's getter, kept now; an
|
|
1220
|
+
// event the page makes up (isTrusted is false) changes nothing.
|
|
1221
|
+
const pointerTypeOf = getterOf(typeof PointerEvent === "function" ? PointerEvent.prototype : null, "pointerType");
|
|
1222
|
+
const onPointer = (event) => {
|
|
1223
|
+
if (!event.isTrusted || pointerTypeOf === null) {
|
|
1224
|
+
return;
|
|
1225
|
+
}
|
|
1226
|
+
const kind = callOf(pointerTypeOf, event, []);
|
|
1227
|
+
const next = kind === "touch" || kind === "pen";
|
|
1228
|
+
if (next !== touch) {
|
|
1229
|
+
touch = next;
|
|
1230
|
+
if (boxes !== null) {
|
|
1231
|
+
boxes.markers.className = touch ? "touch" : "";
|
|
1232
|
+
}
|
|
1233
|
+
}
|
|
1234
|
+
};
|
|
1235
|
+
for (const type of ["pointerdown", "pointermove"]) {
|
|
1236
|
+
window.addEventListener(type, onPointer, true);
|
|
1237
|
+
}
|
|
1173
1238
|
for (const type of ["pointerdown", "pointerup", "pointercancel", "mousedown", "mouseup", "click", "dblclick", "auxclick", "contextmenu", "touchstart", "touchend", "touchcancel", "pointerover", "pointerout", "pointerenter", "pointerleave", "pointermove", "mouseover", "mouseout", "mouseenter", "mouseleave", "mousemove"]) {
|
|
1174
1239
|
window.addEventListener(type, onMarker, true);
|
|
1175
1240
|
}
|
package/docs/ADOPTING.md
CHANGED
|
@@ -280,6 +280,25 @@ composer.onDone(() => display.annotations.clearSelection());
|
|
|
280
280
|
to clear). Like `start` and `show`, only where the config declares `annotate`. The shell is your
|
|
281
281
|
content server's: an older one ignores it.
|
|
282
282
|
|
|
283
|
+
- **React** (P118): `PortholeFrame` and `PortholeView` take the same as props: `annotating`,
|
|
284
|
+
`annotations`, `focusedAnnotation` and `trackedAnnotation` (the mark to follow, by value; `null`
|
|
285
|
+
stops), every report through `onAnnotation` (`tracked` too). The selection is cleared through a
|
|
286
|
+
ref, which holds `clearSelection()` only (a `PortholeFrameHandle`; never the display, whose life
|
|
287
|
+
is the binding's); with no display running it does nothing. Errors the core's calls throw (an id
|
|
288
|
+
no shown mark has, a config without `annotate`) reach `onHostError`, kind `"annotations"`.
|
|
289
|
+
|
|
290
|
+
```tsx
|
|
291
|
+
const frame = useRef<PortholeFrameHandle>(null);
|
|
292
|
+
<PortholeView ref={frame} display="page" instance={instance} displayId={id} title={title}
|
|
293
|
+
annotating={commenting ? { elements: false, text: true } : null}
|
|
294
|
+
annotations={marks} trackedAnnotation={openCard?.markId ?? null}
|
|
295
|
+
onAnnotation={(report) => {
|
|
296
|
+
if (report.type === "tracked") card.moveBeside(report.rect);
|
|
297
|
+
if (report.type === "selected") composer.openBeside(report.rect, report.anchor);
|
|
298
|
+
}} />
|
|
299
|
+
composer.onDone(() => frame.current?.clearSelection());
|
|
300
|
+
```
|
|
301
|
+
|
|
283
302
|
- **Ids say nothing, and a count only where the page may know it**: the content reads every
|
|
284
303
|
`show`. Who wrote what stays in your view, outside the frame.
|
|
285
304
|
- **Drafts only to their author's frame**: the page reads which marks are drafts (that its viewer
|
package/docs/DECISIONS.md
CHANGED
|
@@ -6258,3 +6258,117 @@ differently, since a draft runs nothing.
|
|
|
6258
6258
|
Tested: `test/shell.test.ts` (`<`, `</`, `</di`, inside an attribute, and whole content
|
|
6259
6259
|
unchanged); `leak/react.spec.ts` "content streams through props…" (a draft cut after `</` and
|
|
6260
6260
|
after `<` draws neither).
|
|
6261
|
+
|
|
6262
|
+
## P118 · 2026-10-28 · React: `trackedAnnotation` and a handle with `clearSelection` · Accepted
|
|
6263
|
+
|
|
6264
|
+
**Context.** Raft's web app (Kirby) shows displays through `PortholeFrame` and `PortholeView`,
|
|
6265
|
+
which hold the display handle inside: it could not follow a mark (`annotations.track`, P112) or
|
|
6266
|
+
clear a used selection (`annotations.clearSelection()`, P115), both added to the core in 0.14.
|
|
6267
|
+
|
|
6268
|
+
**Decision.** Two additions to both components, the core's calls and nothing more:
|
|
6269
|
+
|
|
6270
|
+
- **`trackedAnnotation?: string | null`**, by value, as `annotations` and `focusedAnnotation`
|
|
6271
|
+
are: the binding calls `display.annotations.track(id)` when the prop changes and when a display
|
|
6272
|
+
is made with it set (a new generation, config or instance), after the marks are shown, so a
|
|
6273
|
+
mark and its following can arrive in one render. `null`, or leaving the prop out once it was
|
|
6274
|
+
set, calls `track(null)`. The core's semantics hold: an id no shown mark has, or a config
|
|
6275
|
+
without `annotate`, is the core's `TypeError`, told to `onHostError` (kind `"annotations"`) and
|
|
6276
|
+
never thrown during render; `annotations` without the followed mark stop the following, as the
|
|
6277
|
+
core's `show` does, and the binding follows it again when the marks have it back (the prop says
|
|
6278
|
+
to follow it; no second error is told while it is off). The `tracked` reports reach the existing
|
|
6279
|
+
`onAnnotation`, as every annotation report does (no new callback).
|
|
6280
|
+
- **A `ref`** holding a `PortholeFrameHandle`, exactly `{ clearSelection(): void }`, through
|
|
6281
|
+
React 19's `ref` prop and `useImperativeHandle` (the binding's peer is React 19.2+; no
|
|
6282
|
+
`forwardRef`). `clearSelection()` calls `display.annotations.clearSelection()` on the display
|
|
6283
|
+
running now; with none (waiting to near the screen, stopped for others, a view's fallback) it
|
|
6284
|
+
does nothing. As with the prop, a config without `annotate` is `onHostError`, not a throw. The
|
|
6285
|
+
handle is the same object for the component's life; a `PortholeView`'s is its own and reaches
|
|
6286
|
+
the frame it draws.
|
|
6287
|
+
|
|
6288
|
+
**Rejected.** Exposing the whole `DisplayHandle` through the ref: the binding owns the display's
|
|
6289
|
+
lifecycle (it is made and destroyed as frames near the screen, stop and run again), and a host
|
|
6290
|
+
holding it would call into a destroyed display or fight the props (`show`, `start`) the binding
|
|
6291
|
+
feeds it. `clearSelection` as a prop (a counter to bump): it is an event, not a state, and a ref
|
|
6292
|
+
says so. A `track` method on the handle: following is state the host keeps (which comment's card
|
|
6293
|
+
is open), so it is a prop, by value, like the marks.
|
|
6294
|
+
|
|
6295
|
+
Tested: `test/react-ssr.test.ts` (the prop's and the handle's types, exactly `clearSelection`;
|
|
6296
|
+
both render on the server, the ref unset there); `leak/react.spec.ts` "trackedAnnotation follows
|
|
6297
|
+
its mark through onAnnotation's `tracked`, and null stops it (P118)" (followed on mount, reports
|
|
6298
|
+
as the frame scrolls, none after `null`, again when set again, an unshown id told as a host error)
|
|
6299
|
+
and "a ref's clearSelection takes the frame's selection away; nothing without a display (P118)"
|
|
6300
|
+
(a text selection cleared, a frame not yet running and a config without `annotate`, the ref let
|
|
6301
|
+
go on unmount).
|
|
6302
|
+
|
|
6303
|
+
## P119 · 2026-10-29 · On touch, a marker's hit area is at least 44 by 44 px · Accepted
|
|
6304
|
+
|
|
6305
|
+
**Context.** A marker is a bubble about 34 by 18 CSS px (18 by 18 without a number), and the shell
|
|
6306
|
+
took a press only on that box: a finger a few px off landed on the paragraph under it. Raft's QA
|
|
6307
|
+
found that on phones a tap on a comment's marker often opened nothing. 44 px is the usual touch
|
|
6308
|
+
target. This is the hit-area half of porthole#42; checking taps on a real iOS Safari (the hover
|
|
6309
|
+
redraw) stays open there.
|
|
6310
|
+
|
|
6311
|
+
**Decision.** While touch is in use, each marker also takes the pointer in a box of at least 44 by
|
|
6312
|
+
44 CSS px centred on its bubble (its own size where the bubble is larger). The bubble looks the same.
|
|
6313
|
+
|
|
6314
|
+
- **Where.** In the shell's own layer, as an invisible `::before` on each marker (`.touch>.marker`,
|
|
6315
|
+
`max(100% + 2px, 44px)` square, centred). The browser's own hit test then gives the press to the
|
|
6316
|
+
layer, so it follows the path a press on the bubble takes today, unchanged: stopped in the shell's
|
|
6317
|
+
first window listener, read through the platform's getters, and reported `activated` only for a
|
|
6318
|
+
trusted click with the main button whose target is the layer, with the bubble's own box as
|
|
6319
|
+
`rect`. Nothing the page draws or sends can make a box like this, and the host's gate (transient
|
|
6320
|
+
activation, its own shown ids) is unchanged.
|
|
6321
|
+
- **When.** While the last trusted `pointerdown` or `pointermove` was a finger or a pen
|
|
6322
|
+
(`pointerType`, read through `PointerEvent.prototype`'s getter kept before content runs). Before
|
|
6323
|
+
any pointer is seen, while `(any-pointer: coarse)` matches (a phone, a tablet, a laptop with a touch
|
|
6324
|
+
screen). A mouse moves before it presses, so its first move takes the boxes away, and a mouse
|
|
6325
|
+
press is hit-tested on the bubbles alone, as before, even on a touch laptop. That is why
|
|
6326
|
+
`(pointer: coarse)` alone was not used: it describes the main pointer, so a touch laptop would
|
|
6327
|
+
never get the boxes. `(any-pointer: coarse)` alone was not used either: on that laptop a mouse
|
|
6328
|
+
would get them too. On Chromium, WebKit and Firefox under Playwright's `hasTouch`, both queries
|
|
6329
|
+
match (measured), so even the first tap gets the boxes.
|
|
6330
|
+
- **Which marker.** A point on a bubble is that bubble's (the topmost, as before). Otherwise, among
|
|
6331
|
+
the markers whose 44 px box holds the point, it is the one whose bubble's centre is nearest
|
|
6332
|
+
(`MARKER_HIT`, spliced into the runtime and unit-tested on its own). The CSS only decides whether
|
|
6333
|
+
the layer gets the press; the shell's own geometry decides which marker it is.
|
|
6334
|
+
|
|
6335
|
+
**Trade-off.** On touch, a tap within 13 px above or below a bubble (5 px beside a "1" bubble,
|
|
6336
|
+
13 px beside an empty one) is the marker's, not the page's. A marker in a line's gutter lies beside
|
|
6337
|
+
the line's end, so its box can cover a few px of the words on the lines above and below. A tap
|
|
6338
|
+
there opens the marker rather than reaching the paragraph. That is the point of a touch target.
|
|
6339
|
+
The page still gets every tap past the box (tested). A touch laptop's first finger after a mouse is
|
|
6340
|
+
hit-tested as the mouse left it (the boxes come with that finger's `pointerdown`, after the browser
|
|
6341
|
+
has already picked its target), so that one tap gets today's small target. A mouse resting
|
|
6342
|
+
unmoved over a box after a finger can click it: the boxes go with the mouse's next move.
|
|
6343
|
+
|
|
6344
|
+
**Rejected.** Taking the page's own events for a press near a marker (claiming a `pointerdown` on
|
|
6345
|
+
the paragraph, then its `click`). WebKit makes no click of a tap on an element without a click
|
|
6346
|
+
listener (P105), so the shell would have to report on `touchend` instead, a different path from a
|
|
6347
|
+
click's, and the page would already have heard the press begin. Enlarging the bubble itself: it
|
|
6348
|
+
would cover more of the words for everyone, mouse users included.
|
|
6349
|
+
|
|
6350
|
+
**No negative control.** This opens nothing and closes nothing: the press is still the trusted
|
|
6351
|
+
click on the shell's own layer that P105's controls (`marker-click`, `marker-prevent`,
|
|
6352
|
+
`marker-originals`) already hold. A weakening "no 44 px box" would be a missing feature, not a
|
|
6353
|
+
broken defense, and the probes below fail without the boxes (checked by turning them off).
|
|
6354
|
+
|
|
6355
|
+
**Investigated with it (Raft QA, porthole#42).** (1) After the page scrolls itself
|
|
6356
|
+
(`window.scrollBy`) and settles, under Chromium's iPhone 13 and Pixel 5: a tap or a mouse click at
|
|
6357
|
+
the bubble's centre does report `activated`. A hover redraw replaces no marker's node (P105 keeps
|
|
6358
|
+
them across draws), and the marker's node is under its bubble. `document.elementFromPoint` in the
|
|
6359
|
+
frame answers the layer, not the marker, by design: the layer's shadow root is closed. (2) An
|
|
6360
|
+
element's marker pinned at the frame's top once the element's start has scrolled above it takes a
|
|
6361
|
+
mouse click and a tap at its drawn pixels, on all three engines and on main before this change.
|
|
6362
|
+
Neither reproduced in Porthole's reference host. What QA saw is to be looked for in the viewer: a
|
|
6363
|
+
host element over the frame's top edge, a tap's point not in the page's own coordinates, a
|
|
6364
|
+
nested page's offset, or the host's guard on its view.
|
|
6365
|
+
|
|
6366
|
+
Tested: `test/annotate.test.ts` (the hit rule: on a bubble, 44 by 44 on touch only, the edges, a
|
|
6367
|
+
bubble wider than 44, the nearest of two, a bubble over a nearer centre); `leak/annotate.spec.ts`
|
|
6368
|
+
on Chromium, WebKit and Firefox (a touch screen, and Pixel 5 or iPhone 13): "on touch, a marker
|
|
6369
|
+
takes a tap a few px off its bubble (44 by 44), after the page scrolled itself…" (11 px below and
|
|
6370
|
+
above, 4 px beside, after a `scrollBy`, nothing heard by the content, 30 px off the page's own
|
|
6371
|
+
tap); "…two markers' 44 px boxes overlap, a tap is the nearest bubble's"; "a paragraph's marker
|
|
6372
|
+
pinned at the frame's top… takes a mouse click and a tap where it is drawn" (at its drawn
|
|
6373
|
+
pixels); "a mouse is as before…" (a click 11 px below or 4 px beside the bubble is the page's,
|
|
6374
|
+
with no touch and on a touch screen after a finger).
|
package/docs/DESIGN.md
CHANGED
|
@@ -741,7 +741,8 @@ binding is mounting and lifecycle (P034).
|
|
|
741
741
|
onContentError onHostError onResize onNavigated onNavigationBlocked onRefused onMuted
|
|
742
742
|
onInitialized onOutcome
|
|
743
743
|
fill? // fill the box and scroll inside, not grow with the content
|
|
744
|
-
annotating? annotations? focusedAnnotation? onAnnotation? // where annotate is declared
|
|
744
|
+
annotating? annotations? focusedAnnotation? trackedAnnotation? onAnnotation? // where annotate is declared
|
|
745
|
+
ref? // a PortholeFrameHandle: clearSelection() (P118)
|
|
745
746
|
aliases? themeKey? renderPlaceholder? eager? confirm? document? instance?
|
|
746
747
|
className? style? />
|
|
747
748
|
</PortholeProvider>
|
|
@@ -775,8 +776,10 @@ binding is mounting and lifecycle (P034).
|
|
|
775
776
|
overwrites a remembered height (the first host's frame jumped there).
|
|
776
777
|
- **Annotations** follow props: `annotating` (what the person may point at now, or
|
|
777
778
|
null), `annotations` (the marks), `focusedAnnotation` (each new id is brought into
|
|
778
|
-
view; `{ id, key }` with a new key focuses the same one again)
|
|
779
|
-
|
|
779
|
+
view; `{ id, key }` with a new key focuses the same one again), `trackedAnnotation`
|
|
780
|
+
(the mark followed, or null, P118); `onAnnotation` gets what the frame reported, `tracked`
|
|
781
|
+
boxes too. A frame that mounts again gets them all. A `ref` holds `clearSelection()` alone
|
|
782
|
+
(`PortholeFrameHandle`), a no-op while no display runs.
|
|
780
783
|
- **Errors** (P055): `onContentError` gets what the content did wrong (what it
|
|
781
784
|
threw, what the sandbox blocked, a navigation the shell stopped, that it kept
|
|
782
785
|
navigating away): the agent's to hear. `onNavigationBlocked` gets a stopped
|
|
@@ -1082,7 +1085,14 @@ chooses), and the annotation runtime is in the shell only then.
|
|
|
1082
1085
|
moves over it, are stopped in the shell's first window listener, read through the
|
|
1083
1086
|
platform's own functions kept before content runs (P105), and a trusted click is
|
|
1084
1087
|
reported `activated`; a tap too, on WebKit as well, since each marker has a click
|
|
1085
|
-
listener of its own (WebKit makes a tap a click only on such an element, P105).
|
|
1088
|
+
listener of its own (WebKit makes a tap a click only on such an element, P105). On
|
|
1089
|
+
touch (P119), while the last pointer down or moved was a finger or a pen (before any,
|
|
1090
|
+
where `(any-pointer: coarse)` matches), each marker also takes the pointer in a box of
|
|
1091
|
+
at least 44 by 44 px centred on its bubble (an invisible `::before` in the layer), the
|
|
1092
|
+
bubble itself unchanged; a press there is a press on the marker, and where two such
|
|
1093
|
+
boxes overlap it is the marker whose bubble's centre is nearest (on a bubble, that
|
|
1094
|
+
bubble). A mouse's move takes the boxes away, so a mouse is hit-tested on bubbles
|
|
1095
|
+
alone. Against content that patches none of the built-ins, none of
|
|
1086
1096
|
its handlers, nor what is under the marker, gets them; content that patches others
|
|
1087
1097
|
can reach the layer's nodes (P105). Either way the content can tell a press
|
|
1088
1098
|
happened, by `:active`, `relatedTarget` and user activation. Markers step aside
|
|
@@ -1436,10 +1446,10 @@ control the tables above name to the registry):
|
|
|
1436
1446
|
| `annotation-activated` | `annotate.spec.ts` | `a hostile page fakes a marker's click: the host takes it only for a mark it shows with a marker` | — | — |
|
|
1437
1447
|
| `annotation-activated-count` | `annotate.spec.ts` | `a hostile page fakes a marker's click: the host takes it only for a mark it shows with a marker` | — | — |
|
|
1438
1448
|
| `marker-trusted` | `annotate.spec.ts` | `a hostile page fakes a marker's click: the host takes it only for a mark it shows with a marker` | — | — |
|
|
1439
|
-
| `marker-click` | `annotate.spec.ts` | `markers: a mark with a count gets a numbered bubble; its click is reported and never reaches the content`, `a marker's press, of any kind, moves nothing of the content's: no handler, no focus, no selection`, `a page that patches the event's built-ins neither hears a marker's press nor stops its report (P105)`, `a tap on a marker is reported on every engine, and the content hears none of it (P105)`, `drafts (P107): a dashed line and a hollow marker with no number, apart from posted marks; their clicks are reported the same` | — | — |
|
|
1449
|
+
| `marker-click` | `annotate.spec.ts` | `markers: a mark with a count gets a numbered bubble; its click is reported and never reaches the content`, `a marker's press, of any kind, moves nothing of the content's: no handler, no focus, no selection`, `a page that patches the event's built-ins neither hears a marker's press nor stops its report (P105)`, `a tap on a marker is reported on every engine, and the content hears none of it (P105)`, `drafts (P107): a dashed line and a hollow marker with no number, apart from posted marks; their clicks are reported the same`, `on touch, a marker takes a tap a few px off its bubble (44 by 44), after the page scrolled itself; a tap past that is the page's (P119)`, `on touch, where two markers' 44 px boxes overlap, a tap is the nearest bubble's (P119)`, `a paragraph's marker pinned at the frame's top once its start scrolled away takes a mouse click and a tap where it is drawn (P119, porthole#42)` | — | — |
|
|
1440
1450
|
| `marker-prevent` | `annotate.spec.ts` | `a marker's press, of any kind, moves nothing of the content's: no handler, no focus, no selection` | — | — |
|
|
1441
1451
|
| `marker-place` | `annotate.spec.ts` | `text markers cover no word: on a column page, and on a phone's lines with one marker each (P105, #36)` | — | — |
|
|
1442
|
-
| `marker-tap` | `annotate.spec.ts` | nothing | WebKit: `a tap on a marker is reported on every engine, and the content hears none of it (P105)` | no probe can see it on Chromium and Firefox: they make a tap a click on the marker without a listener of its own (measured, P105) |
|
|
1452
|
+
| `marker-tap` | `annotate.spec.ts` | nothing | WebKit: `a tap on a marker is reported on every engine, and the content hears none of it (P105)`, `on touch, a marker takes a tap a few px off its bubble (44 by 44), after the page scrolled itself; a tap past that is the page's (P119)`, `on touch, where two markers' 44 px boxes overlap, a tap is the nearest bubble's (P119)`, `a paragraph's marker pinned at the frame's top once its start scrolled away takes a mouse click and a tap where it is drawn (P119, porthole#42)` | no probe can see it on Chromium and Firefox: they make a tap a click on the marker without a listener of its own (measured, P105) |
|
|
1443
1453
|
| `marker-originals` | `annotate.spec.ts` | `a page that patches the event's built-ins neither hears a marker's press nor stops its report (P105)` | — | — |
|
|
1444
1454
|
| `follow-throttle` | `annotate.spec.ts` | `an honest scroll session, long, in comment mode, leaves room for a marker's click: follow-ups, the selection's too, at most one a second` | — | — |
|
|
1445
1455
|
| `selection-follow` | `annotate.spec.ts` | `an honest scroll session, long, in comment mode, leaves room for a marker's click: follow-ups, the selection's too, at most one a second` | — | — |
|
package/docs/THREAT_MODEL.md
CHANGED
|
@@ -5,7 +5,7 @@ What Porthole protects, from whom, and where that protection ends. For each way
|
|
|
5
5
|
guaranteed. [ADOPTING.md](ADOPTING.md) says how to set each one up, and
|
|
6
6
|
[DESIGN.md](DESIGN.md) lists every defense with the test that proves it.
|
|
7
7
|
|
|
8
|
-
**Status.** This describes Porthole 0.14.
|
|
8
|
+
**Status.** This describes Porthole 0.14.3 (2026-10-29). A review on 2026-10-19 found gaps, and every decision it led to
|
|
9
9
|
has merged ([§8](#8-fixes-in-flight) lists them). P096 changed the negative-control runner and CI,
|
|
10
10
|
and the shipped conformance probes' messages and timing, not what they check. P104 (0.9.0's
|
|
11
11
|
annotation markers) had a review of its own, and P105, in 0.10.0, is what it led to. 0.11.0 was
|
|
@@ -679,7 +679,12 @@ own frame, below the shell, P111), so:
|
|
|
679
679
|
`marker-prevent`), so content can't act on it or cancel it; nor can it read or reach inside the
|
|
680
680
|
shell's layer (a closed shadow root). Content can still tell that a marker was pressed, and
|
|
681
681
|
roughly where: the pointer leaving its own element names the layer, the layer matches `:hover`
|
|
682
|
-
and `:active`, and the frame gets user activation.
|
|
682
|
+
and `:active`, and the frame gets user activation. On touch (P119), a marker is also the
|
|
683
|
+
44 by 44 px box around its bubble, drawn in that same layer: a tap there is a press on the
|
|
684
|
+
marker, with the same checks (a trusted click, the main button, on the layer), so the content
|
|
685
|
+
loses a tap within 13 px of a bubble (a few px of its words above and below it), as it loses
|
|
686
|
+
one on the bubble. Which pointer is used is read from trusted pointer events only; a page that
|
|
687
|
+
makes its own up changes nothing, and a real `activated` still needs a real click.
|
|
683
688
|
- *What doesn't hold against content that does.* The shell shares the content's realm. It reads
|
|
684
689
|
and stops a marker's press through the platform's own functions and getters, kept before
|
|
685
690
|
content runs (P105, control `marker-originals`), so patching `Event`'s or `MouseEvent`'s
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.14.
|
|
3
|
+
"version": "0.14.3",
|
|
4
4
|
"description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
|
|
5
5
|
"homepage": "https://github.com/botiverse/porthole#readme",
|
|
6
6
|
"bugs": {
|