@botiverse/porthole 0.1.1 → 0.1.3

package/src/conformance/clipboard.ts

@@ -0,0 +1,184 @@
+import { expect, type Page } from "@playwright/test";
+import type { LaunchedDisplay } from "./index.ts";
+import { inline, type Probe } from "./kit.ts";
+import { settle } from "./oracles.ts";
+
+/**
+ * The clipboard (item 13, P051): content can't write it, whatever it tries in a person's click,
+ * and what a person copies themselves is what they selected. `copyText` is the way copy buttons
+ * work instead (item 12, P052). The oracle is the person's own clipboard: known text put on it
+ * from the host's page, then pasted back into a text area there.
+ */
+
+const SEED = "porthole-seed";
+
+/** A text area of the oracle's own on the host's page. */
+async function area(page: Page, id: string): Promise<void> {
+  await page.evaluate((each) => {
+    if (document.getElementById(each) === null) {
+      const element = document.createElement("textarea");
+      element.id = each;
+      element.style.cssText = "display:block;width:200px;height:40px";
+      document.body.prepend(element);
+    }
+  }, id);
+}
+
+/** Puts `text` on the clipboard the way a person does: selects it on the host's page, copies. */
+async function seed(page: Page, text: string): Promise<void> {
+  await area(page, "porthole-oracle-seed");
+  await page.evaluate((each) => {
+    (document.getElementById("porthole-oracle-seed") as HTMLTextAreaElement).value = each;
+  }, text);
+  await page.locator("#porthole-oracle-seed").click();
+  await page.keyboard.press("ControlOrMeta+A");
+  await page.keyboard.press("ControlOrMeta+C");
+}
+
+/** What is on the clipboard: pasted into a text area on the host's page. */
+async function pasted(page: Page): Promise<string> {
+  await area(page, "porthole-oracle-paste");
+  await page.evaluate(() => {
+    (document.getElementById("porthole-oracle-paste") as HTMLTextAreaElement).value = "";
+  });
+  await page.locator("#porthole-oracle-paste").click();
+  await page.keyboard.press("ControlOrMeta+V");
+  await settle(200);
+  return page.evaluate(
+    () => (document.getElementById("porthole-oracle-paste") as HTMLTextAreaElement).value,
+  );
+}
+
+/** Clicks `selector` in the display (a real click: the user activation a person gives). */
+async function click(display: LaunchedDisplay, selector: string): Promise<void> {
+  await (await display.frame()).locator(selector).click();
+}
+
+async function bodyData(display: LaunchedDisplay, name: string): Promise<string> {
+  const frame = await display.frame();
+  await expect
+    .poll(() => frame.locator("body").getAttribute(`data-${name}`), { timeout: 5_000 })
+    .not.toBeNull();
+  return (await frame.locator("body").getAttribute(`data-${name}`)) ?? "";
+}
+
+const settled = (name: string) =>
+  `(value) => (document.body.dataset.${name} = String(value)), (error) => (document.body.dataset.${name} = "refused: " + (error && error.name))`;
+
+export const CLIPBOARD_PROBES: readonly Probe[] = [
+  {
+    id: "13.clipboard-api",
+    item: 13,
+    title:
+      "content can't write (or read) the clipboard through the async Clipboard API, even in a click",
+    async run(context) {
+      const display = await context.launch({
+        config: inline(),
+        content: `<button id="go">copy</button>
+<script>
+  document.getElementById("go").addEventListener("click", () => {
+    navigator.clipboard.writeText("porthole-pwned-text").then(${settled("text")});
+    if (typeof ClipboardItem === "function") {
+      navigator.clipboard.write([new ClipboardItem({ "text/plain": new Blob(["porthole-pwned-item"], { type: "text/plain" }) })]).then(${settled("item")});
+    } else {
+      document.body.dataset.item = "refused: no ClipboardItem";
+    }
+    navigator.clipboard.readText().then(${settled("read")});
+  });
+</script>`,
+      });
+      await seed(context.page, SEED);
+      await click(display, "#go");
+      expect(await bodyData(display, "text")).toMatch(/^refused/u);
+      expect(await bodyData(display, "item")).toMatch(/^refused/u);
+      expect(await bodyData(display, "read")).toMatch(/^refused/u);
+      expect(await pasted(context.page), "the clipboard still holds the person's own").toBe(SEED);
+    },
+  },
+  {
+    id: "13.clipboard-command",
+    item: 13,
+    title:
+      "content can't copy or cut its own text onto the clipboard with execCommand, even in a click",
+    async run(context) {
+      const display = await context.launch({
+        config: inline(),
+        content: `<button id="go">copy</button>
+<script>
+  document.getElementById("go").addEventListener("click", () => {
+    const area = document.createElement("textarea");
+    area.value = "porthole-pwned-command";
+    area.style.cssText = "position:absolute;left:-9999px";
+    document.body.append(area);
+    area.select();
+    let copied = "threw";
+    let cut = "threw";
+    try { copied = document.execCommand("copy"); } catch (_) {}
+    area.select();
+    try { cut = document.execCommand("cut"); } catch (_) {}
+    document.body.dataset.copied = String(copied) + "," + String(cut);
+  });
+</script>`,
+      });
+      await seed(context.page, SEED);
+      await click(display, "#go");
+      expect(await bodyData(display, "copied")).not.toContain("true");
+      expect(await pasted(context.page), "the clipboard still holds the person's own").toBe(SEED);
+    },
+  },
+  {
+    id: "13.clipboard-event",
+    item: 13,
+    title:
+      "what a person copies is what they selected: no copy listener of the content's can swap it",
+    async run(context) {
+      const display = await context.launch({
+        config: inline(),
+        content: `<p id="safe">porthole-selected-text</p>
+<script>
+  const swap = (event) => {
+    event.clipboardData.setData("text/plain", "porthole-pwned-event");
+    event.preventDefault();
+    document.body.dataset.ran = "yes";
+  };
+  document.addEventListener("copy", swap);
+  document.addEventListener("copy", swap, true);
+  window.addEventListener("copy", swap);
+  document.getElementById("safe").oncopy = swap;
+</script>`,
+      });
+      await seed(context.page, SEED);
+      const frame = await display.frame();
+      await frame.locator("#safe").click({ clickCount: 3 });
+      await context.page.keyboard.press("ControlOrMeta+C");
+      await settle(200);
+      // The positive control: the person's own copy works, and copies what they selected.
+      expect((await pasted(context.page)).trim()).toBe("porthole-selected-text");
+      expect(await frame.locator("body").getAttribute("data-ran")).toBeNull();
+    },
+  },
+  {
+    id: "12.copy-text",
+    item: 12,
+    title:
+      "copyText reaches the host's handler from a click, with the whole text, never without one",
+    async run(context) {
+      const display = await context.launch({
+        config: inline({ capabilities: { copyText: {} } }),
+        content: `<button id="copy">Copy the command</button>
+<script>
+  document.getElementById("copy").addEventListener("click", () => {
+    copyText("npm test -- --run").then(${settled("result")});
+  });
+  copyText("copied on load").then(${settled("onload")});
+</script>`,
+      });
+      expect(await bodyData(display, "onload")).toMatch(/^refused/u);
+      await click(display, "#copy");
+      expect(await bodyData(display, "result")).toBe("true");
+      expect(await display.calls()).toEqual([
+        { capability: "copyText", args: { text: "npm test -- --run" } },
+      ]);
+    },
+  },
+];

