@botiverse/porthole 0.1.3 → 0.1.5

package/dist/host/create-host.js

@@ -57,6 +57,16 @@ export function createHost(config, options = {}) {
                     listener(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) => {
+                emit("contentError", { message });
+                emit("error", { message, source: "content" });
+            };
+            const hostError = (message, kind) => {
+                emit("hostError", { message, kind });
+                emit("error", { message, source: "host" });
+            };
             let scheme = mount.scheme;
             let height = mount.initialHeightPx ?? 0;
             let surface = null;
@@ -228,7 +238,7 @@ export function createHost(config, options = {}) {
                         return;
                     }
                     case "error":
-                        emit("error", { message: event.message });
+                        contentError(event.message);
                         return;
                     case "refused":
                         emit("refused", { capability: event.capability, refusal: event.refusal });
@@ -260,8 +270,9 @@ export function createHost(config, options = {}) {
                     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 }),
                 });
@@ -327,9 +338,7 @@ export function createHost(config, options = {}) {
                     }
                     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.");
                     }
                 });
             };
@@ -345,6 +354,7 @@ export function createHost(config, options = {}) {
                         html: compiled.shellDocument({
                             origins: [container.ownerDocument.defaultView?.location.origin ?? ""],
                             title: mount.title,
+                            ...nonceOf(options.nonce),
                             ...(mount.document === undefined ? {} : { document: mount.document }),
                         }),
                     });
@@ -365,7 +375,9 @@ export function createHost(config, options = {}) {
                     }
                 }, (error) => {
                     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" });
                     }
                 });
             };
@@ -431,3 +443,8 @@ export function createHost(config, options = {}) {
         },
     };
 }
+/** The host's nonce option, read now (`HostOptions.nonce`). */
+function nonceOf(nonce) {
+    const value = typeof nonce === "function" ? nonce() : nonce;
+    return value === undefined || value === "" ? {} : { nonce: value };
+}

package/dist/host/types.d.ts

