@botiverse/porthole 0.14.1 → 0.14.2
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 +12 -0
- 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/docs/ADOPTING.md +19 -0
- package/docs/DECISIONS.md +41 -0
- package/docs/DESIGN.md +6 -3
- package/docs/THREAT_MODEL.md +1 -1
- 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/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,18 @@
|
|
|
4
4
|
section); the reasons for every change are in [docs/DECISIONS.md](docs/DECISIONS.md), by the
|
|
5
5
|
P-numbers below.
|
|
6
6
|
|
|
7
|
+
## 0.14.2
|
|
8
|
+
|
|
9
|
+
- **New (React, P118):** `PortholeFrame` and `PortholeView` take `trackedAnnotation` (a shown
|
|
10
|
+
mark's id, or `null`): by value, it follows that mark (`annotations.track`), its `tracked` boxes
|
|
11
|
+
reaching `onAnnotation`; `null` stops. And a `ref` (React 19's `ref` prop) holding a
|
|
12
|
+
`PortholeFrameHandle`, `{ clearSelection() }`: takes the frame's text selection away
|
|
13
|
+
(`annotations.clearSelection()`) where a display runs, nothing otherwise. Neither throws: an
|
|
14
|
+
unshown id, or a config without `annotate`, is `onHostError` (kind `"annotations"`). New export
|
|
15
|
+
from `/react`: `PortholeFrameHandle`.
|
|
16
|
+
- **Tests (P118):** `test/react-ssr.test.ts` (types, server render); `leak/react.spec.ts` (a mark
|
|
17
|
+
followed through the prop and stopped by `null`; the ref clearing a selection in the frame).
|
|
18
|
+
|
|
7
19
|
## 0.14.1
|
|
8
20
|
|
|
9
21
|
- **Security (P114, porthole#56's P1):** a nested page's shell, its page and the page's files are
|
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/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,44 @@ 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).
|
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
|
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.2 (2026-10-28). 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
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.14.
|
|
3
|
+
"version": "0.14.2",
|
|
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": {
|
package/src/react/frame.tsx
CHANGED
|
@@ -7,6 +7,7 @@ import {
|
|
|
7
7
|
useEffect,
|
|
8
8
|
useEffectEvent,
|
|
9
9
|
useId,
|
|
10
|
+
useImperativeHandle,
|
|
10
11
|
useLayoutEffect,
|
|
11
12
|
useMemo,
|
|
12
13
|
useRef,
|
|
@@ -15,6 +16,7 @@ import {
|
|
|
15
16
|
type CSSProperties,
|
|
16
17
|
type ReactElement,
|
|
17
18
|
type ReactNode,
|
|
19
|
+
type Ref,
|
|
18
20
|
} from "react";
|
|
19
21
|
import type { AnnotateMode, AnnotationMark, AnnotationReport } from "../annotate/types.ts";
|
|
20
22
|
import type {
|
|
@@ -480,6 +482,21 @@ export interface PlaceholderProps {
|
|
|
480
482
|
readonly run: () => void;
|
|
481
483
|
}
|
|
482
484
|
|
|
485
|
+
/**
|
|
486
|
+
* What a `ref` on `PortholeFrame` or `PortholeView` holds (P118): the display's few imperative
|
|
487
|
+
* calls, never the display itself. The same handle for the frame's whole life: its calls do
|
|
488
|
+
* nothing while no display runs (waiting to near the screen, stopped, a fallback drawn).
|
|
489
|
+
*/
|
|
490
|
+
export interface PortholeFrameHandle {
|
|
491
|
+
/**
|
|
492
|
+
* Takes the page's text selection away, and its highlight (`annotations.clearSelection()`,
|
|
493
|
+
* P115), once the host has used it (a comment posted, a draft added). No `unselected` follows.
|
|
494
|
+
* Nothing runs: nothing happens. A config without `annotate`: `onHostError`, kind
|
|
495
|
+
* `"annotations"` (the core's call throws; this never does).
|
|
496
|
+
*/
|
|
497
|
+
clearSelection(): void;
|
|
498
|
+
}
|
|
499
|
+
|
|
483
500
|
export interface PortholeFrameProps {
|
|
484
501
|
/** A preset's config. Keep it stable (module scope or memoized): a new one remounts the frame. */
|
|
485
502
|
readonly config: PortholeConfig;
|
|
@@ -606,6 +623,17 @@ export interface PortholeFrameProps {
|
|
|
606
623
|
| string
|
|
607
624
|
| { readonly id: string; readonly key: string | number }
|
|
608
625
|
| null;
|
|
626
|
+
/**
|
|
627
|
+
* The mark to follow (`annotations.track`, P112, P118): while it moves, `onAnnotation` gets
|
|
628
|
+
* `{ type: "tracked", id, rect }` at most once per animation frame, for it alone. `null` (or
|
|
629
|
+
* leaving it out once set) stops. By value: given when it changes, and when the display is made.
|
|
630
|
+
* Only a shown mark (`annotations`) is followed: another id, or a config without `annotate`, is
|
|
631
|
+
* `onHostError` (kind `"annotations"`), as the core's call throws. `annotations` without it
|
|
632
|
+
* stop the following, as the core's `show` does; it starts again once they have it back.
|
|
633
|
+
*/
|
|
634
|
+
readonly trackedAnnotation?: string | null;
|
|
635
|
+
/** The display's imperative calls (`PortholeFrameHandle`, P118): React 19's `ref` prop. */
|
|
636
|
+
readonly ref?: Ref<PortholeFrameHandle>;
|
|
609
637
|
/**
|
|
610
638
|
* What the frame reported: a selection (an anchor and where it is), its clearing, a cancelled
|
|
611
639
|
* pick, where marks are (again once a scroll settles: those that moved), a marker clicked
|
|
@@ -674,7 +702,29 @@ export function PortholeFrame(props: PortholeFrameProps): ReactElement {
|
|
|
674
702
|
() => live.state(key),
|
|
675
703
|
(): FrameState => "waiting",
|
|
676
704
|
);
|
|
677
|
-
const { eager } = props;
|
|
705
|
+
const { eager, ref: handleRef } = props;
|
|
706
|
+
// The running display (the Mount's), for the handle's calls; null while none runs.
|
|
707
|
+
const display = useRef<DisplayHandle | null>(null);
|
|
708
|
+
const running = useCallback((each: DisplayHandle | null) => {
|
|
709
|
+
display.current = each;
|
|
710
|
+
}, []);
|
|
711
|
+
// The props as of the last render, read when the handle is called (never during render).
|
|
712
|
+
const own = useRef(props);
|
|
713
|
+
useLayoutEffect(() => {
|
|
714
|
+
own.current = props;
|
|
715
|
+
});
|
|
716
|
+
useImperativeHandle(
|
|
717
|
+
handleRef,
|
|
718
|
+
(): PortholeFrameHandle => ({
|
|
719
|
+
clearSelection() {
|
|
720
|
+
const now = display.current;
|
|
721
|
+
if (now !== null) {
|
|
722
|
+
attempt(() => now.annotations.clearSelection(), own.current);
|
|
723
|
+
}
|
|
724
|
+
},
|
|
725
|
+
}),
|
|
726
|
+
[],
|
|
727
|
+
);
|
|
678
728
|
|
|
679
729
|
useEffect(() => {
|
|
680
730
|
const element = box.current;
|
|
@@ -743,6 +793,7 @@ export function PortholeFrame(props: PortholeFrameProps): ReactElement {
|
|
|
743
793
|
key={String(props.generation ?? 0)}
|
|
744
794
|
frame={props}
|
|
745
795
|
page={page}
|
|
796
|
+
running={running}
|
|
746
797
|
initialHeightPx={height}
|
|
747
798
|
placeholder={placeholder}
|
|
748
799
|
run={run}
|
|
@@ -757,6 +808,8 @@ export function PortholeFrame(props: PortholeFrameProps): ReactElement {
|
|
|
757
808
|
interface MountProps {
|
|
758
809
|
readonly frame: PortholeFrameProps;
|
|
759
810
|
readonly page: PageState;
|
|
811
|
+
/** Tells the frame which display runs now (null: none), for its handle. */
|
|
812
|
+
readonly running: (display: DisplayHandle | null) => void;
|
|
760
813
|
readonly initialHeightPx: number;
|
|
761
814
|
readonly placeholder: (props: PlaceholderProps) => ReactNode;
|
|
762
815
|
readonly run: () => void;
|
|
@@ -765,9 +818,19 @@ interface MountProps {
|
|
|
765
818
|
type AnyHandler = (args: unknown, context: CallContext) => unknown;
|
|
766
819
|
|
|
767
820
|
/** One running display: created when mounted, torn down when unmounted, fed as props change. */
|
|
768
|
-
function Mount({
|
|
821
|
+
function Mount({
|
|
822
|
+
frame,
|
|
823
|
+
page,
|
|
824
|
+
running,
|
|
825
|
+
initialHeightPx,
|
|
826
|
+
placeholder,
|
|
827
|
+
run,
|
|
828
|
+
}: MountProps): ReactElement {
|
|
769
829
|
const holder = useRef<HTMLDivElement>(null);
|
|
770
830
|
const handle = useRef<DisplayHandle | null>(null);
|
|
831
|
+
// The mark the display follows now, as the core keeps it (P118), and the prop as last seen.
|
|
832
|
+
const following = useRef<string | null>(null);
|
|
833
|
+
const asked = useRef<string | null>(null);
|
|
771
834
|
const [ready, setReady] = useState(false);
|
|
772
835
|
// The height this display started at: later reports don't make it start again.
|
|
773
836
|
const [startHeight] = useState(initialHeightPx);
|
|
@@ -969,6 +1032,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
|
|
|
969
1032
|
return;
|
|
970
1033
|
}
|
|
971
1034
|
handle.current = display;
|
|
1035
|
+
running(display);
|
|
972
1036
|
const events: (keyof DisplayEvents)[] = [
|
|
973
1037
|
"initialized",
|
|
974
1038
|
"resize",
|
|
@@ -989,12 +1053,24 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
|
|
|
989
1053
|
if (config.capabilities.annotate !== undefined) {
|
|
990
1054
|
applyAnnotations(display, first);
|
|
991
1055
|
}
|
|
1056
|
+
// The followed mark, once the marks are shown; without `annotate`, the core's error.
|
|
1057
|
+
following.current = null;
|
|
1058
|
+
const wanted = first.trackedAnnotation ?? null;
|
|
1059
|
+
asked.current = wanted;
|
|
1060
|
+
if (wanted !== null) {
|
|
1061
|
+
attempt(() => {
|
|
1062
|
+
display.annotations.track(wanted);
|
|
1063
|
+
following.current = wanted;
|
|
1064
|
+
}, first);
|
|
1065
|
+
}
|
|
992
1066
|
if (first.content !== undefined) {
|
|
993
1067
|
display.setContent(first.content, { partial: first.partial === true });
|
|
994
1068
|
}
|
|
995
1069
|
return () => {
|
|
996
1070
|
display.destroy();
|
|
997
1071
|
handle.current = null;
|
|
1072
|
+
running(null);
|
|
1073
|
+
following.current = null;
|
|
998
1074
|
};
|
|
999
1075
|
// A new display only for a new config, document or instance, or what the provider makes
|
|
1000
1076
|
// displays with (its nonce, hostInfo by value, whether it locates or confirms; generation, by
|
|
@@ -1017,6 +1093,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
|
|
|
1017
1093
|
hostInfo,
|
|
1018
1094
|
locate,
|
|
1019
1095
|
nonce,
|
|
1096
|
+
running,
|
|
1020
1097
|
]);
|
|
1021
1098
|
|
|
1022
1099
|
useEffect(() => {
|
|
@@ -1057,9 +1134,34 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
|
|
|
1057
1134
|
useEffect(() => {
|
|
1058
1135
|
const display = handle.current;
|
|
1059
1136
|
if (annotates && display !== null) {
|
|
1060
|
-
attempt(() =>
|
|
1137
|
+
attempt(() => {
|
|
1138
|
+
display.annotations.show(annotations ?? []);
|
|
1139
|
+
// A show without the followed mark stops the following (the core's own).
|
|
1140
|
+
if (following.current !== null && !shown(annotations, following.current)) {
|
|
1141
|
+
following.current = null;
|
|
1142
|
+
}
|
|
1143
|
+
}, latest());
|
|
1061
1144
|
}
|
|
1062
1145
|
}, [annotates, annotations]);
|
|
1146
|
+
// The followed mark follows its prop (after the marks above, so the two can change together).
|
|
1147
|
+
const trackedAnnotation = frame.trackedAnnotation ?? null;
|
|
1148
|
+
useEffect(() => {
|
|
1149
|
+
const display = handle.current;
|
|
1150
|
+
const changed = trackedAnnotation !== asked.current;
|
|
1151
|
+
asked.current = trackedAnnotation;
|
|
1152
|
+
if (display === null || trackedAnnotation === following.current) {
|
|
1153
|
+
return;
|
|
1154
|
+
}
|
|
1155
|
+
// Its mark was taken off (the error, if any, was told when the prop said it): followed again
|
|
1156
|
+
// once the marks have it back.
|
|
1157
|
+
if (!changed && trackedAnnotation !== null && !shown(annotations, trackedAnnotation)) {
|
|
1158
|
+
return;
|
|
1159
|
+
}
|
|
1160
|
+
attempt(() => {
|
|
1161
|
+
display.annotations.track(trackedAnnotation);
|
|
1162
|
+
following.current = trackedAnnotation;
|
|
1163
|
+
}, latest());
|
|
1164
|
+
}, [trackedAnnotation, annotations]);
|
|
1063
1165
|
useEffect(() => {
|
|
1064
1166
|
const display = handle.current;
|
|
1065
1167
|
const id = focusOf(latest().focusedAnnotation);
|
|
@@ -1161,6 +1263,11 @@ function useByValue<T>(value: T): T {
|
|
|
1161
1263
|
return useMemo(() => (key === "" ? undefined : JSON.parse(key)) as T, [key]);
|
|
1162
1264
|
}
|
|
1163
1265
|
|
|
1266
|
+
/** Whether `marks` has a mark `id`. */
|
|
1267
|
+
function shown(marks: readonly AnnotationMark[] | undefined, id: string): boolean {
|
|
1268
|
+
return (marks ?? []).some((mark) => mark.id === id);
|
|
1269
|
+
}
|
|
1270
|
+
|
|
1164
1271
|
/** The id `focusedAnnotation` names, if any. */
|
|
1165
1272
|
function focusOf(value: PortholeFrameProps["focusedAnnotation"]): string | null {
|
|
1166
1273
|
return typeof value === "string"
|
package/src/react/index.ts
CHANGED
package/src/react/view.tsx
CHANGED
|
@@ -2,6 +2,8 @@ import {
|
|
|
2
2
|
useCallback,
|
|
3
3
|
useContext,
|
|
4
4
|
useEffect,
|
|
5
|
+
useImperativeHandle,
|
|
6
|
+
useRef,
|
|
5
7
|
useState,
|
|
6
8
|
useSyncExternalStore,
|
|
7
9
|
type ReactElement,
|
|
@@ -11,7 +13,12 @@ import type { ColorScheme } from "../config/schema.ts";
|
|
|
11
13
|
import { frameFallback, type FrameFallback, type PortholeClient } from "../host/client.ts";
|
|
12
14
|
import type { FrameOutcome } from "../host/types.ts";
|
|
13
15
|
import type { InstanceRef } from "../isolation/types.ts";
|
|
14
|
-
import {
|
|
16
|
+
import {
|
|
17
|
+
PortholeFrame,
|
|
18
|
+
PortholeContext,
|
|
19
|
+
type PortholeFrameHandle,
|
|
20
|
+
type PortholeFrameProps,
|
|
21
|
+
} from "./frame.tsx";
|
|
15
22
|
|
|
16
23
|
/**
|
|
17
24
|
* The host kit's React side (P072): a display by its kind, served or opaque as the server says
|
|
@@ -91,7 +98,17 @@ function DefaultFallback({ title, message, link }: PortholeFallbackProps): React
|
|
|
91
98
|
export function PortholeView(props: PortholeViewProps): ReactElement | null {
|
|
92
99
|
const client = useClient();
|
|
93
100
|
const meta = useMeta(client);
|
|
94
|
-
const { display, instance, content, fallback, pending, onOutcome, ...frame } = props;
|
|
101
|
+
const { display, instance, content, fallback, pending, onOutcome, ref, ...frame } = props;
|
|
102
|
+
// The view's handle (P118) is there while the view is, a fallback drawn or not: its calls reach
|
|
103
|
+
// the frame's display when one runs, and do nothing otherwise.
|
|
104
|
+
const shown = useRef<PortholeFrameHandle>(null);
|
|
105
|
+
useImperativeHandle(
|
|
106
|
+
ref,
|
|
107
|
+
(): PortholeFrameHandle => ({
|
|
108
|
+
clearSelection: () => shown.current?.clearSelection(),
|
|
109
|
+
}),
|
|
110
|
+
[],
|
|
111
|
+
);
|
|
95
112
|
const [failed, setFailed] = useState<FrameFallback | null>(null);
|
|
96
113
|
const [generation, setGeneration] = useState(0);
|
|
97
114
|
const [link, setLink] = useState<string | null>(null);
|
|
@@ -145,6 +162,7 @@ export function PortholeView(props: PortholeViewProps): ReactElement | null {
|
|
|
145
162
|
return (
|
|
146
163
|
<PortholeFrame
|
|
147
164
|
{...frame}
|
|
165
|
+
ref={shown}
|
|
148
166
|
config={config}
|
|
149
167
|
generation={(frame.generation ?? 0) + generation}
|
|
150
168
|
{...(instance === undefined ? {} : { instance })}
|