package/src/conformance/kit.ts

@@ -29,7 +29,7 @@ export interface Probe {
   readonly id: string;
   /**
    * The DESIGN.md egress-table item it proves; 0 for the shell's own wiring and interop, 11 for
-   * behavior (streaming, sizing, theming), 12 for host-function gates.
+   * behavior (streaming, sizing, theming), 12 for host-function gates, 13 for the clipboard.
    */
   readonly item: number;
   readonly title: string;

package/src/conformance/probes.ts

@@ -13,6 +13,7 @@ import { resolveTheme } from "../theme/variables.ts";
 import type { ConformanceHost, LaunchedDisplay, LeakSuiteOptions } from "./index.ts";
 import { attack, inline, js, type Probe, type ProbeContext } from "./kit.ts";
 import { BEHAVIOR_PROBES } from "./behavior.ts";
+import { CLIPBOARD_PROBES } from "./clipboard.ts";
 import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import {
@@ -1025,6 +1026,7 @@ export const PROBES: readonly Probe[] = [
     },
   },
   ...BEHAVIOR_PROBES,
+  ...CLIPBOARD_PROBES,
 ];
 
 type AnyTest = TestType<

package/src/guide/guide.ts

@@ -1,4 +1,9 @@
-import { capabilitySpec, type CapabilityName, type Gate } from "../config/capabilities.ts";
+import {
+  MAX_COPY_CHARS,
+  capabilitySpec,
+  type CapabilityName,
+  type Gate,
+} from "../config/capabilities.ts";
 import type { PortholeConfig } from "../config/schema.ts";
 import { BUILT_IN_TOPICS } from "../config/validate.ts";
 import {
@@ -115,7 +120,7 @@ const loadsScripts = (config: PortholeConfig): boolean =>
   egressOrigins(config, "script").length > 0;
 
 /** What the sandbox withholds, from the sandbox tokens and the shell's own walls. */
-function forbidden(config: PortholeConfig): string {
+function forbidden(config: PortholeConfig, c: Context): string {
   const tokens = sandboxTokens(config);
   const items = ["position: fixed", "full screen"];
   if (!tokens.includes("allow-modals")) {
@@ -130,7 +135,11 @@ function forbidden(config: PortholeConfig): string {
   if (!tokens.includes("allow-downloads")) {
     items.push("downloads");
   }
-  items.push("clipboard writes", "frames (iframe, object, embed)", "WebRTC");
+  items.push(
+    c.global("copyText") ? "the clipboard (copy buttons call copyText)" : "the clipboard",
+    "frames (iframe, object, embed)",
+    "WebRTC",
+  );
   return `Not allowed: ${items.join(", ")}.`;
 }
 
@@ -172,7 +181,7 @@ function widget(c: Context): string {
     "- Cards in a row wrap (flex-wrap: wrap; flex: 1 1 100px), or a grid of repeat(auto-fit, minmax(160px, 1fr)): at most 2 columns under 500 px, never a fixed repeat(3, …).",
     "- Touch: anything clickable is at least 44 px tall. Phones don't hover: what a hover shows, a tap (click) shows too.",
     "",
-    `${forbidden(config)} ${network(config)} Keep it under ${Math.floor(limits.maxBytes / 1000)} KB.`,
+    `${forbidden(config, c)} ${network(config)} Keep it under ${Math.floor(limits.maxBytes / 1000)} KB.`,
     loadsScripts(config)
       ? "\nLibraries: pin an exact version at least two weeks old (chart.js@4.4.1 in its URL), never @latest or a range, so the code can't be swapped under you and draws the same every time."
       : null,
@@ -337,6 +346,12 @@ const ENTRIES: { readonly [N in CapabilityName]: (c: Context, gates: readonly Ga
       `- Data: the MCP Apps request resources/read (with the App SDK, app.readServerResource). ${gateWords(gates, "the request")}`,
     setModelContext: (_c, gates) =>
       `- Context for the agent: the MCP Apps request ui/update-model-context (with the App SDK, app.updateModelContext). ${gateWords(gates, "it")}`,
+    copyText: (c, gates) =>
+      c.global("copyText")
+        ? `- copyText(text): copies text to the person's clipboard (at most ${MAX_COPY_CHARS.toLocaleString("en-US")} characters), and the app shows them what was copied. Use it for every copy button: nothing else in the ${c.noun} can write the clipboard. ${gateWords(gates, "the text")} It returns a promise: true if it was copied.`
+        : `- Copying: the request porthole/copy-text with { text } (at most ${MAX_COPY_CHARS.toLocaleString("en-US")} characters) copies text to the person's clipboard, and the app shows them what was copied; nothing else in the ${c.noun} can write the clipboard. ${gateWords(gates, "the text")}`,
+    annotate: (c) =>
+      `- Comments: the person may point at parts of the ${c.noun} to comment on them. Give headings and the parts that matter stable ids (id="revenue"), so comments stay on them when the ${c.noun} is written again.`,
     reportError: (c, gates) =>
       `- Errors: what your code throws, and anything the sandbox blocks, is reported to the app (at most ${c.config.limits.maxErrorReports} a run). ${gateWords(gates, "it")}`.trim(),
     resize: () => "",

package/src/host/clipboard.ts

@@ -0,0 +1,41 @@
+/**
+ * Writing the clipboard from the host's page, for a `copyText` handler (P052): content never
+ * writes it itself (P051). The person's click in the frame gives the host's page user activation
+ * (it propagates to ancestors; measured on Chromium, WebKit and Firefox), which the write needs.
+ */
+
+/**
+ * Writes `text` to the clipboard: the async Clipboard API, else a selected text area and the copy
+ * command. Resolves whether it worked; it can fail without a recent gesture, so a host shows the
+ * text either way (and offers its own Copy button when it failed).
+ */
+export async function writeClipboard(text: string, document: Document): Promise<boolean> {
+  const view = document.defaultView;
+  try {
+    if (view?.navigator.clipboard !== undefined) {
+      await view.navigator.clipboard.writeText(text);
+      return true;
+    }
+  } catch {
+    // Fall through to the copy command.
+  }
+  const focused = document.activeElement;
+  const area = document.createElement("textarea");
+  area.value = text;
+  area.setAttribute("readonly", "");
+  area.setAttribute("aria-hidden", "true");
+  area.style.cssText =
+    "position:fixed;top:0;left:0;width:1px;height:1px;opacity:0;pointer-events:none;border:0;padding:0";
+  try {
+    document.body.append(area);
+    area.select();
+    return document.execCommand("copy");
+  } catch {
+    return false;
+  } finally {
+    area.remove();
+    if (focused !== null && typeof (focused as HTMLElement).focus === "function") {
+      (focused as HTMLElement).focus({ preventScroll: true });
+    }
+  }
+}

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,7 @@ import {
 import { shellAdapter } from "../protocol/shell-adapter.ts";
 import { resolveTheme } from "../theme/variables.ts";
 import type {
+  AnnotationControls,
   DisplayEvents,
   DisplayHandle,
   HostOptions,
@@ -31,6 +40,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);
 
 /**
@@ -90,6 +110,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;
@@ -142,10 +285,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();
@@ -197,6 +344,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 +357,10 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
           emit: (event) => {
             if (event.type === "initialized") {
               watch.initialized();
+              if (!handshaken) {
+                handshaken = true;
+                giveAnnotations();
+              }
               emit("initialized", undefined);
             }
           },
@@ -274,6 +428,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
 
       const controls = {
         displayId: mount.displayId,
+        annotations,
         setTheme(next: ColorScheme) {
           scheme = next;
           surface?.setColorScheme(next);

package/src/host/outcome.ts

@@ -25,6 +25,7 @@ const BLOCKS: readonly FrameBlock[] = [
   "cookies",
   "session",
   "upstream",
+  "denied",
   "not-found",
   "error",
 ];
@@ -33,6 +34,7 @@ interface FrameStatus {
   readonly state: "entering" | "blocked";
   readonly reason?: FrameBlock;
   readonly status?: number;
+  readonly code?: string;
 }
 
 /** A frame-status message, or null for anything else. */
@@ -44,7 +46,12 @@ export function parseFrameStatus(data: unknown): FrameStatus | null {
   if (message.jsonrpc !== "2.0" || message.method !== FRAME_STATUS_METHOD) {
     return null;
   }
-  const params = message.params as { state?: unknown; reason?: unknown; status?: unknown } | null;
+  const params = message.params as {
+    state?: unknown;
+    reason?: unknown;
+    status?: unknown;
+    code?: unknown;
+  } | null;
   if (params === null || typeof params !== "object") {
     return null;
   }
@@ -63,6 +70,9 @@ export function parseFrameStatus(data: unknown): FrameStatus | null {
     ...(typeof params.status === "number" && Number.isInteger(params.status)
       ? { status: params.status }
       : {}),
+    ...(typeof params.code === "string" && /^[a-z0-9-]{1,40}$/u.test(params.code)
+      ? { code: params.code }
+      : {}),
   };
 }
 
@@ -82,7 +92,8 @@ export function watchOutcome(options: {
 }): OutcomeWatch {
   const { surface, source, speaks } = options;
   const reports = source.kind === "url" && source.reports === true;
-  let decided = false;
+  // The first outcome; after a load, only a later block (a status page, access revoked) is told.
+  let decided: FrameOutcome["state"] | null = null;
   let heard = false;
   let entering = false;
   let loads = 0;
@@ -94,18 +105,24 @@ export function watchOutcome(options: {
     }, ms);
     timers.add(timer);
   };
-  const stop = () => {
+  const clearTimers = () => {
     for (const timer of timers) {
       clearTimeout(timer);
     }
     timers.clear();
+  };
+  const stop = () => {
+    clearTimers();
     unlisten();
     unload();
   };
   const decide = (outcome: FrameOutcome) => {
-    if (!decided) {
-      decided = true;
-      stop();
+    if (decided === null) {
+      decided = outcome.state;
+      clearTimers();
+      options.onOutcome(outcome);
+    } else if (decided === "loaded" && outcome.state === "blocked") {
+      decided = "blocked";
       options.onOutcome(outcome);
     }
   };
@@ -119,6 +136,7 @@ export function watchOutcome(options: {
         state: "blocked",
         reason: status.reason ?? "error",
         ...(status.status === undefined ? {} : { status: status.status }),
+        ...(status.code === undefined ? {} : { code: status.code }),
       });
     }
   });
@@ -130,7 +148,7 @@ export function watchOutcome(options: {
     });
   const unload = surface.onLoad(() => {
     loads += 1;
-    if (decided) {
+    if (decided !== null) {
       return;
     }
     if (speaks) {

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";
@@ -62,18 +63,27 @@ export type FrameBlock =
   | "session"
   /** 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";
 
 /**
- * How a display's first document went, once per run: 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
- * `limits.loadTimeoutMs`. A host shows its own fallback ("Open in a new tab") on anything but
- * loaded.
+ * 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
+ * `limits.loadTimeoutMs`. Once per run, plus a later `blocked` if the frame shows a status page
+ * after it loaded (access revoked mid-session). A host shows its own fallback ("Open in a new
+ * tab") on anything but loaded.
  */
 export type FrameOutcome =
   | { readonly state: "loaded" }
-  | { readonly state: "blocked"; readonly reason: FrameBlock; readonly status?: number }
+  | {
+      readonly state: "blocked";
+      readonly reason: FrameBlock;
+      readonly status?: number;
+      /** The host's own reason code, for `denied` (`Authorizer`). */
+      readonly code?: string;
+    }
   | { readonly state: "timeout" };
 
 export interface DisplayEvents {
@@ -91,6 +101,28 @@ export interface DisplayEvents {
   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 {
@@ -106,6 +138,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. */