@botiverse/porthole 0.1.3 → 0.1.4

package/src/config/schema.ts

@@ -175,4 +175,16 @@ export interface PortholeConfig {
   readonly sandbox?: readonly UrlSandboxExtra[];
   /** Url mode only: features delegated to the frame (`URL_PERMISSIONS`); none by default. */
   readonly permissions?: readonly UrlPermission[];
+  /**
+   * Domain isolation: how far a display's storage reaches, for the manual. Storage is per origin,
+   * and the host picks each display's origin (`InstanceRef.scope`); a host that gives several
+   * displays one scope (all of a conversation's widgets) names it here (`{ shared:
+   * "conversation" }`), so the manual says storage is shared across it and keys need a prefix.
+   */
+  readonly storage?: StorageConfig;
+}
+
+export interface StorageConfig {
+  /** What the displays sharing one origin have in common, as a noun ("conversation"). */
+  readonly shared?: string;
 }

package/src/config/validate.ts

@@ -131,6 +131,7 @@ export function validateConfig(input: unknown): PortholeConfig {
       "embedder",
       "sandbox",
       "permissions",
+      "storage",
     ],
     "config",
   );
@@ -315,6 +316,20 @@ export function validateConfig(input: unknown): PortholeConfig {
     });
   }
 
+  if (config.storage !== undefined) {
+    const storage = object(config.storage, "config.storage");
+    only(storage, ["shared"], "config.storage");
+    if (config.isolation !== "domain") {
+      fail("config.storage", "only domain isolation keeps storage across displays");
+    }
+    if (
+      storage.shared !== undefined &&
+      (typeof storage.shared !== "string" || !/^[a-z][a-z -]{0,39}$/u.test(storage.shared))
+    ) {
+      fail("config.storage.shared", 'must be a short lowercase noun ("conversation")');
+    }
+  }
+
   if (config.permissions !== undefined) {
     if (config.mode !== "url") {
       fail("config.permissions", "only url mode may be delegated features");

package/src/conformance/served.ts

@@ -38,8 +38,17 @@ export interface ServedConformanceHost {
    * Shows `instance` in `page` as the host does: a fresh ticket from its backend, framed under
    * the config's sandbox, in an embedding page that sends the config's `embedderCsp`. The same page
    * may show several, one after another.
+   *
+   * For a served shell the suite gives `options.content`, a line of HTML: a host that speaks to
+   * the shell (`createHost`, the React binding) sends it as the display's content, since a shell
+   * draws nothing (and reports no height) until it has content, and the cases click inside it. A
+   * host whose frame has a height of its own may ignore it.
    */
-  show(page: Page, instance: InstanceRef): Promise<ServedDisplay>;
+  show(
+    page: Page,
+    instance: InstanceRef,
+    options?: { readonly content?: string },
+  ): Promise<ServedDisplay>;
   /** A fresh ticketed location for `instance`, as the host's backend issues it. */
   locate(instance: InstanceRef): Promise<FrameLocation>;
   /** Navigates `page` to a page on an origin that is not one of the host's, framing `url`. */
@@ -74,6 +83,9 @@ type Fixtures = { page: Page; browserName: string };
 
 const SETTLE_MS = 800;
 
+/** What a served shell is given to draw (`ServedConformanceHost.show`'s `content`). */
+const SHELL_CONTENT = '<p id="porthole-probe-content">Porthole conformance probe</p>';
+
 /** What the frame can see of its host: everything here must be closed to it. */
 async function reachIntoHost(frame: Frame): Promise<Record<string, string>> {
   return frame.evaluate(() => {
@@ -185,13 +197,16 @@ export function servedTests(
       ["domain", (scope: string) => host.shell(scope)],
       ["url", (scope: string) => host.app(scope)],
     ] as const;
+    // A served shell draws (and has a height to click in) once its host gives it content.
+    const showMode = (page: Page, mode: "domain" | "url", instance: InstanceRef) =>
+      host.show(page, instance, mode === "domain" ? { content: SHELL_CONTENT } : {});
 
     for (const [mode, instance] of modes) {
       define(
         `served.${mode}.origin`,
         "content runs on its own origin, never the host's",
         async ({ page }) => {
-          const display = await host.show(page, instance(`${mode}-origin`));
+          const display = await showMode(page, mode, instance(`${mode}-origin`));
           const frame = await display.frame();
           const origin = await frame.evaluate(() => window.origin);
           expect(origin).toBe(display.origin);
@@ -203,7 +218,7 @@ export function servedTests(
         `served.${mode}.no-reach`,
         "content can't reach the host's DOM, storage, cookies or URL",
         async ({ page }) => {
-          const display = await host.show(page, instance(`${mode}-reach`));
+          const display = await showMode(page, mode, instance(`${mode}-reach`));
           await plantHostSecrets(page);
           expect(await reachIntoHost(await display.frame())).toEqual(CLOSED);
         },
@@ -213,7 +228,7 @@ export function servedTests(
         `served.${mode}.no-top-navigation`,
         "content can't navigate the host's page, even after a click",
         async ({ page }) => {
-          const display = await host.show(page, instance(`${mode}-top`));
+          const display = await showMode(page, mode, instance(`${mode}-top`));
           const frame = await display.frame();
           const before = page.url();
           const target = await host.canary(`${mode}-top`);
@@ -246,7 +261,7 @@ export function servedTests(
         `served.${mode}.no-popups`,
         "content can't open a window, even after a click",
         async ({ page }) => {
-          const display = await host.show(page, instance(`${mode}-popup`));
+          const display = await showMode(page, mode, instance(`${mode}-popup`));
           const frame = await display.frame();
           const target = await host.canary(`${mode}-popup`);
           const opened: Page[] = [];
@@ -283,13 +298,13 @@ export function servedTests(
       "served.domain.storage-scope",
       "storage persists within a scope and is never shared across scopes",
       async ({ page }) => {
-        const first = await host.show(page, host.shell("scope-a"));
+        const first = await host.show(page, host.shell("scope-a"), { content: SHELL_CONTENT });
         await (await first.frame()).evaluate(() => localStorage.setItem("kept", "a"));
         await first.destroy();
-        const again = await host.show(page, host.shell("scope-a"));
+        const again = await host.show(page, host.shell("scope-a"), { content: SHELL_CONTENT });
         expect(await (await again.frame()).evaluate(() => localStorage.getItem("kept"))).toBe("a");
         expect(again.origin).toBe(first.origin);
-        const other = await host.show(page, host.shell("scope-b"));
+        const other = await host.show(page, host.shell("scope-b"), { content: SHELL_CONTENT });
         expect(other.origin).not.toBe(first.origin);
         expect(await (await other.frame()).evaluate(() => localStorage.getItem("kept"))).toBeNull();
       },
@@ -367,7 +382,7 @@ export function servedTests(
       "served.domain.egress",
       "the CSP in the document's headers closes egress",
       async ({ page }) => {
-        const display = await host.show(page, host.shell("egress"));
+        const display = await host.show(page, host.shell("egress"), { content: SHELL_CONTENT });
         const frame = await display.frame();
         const fetched = await frame.evaluate(
           async (url) => {

package/src/guide/guide.ts

@@ -368,7 +368,9 @@ function interactive(c: Context): string {
   const state =
     config.isolation === "opaque"
       ? `- State isn't saved: localStorage works but lasts only while the ${noun} is on screen, and a reload or another device starts fresh. Keep what matters in the ${noun}'s code.`
-      : `- localStorage is kept for this ${noun} in this browser; another device starts fresh.`;
+      : config.storage?.shared === undefined
+        ? `- localStorage is kept for this ${noun} in this browser; another device starts fresh.`
+        : `- localStorage is shared by every ${noun} in this ${config.storage.shared}, in this browser (another device starts fresh): prefix your keys with a name of this ${noun}'s own ("budget:filters", not "filters"), or ${noun}s overwrite each other.`;
   const none =
     entries.length === 0
       ? `- It can only draw: it has no way to send anything to you or the app.`

package/src/host/create-host.ts

@@ -26,6 +26,7 @@ import { shellAdapter } from "../protocol/shell-adapter.ts";
 import { resolveTheme } from "../theme/variables.ts";
 import type {
   AnnotationControls,
+  HostErrorKind,
   DisplayEvents,
   DisplayHandle,
   HostOptions,
@@ -96,6 +97,16 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
           (listener as (detail: DisplayEvents[E]) => void)(detail);
         }
       };
+      // What the content did wrong (the agent's to hear and fix), and what failed on the host's
+      // side (its own to handle), each on its own event and on `error` with its source.
+      const contentError = (message: string) => {
+        emit("contentError", { message });
+        emit("error", { message, source: "content" });
+      };
+      const hostError = (message: string, kind: HostErrorKind) => {
+        emit("hostError", { message, kind });
+        emit("error", { message, source: "host" });
+      };
 
       let scheme: ColorScheme = mount.scheme;
       let height = mount.initialHeightPx ?? 0;
@@ -277,7 +288,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
             return;
           }
           case "error":
-            emit("error", { message: event.message });
+            contentError(event.message);
             return;
           case "refused":
             emit("refused", { capability: event.capability, refusal: event.refusal });
@@ -311,8 +322,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
           allow: compiled.allow,
           referrerPolicy: compiled.referrerPolicy,
           colorScheme: scheme,
-          // An app reports no size: its frame fills the host's container, at least the minimum.
-          ...(speaks
+          // An app reports no size: its frame fills the host's container, at least the minimum;
+          // so does any display the host mounts to fill (its content scrolls inside).
+          ...(speaks && mount.fill !== true
             ? { initialHeightPx: height }
             : { fill: true, initialHeightPx: config.limits.minHeightPx }),
         });
@@ -377,9 +389,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
             run();
           } else {
             stop();
-            emit("error", {
-              message: "The content kept navigating its frame away; it was stopped.",
-            });
+            contentError("The content kept navigating its frame away; it was stopped.");
           }
         });
       };
@@ -396,6 +406,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
             html: compiled.shellDocument({
               origins: [container.ownerDocument.defaultView?.location.origin ?? ""],
               title: mount.title,
+              ...nonceOf(options.nonce),
               ...(mount.document === undefined ? {} : { document: mount.document }),
             }),
           });
@@ -418,7 +429,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
           },
           (error: unknown) => {
             if (mine === generation && !controller.signal.aborted) {
-              emit("error", { message: error instanceof Error ? error.message : String(error) });
+              // The host's own failure (its backend down, access gone): never the content's.
+              hostError(error instanceof Error ? error.message : String(error), "locate");
+              emit("outcome", { state: "blocked", reason: "locate" });
             }
           },
         );
@@ -488,3 +501,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
     },
   };
 }
+
+/** The host's nonce option, read now (`HostOptions.nonce`). */
+function nonceOf(nonce: HostOptions["nonce"]): { nonce?: string } {
+  const value = typeof nonce === "function" ? nonce() : nonce;
+  return value === undefined || value === "" ? {} : { nonce: value };
+}

package/src/host/types.ts

@@ -34,6 +34,13 @@ export interface HostOptions<C extends AdapterConnection = ShellConnection> {
   readonly platform?: PlatformHost;
   /** Required for domain and external isolation: where an instance's frame loads from. */
   readonly locator?: InstanceLocator;
+  /**
+   * The embedding page's CSP nonce, where its `script-src` is nonce-based (P054): an opaque frame
+   * (`srcdoc`) inherits the page's policy, so the shell and the content's scripts carry it. A
+   * function is read each time a frame starts (a page whose nonce changes). Served frames inherit
+   * nothing and need none.
+   */
+  readonly nonce?: string | (() => string | undefined);
 }
 
 export interface MountOptions {
@@ -50,8 +57,23 @@ export interface MountOptions {
   readonly document?: string;
   /** The height to start at, before the content reports its own. */
   readonly initialHeightPx?: number;
+  /**
+   * Fill the container (give it a height) instead of taking the content's height: the content
+   * scrolls inside its frame (an artifact viewer's page). The content's sizes are still reported
+   * (`resize`). A url-mode app always fills.
+   */
+  readonly fill?: boolean;
 }
 
+/** What failed on the host's side (`hostError`). */
+export type HostErrorKind =
+  /** The locator rejected: the host's backend didn't give a location. */
+  | "locate"
+  /** A display couldn't be made (the React binding: a bad config, a missing handler). */
+  | "mount"
+  /** An annotation call was refused (an invalid mark, an unknown id). */
+  | "annotations";
+
 /** What a display reports, by event name. */
 /** Why a display's frame showed nothing of its content (`FrameOutcome`). */
 export type FrameBlock =
@@ -65,6 +87,8 @@ export type FrameBlock =
   | "upstream"
   /** The host's own check refused it (revoked, no longer a member): `code` says which. */
   | "denied"
+  /** The host's locator failed (its backend down, access gone): see the `hostError` event. */
+  | "locate"
   | "not-found"
   | "error";
 
@@ -93,8 +117,21 @@ export interface DisplayEvents {
   readonly outcome: FrameOutcome;
   /** The content's size, after the config's limits. */
   readonly resize: { readonly height: number; readonly width?: number };
-  /** What the content threw, or what the sandbox blocked (its own words: untrusted). */
-  readonly error: { readonly message: string };
+  /**
+   * What the content did wrong: what it threw, what the sandbox blocked (its own words:
+   * untrusted), or that it kept navigating its frame away. The agent's to hear and fix.
+   */
+  readonly contentError: { readonly message: string };
+  /**
+   * What failed on the host's side (`kind`): its locator, for now. The host's to handle; never
+   * the agent's. The display's `outcome` says `blocked: locate` too.
+   */
+  readonly hostError: { readonly message: string; readonly kind: HostErrorKind };
+  /**
+   * Both of the above, with their `source`: for a host that listened here before they were
+   * split (0.1.3). Prefer `contentError` and `hostError`.
+   */
+  readonly error: { readonly message: string; readonly source: "content" | "host" };
   /** The content navigated its frame away; the frame was started again from its content. */
   readonly navigated: undefined;
   /** A call didn't run. */

package/src/index.ts

@@ -29,6 +29,7 @@ export type {
   LayoutConfig,
   Limits,
   PortholeConfig,
+  StorageConfig,
   ThemeConfig,
   ThemeValue,
 } from "./config/schema.ts";
@@ -65,6 +66,7 @@ export {
   effectiveGates,
   egressOrigins,
   embedderCsp,
+  embedderFrameSourcesOf,
   type CspDirective,
   type EgressKind,
 } from "./compile/policy.ts";

package/src/presets/presets.ts

@@ -9,6 +9,7 @@ import type {
   LayoutConfig,
   Limits,
   PortholeConfig,
+  StorageConfig,
   ThemeValue,
   UrlPermission,
   UrlSandboxExtra,
@@ -45,6 +46,8 @@ export interface PresetOptions {
   readonly isolation?: Exclude<IsolationKind, "external">;
   readonly contentOrigins?: readonly string[];
   readonly embedder?: EmbedderConfig;
+  /** Domain isolation: what displays sharing an origin share (`StorageConfig`), for the manual. */
+  readonly storage?: StorageConfig;
 }
 
 /** The url preset's options: where the app is served, and the embedding page's extra frames. */
@@ -174,6 +177,7 @@ function build(
     guide: options.guide ?? {},
     contentOrigins: options.contentOrigins ?? [],
     embedder: options.embedder ?? {},
+    ...(options.storage === undefined ? {} : { storage: options.storage }),
   });
 }
 

package/src/react/frame.tsx

@@ -29,7 +29,7 @@ import type { CapabilityName } from "../config/capabilities.ts";
 import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
 import { writeClipboard } from "../host/clipboard.ts";
 import { createHost } from "../host/create-host.ts";
-import type { DisplayEvents, DisplayHandle, FrameOutcome } from "../host/types.ts";
+import type { DisplayEvents, DisplayHandle, FrameOutcome, HostErrorKind } from "../host/types.ts";
 import type { InstanceLocator, InstanceRef } from "../isolation/types.ts";
 import { ConfirmDialog } from "./dialog.tsx";
 import { createLiveFrames, type FrameState, type LiveFrames } from "./live.ts";
@@ -53,7 +53,9 @@ interface PageState {
   readonly heights: Map<string, number>;
   readonly confirm?: Confirm;
   readonly hostInfo?: { readonly name: string; readonly version: string };
-  readonly locator?: InstanceLocator;
+  readonly nonce?: string;
+  /** The provider's locator, read when a frame locates (so an inline one restarts nothing). */
+  readonly locate?: InstanceLocator["locate"];
   /** The default `copyText`: copies on the host's page and shows the toast (P052). */
   readonly copyText?: CapabilityHandler<"copyText">;
 }
@@ -77,6 +79,11 @@ export interface PortholeProviderProps {
   readonly dialogClassName?: string;
   /** A class for the default copy toast, to restyle it. */
   readonly toastClassName?: string;
+  /**
+   * The page's CSP nonce, where its `script-src` is nonce-based: opaque frames inherit the page's
+   * policy, so their shell carries it (P054).
+   */
+  readonly nonce?: string;
   readonly children?: ReactNode;
 }
 
@@ -113,7 +120,22 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
     return copied;
   }, []);
   const closeNotice = useCallback(() => setNotice(null), []);
-  const { hostInfo, locator } = props;
+  // Compared by value, and read when used: an inline hostInfo or locator doesn't start every
+  // frame again on each render.
+  const hostInfo = useByValue(props.hostInfo);
+  const ownLocator = useRef(props.locator);
+  useLayoutEffect(() => {
+    ownLocator.current = props.locator;
+  });
+  const locate = useCallback<InstanceLocator["locate"]>(
+    (instance, signal) =>
+      ownLocator.current === undefined
+        ? Promise.reject(new Error("No locator (PortholeProvider.locator)"))
+        : ownLocator.current.locate(instance, signal),
+    [],
+  );
+  const locates = props.locator !== undefined;
+  const { nonce } = props;
   const value = useMemo<PageState>(
     () => ({
       live,
@@ -121,9 +143,10 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
       confirm,
       copyText,
       ...(hostInfo === undefined ? {} : { hostInfo }),
-      ...(locator === undefined ? {} : { locator }),
+      ...(locates ? { locate } : {}),
+      ...(nonce === undefined ? {} : { nonce }),
     }),
-    [live, heights, confirm, copyText, hostInfo, locator],
+    [live, heights, confirm, copyText, hostInfo, locates, locate, nonce],
   );
   const current = queue[0] ?? null;
   return (
@@ -192,9 +215,28 @@ export interface PortholeFrameProps {
   readonly generation?: number;
   /** Run at once, without waiting to near the screen (it still counts toward the page's most). */
   readonly eager?: boolean;
+  /**
+   * Fill the box (give it, or its parent, a height) and let the content scroll inside, instead of
+   * growing with the content: an artifact viewer's page. A url-mode app always fills.
+   */
+  readonly fill?: boolean;
   readonly onInitialized?: () => void;
   readonly onResize?: (size: { readonly height: number; readonly width?: number }) => void;
-  readonly onError?: (message: string) => void;
+  /**
+   * What the content did wrong (what it threw, what the sandbox blocked, that it kept navigating
+   * away): the agent's to hear and fix.
+   */
+  readonly onContentError?: (message: string) => void;
+  /**
+   * What failed on the host's side: its locator (`locate`), a display that couldn't be made
+   * (`mount`), an annotation call refused (`annotations`). Never the agent's.
+   */
+  readonly onHostError?: (error: {
+    readonly message: string;
+    readonly kind: HostErrorKind;
+  }) => void;
+  /** Both, with their source (as before 0.1.4). Prefer `onContentError` and `onHostError`. */
+  readonly onError?: (message: string, source: "content" | "host") => void;
   /** The content navigated its frame away; it was started again (or stopped, after a few). */
   readonly onNavigated?: () => void;
   readonly onRefused?: (capability: CapabilityName, refusal: Refusal) => void;
@@ -223,8 +265,14 @@ export interface PortholeFrameProps {
   readonly annotating?: AnnotateMode | null;
   /** The anchors to mark in the frame (the host's comments). Keep it stable (memoized). */
   readonly annotations?: readonly AnnotationMark[];
-  /** The mark to bring into view and make the active one; each new id focuses it. */
-  readonly focusedAnnotation?: string | null;
+  /**
+   * The mark to bring into view and make the active one; each new id focuses it. To focus the
+   * same mark again (a second click on its comment), give `{ id, key }` with a new key.
+   */
+  readonly focusedAnnotation?:
+    | string
+    | { readonly id: string; readonly key: string | number }
+    | null;
   /**
    * What the frame reported: a selection (an anchor and where it is), its clearing, a cancelled
    * pick, where marks are. The content's word: UI hints, never permissions.
@@ -343,6 +391,8 @@ export function PortholeFrame(props: PortholeFrameProps): ReactElement {
       style={{
         position: "relative",
         width: "100%",
+        // A display that fills takes its parent's height (the host sizes the parent, or this box).
+        ...(props.fill === true || props.config.mode === "url" ? { height: "100%" } : {}),
         ...(state === "running" ? {} : { minHeight: Math.max(height, PLACEHOLDER_HEIGHT_PX) }),
         ...props.style,
       }}
@@ -380,8 +430,11 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
   const [ready, setReady] = useState(false);
   // The height this display started at: later reports don't make it start again.
   const [startHeight] = useState(initialHeightPx);
-  const { config, document: view, instance, content, partial, scheme } = frame;
-  const fills = config.mode === "url";
+  const { document: view, content, partial, scheme } = frame;
+  // By value: a config or instance made inline (each render) is the same display.
+  const config = useByValue(frame.config);
+  const instance = useByValue(frame.instance);
+  const fills = config.mode === "url" || frame.fill === true;
 
   // The latest props, read when the display calls back (never during render).
   const latest = useEffectEvent(() => frame);
@@ -398,9 +451,17 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
           frame.onResize?.(size);
           return;
         }
-        case "error":
-          frame.onError?.((detail as DisplayEvents["error"]).message);
+        case "contentError":
+          frame.onContentError?.((detail as DisplayEvents["contentError"]).message);
+          return;
+        case "hostError":
+          frame.onHostError?.(detail as DisplayEvents["hostError"]);
           return;
+        case "error": {
+          const { message, source } = detail as DisplayEvents["error"];
+          frame.onError?.(message, source);
+          return;
+        }
         case "navigated":
           frame.onNavigated?.();
           return;
@@ -468,7 +529,8 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
           : {}),
         theme: (each) => latest().theme?.(each) ?? {},
         ...(page.hostInfo === undefined ? {} : { hostInfo: page.hostInfo }),
-        ...(page.locator === undefined ? {} : { locator: page.locator }),
+        ...(page.locate === undefined ? {} : { locator: { locate: page.locate } }),
+        ...(page.nonce === undefined ? {} : { nonce: page.nonce }),
       }).mount(container, {
         displayId: first.displayId,
         title: first.title,
@@ -476,9 +538,10 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
         initialHeightPx: startHeight,
         ...(view === undefined ? {} : { document: view }),
         ...(instance === undefined ? {} : { instance }),
+        ...(fills ? { fill: true } : {}),
       });
     } catch (error) {
-      first.onError?.(error instanceof Error ? error.message : String(error));
+      hostFailed(first, error, "mount");
       return;
     }
     handle.current = display;
@@ -491,6 +554,8 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
       "muted",
       "outcome",
       "annotation",
+      "contentError",
+      "hostError",
     ];
     for (const event of events) {
       display.on(event, (detail) => notify(event, detail));
@@ -507,7 +572,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
     };
     // A new display only for a new config, document, instance or page (or generation, by key);
     // content, theme, handlers, id and title are fed to the running one.
-  }, [config, view, instance, page, startHeight]);
+  }, [config, view, instance, page, startHeight, fills]);
 
   useEffect(() => {
     if (content !== undefined) {
@@ -516,7 +581,16 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
   }, [content, partial]);
   // Annotations follow their props (a new display gets them all when it is made, above).
   const annotates = config.capabilities.annotate !== undefined;
-  const { annotating, annotations, focusedAnnotation } = frame;
+  const { annotating } = frame;
+  const focusedAnnotation = focusOf(frame.focusedAnnotation);
+  const focusToken =
+    focusedAnnotation === null
+      ? ""
+      : typeof frame.focusedAnnotation === "object" && frame.focusedAnnotation !== null
+        ? JSON.stringify([frame.focusedAnnotation.id, frame.focusedAnnotation.key])
+        : JSON.stringify([focusedAnnotation]);
+  // By value: the same marks given again don't mark them again.
+  const annotations = useByValue(frame.annotations);
   const mode =
     annotating === undefined || annotating === null
       ? ""
@@ -543,10 +617,11 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
   }, [annotates, annotations]);
   useEffect(() => {
     const display = handle.current;
-    if (annotates && display !== null && typeof focusedAnnotation === "string") {
-      attempt(() => display.annotations.focus(focusedAnnotation), latest());
+    const id = focusOf(latest().focusedAnnotation);
+    if (annotates && display !== null && focusToken !== "" && id !== null) {
+      attempt(() => display.annotations.focus(id), latest());
     }
-  }, [annotates, focusedAnnotation]);
+  }, [annotates, focusToken]);
   useEffect(() => {
     handle.current?.setTheme(scheme);
   }, [scheme]);
@@ -577,12 +652,19 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
   );
 }
 
-/** Runs an annotation call, telling the frame's `onError` what it threw (a bad anchor, say). */
+/** Tells the frame's props what failed on the host's side. */
+function hostFailed(frame: PortholeFrameProps, error: unknown, kind: HostErrorKind): void {
+  const message = error instanceof Error ? error.message : String(error);
+  frame.onHostError?.({ message, kind });
+  frame.onError?.(message, "host");
+}
+
+/** Runs an annotation call, telling the frame's props what it threw (a bad anchor, say). */
 function attempt(run: () => void, frame: PortholeFrameProps): void {
   try {
     run();
   } catch (error) {
-    frame.onError?.(error instanceof Error ? error.message : String(error));
+    hostFailed(frame, error, "annotations");
   }
 }
 
@@ -592,11 +674,31 @@ function applyAnnotations(display: DisplayHandle, frame: PortholeFrameProps): vo
     if (frame.annotations !== undefined && frame.annotations.length > 0) {
       display.annotations.show(frame.annotations);
     }
-    if (typeof frame.focusedAnnotation === "string") {
-      display.annotations.focus(frame.focusedAnnotation);
+    const focused = focusOf(frame.focusedAnnotation);
+    if (focused !== null) {
+      display.annotations.focus(focused);
     }
     if (frame.annotating !== undefined && frame.annotating !== null) {
       display.annotations.start(frame.annotating);
     }
   }, frame);
 }
+
+/**
+ * `value` as long as it is equal by value (as JSON): plain data a host builds inline on each
+ * render (a config, an instance, marks, hostInfo) keeps one identity, so effects keyed on it run
+ * only when it really changes.
+ */
+function useByValue<T>(value: T): T {
+  const key = value === undefined ? "" : JSON.stringify(value);
+  return useMemo(() => (key === "" ? undefined : JSON.parse(key)) as T, [key]);
+}
+
+/** The id `focusedAnnotation` names, if any. */
+function focusOf(value: PortholeFrameProps["focusedAnnotation"]): string | null {
+  return typeof value === "string"
+    ? value
+    : value === null || value === undefined
+      ? null
+      : value.id;
+}