@botiverse/porthole 0.1.2 → 0.1.4

package/dist/shell/document.d.ts

@@ -21,6 +21,12 @@ export interface ShellDocumentOptions {
      * both apply, and the stricter wins.
      */
     readonly cspMeta?: boolean;
+    /**
+     * The embedding page's CSP nonce, where its `script-src` is nonce-based (P054): a `srcdoc` frame
+     * inherits the embedding page's policy, so the shell's script and style carry it, and so does
+     * every script the shell runs for the content. The frame can read it.
+     */
+    readonly nonce?: string;
 }
 /**
  * The frame's document: its policy first, then the base styles, an empty root, and the runtime.

package/dist/shell/document.js

@@ -1,5 +1,8 @@
 import { hostOriginProblem } from "../isolation/served.js";
+import { ANNOTATE_RUNTIME } from "./annotate.js";
 import { SHELL_RUNTIME } from "./runtime.js";
+/** A CSP nonce: base64 or base64url characters, 8 to 256 of them. */
+const NONCE = /^[A-Za-z0-9+/_=-]{8,256}$/u;
 const escapeAttribute = (value) => value.replace(/&/gu, "&amp;").replace(/"/gu, "&quot;").replace(/</gu, "&lt;");
 const escapeText = (value) => value.replace(/&/gu, "&amp;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;");
 /** JSON that is safe inside a `<script>`: no `</script>`, no `<!--`. */
@@ -52,7 +55,13 @@ export function shellDocument(plan, csp, options) {
             throw new TypeError(`shellDocument: ${problem}`);
         }
     }
