@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 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
@@ -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
@@ -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(() => display.annotations.show(annotations ?? []), latest());
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"
@@ -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";
@@ -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); `onAnnotation` gets
779
- what the frame reported. A frame that mounts again gets them all.
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
@@ -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.1 (2026-10-28). A review on 2026-10-19 found gaps, and every decision it led to
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.1",
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": {
@@ -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({ frame, page, initialHeightPx, placeholder, run }: MountProps): ReactElement {
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(() => display.annotations.show(annotations ?? []), latest());
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"
@@ -13,6 +13,7 @@ export {
13
13
  PortholeFrame,
14
14
  PortholeProvider,
15
15
  type PlaceholderProps,
16
+ type PortholeFrameHandle,
16
17
  type PortholeFrameProps,
17
18
  type ConfirmActions,
18
19
  type PortholeProviderProps,
@@ -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 { PortholeFrame, PortholeContext, type PortholeFrameProps } from "./frame.tsx";
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 })}