@@ -35,6 +35,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 {
     /** The host's id for this display: what its height is remembered by, and calls name. */
@@ -50,7 +57,21 @@ 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 = 
@@ -63,7 +84,9 @@ export type FrameBlock =
 /** Its app didn't answer. */
  | "upstream"
 /** The host's own check refused it (revoked, no longer a member): `code` says which. */
- | "denied" | "not-found" | "error";
+ | "denied"
+/** The host's locator failed (its backend down, access gone): see the `hostError` event. */
+ | "locate" | "not-found" | "error";
 /**
  * How a display's document went: it loaded (a shell or view finished its handshake; a url-mode
  * app's document loaded), it was blocked (and why), or nothing settled in
@@ -92,9 +115,28 @@ export interface DisplayEvents {
         readonly height: number;
         readonly width?: number;
     };
-    /** What the content threw, or what the sandbox blocked (its own words: untrusted). */
+    /**
+     * 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;

package/dist/index.d.ts

@@ -3,14 +3,15 @@
  * frame's policies, the shell, and the agent manual; the host mounts displays under it.
  */
 export { CAPABILITIES, CAPABILITY_NAMES, MAX_COPY_CHARS, capabilitySpec, isCapabilityName, type CapabilityArgs, type CapabilityName, type CapabilityResults, type CapabilitySpec, type Gate, type HandledCapability, } from "./config/capabilities.ts";
-export type { CapabilityConfig, CapabilityMap, ColorScheme, DisplayMode, EgressConfig, EmbedderConfig, GuideConfig, IsolationKind, LayoutConfig, Limits, PortholeConfig, ThemeConfig, ThemeValue, } from "./config/schema.ts";
+export type { CapabilityConfig, CapabilityMap, ColorScheme, DisplayMode, EgressConfig, EmbedderConfig, GuideConfig, IsolationKind, LayoutConfig, Limits, PortholeConfig, StorageConfig, ThemeConfig, ThemeValue, } from "./config/schema.ts";
+export { PASSIVE_KINDS, type PassiveKind } from "./config/schema.ts";
 export { BUILT_IN_TOPICS, ConfigError, isOriginSource, originSourceProblem, validateConfig, } from "./config/validate.ts";
 export { URL_PERMISSIONS, URL_SANDBOX_EXTRAS, type UrlPermission, type UrlSandboxExtra, } from "./config/schema.ts";
 export { hostOriginProblem, isHostOrigin } from "./isolation/served.ts";
 export { FRAME_STATUS_METHOD } from "./isolation/types.ts";
 export { LIBRARY_CDNS, presets, type PresetName, type PresetOptions, type UrlPresetOptions, } from "./presets/presets.ts";
 export { compile, type CompiledConfig } from "./compile/compile.ts";
-export { allEgressOrigins, declaredCapabilities, effectiveGates, egressOrigins, embedderCsp, type CspDirective, type EgressKind, } from "./compile/policy.ts";
+export { allEgressOrigins, anyHttps, declaredCapabilities, effectiveGates, egressOrigins, embedderCsp, embedderFrameSourcesOf, type CspDirective, type EgressKind, } from "./compile/policy.ts";
 export { shellPlan, type ShellPlan } from "./shell/plan.ts";
 export type { ShellDocumentOptions } from "./shell/document.ts";
 export { generateGuide, generateToolDescription, type BuiltInTopic, type GuideTopic, } from "./guide/guide.ts";

package/dist/index.js

@@ -4,6 +4,7 @@
  */
 // The config and its vocabulary.
 export { CAPABILITIES, CAPABILITY_NAMES, MAX_COPY_CHARS, capabilitySpec, isCapabilityName, } from "./config/capabilities.js";
+export { PASSIVE_KINDS } from "./config/schema.js";
 export { BUILT_IN_TOPICS, ConfigError, isOriginSource, originSourceProblem, validateConfig, } from "./config/validate.js";
 export { URL_PERMISSIONS, URL_SANDBOX_EXTRAS, } from "./config/schema.js";
 export { hostOriginProblem, isHostOrigin } from "./isolation/served.js";
@@ -12,7 +13,7 @@ export { FRAME_STATUS_METHOD } from "./isolation/types.js";
 export { LIBRARY_CDNS, presets, } from "./presets/presets.js";
 // The compiler.
 export { compile } from "./compile/compile.js";
-export { allEgressOrigins, declaredCapabilities, effectiveGates, egressOrigins, embedderCsp, } from "./compile/policy.js";
+export { allEgressOrigins, anyHttps, declaredCapabilities, effectiveGates, egressOrigins, embedderCsp, embedderFrameSourcesOf, } from "./compile/policy.js";
 export { shellPlan } from "./shell/plan.js";
 export { generateGuide, generateToolDescription, } from "./guide/guide.js";
 export { GUIDE_EXAMPLES } from "./guide/examples.js";

package/dist/presets/presets.d.ts

@@ -1,5 +1,5 @@
 import type { CapabilityName } from "../config/capabilities.ts";
-import type { CapabilityConfig, EgressConfig, EmbedderConfig, GuideConfig, IsolationKind, LayoutConfig, Limits, PortholeConfig, ThemeValue, UrlPermission, UrlSandboxExtra } from "../config/schema.ts";
+import type { CapabilityConfig, EgressConfig, EmbedderConfig, GuideConfig, IsolationKind, LayoutConfig, Limits, PortholeConfig, StorageConfig, ThemeValue, UrlPermission, UrlSandboxExtra } from "../config/schema.ts";
 /**
  * The preset policy layer (P001): named configs with safe defaults. Every preset starts with
  * egress closed and only the capabilities that carry nothing out of the frame (its size, its
@@ -30,6 +30,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. */
 export interface UrlPresetOptions {

package/dist/presets/presets.js

@@ -60,6 +60,10 @@ const mergeEgress = (base, extra) => {
             merged[kind] = origins;
         }
     }
+    const passive = [...new Set([...(base.anyHttps ?? []), ...(extra?.anyHttps ?? [])])];
+    if (passive.length > 0) {
+        merged.anyHttps = passive;
+    }
     return merged;
 };
 /** The default variables, with the host's changes and additions, less those it dropped (null). */
