@botiverse/porthole 0.1.2 → 0.1.4

package/src/host/create-host.ts

@@ -1,4 +1,12 @@
+import {
+  ANNOTATE_METHODS,
+  type AnnotateMode,
+  type AnnotationMark,
+  type AnnotationReport,
+} from "../annotate/types.ts";
+import { annotateMode, checkMarks, parseReport } from "../annotate/validate.ts";
 import { createBridge, type BridgeEvent } from "../bridge/bridge.ts";
+import type { HostFunctionBridge } from "../bridge/types.ts";
 import { compile } from "../compile/compile.ts";
 import { declaredCapabilities } from "../compile/policy.ts";
 import { capabilitySpec } from "../config/capabilities.ts";
@@ -17,6 +25,8 @@ import {
 import { shellAdapter } from "../protocol/shell-adapter.ts";
 import { resolveTheme } from "../theme/variables.ts";
 import type {
+  AnnotationControls,
+  HostErrorKind,
   DisplayEvents,
   DisplayHandle,
   HostOptions,
@@ -31,6 +41,17 @@ const DEFAULT_LOAD_TIMEOUT_MS = 15_000;
 const MAX_RESTARTS = 3;
 
 const BASE_KEYS = new Set(["hostContextChanged", "teardown", "close"]);
+
+/** The frame's annotation reports, by method. */
+const REPORTS: Readonly<Record<string, AnnotationReport["type"]>> = {
+  [ANNOTATE_METHODS.selected]: "selected",
+  [ANNOTATE_METHODS.unselected]: "unselected",
+  [ANNOTATE_METHODS.cancelled]: "cancelled",
+  [ANNOTATE_METHODS.anchored]: "anchored",
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
 const STANDARD = new Set(MCP_APPS_STYLE_VARIABLES);
 
 /**
@@ -76,6 +97,16 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
           (listener as (detail: DisplayEvents[E]) => void)(detail);
         }
       };
+      // What the content did wrong (the agent's to hear and fix), and what failed on the host's
+      // side (its own to handle), each on its own event and on `error` with its source.
+      const contentError = (message: string) => {
+        emit("contentError", { message });
+        emit("error", { message, source: "content" });
+      };
+      const hostError = (message: string, kind: HostErrorKind) => {
+        emit("hostError", { message, kind });
+        emit("error", { message, source: "host" });
+      };
 
       let scheme: ColorScheme = mount.scheme;
       let height = mount.initialHeightPx ?? 0;
@@ -90,6 +121,129 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
       const view = container.ownerDocument.defaultView;
       // The adapter's own operations, the last call of each, replayed into every new frame.
       const replay = new Map<string, unknown[]>();
+      // Annotations: the host's state, given to each frame once it finished its handshake.
+      const annotates = config.capabilities.annotate !== undefined;
+      let annotating: Required<AnnotateMode> | null = null;
+      let marks: AnnotationMark[] = [];
+      let activeMark: string | null = null;
+      let handshaken = false;
+      const toFrame = (method: string, params: Record<string, unknown>) => {
+        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: unknown, bridge: HostFunctionBridge) => {
+        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: string) => {
+        if (!annotates) {
+          throw new TypeError(`annotations.${operation}: the config doesn't declare annotate`);
+        }
+      };
+      const annotations: AnnotationControls = {
+        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 = (): HostContext => {
         const width = container.getBoundingClientRect().width;
@@ -134,7 +288,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
             return;
           }
           case "error":
-            emit("error", { message: event.message });
+            contentError(event.message);
             return;
           case "refused":
             emit("refused", { capability: event.capability, refusal: event.refusal });
@@ -142,10 +296,14 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
           case "muted":
             emit("muted", undefined);
             return;
+          case "annotation":
+            emit("annotation", event.report);
+            return;
         }
       };
 
       const stop = () => {
+        handshaken = false;
         abort?.abort();
         abort = null;
         outcomeWatch?.stop();
@@ -164,8 +322,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
           allow: compiled.allow,
           referrerPolicy: compiled.referrerPolicy,
           colorScheme: scheme,
-          // An app reports no size: its frame fills the host's container, at least the minimum.
-          ...(speaks
+          // An app reports no size: its frame fills the host's container, at least the minimum;
+          // so does any display the host mounts to fill (its content scrolls inside).
+          ...(speaks && mount.fill !== true
             ? { initialHeightPx: height }
             : { fill: true, initialHeightPx: config.limits.minHeightPx }),
         });
@@ -197,6 +356,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
           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,
@@ -207,6 +369,10 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
           emit: (event) => {
             if (event.type === "initialized") {
               watch.initialized();
+              if (!handshaken) {
+                handshaken = true;
+                giveAnnotations();
+              }
               emit("initialized", undefined);
             }
           },
@@ -223,9 +389,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
             run();
           } else {
             stop();
-            emit("error", {
-              message: "The content kept navigating its frame away; it was stopped.",
-            });
+            contentError("The content kept navigating its frame away; it was stopped.");
           }
         });
       };
@@ -242,6 +406,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
             html: compiled.shellDocument({
               origins: [container.ownerDocument.defaultView?.location.origin ?? ""],
               title: mount.title,
+              ...nonceOf(options.nonce),
               ...(mount.document === undefined ? {} : { document: mount.document }),
             }),
           });
@@ -264,7 +429,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
           },
           (error: unknown) => {
             if (mine === generation && !controller.signal.aborted) {
-              emit("error", { message: error instanceof Error ? error.message : String(error) });
+              // The host's own failure (its backend down, access gone): never the content's.
+              hostError(error instanceof Error ? error.message : String(error), "locate");
+              emit("outcome", { state: "blocked", reason: "locate" });
             }
           },
         );
@@ -274,6 +441,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
 
       const controls = {
         displayId: mount.displayId,
+        annotations,
         setTheme(next: ColorScheme) {
           scheme = next;
           surface?.setColorScheme(next);
@@ -333,3 +501,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
     },
   };
 }
+
+/** The host's nonce option, read now (`HostOptions.nonce`). */
+function nonceOf(nonce: HostOptions["nonce"]): { nonce?: string } {
+  const value = typeof nonce === "function" ? nonce() : nonce;
+  return value === undefined || value === "" ? {} : { nonce: value };
+}

package/src/host/types.ts

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

@@ -7,6 +7,7 @@
 export {
   CAPABILITIES,
   CAPABILITY_NAMES,
+  MAX_COPY_CHARS,
   capabilitySpec,
   isCapabilityName,
   type CapabilityArgs,
@@ -28,6 +29,7 @@ export type {
   LayoutConfig,
   Limits,
   PortholeConfig,
+  StorageConfig,
   ThemeConfig,
   ThemeValue,
 } from "./config/schema.ts";
@@ -64,6 +66,7 @@ export {
   effectiveGates,
   egressOrigins,
   embedderCsp,
+  embedderFrameSourcesOf,
   type CspDirective,
   type EgressKind,
 } from "./compile/policy.ts";
@@ -105,6 +108,7 @@ export type {
   ShellConnection,
 } from "./protocol/adapter.ts";
 export {
+  COPY_TEXT_METHOD,
   MCP_APPS_METHODS,
   MCP_APPS_PROTOCOL_VERSION,
   MCP_APPS_STYLE_VARIABLES,
@@ -124,7 +128,9 @@ export type {
   Refusal,
 } from "./bridge/types.ts";
 export { createHost } from "./host/create-host.ts";
+export { writeClipboard } from "./host/clipboard.ts";
 export type {
+  AnnotationControls,
   DisplayControls,
   DisplayEvents,
   FrameBlock,
@@ -134,3 +140,21 @@ export type {
   MountOptions,
   PortholeHost,
 } from "./host/types.ts";
+
+// Annotations (P053): anchors, what a frame reports, and the host's checks on both.
+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/src/mcp/adapter.ts

@@ -14,7 +14,7 @@ import {
   MCP_APPS_PROTOCOL_VERSION,
   type HostContext,
 } from "../protocol/mcp-apps.ts";
-import { MCP_APPS_STYLE_VARIABLES } from "../protocol/mcp-apps.ts";
+import { COPY_TEXT_METHOD, MCP_APPS_STYLE_VARIABLES } from "../protocol/mcp-apps.ts";
 
 /**
  * The MCP Apps adapter (P004, P007): the host side of the protocol for full MCP Apps views, written
@@ -283,6 +283,15 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
           () => ({}),
         );
         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/src/presets/presets.ts

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

package/src/protocol/mcp-apps.ts

@@ -115,6 +115,12 @@ export const MCP_APPS_STYLE_VARIABLES: readonly string[] = [
  */
 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/src/protocol/shell-adapter.ts

@@ -8,7 +8,12 @@ import {
   type JsonRpcRequest,
   type JsonRpcResponse,
 } from "./jsonrpc.ts";
-import { MCP_APPS_METHODS as M, MCP_APPS_PROTOCOL_VERSION, type HostContext } from "./mcp-apps.ts";
+import {
+  COPY_TEXT_METHOD,
+  MCP_APPS_METHODS as M,
+  MCP_APPS_PROTOCOL_VERSION,
+  type HostContext,
+} from "./mcp-apps.ts";
 
 /**
  * The core's adapter: the host side of the MCP Apps subset the shell speaks, which content using
@@ -42,6 +47,7 @@ const REQUESTS: Readonly<
     }),
   },
   [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 }),
@@ -63,7 +69,10 @@ function answer(
   outcome: CallOutcome<unknown>,
 ): { result: unknown } | { error: { code: number; message: string } } {
   const flagged =
-    capability === "sendPrompt" || capability === "openLink" || capability === "downloadFile";
+    capability === "sendPrompt" ||
+    capability === "openLink" ||
+    capability === "downloadFile" ||
+    capability === "copyText";
   if (!outcome.ok) {
     return flagged
       ? { result: { isError: true } }

package/src/react/dialog.tsx

@@ -66,6 +66,8 @@ function words(request: ConfirmRequest): Words {
       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) };
   }