@botiverse/porthole 0.1.2 → 0.1.3

package/dist/conformance/clipboard.js

@@ -0,0 +1,167 @@
+import { expect } from "@playwright/test";
+import { inline } from "./kit.js";
+import { settle } from "./oracles.js";
+/**
+ * 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, id) {
+    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, text) {
+    await area(page, "porthole-oracle-seed");
+    await page.evaluate((each) => {
+        document.getElementById("porthole-oracle-seed").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) {
+    await area(page, "porthole-oracle-paste");
+    await page.evaluate(() => {
+        document.getElementById("porthole-oracle-paste").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").value);
+}
+/** Clicks `selector` in the display (a real click: the user activation a person gives). */
+async function click(display, selector) {
+    await (await display.frame()).locator(selector).click();
+}
+async function bodyData(display, name) {
+    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) => `(value) => (document.body.dataset.${name} = String(value)), (error) => (document.body.dataset.${name} = "refused: " + (error && error.name))`;
+export const CLIPBOARD_PROBES = [
+    {
+        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/dist/conformance/kit.d.ts

@@ -26,7 +26,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/dist/conformance/probes.js

@@ -3,6 +3,7 @@ import { presets } from "../presets/presets.js";
 import { resolveTheme } from "../theme/variables.js";
 import { attack, inline, js } from "./kit.js";
 import { BEHAVIOR_PROBES } from "./behavior.js";
+import { CLIPBOARD_PROBES } from "./clipboard.js";
 import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { httpOracle, settle, udpOracle, } from "./oracles.js";
@@ -817,6 +818,7 @@ export const PROBES = [
         },
     },
     ...BEHAVIOR_PROBES,
+    ...CLIPBOARD_PROBES,
 ];
 /** Every probe as a test entry (see `ConformanceTest`). */
 export function leakTests(host, options = {}) {

package/dist/guide/guide.js

@@ -1,4 +1,4 @@
-import { capabilitySpec } from "../config/capabilities.js";
+import { MAX_COPY_CHARS, capabilitySpec, } from "../config/capabilities.js";
 import { BUILT_IN_TOPICS } from "../config/validate.js";
 import { declaredCapabilities, effectiveGates, egressOrigins, sandboxTokens, } from "../compile/policy.js";
 import { shellPlan } from "../shell/plan.js";
@@ -67,7 +67,7 @@ function network(config) {
 const optsIn = (config) => config.mode === "artifact" && (config.theme.documents ?? "declared") === "declared";
 const loadsScripts = (config) => egressOrigins(config, "script").length > 0;
 /** What the sandbox withholds, from the sandbox tokens and the shell's own walls. */
-function forbidden(config) {
+function forbidden(config, c) {
     const tokens = sandboxTokens(config);
     const items = ["position: fixed", "full screen"];
     if (!tokens.includes("allow-modals")) {
@@ -82,7 +82,7 @@ function forbidden(config) {
     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(", ")}.`;
 }
 function widget(c) {
@@ -102,7 +102,7 @@ function widget(c) {
     const smallest = Math.round(((13 * layout.minWidthPx) / viewBox) * 10) / 10;
     const largest = Math.round(((13 * 400) / viewBox) * 10) / 10;
     const textSize = themeDefault(config.theme.variables["--font-text-md-size"] ?? "14px", "light").replace(/^(\d+(?:\.\d+)?)px$/u, "$1 px");
-    return lines(`# ${title}${tool}`, "", what, "", `Where it runs: in a sandboxed frame as wide as the column it sits in, about ${layout.narrowWidthPx} px on a phone (${layout.minWidthPx} on a small one) and ${layout.wideWidthPx} on a desktop; the same ${noun} is read on both, so never write for one of them. Design for ${layout.narrowWidthPx} first; where the layout depends on the width, read it as it runs (the box's clientWidth, again from a ResizeObserver). ${height} ${optsIn(config) ? `It shows in light, as you style it; to follow the person's light or dark theme, declare it in its head (<meta name="color-scheme" content="light dark">) and draw with the variables below.` : "It runs in the person's light or dark theme."} It runs again each time it is shown${loadsScripts(config) ? ": pin library versions" : ""}.`, "", "Sizes that read on a phone:", c.when(`- Words go in HTML (titles, notes, legends, readouts): it keeps its size and wraps. The frame's text is already ${textSize} --font-sans in --color-text-primary; notes --font-text-sm-size, never under 12 px.`), `- An SVG scales with the frame: its text shows at font-size × frame width ÷ viewBox width, so a 680-wide viewBox turns 12 into 5 px on a phone. Draw it for the phone: viewBox="0 0 ${viewBox} H", no text under 13, width="100%" style="max-width: 400px"; its text then shows at ${smallest} to ${largest} px on every screen. Or draw it 1 unit = 1 px with a script (topic chart).`, `- The frame never scrolls sideways: nothing fixed wider than ${layout.minWidthPx} px; images max-width: 100%; a grid or flex child with long text min-width: 0; a wide table or code block in its own box with overflow-x: auto.`, "- 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.`, loadsScripts(config)
+    return lines(`# ${title}${tool}`, "", what, "", `Where it runs: in a sandboxed frame as wide as the column it sits in, about ${layout.narrowWidthPx} px on a phone (${layout.minWidthPx} on a small one) and ${layout.wideWidthPx} on a desktop; the same ${noun} is read on both, so never write for one of them. Design for ${layout.narrowWidthPx} first; where the layout depends on the width, read it as it runs (the box's clientWidth, again from a ResizeObserver). ${height} ${optsIn(config) ? `It shows in light, as you style it; to follow the person's light or dark theme, declare it in its head (<meta name="color-scheme" content="light dark">) and draw with the variables below.` : "It runs in the person's light or dark theme."} It runs again each time it is shown${loadsScripts(config) ? ": pin library versions" : ""}.`, "", "Sizes that read on a phone:", c.when(`- Words go in HTML (titles, notes, legends, readouts): it keeps its size and wraps. The frame's text is already ${textSize} --font-sans in --color-text-primary; notes --font-text-sm-size, never under 12 px.`), `- An SVG scales with the frame: its text shows at font-size × frame width ÷ viewBox width, so a 680-wide viewBox turns 12 into 5 px on a phone. Draw it for the phone: viewBox="0 0 ${viewBox} H", no text under 13, width="100%" style="max-width: 400px"; its text then shows at ${smallest} to ${largest} px on every screen. Or draw it 1 unit = 1 px with a script (topic chart).`, `- The frame never scrolls sideways: nothing fixed wider than ${layout.minWidthPx} px; images max-width: 100%; a grid or flex child with long text min-width: 0; a wide table or code block in its own box with overflow-x: auto.`, "- 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, 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, "", optsIn(config)
         ? `Colors, for a ${noun} that declares light and dark: every color from these variables, never hard-coded, so both work; its own background then stays transparent (it sits on the app's surface).`
@@ -189,6 +189,10 @@ const ENTRIES = {
     callTool: (_c, gates) => `- Tools: the MCP Apps request tools/call (with the App SDK, app.callServerTool). ${gateWords(gates, "the call")}`,
     readData: (_c, gates) => `- 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/dist/host/clipboard.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 declare function writeClipboard(text: string, document: Document): Promise<boolean>;

package/dist/host/clipboard.js

@@ -0,0 +1,43 @@
+/**
+ * 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, document) {
+    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.focus === "function") {
+            focused.focus({ preventScroll: true });
+        }
+    }
+}

package/dist/host/create-host.js

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

package/dist/host/types.d.ts

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

package/dist/index.d.ts

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

package/dist/index.js

@@ -3,7 +3,7 @@
  * frame's policies, the shell, and the agent manual; the host mounts displays under it.
  */
 // The config and its vocabulary.
-export { CAPABILITIES, CAPABILITY_NAMES, capabilitySpec, isCapabilityName, } from "./config/capabilities.js";
+export { CAPABILITIES, CAPABILITY_NAMES, MAX_COPY_CHARS, capabilitySpec, isCapabilityName, } from "./config/capabilities.js";
 export { BUILT_IN_TOPICS, ConfigError, isOriginSource, originSourceProblem, validateConfig, } from "./config/validate.js";
 export { URL_PERMISSIONS, URL_SANDBOX_EXTRAS, } from "./config/schema.js";
 export { hostOriginProblem, isHostOrigin } from "./isolation/served.js";
@@ -18,5 +18,9 @@ export { generateGuide, generateToolDescription, } from "./guide/guide.js";
 export { GUIDE_EXAMPLES } from "./guide/examples.js";
 // Theme.
 export { CHART_PALETTE, DEFAULT_THEME, DEFAULT_THEME_EVENT, DEFAULT_THEME_VARIABLES, resolveTheme, themeDefault, } from "./theme/variables.js";
-export { MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS_STYLE_VARIABLES, PORTHOLE_STYLES, } from "./protocol/mcp-apps.js";
+export { COPY_TEXT_METHOD, MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS_STYLE_VARIABLES, PORTHOLE_STYLES, } from "./protocol/mcp-apps.js";
 export { createHost } from "./host/create-host.js";
+export { writeClipboard } from "./host/clipboard.js";
+// Annotations (P053): anchors, what a frame reports, and the host's checks on both.
+export { ANNOTATE_METHODS, ANNOTATION_LIMITS, } from "./annotate/types.js";
+export { parseAnchor, parseRect, parseReport } from "./annotate/validate.js";

package/dist/mcp/adapter.js

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

package/dist/protocol/mcp-apps.d.ts

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

package/dist/protocol/mcp-apps.js

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