@botiverse/porthole 0.1.2 → 0.1.4

package/dist/host/create-host.js

@@ -1,3 +1,5 @@
+import { ANNOTATE_METHODS, } from "../annotate/types.js";
+import { annotateMode, checkMarks, parseReport } from "../annotate/validate.js";
 import { createBridge } from "../bridge/bridge.js";
 import { compile } from "../compile/compile.js";
 import { declaredCapabilities } from "../compile/policy.js";
@@ -13,6 +15,14 @@ const DEFAULT_LOAD_TIMEOUT_MS = 15_000;
 /** How many times a display is started again after its content navigated its frame away. */
 const MAX_RESTARTS = 3;
 const BASE_KEYS = new Set(["hostContextChanged", "teardown", "close"]);
+/** The frame's annotation reports, by method. */
+const REPORTS = {
+    [ANNOTATE_METHODS.selected]: "selected",
+    [ANNOTATE_METHODS.unselected]: "unselected",
+    [ANNOTATE_METHODS.cancelled]: "cancelled",
+    [ANNOTATE_METHODS.anchored]: "anchored",
+};
+const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 const STANDARD = new Set(MCP_APPS_STYLE_VARIABLES);
 /**
  * Compiles `config` once and returns a host that mounts displays under it. Throws a `ConfigError`
@@ -47,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;
@@ -60,6 +80,125 @@ export function createHost(config, options = {}) {
             const view = container.ownerDocument.defaultView;
             // The adapter's own operations, the last call of each, replayed into every new frame.
             const replay = new Map();
+            // Annotations: the host's state, given to each frame once it finished its handshake.
+            const annotates = config.capabilities.annotate !== undefined;
+            let annotating = null;
+            let marks = [];
+            let activeMark = null;
+            let handshaken = false;
+            const toFrame = (method, params) => {
+                if (handshaken && surface !== null) {
+                    surface.transport.send({ jsonrpc: "2.0", method, params });
+                }
+            };
+            const giveAnnotations = () => {
+                if (marks.length > 0) {
+                    toFrame(ANNOTATE_METHODS.show, {
+                        marks,
+                        ...(activeMark === null ? {} : { active: activeMark }),
+                    });
+                }
+                if (annotating !== null) {
+                    toFrame(ANNOTATE_METHODS.start, { ...annotating });
+                }
+            };
+            /**
+             * A report from the frame: checked, taken only while the host asked for it (a selection
+             * only in select mode, results only for its own marks), then through the bridge's gates.
+             */
+            const onAnnotation = (raw, bridge) => {
+                if (!isRecord(raw) ||
+                    raw.jsonrpc !== "2.0" ||
+                    "id" in raw ||
+                    typeof raw.method !== "string") {
+                    return;
+                }
+                const type = REPORTS[raw.method];
+                if (type === undefined) {
+                    return;
+                }
+                let report = parseReport({ ...(isRecord(raw.params) ? raw.params : {}), type });
+                if (report === null) {
+                    void bridge.call("annotate", null);
+                    return;
+                }
+                switch (report.type) {
+                    case "selected": {
+                        const kind = report.anchor.kind;
+                        if (annotating === null ||
+                            !(kind === "element" ? annotating.elements : annotating.text)) {
+                            return;
+                        }
+                        if (kind === "element") {
+                            annotating = annotating.text ? { elements: false, text: true } : null;
+                        }
+                        break;
+                    }
+                    case "unselected":
+                        if (annotating?.text !== true) {
+                            return;
+                        }
+                        break;
+                    case "cancelled":
+                        if (annotating?.elements !== true) {
+                            return;
+                        }
+                        annotating = annotating.text ? { elements: false, text: true } : null;
+                        break;
+                    case "anchored": {
+                        const known = new Set(marks.map((mark) => mark.id));
+                        const results = report.results.filter((result) => known.has(result.id));
+                        if (results.length === 0) {
+                            return;
+                        }
+                        report = { type: "anchored", results };
+                        break;
+                    }
+                }
+                void bridge.call("annotate", report);
+            };
+            const needsAnnotate = (operation) => {
+                if (!annotates) {
+                    throw new TypeError(`annotations.${operation}: the config doesn't declare annotate`);
+                }
+            };
+            const annotations = {
+                start(mode) {
+                    needsAnnotate("start");
+                    annotating = annotateMode(mode);
+                    toFrame(ANNOTATE_METHODS.start, { ...annotating });
+                },
+                stop() {
+                    needsAnnotate("stop");
+                    annotating = null;
+                    toFrame(ANNOTATE_METHODS.stop, {});
+                },
+                show(next) {
+                    needsAnnotate("show");
+                    marks = checkMarks(next);
+                    if (activeMark !== null && !marks.some((mark) => mark.id === activeMark)) {
+                        activeMark = null;
+                    }
+                    toFrame(ANNOTATE_METHODS.show, {
+                        marks,
+                        ...(activeMark === null ? {} : { active: activeMark }),
+                    });
+                },
+                focus(id) {
+                    needsAnnotate("focus");
+                    if (!marks.some((mark) => mark.id === id)) {
+                        throw new TypeError(`annotations.focus: no mark ${JSON.stringify(id)} is shown`);
+                    }
+                    activeMark = id;
+                    toFrame(ANNOTATE_METHODS.focus, { id });
+                },
+                clear() {
+                    needsAnnotate("clear");
+                    marks = [];
+                    activeMark = null;
+                    toFrame(ANNOTATE_METHODS.clear, {});
+                },
+            };
             const hostContext = () => {
                 const width = container.getBoundingClientRect().width;
                 // The spec's names in `styles` (the App SDK refuses others there), the rest in our field.
@@ -99,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 });
@@ -107,9 +246,13 @@ export function createHost(config, options = {}) {
                     case "muted":
                         emit("muted", undefined);
                         return;
+                    case "annotation":
+                        emit("annotation", event.report);
+                        return;
                 }
             };
             const stop = () => {
+                handshaken = false;
                 abort?.abort();
                 abort = null;
                 outcomeWatch?.stop();
@@ -127,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 }),
                 });