-    const runtime = SHELL_RUNTIME.replace("__PLAN__", () => scriptJson({
+    if (options.nonce !== undefined && !NONCE.test(options.nonce)) {
+        throw new TypeError("shellDocument: a nonce is 8 to 256 base64 characters");
+    }
+    const nonce = options.nonce === undefined ? "" : ` nonce="${options.nonce}"`;
+    // The annotation runtime only where it is declared; spliced in before the plan, which may carry
+    // any text (a document) and must not be searched.
+    const runtime = SHELL_RUNTIME.replace("__ANNOTATE__", () => plan.capabilities.annotate === undefined ? "" : ANNOTATE_RUNTIME).replace("__PLAN__", () => scriptJson({
         ...plan,
         origins: options.origins,
         ...(options.document === undefined ? {} : { document: options.document }),
@@ -72,13 +81,13 @@ export function shellDocument(plan, csp, options) {
 ${head.join("\n")}
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>${escapeText(options.title ?? "Content")}</title>
-<style>
+<style${nonce}>
 ${BASE_STYLE}
 </style>
 </head>
 <body>
 <div id="porthole-root"></div>
-<script>${runtime}</script>
+<script${nonce}>${runtime}</script>
 </body>
 </html>
 `;

package/dist/shell/plan.d.ts

@@ -32,6 +32,8 @@ export interface ShellPlan {
     readonly storage: "memory" | "native";
     readonly maxErrorReports: number;
     readonly maxPromptChars: number;
+    /** The most text `copyText` carries. */
+    readonly maxCopyChars: number;
     readonly protocolVersion: string;
 }
 export declare function shellPlan(config: PortholeConfig): ShellPlan | null;

package/dist/shell/plan.js

@@ -1,4 +1,4 @@
-import { capabilitySpec } from "../config/capabilities.js";
+import { MAX_COPY_CHARS, capabilitySpec } from "../config/capabilities.js";
 import { declaredCapabilities, effectiveGates } from "../compile/policy.js";
 import { MCP_APPS_PROTOCOL_VERSION } from "../protocol/mcp-apps.js";
 export function shellPlan(config) {
@@ -30,6 +30,7 @@ export function shellPlan(config) {
         storage: config.isolation === "opaque" ? "memory" : "native",
         maxErrorReports: config.limits.maxErrorReports,
         maxPromptChars: config.limits.maxPromptChars,
+        maxCopyChars: MAX_COPY_CHARS,
         protocolVersion: MCP_APPS_PROTOCOL_VERSION,
     };
 }

package/dist/shell/runtime.d.ts

@@ -13,7 +13,10 @@
  *    engine enforces `frame-src 'none'` for `srcdoc`/`about:blank` children); and the resource
  *    hints and refreshes a CSP doesn't govern;
  * 4. closes the parser entry points that could build a shadow root step 3 can't see (declarative
- *    shadow DOM through `setHTMLUnsafe`, `parseHTMLUnsafe`, `document.write`).
+ *    shadow DOM through `setHTMLUnsafe`, `parseHTMLUnsafe`, `document.write`);
+ * 5. keeps content off the clipboard: the async Clipboard API refuses, `execCommand` won't copy or
+ *    cut, and copy and cut events never reach content, so what a person copies is what they
+ *    selected (P051). Copy buttons go through the host (`copyText`, P052).
  * A whole document (an artifact page, an MCP Apps view) is never written in: it is parsed inert,
  * imported, and its scripts run in order, as a fragment's are.
  *

package/dist/shell/runtime.js

@@ -13,7 +13,10 @@
  *    engine enforces `frame-src 'none'` for `srcdoc`/`about:blank` children); and the resource
  *    hints and refreshes a CSP doesn't govern;
  * 4. closes the parser entry points that could build a shadow root step 3 can't see (declarative
- *    shadow DOM through `setHTMLUnsafe`, `parseHTMLUnsafe`, `document.write`).
+ *    shadow DOM through `setHTMLUnsafe`, `parseHTMLUnsafe`, `document.write`);
+ * 5. keeps content off the clipboard: the async Clipboard API refuses, `execCommand` won't copy or
+ *    cut, and copy and cut events never reach content, so what a person copies is what they
+ *    selected (P051). Copy buttons go through the host (`copyText`, P052).
  * A whole document (an artifact page, an MCP Apps view) is never written in: it is parsed inert,
  * imported, and its scripts run in order, as a fragment's are.
  *
@@ -28,6 +31,9 @@
 export const SHELL_RUNTIME = String.raw `(() => {
   "use strict";
   const plan = __PLAN__;
+  // The embedding page's nonce, where it gave one (a srcdoc frame inherits its policy): every
+  // script the shell runs for the content carries it.
+  const nonce = document.currentScript && document.currentScript.nonce ? document.currentScript.nonce : "";
   const declared = (name) => Object.prototype.hasOwnProperty.call(plan.capabilities, name);
   // Fixed in place: content can neither restore what is removed nor replace what is wrapped.
   const lock = (target, name, value) => {
@@ -263,13 +269,32 @@ export const SHELL_RUNTIME = String.raw `(() => {
       this.innerHTML = String(html);
     });
   }
+  // insertHTML parses markup outside these guards; copy, cut and paste reach the clipboard (P051).
+  const REFUSED_COMMANDS = ["inserthtml", "copy", "cut", "paste"];
   const execCommand = Document.prototype.execCommand;
   if (typeof execCommand === "function") {
     lock(Document.prototype, "execCommand", function (command, ...rest) {
-      return String(command).toLowerCase() === "inserthtml" ? false : execCommand.call(this, command, ...rest);
+      return REFUSED_COMMANDS.indexOf(String(command).toLowerCase()) !== -1 ? false : execCommand.call(this, command, ...rest);
     });
   }
 
+  // The clipboard is the host's to write (P051): content can neither write nor read it. A copy
+  // the person makes (their keys, their menu) copies their selection as the browser makes it: no
+  // copy or cut listener of the content's runs, so none can swap what goes on the clipboard.
+  const noClipboard = function () {
+    return Promise.reject(new DOMException("Content can't use the clipboard here" + (declared("copyText") ? ": call copyText(text) from a click" : ""), "NotAllowedError"));
+  };
+  if (typeof Clipboard === "function") {
+    for (const name of ["write", "writeText", "read", "readText"]) {
+      if (typeof Clipboard.prototype[name] === "function") {
+        lock(Clipboard.prototype, name, noClipboard);
+      }
+    }
+  }
+  for (const type of ["copy", "cut"]) {
+    window.addEventListener(type, (event) => event.stopImmediatePropagation(), true);
+  }
+
   // A connected link or meta can't become a guarded one: the change is tried on a detached copy
   // first, and if the copy would be guarded, the element leaves the document before it changes.
   const watched = (element) => element && element.nodeType === 1 && (element.localName === "link" || element.localName === "meta");
@@ -463,6 +488,9 @@ export const SHELL_RUNTIME = String.raw `(() => {
       }
       // A script made by a script is async unless told otherwise: keep the page's order.
       live.async = script.hasAttribute("async");
+      if (nonce !== "") {
+        live.nonce = nonce;
+      }
       live.textContent = script.textContent;
       const external = live.hasAttribute("src") && !live.async && live.type !== "module";
       const loaded = external
@@ -487,6 +515,27 @@ export const SHELL_RUNTIME = String.raw `(() => {
     window.dispatchEvent(new Event("load"));
   };
 
+  // Whether the content is in place: a fragment or page the shell draws, once drawn whole; a
+  // view the plan carries, once rendered; a view that is the document itself, from the start.
+  const contentHooks = [];
+  let contentIn = typeof plan.document !== "string" && plan.protocol !== "shell";
+  const contentIsIn = () => contentIn;
+  const whenContentIsIn = (run) => {
+    if (contentIn) {
+      run();
+    } else {
+      contentHooks.push(run);
+    }
+  };
+  const contentArrived = () => {
+    if (!contentIn) {
+      contentIn = true;
+      for (const run of contentHooks.splice(0)) {
+        run();
+      }
+    }
+  };
+
   // A fragment takes the person's scheme; a whole document only if it declares that it supports
   // both (or the config says always), else it shows as its author styled it (P039).
   let lastContext = null;
@@ -522,6 +571,7 @@ export const SHELL_RUNTIME = String.raw `(() => {
     schemeFollows();
     await runScripts(scripts);
     announceLoaded();
+    contentArrived();
   };
 
   // A document the plan carries (a served page, an MCP Apps view) is rendered once the shell's own
@@ -534,6 +584,8 @@ export const SHELL_RUNTIME = String.raw `(() => {
     }
   };
 
+  __ANNOTATE__
+
   if (plan.protocol !== "shell") {
     // A view that speaks for itself.
     if (typeof plan.document === "string") {
@@ -624,6 +676,18 @@ export const SHELL_RUNTIME = String.raw `(() => {
       );
     });
   }
+  if (declared("copyText")) {
+    lock(window, "copyText", (text) => {
+      if (!gestured("copyText")) {
+        return refuse("copyText needs a click: call it from a button's handler");
+      }
+      const words = String(text);
+      if (words === "" || words.length > plan.maxCopyChars) {
+        return refuse("copyText takes 1 to " + plan.maxCopyChars + " characters");
+      }
+      return request("porthole/copy-text", { text: words }).then((result) => !(result && result.isError));
+    });
+  }
   if (declared("openLink")) {
     lock(window, "openLink", (url) => {
       if (!gestured("openLink")) {
@@ -636,7 +700,10 @@ export const SHELL_RUNTIME = String.raw `(() => {
   window.addEventListener("error", (event) => {
     const error = event.error;
     const where = event.lineno ? " (line " + event.lineno + ")" : "";
-    report(error && error.stack ? String(error.stack).split("\n").slice(0, 3).join(" ") : event.message + where);
+    // V8's stack starts with the message; WebKit's and Firefox's don't, so it goes first there.
+    const stack = error && error.stack ? String(error.stack).split("\n").slice(0, 3).join(" ") : "";
+    const said = error && error.message !== undefined ? String(error.name || "Error") + ": " + String(error.message) : event.message;
+    report(stack === "" ? said + where : stack.indexOf(String(error.message)) === -1 ? said + " " + stack : stack);
   });
   window.addEventListener("unhandledrejection", (event) => {
     const reason = event.reason;
@@ -768,6 +835,7 @@ export const SHELL_RUNTIME = String.raw `(() => {
     schedule();
     await runScripts(scripts);
     announceLoaded();
+    contentArrived();
     schedule();
   };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botiverse/porthole",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
   "license": "Apache-2.0",
   "files": [

package/src/annotate/types.ts

@@ -0,0 +1,126 @@
+/**
+ * Annotations (P053): a person points at part of a display (an element, or text they select) to
+ * comment on it, and the host marks the anchors already made. The host drives the shell with
+ * Porthole's own messages (`porthole/annotate.*`); the shell answers with anchors and where they
+ * are. An anchor is a set of W3C Web Annotation selectors, so it can be found again after the
+ * content changes; finding it is best-effort, and says so (`orphaned`).
+ *
+ * Everything the frame reports is the content's word: the shell shares its realm with the
+ * content, which can interfere or fake a report. The host checks each report's shape and size
+ * and takes reports only while it asked for them. Use them as UI hints (where to draw a comment,
+ * what to quote), never as permissions.
+ */
+
+/** The element a CSS selector matches (W3C `CssSelector`). */
+export interface CssSelector {
+  readonly type: "CssSelector";
+  readonly value: string;
+}
+
+/** Text, with a little of what comes before and after it (W3C `TextQuoteSelector`). */
+export interface TextQuoteSelector {
+  readonly type: "TextQuoteSelector";
+  readonly exact: string;
+  readonly prefix?: string;
+  readonly suffix?: string;
+}
+
+/**
+ * Offsets into the document's text: the text of the body's text nodes, in order, without
+ * scripts, styles and templates (W3C `TextPositionSelector`).
+ */
+export interface TextPositionSelector {
+  readonly type: "TextPositionSelector";
+  readonly start: number;
+  readonly end: number;
+}
+
+export type AnnotationSelector = CssSelector | TextQuoteSelector | TextPositionSelector;
+
+export interface AnnotationAnchor {
+  /** What the person pointed at: an element, or a text selection. */
+  readonly kind: "element" | "text";
+  /** At most one of each type; tried in turn when the anchor is found again. */
+  readonly selectors: readonly AnnotationSelector[];
+  /** A short description for the host to show ("h2#revenue Revenue grew 12%"); the content's. */
+  readonly label: string;
+}
+
+/** A box in the frame's viewport, CSS px: add the frame element's position to place it on the page. */
+export interface AnnotationRect {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/** What the person may point at while the host is asking. */
+export interface AnnotateMode {
+  /** Elements, picked with a click or tap (the one under the pointer is outlined); one pick. */
+  readonly elements?: boolean;
+  /** Text, by selecting it: each settled selection is reported, and its clearing. */
+  readonly text?: boolean;
+}
+
+/** An anchor the host marks in the frame, under its own id. */
+export interface AnnotationMark {
+  readonly id: string;
+  readonly anchor: AnnotationAnchor;
+}
+
+/** Whether a mark's anchor was found in the content as it is now. */
+export type AnchorState = "attached" | "orphaned";
+
+export interface AnchorResult {
+  readonly id: string;
+  readonly state: AnchorState;
+  /** Where it is now, when attached. */
+  readonly rect?: AnnotationRect;
+}
+
+/** What the frame reports, once the host has checked it. */
+export type AnnotationReport =
+  /** The person pointed at an element or settled a text selection. */
+  | {
+      readonly type: "selected";
+      readonly anchor: AnnotationAnchor;
+      readonly rect: AnnotationRect;
+    }
+  /** The text selection went away. */
+  | { readonly type: "unselected" }
+  /** The person pressed Escape while picking an element. */
+  | { readonly type: "cancelled" }
+  /** Where the marked anchors are now, after `show`, `focus`, or a change of the content. */
+  | { readonly type: "anchored"; readonly results: readonly AnchorResult[] };
+
+/** Porthole's own messages for annotations (own-prefixed, P002). */
+export const ANNOTATE_METHODS = {
+  /** Host → frame: let the person point (`AnnotateMode`). */
+  start: "porthole/annotate.start",
+  /** Host → frame: stop. */
+  stop: "porthole/annotate.stop",
+  /** Host → frame: mark these anchors (replacing what was marked). */
+  show: "porthole/annotate.show",
+  /** Host → frame: bring one mark into view and make it the active one. */
+  focus: "porthole/annotate.focus",
+  /** Host → frame: remove every mark. */
+  clear: "porthole/annotate.clear",
+  /** Frame → host. */
+  selected: "porthole/annotate.selected",
+  unselected: "porthole/annotate.unselected",
+  cancelled: "porthole/annotate.cancelled",
+  anchored: "porthole/annotate.anchored",
+} as const;
+
+/** The most of each part of an anchor or report the host takes. */
+export const ANNOTATION_LIMITS = {
+  label: 120,
+  cssSelector: 1_000,
+  exact: 4_000,
+  context: 64,
+  /** The most marks one `show` carries, and results one report. */
+  marks: 500,
+  id: 128,
+  position: 50_000_000,
+  coordinate: 10_000_000,
+} as const;

package/src/annotate/validate.ts

@@ -0,0 +1,186 @@
+import {
+  ANNOTATION_LIMITS as LIMITS,
+  type AnchorResult,
+  type AnnotateMode,
+  type AnnotationAnchor,
+  type AnnotationMark,
+  type AnnotationRect,
+  type AnnotationReport,
+  type AnnotationSelector,
+} from "./types.ts";
+
+/**
+ * The host's checks on what a frame says about annotations (P053), and on anchors a host stores
+ * and sends back. Each rebuilds what it accepts from known fields only, within `ANNOTATION_LIMITS`,
+ * and answers null for anything else: a report is dropped whole, never repaired.
+ */
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+const text = (value: unknown, max: number, min = 0): value is string =>
+  typeof value === "string" && value.length >= min && value.length <= max;
+
+const count = (value: unknown, max: number): value is number =>
+  typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= max;
+
+function selector(value: unknown): AnnotationSelector | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+  switch (value.type) {
+    case "CssSelector":
+      return text(value.value, LIMITS.cssSelector, 1)
+        ? { type: "CssSelector", value: value.value }
+        : null;
+    case "TextQuoteSelector": {
+      const { exact, prefix, suffix } = value;
+      if (
+        !text(exact, LIMITS.exact, 1) ||
+        (prefix !== undefined && !text(prefix, LIMITS.context)) ||
+        (suffix !== undefined && !text(suffix, LIMITS.context))
+      ) {
+        return null;
+      }
+      return {
+        type: "TextQuoteSelector",
+        exact,
+        ...(prefix === undefined || prefix === "" ? {} : { prefix }),
+        ...(suffix === undefined || suffix === "" ? {} : { suffix }),
+      };
+    }
+    case "TextPositionSelector":
+      return count(value.start, LIMITS.position) &&
+        count(value.end, LIMITS.position) &&
+        value.start <= value.end
+        ? { type: "TextPositionSelector", start: value.start, end: value.end }
+        : null;
+    default:
+      return null;
+  }
+}
+
+/** An anchor, rebuilt from its known fields; null if any part is malformed or too large. */
+export function parseAnchor(value: unknown): AnnotationAnchor | null {
+  if (!isRecord(value) || (value.kind !== "element" && value.kind !== "text")) {
+    return null;
+  }
+  if (!Array.isArray(value.selectors) || value.selectors.length === 0) {
+    return null;
+  }
+  if (value.selectors.length > 3 || !text(value.label, LIMITS.label)) {
+    return null;
+  }
+  const selectors: AnnotationSelector[] = [];
+  for (const each of value.selectors) {
+    const parsed = selector(each);
+    if (parsed === null || selectors.some((other) => other.type === parsed.type)) {
+      return null;
+    }
+    selectors.push(parsed);
+  }
+  // A text anchor is found by its words; an element one needs a way to find the element.
+  const quote = selectors.some((each) => each.type === "TextQuoteSelector");
+  const css = selectors.some((each) => each.type === "CssSelector");
+  if (value.kind === "text" ? !quote : !css && !quote) {
+    return null;
+  }
+  return { kind: value.kind, selectors, label: value.label };
+}
+
+const coordinate = (value: unknown): value is number =>
+  typeof value === "number" && Number.isFinite(value) && Math.abs(value) <= LIMITS.coordinate;
+
+/** A box in the frame's viewport; null unless every number is finite and sizes aren't negative. */
+export function parseRect(value: unknown): AnnotationRect | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+  const { x, y, width, height } = value;
+  if (!coordinate(x) || !coordinate(y) || !coordinate(width) || !coordinate(height)) {
+    return null;
+  }
+  if (width < 0 || height < 0) {
+    return null;
+  }
+  return { x, y, width, height };
+}
+
+const markId = (value: unknown): value is string => text(value, LIMITS.id, 1);
+
+function results(value: unknown): AnchorResult[] | null {
+  if (!Array.isArray(value) || value.length > LIMITS.marks) {
+    return null;
+  }
+  const out: AnchorResult[] = [];
+  for (const each of value) {
+    if (!isRecord(each) || !markId(each.id)) {
+      return null;
+    }
+    if (each.state === "orphaned") {
+      out.push({ id: each.id, state: "orphaned" });
+      continue;
+    }
+    if (each.state !== "attached") {
+      return null;
+    }
+    const rect = each.rect === undefined ? undefined : parseRect(each.rect);
+    if (rect === null) {
+      return null;
+    }
+    out.push({ id: each.id, state: "attached", ...(rect === undefined ? {} : { rect }) });
+  }
+  return out;
+}
+
+/** A report from the frame, checked; null if malformed (it is then dropped). */
+export function parseReport(value: unknown): AnnotationReport | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+  switch (value.type) {
+    case "selected": {
+      const anchor = parseAnchor(value.anchor);
+      const rect = parseRect(value.rect);
+      return anchor === null || rect === null ? null : { type: "selected", anchor, rect };
+    }
+    case "unselected":
+      return { type: "unselected" };
+    case "cancelled":
+      return { type: "cancelled" };
+    case "anchored": {
+      const checked = results(value.results);
+      return checked === null ? null : { type: "anchored", results: checked };
+    }
+    default:
+      return null;
+  }
+}
+
+/** What the host may start with: elements, text, or both (default both). */
+export function annotateMode(mode: AnnotateMode | undefined): Required<AnnotateMode> {
+  const elements = mode?.elements ?? true;
+  const words = mode?.text ?? true;
+  if (typeof elements !== "boolean" || typeof words !== "boolean" || (!elements && !words)) {
+    throw new TypeError("annotations.start: elements, text, or both");
+  }
+  return { elements, text: words };
+}
+
+/** The host's marks, checked before they go to the frame; throws on the first bad one. */
+export function checkMarks(marks: readonly AnnotationMark[]): AnnotationMark[] {
+  if (!Array.isArray(marks) || marks.length > LIMITS.marks) {
+    throw new TypeError(`annotations.show: at most ${LIMITS.marks} marks`);
+  }
+  const seen = new Set<string>();
+  return marks.map((mark, index) => {
+    const anchor = parseAnchor(mark?.anchor);
+    if (!markId(mark?.id) || seen.has(mark.id) || anchor === null) {
+      throw new TypeError(
+        `annotations.show: mark ${index} needs a unique id (1 to ${LIMITS.id} characters) and a valid anchor`,
+      );
+    }
+    seen.add(mark.id);
+    return { id: mark.id, anchor };
+  });
+}

package/src/bridge/bridge.ts

@@ -1,9 +1,12 @@
 import {
+  MAX_COPY_CHARS,
   capabilitySpec,
   type CapabilityArgs,
   type CapabilityName,
   type CapabilityResults,
 } from "../config/capabilities.ts";
+import type { AnnotationReport } from "../annotate/types.ts";
+import { parseReport } from "../annotate/validate.ts";
 import type { PortholeConfig } from "../config/schema.ts";
 import { effectiveGates } from "../compile/policy.ts";
 import type {
@@ -26,6 +29,7 @@ import type {
 export type BridgeEvent =
   | { readonly type: "resize"; readonly height: number; readonly width?: number }
   | { readonly type: "error"; readonly message: string }
+  | { readonly type: "annotation"; readonly report: AnnotationReport }
   | { readonly type: "refused"; readonly capability: CapabilityName; readonly refusal: Refusal }
   | { readonly type: "muted" };
 
@@ -129,6 +133,13 @@ const VALIDATORS: { readonly [N in CapabilityName]: Validator<N> } = {
       ? { message: message.slice(0, 2_000) }
       : null;
   },
+  copyText: (args) => {
+    const text = isRecord(args) ? args.text : undefined;
+    return typeof text === "string" && text !== "" && text.length <= MAX_COPY_CHARS
+      ? { text }
+      : null;
+  },
+  annotate: (args) => parseReport(args),
   resize: (args) => {
     if (
       !isRecord(args) ||
@@ -250,6 +261,8 @@ export function createBridge(options: BridgeOptions): HostFunctionBridge {
         if (capability === "resize") {
           const size = args as CapabilityArgs["resize"];
           onEvent({ type: "resize", ...size });
+        } else if (capability === "annotate") {
+          onEvent({ type: "annotation", report: args as CapabilityArgs["annotate"] });
         } else {
           onEvent({ type: "error", message: (args as CapabilityArgs["reportError"]).message });
         }

package/src/compile/policy.ts

@@ -99,12 +99,15 @@ export function sandboxTokens(config: PortholeConfig): string[] {
 }
 
 /**
- * The frame's `allow` attribute (Permissions Policy). Empty: no camera, microphone, geolocation,
- * clipboard, fullscreen or other powerful feature is delegated to the frame; a url-mode config
- * may delegate clipboard writes and full screen to the app's own origin (P049).
+ * The frame's `allow` attribute (Permissions Policy). No camera, microphone, geolocation,
+ * fullscreen or other powerful feature is delegated to the frame, and the clipboard is denied by
+ * name (P051): content never writes it, the host does (`copyText`). A url-mode config may
+ * delegate clipboard writes and full screen to the app's own origin (P049).
  */
 export function allowAttribute(config: PortholeConfig): string {
-  return config.mode === "url" ? (config.permissions ?? []).join("; ") : "";
+  return config.mode === "url"
+    ? (config.permissions ?? []).join("; ")
+    : "clipboard-read 'none'; clipboard-write 'none'";
 }
 
 /**
@@ -126,6 +129,15 @@ export function embedderFrameSources(config: PortholeConfig): string[] {
  * engine Porthole supports reads frames from `frame-src`, P038).
  */
 export function embedderCsp(configs: readonly PortholeConfig[]): string {
-  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: readonly PortholeConfig[]): string[] {
+  return unique(configs.flatMap(embedderFrameSources));
+}