@botiverse/porthole 0.1.3 → 0.1.4

package/dist/compile/policy.d.ts

@@ -55,3 +55,9 @@ export declare function embedderFrameSources(config: PortholeConfig): string[];
  * engine Porthole supports reads frames from `frame-src`, P038).
  */
 export declare function embedderCsp(configs: readonly PortholeConfig[]): string;
+/**
+ * The `frame-src` sources the embedding page must allow for every kind of display it shows, as a
+ * list, for a host that writes its own policy around them (empty: it frames nothing of
+ * Porthole's but `srcdoc`, which needs none).
+ */
+export declare function embedderFrameSourcesOf(configs: readonly PortholeConfig[]): string[];

package/dist/compile/policy.js

@@ -102,6 +102,14 @@ export function embedderFrameSources(config) {
  * engine Porthole supports reads frames from `frame-src`, P038).
  */
 export function embedderCsp(configs) {
-    const sources = unique(configs.flatMap(embedderFrameSources));
+    const sources = embedderFrameSourcesOf(configs);
     return serializeCsp([["frame-src", ...(sources.length === 0 ? ["'none'"] : sources)]]);
 }
+/**
+ * The `frame-src` sources the embedding page must allow for every kind of display it shows, as a
+ * list, for a host that writes its own policy around them (empty: it frames nothing of
+ * Porthole's but `srcdoc`, which needs none).
+ */
+export function embedderFrameSourcesOf(configs) {
+    return unique(configs.flatMap(embedderFrameSources));
+}

package/dist/config/schema.d.ts

@@ -157,4 +157,15 @@ 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/dist/config/validate.js

@@ -111,6 +111,7 @@ export function validateConfig(input) {
         "embedder",
         "sandbox",
         "permissions",
+        "storage",
     ], "config");
     if (!MODES.includes(config.mode)) {
         fail("config.mode", `must be one of ${MODES.join(", ")}`);
@@ -258,6 +259,17 @@ export function validateConfig(input) {
             }
         });
     }
+    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/dist/conformance/served.d.ts

@@ -35,8 +35,15 @@ 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`. */

package/dist/conformance/served.js

@@ -14,6 +14,8 @@
 import { expect } from "@playwright/test";
 import { MCP_APPS_METHODS } from "../protocol/mcp-apps.js";
 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) {
     return frame.evaluate(() => {
@@ -109,21 +111,23 @@ export function servedTests(host, options = {}) {
             ["domain", (scope) => host.shell(scope)],
             ["url", (scope) => host.app(scope)],
         ];
+        // A served shell draws (and has a height to click in) once its host gives it content.
+        const showMode = (page, mode, instance) => 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);
                 expect(origin).not.toBe(new URL(page.url()).origin);
             });
             define(`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);
             });
             define(`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`);
@@ -153,7 +157,7 @@ export function servedTests(host, options = {}) {
                 expect(await host.canaryHits(`${mode}-top`)).toBe(0);
             });
             define(`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 = [];
@@ -186,13 +190,13 @@ export function servedTests(host, options = {}) {
             });
         }
         define("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();
         });
@@ -247,7 +251,7 @@ export function servedTests(host, options = {}) {
             }
         });
         define("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) => {
                 try {

package/dist/guide/guide.js

@@ -206,7 +206,9 @@ function interactive(c) {
         .filter((entry) => entry !== "");
     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.`
         : null;

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,14 @@
  * 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 { 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";

package/dist/index.js

@@ -12,7 +12,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, 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

@@ -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/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.