@@ -160,6 +304,9 @@ export function createHost(config, options = {}) {
                     userActivation: () => created.userActivation(),
                     onEvent: onBridge,
                 });
+                if (annotates) {
+                    created.transport.listen((raw) => onAnnotation(raw, bridge));
+                }
                 const opened = adapter.connect({
                     display: { id: mount.displayId, title: mount.title },
                     compiled,
@@ -170,6 +317,10 @@ export function createHost(config, options = {}) {
                     emit: (event) => {
                         if (event.type === "initialized") {
                             watch.initialized();
+                            if (!handshaken) {
+                                handshaken = true;
+                                giveAnnotations();
+                            }
                             emit("initialized", undefined);
                         }
                     },
@@ -187,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.");
                     }
                 });
             };
@@ -205,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 }),
                         }),
                     });
@@ -225,13 +375,16 @@ 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" });
                     }
                 });
             };
             run();
             const controls = {
                 displayId: mount.displayId,
+                annotations,
                 setTheme(next) {
                     scheme = next;
                     surface?.setColorScheme(next);
@@ -290,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

@@ -1,3 +1,4 @@
+import type { AnnotateMode, AnnotationMark, AnnotationReport } from "../annotate/types.ts";
 import type { Confirm, CapabilityHandlers, Refusal } from "../bridge/types.ts";
 import type { CompiledConfig } from "../compile/compile.ts";
 import type { CapabilityName } from "../config/capabilities.ts";
@@ -34,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. */
@@ -49,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 = 
@@ -62,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
@@ -91,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;
@@ -104,6 +147,27 @@ export interface DisplayEvents {
     };
     /** Too many declines: the display stops asking until it runs again. */
     readonly muted: undefined;
+    /**
+     * What the frame reported about annotations (`annotate`, P053), checked and taken only while
+     * the host asked for it: a selection, its clearing, a cancelled pick, where marks are. The
+     * content's word: UI hints, never permissions.
+     */
+    readonly annotation: AnnotationReport;
+}
+/**
+ * Annotations on a display whose config declares `annotate` (P053). The host's state is kept and
+ * given to every frame the display runs (a reload, a navigation recovered from).
+ */
+export interface AnnotationControls {
+    /** Lets the person point at elements, select text, or both (default both). */
+    start(mode?: AnnotateMode): void;
+    stop(): void;
+    /** Marks these anchors (replacing the marks before); the frame reports where they are. */
+    show(marks: readonly AnnotationMark[]): void;
+    /** Brings a mark into view in the frame and makes it the active one. */
+    focus(id: string): void;
+    /** Removes every mark. */
+    clear(): void;
 }
 export interface DisplayControls {
     readonly displayId: string;
@@ -115,6 +179,8 @@ export interface DisplayControls {
     /** The host's theme values changed (same scheme): read them now and re-theme the frame. */
     refreshTheme(): void;
     on<E extends keyof DisplayEvents>(event: E, listener: (detail: DisplayEvents[E]) => void): () => void;
+    /** Annotations (`annotate`): throws on use where the config doesn't declare it. */
+    readonly annotations: AnnotationControls;
     /** Runs the content again from the start, in a new frame. */
     reload(): void;
     /** Tears the view down and removes the frame. */

package/dist/index.d.ts

@@ -2,15 +2,15 @@
  * `@botiverse/porthole`: the framework-agnostic core. One config (a preset's) compiles into the
  * frame's policies, the shell, and the agent manual; the host mounts displays under it.
  */
-export { CAPABILITIES, CAPABILITY_NAMES, 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 { 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, StorageConfig, ThemeConfig, ThemeValue, } 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, 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";
@@ -20,7 +20,10 @@ export type { FrameLocation, FrameSource, InstanceLocator, InstanceRef, ServedDo
 export type { PlatformHost, Surface, SurfaceSpec } from "./platform/types.ts";
 export type { Transport } from "./transport/types.ts";
 export type { AdapterConnection, AdapterEvent, AdapterSession, ProtocolAdapter, ShellConnection, } from "./protocol/adapter.ts";
-export { MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS_STYLE_VARIABLES, PORTHOLE_STYLES, type HostContext, } from "./protocol/mcp-apps.ts";
+export { COPY_TEXT_METHOD, MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS_STYLE_VARIABLES, PORTHOLE_STYLES, type HostContext, } from "./protocol/mcp-apps.ts";
 export type { CallContext, CallOutcome, CapabilityHandler, CapabilityHandlers, Confirm, ConfirmAnswer, ConfirmRequest, Proceed, HostFunctionBridge, Refusal, } from "./bridge/types.ts";
 export { createHost } from "./host/create-host.ts";
-export type { DisplayControls, DisplayEvents, FrameBlock, FrameOutcome, DisplayHandle, HostOptions, MountOptions, PortholeHost, } from "./host/types.ts";
+export { writeClipboard } from "./host/clipboard.ts";
+export type { AnnotationControls, DisplayControls, DisplayEvents, FrameBlock, FrameOutcome, DisplayHandle, HostOptions, MountOptions, PortholeHost, } from "./host/types.ts";
+export { ANNOTATE_METHODS, ANNOTATION_LIMITS, type AnchorResult, type AnchorState, type AnnotateMode, type AnnotationAnchor, type AnnotationMark, type AnnotationRect, type AnnotationReport, type AnnotationSelector, type CssSelector, type TextPositionSelector, type TextQuoteSelector, } from "./annotate/types.ts";
+export { parseAnchor, parseRect, parseReport } from "./annotate/validate.ts";

package/dist/index.js

@@ -3,7 +3,7 @@
  * frame's policies, the shell, and the agent manual; the host mounts displays under it.
  */
 // The config and its vocabulary.
-export { CAPABILITIES, CAPABILITY_NAMES, capabilitySpec, isCapabilityName, } from "./config/capabilities.js";
+export { CAPABILITIES, CAPABILITY_NAMES, MAX_COPY_CHARS, capabilitySpec, isCapabilityName, } from "./config/capabilities.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,11 +12,15 @@ 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, 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";
 // Theme.
 export { CHART_PALETTE, DEFAULT_THEME, DEFAULT_THEME_EVENT, DEFAULT_THEME_VARIABLES, resolveTheme, themeDefault, } from "./theme/variables.js";
-export { MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS_STYLE_VARIABLES, PORTHOLE_STYLES, } from "./protocol/mcp-apps.js";
+export { COPY_TEXT_METHOD, MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS_STYLE_VARIABLES, PORTHOLE_STYLES, } from "./protocol/mcp-apps.js";
 export { createHost } from "./host/create-host.js";
+export { writeClipboard } from "./host/clipboard.js";
+// Annotations (P053): anchors, what a frame reports, and the host's checks on both.
+export { ANNOTATE_METHODS, ANNOTATION_LIMITS, } from "./annotate/types.js";
+export { parseAnchor, parseRect, parseReport } from "./annotate/validate.js";

package/dist/mcp/adapter.js

@@ -1,7 +1,7 @@
 import { egressOrigins } from "../compile/policy.js";
 import { JSON_RPC_ERRORS, parseJsonRpc, } from "../protocol/jsonrpc.js";
 import { MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, } from "../protocol/mcp-apps.js";
-import { MCP_APPS_STYLE_VARIABLES } from "../protocol/mcp-apps.js";
+import { COPY_TEXT_METHOD, MCP_APPS_STYLE_VARIABLES } from "../protocol/mcp-apps.js";
 const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 /** Levels of `notifications/message` that are errors: they go to the host as `reportError`. */
 const ERROR_LEVELS = new Set(["error", "critical", "alert", "emergency"]);
@@ -183,6 +183,15 @@ function connect(session, options) {
                         : { structuredContent: params.structuredContent }),
                 }, () => ({}));
                 return;
+            case COPY_TEXT_METHOD:
+                // Porthole's own request (the standard has no clipboard request): the host copies, and
+                // shows the person what (P052).
+                if (typeof params.text !== "string") {
+                    invalid("needs text");
+                    return;
+                }
+                await call(request, "copyText", { text: params.text }, done);
+                return;
             case MCP_APPS_METHODS.requestDisplayMode: {
                 if (typeof params.mode !== "string" || !DISPLAY_MODES.has(params.mode)) {
                     invalid("needs a display mode");

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

@@ -102,6 +102,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/protocol/mcp-apps.d.ts

@@ -47,6 +47,11 @@ export declare const MCP_APPS_STYLE_VARIABLES: readonly string[];
  * that doesn't know the field ignores it (the host context is open to extra fields).
  */
 export declare const PORTHOLE_STYLES = "porthole/styles";
+/**
+ * Porthole's own request for copying text (`copyText`, P052): `{ text }`, answered `{}` when the
+ * host copied it and `{ isError: true }` when it didn't. The standard has no clipboard request.
+ */
+export declare const COPY_TEXT_METHOD = "porthole/copy-text";
 /** The logger name the shell's error reports (`notifications/message`, level `error`) carry. */
 export declare const SHELL_LOGGER = "porthole";
 /**

package/dist/protocol/mcp-apps.js

@@ -95,5 +95,10 @@ export const MCP_APPS_STYLE_VARIABLES = [
  * that doesn't know the field ignores it (the host context is open to extra fields).
  */
 export const PORTHOLE_STYLES = "porthole/styles";
+/**
+ * Porthole's own request for copying text (`copyText`, P052): `{ text }`, answered `{}` when the
+ * host copied it and `{ isError: true }` when it didn't. The standard has no clipboard request.
+ */
+export const COPY_TEXT_METHOD = "porthole/copy-text";
 /** The logger name the shell's error reports (`notifications/message`, level `error`) carry. */
 export const SHELL_LOGGER = "porthole";

package/dist/protocol/shell-adapter.js

@@ -1,5 +1,5 @@
 import { JSON_RPC_ERRORS, parseJsonRpc, } from "./jsonrpc.js";
-import { MCP_APPS_METHODS as M, MCP_APPS_PROTOCOL_VERSION } from "./mcp-apps.js";
+import { COPY_TEXT_METHOD, MCP_APPS_METHODS as M, MCP_APPS_PROTOCOL_VERSION, } from "./mcp-apps.js";
 /**
  * The core's adapter: the host side of the MCP Apps subset the shell speaks, which content using
  * the official App SDK speaks too. Every message is checked before use; every power goes through
@@ -28,6 +28,7 @@ const REQUESTS = {
         }),
     },
     [M.openLink]: { capability: "openLink", args: (params) => ({ url: params.url }) },
+    [COPY_TEXT_METHOD]: { capability: "copyText", args: (params) => ({ text: params.text }) },
     [M.downloadFile]: {
         capability: "downloadFile",
         args: (params) => ({ contents: params.contents }),
@@ -44,7 +45,10 @@ const REQUESTS = {
 };
 /** What a capability's outcome looks like to the view. */
 function answer(capability, outcome) {
-    const flagged = capability === "sendPrompt" || capability === "openLink" || capability === "downloadFile";
+    const flagged = capability === "sendPrompt" ||
+        capability === "openLink" ||
+        capability === "downloadFile" ||
+        capability === "copyText";
     if (!outcome.ok) {
         return flagged
             ? { result: { isError: true } }

package/dist/react/dialog.js

@@ -47,6 +47,8 @@ function words(request) {
             return { heading: "Share this with the agent?", accept: "Share", detail: json(request.args) };
         case "readData":
             return { heading: "Let it read this?", accept: "Allow", detail: request.args.uri };
+        case "copyText":
+            return { heading: "Copy this text?", accept: "Copy", detail: request.args.text };
         default:
             return { heading: "Allow this?", accept: "Allow", detail: json(request.args) };
     }

package/dist/react/frame.d.ts

@@ -1,8 +1,9 @@
 import { type CSSProperties, type ReactElement, type ReactNode } from "react";
+import type { AnnotateMode, AnnotationMark, AnnotationReport } from "../annotate/types.ts";
 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;
@@ -21,6 +22,13 @@ export interface PortholeProviderProps {
     readonly locator?: InstanceLocator;
     /** A class for the default dialog, to restyle it. */
     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;
@@ -57,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;
@@ -83,6 +110,27 @@ export interface PortholeFrameProps {
      * restyle): the running frame reads them again.
      */
     readonly themeKey?: string | number;
+    /**
+     * Annotations, where the config declares `annotate` (P053): what the person may point at now
+     * (elements, text, or both), or null to stop. A picked element ends element picking: set it
+     * again to pick again.
+     */
+    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. 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.
+     */
+    readonly onAnnotation?: (report: AnnotationReport) => void;
     /** Draws the placeholder instead of the default one. */
     readonly renderPlaceholder?: (props: PlaceholderProps) => ReactNode;
     readonly className?: string;