@@ -102,6 +106,7 @@ function build(mode, defaults, options) {
         guide: options.guide ?? {},
         contentOrigins: options.contentOrigins ?? [],
         embedder: options.embedder ?? {},
+        ...(options.storage === undefined ? {} : { storage: options.storage }),
     });
 }
 export const presets = {

package/dist/react/frame.d.ts

@@ -3,7 +3,7 @@ import type { AnnotateMode, AnnotationMark, AnnotationReport } from "../annotate
 import type { CapabilityHandlers, Confirm, Refusal } from "../bridge/types.ts";
 import type { CapabilityName } from "../config/capabilities.ts";
 import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
-import type { FrameOutcome } from "../host/types.ts";
+import type { FrameOutcome, HostErrorKind } from "../host/types.ts";
 import type { InstanceLocator, InstanceRef } from "../isolation/types.ts";
 /** The height a display holds before it has reported its own. */
 export declare const PLACEHOLDER_HEIGHT_PX = 96;
@@ -24,6 +24,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;
 }
 export declare function PortholeProvider(props: PortholeProviderProps): ReactElement;
@@ -60,12 +65,31 @@ 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;
@@ -94,8 +118,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.

package/dist/react/frame.js

@@ -39,15 +39,27 @@ export function PortholeProvider(props) {
         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((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(() => ({
         live,
         heights,
         confirm,
         copyText,
         ...(hostInfo === undefined ? {} : { hostInfo }),
-        ...(locator === undefined ? {} : { locator }),
-    }), [live, heights, confirm, copyText, hostInfo, locator]);
+        ...(locates ? { locate } : {}),
+        ...(nonce === undefined ? {} : { nonce }),
+    }), [live, heights, confirm, copyText, hostInfo, locates, locate, nonce]);
     const current = queue[0] ?? null;
     return (_jsxs(Page.Provider, { value: value, children: [props.children, props.confirm === undefined ? (_jsx(ConfirmDialog, { request: current?.request ?? null, ...(props.dialogClassName === undefined ? {} : { className: props.dialogClassName }), onAnswer: (accepted) => {
                     // A yes runs the effect inside this very click (a window it opens is the person's).
@@ -134,6 +146,8 @@ export function PortholeFrame(props) {
     return (_jsx("div", { ref: box, className: props.className, "data-porthole-display": props.displayId, "data-porthole-state": state, 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,
         }, 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 })) }));
@@ -145,8 +159,11 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
     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);
     const notify = useEffectEvent((event, detail) => {
@@ -161,9 +178,17 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
                 frame.onResize?.(size);
                 return;
             }
-            case "error":
-                frame.onError?.(detail.message);
+            case "contentError":
+                frame.onContentError?.(detail.message);
+                return;
+            case "hostError":
+                frame.onHostError?.(detail);
                 return;
+            case "error": {
+                const { message, source } = detail;
+                frame.onError?.(message, source);
+                return;
+            }
             case "navigated":
                 frame.onNavigated?.();
                 return;
@@ -220,7 +245,8 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
                     : {}),
                 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,
@@ -228,10 +254,11 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
                 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;
@@ -244,6 +271,8 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
             "muted",
             "outcome",
             "annotation",
+            "contentError",
+            "hostError",
         ];
         for (const event of events) {
             display.on(event, (detail) => notify(event, detail));
@@ -260,7 +289,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
         };
         // 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) {
             handle.current?.setContent(content, { partial: partial === true });
@@ -268,7 +297,15 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
     }, [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
         ? ""
         : JSON.stringify([annotating.elements ?? true, annotating.text ?? true]);
@@ -290,19 +327,27 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
     }, [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]);
+    // A flip or a restyle after the display was made: its first scheme and values went with it.
+    const [mountScheme] = useState(scheme);
+    const flipped = useRef(false);
     useEffect(() => {
-        handle.current?.setTheme(scheme);
-    }, [scheme]);
+        if (flipped.current || scheme !== mountScheme) {
+            flipped.current = true;
+            handle.current?.setTheme(scheme);
+        }
+    }, [scheme, mountScheme]);
     const { themeKey } = frame;
+    const [mountThemeKey] = useState(themeKey);
     useEffect(() => {
-        if (themeKey !== undefined) {
+        if (themeKey !== undefined && themeKey !== mountThemeKey) {
             handle.current?.refreshTheme();
         }
-    }, [themeKey]);
+    }, [themeKey, mountThemeKey]);
     return (_jsxs("div", { "data-porthole-ready": String(ready), style: {
             position: "relative",
             // A url-mode app fills the frame's box (give PortholeFrame a height); the rest size to content.
@@ -310,13 +355,19 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
             ...(ready ? {} : { minHeight: Math.max(startHeight, PLACEHOLDER_HEIGHT_PX) }),
         }, children: [_jsx("div", { ref: holder, "data-porthole-mount": "", style: { opacity: ready ? 1 : 0, ...(fills ? { height: "100%" } : {}) } }), ready ? null : placeholder({ state: "loading", title: frame.title, run })] }));
 }
-/** 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, error, kind) {
+    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, frame) {
     try {
         run();
     }
     catch (error) {
-        frame.onError?.(error instanceof Error ? error.message : String(error));
+        hostFailed(frame, error, "annotations");
     }
 }
 /** A new display's annotations, from the props as they are. */
@@ -325,11 +376,29 @@ function applyAnnotations(display, frame) {
         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(value) {
+    const key = value === undefined ? "" : JSON.stringify(value);
+    return useMemo(() => (key === "" ? undefined : JSON.parse(key)), [key]);
+}
+/** The id `focusedAnnotation` names, if any. */
+function focusOf(value) {
+    return typeof value === "string"
+        ? value
+        : value === null || value === undefined
+            ? null
+            : value.id;
+}

package/dist/server/naming.d.ts

@@ -15,3 +15,9 @@ export declare function isHostLabel(label: unknown): label is string;
  * than being folded into another scope's name.
  */
 export declare function prefixedName(prefix: string): (scope: string) => string;
+/**
+ * Whether a label is reserved (`ContentDomain.reserved`): a whole label, a prefix ending in `*`
+ * (`p-*`), or the host's own function. Entries are checked once, here; a function that throws
+ * reserves the label (fail closed: the request goes to the host's routes, never served as ours).
+ */
+export declare function reservedLabels(reserved: readonly string[] | ((label: string) => boolean) | undefined): (label: string) => boolean;

package/dist/server/naming.js

@@ -32,3 +32,41 @@ export function prefixedName(prefix) {
         return label;
     };
 }
+const PREFIX_ENTRY = /^[a-z0-9]([a-z0-9-]{0,61})?\*$/u;
+/**
+ * Whether a label is reserved (`ContentDomain.reserved`): a whole label, a prefix ending in `*`
+ * (`p-*`), or the host's own function. Entries are checked once, here; a function that throws
+ * reserves the label (fail closed: the request goes to the host's routes, never served as ours).
+ */
+export function reservedLabels(reserved) {
+    if (reserved === undefined) {
+        return () => false;
+    }
+    if (typeof reserved === "function") {
+        return (label) => {
+            try {
+                return reserved(label);
+            }
+            catch {
+                return true;
+            }
+        };
+    }
+    if (!Array.isArray(reserved)) {
+        throw new TypeError("content.reserved: a list of labels and prefixes, or a function");
+    }
+    const whole = new Set();
+    const prefixes = [];
+    for (const entry of reserved) {
+        if (typeof entry === "string" && PREFIX_ENTRY.test(entry)) {
+            prefixes.push(entry.slice(0, -1));
+        }
+        else if (isHostLabel(entry)) {
+            whole.add(entry);
+        }
+        else {
+            throw new TypeError(`content.reserved: ${JSON.stringify(entry)} is not a lowercase DNS label or a prefix ending in *`);
+        }
+    }
+    return (label) => whole.has(label) || prefixes.some((prefix) => label.startsWith(prefix));
+}

package/dist/server/pages.js

@@ -77,6 +77,8 @@ const pageHeaders = (frameAncestors, connect) => ({
     "content-security-policy": policy(frameAncestors, connect),
     "referrer-policy": "no-referrer",
     "x-content-type-options": "nosniff",
+    // Content origins are behind tickets: nothing on them is for search engines.
+    "x-robots-tag": "noindex, nofollow",
 });
 export function statusPage(status, title, detail, frameAncestors, method = "GET", reason = "error", hostOrigins = [], code) {
     const body = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${escape(title)}</title><style>${STYLE}</style></head><body><main data-porthole-status="${status}" data-porthole-reason="${escape(reason)}"${code === undefined ? "" : ` data-porthole-code="${escape(code)}"`} data-porthole-hosts="${escape(JSON.stringify(hostOrigins))}"><h1>${escape(title)}</h1><p>${escape(detail)}</p></main><script src="${STATUS_SCRIPT_PATH}"></script></body></html>`;