@botiverse/porthole 0.1.2 → 0.1.4

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/conformance/served.d.ts

@@ -35,8 +35,15 @@ export interface ServedConformanceHost {
      * Shows `instance` in `page` as the host does: a fresh ticket from its backend, framed under
      * the config's sandbox, in an embedding page that sends the config's `embedderCsp`. The same page
      * may show several, one after another.
+     *
+     * For a served shell the suite gives `options.content`, a line of HTML: a host that speaks to
+     * the shell (`createHost`, the React binding) sends it as the display's content, since a shell
+     * draws nothing (and reports no height) until it has content, and the cases click inside it. A
+     * host whose frame has a height of its own may ignore it.
      */
-    show(page: Page, instance: InstanceRef): Promise<ServedDisplay>;
+    show(page: Page, instance: InstanceRef, options?: {
+        readonly content?: string;
+    }): Promise<ServedDisplay>;
     /** A fresh ticketed location for `instance`, as the host's backend issues it. */
     locate(instance: InstanceRef): Promise<FrameLocation>;
     /** Navigates `page` to a page on an origin that is not one of the host's, framing `url`. */

package/dist/conformance/served.js

@@ -14,6 +14,8 @@
 import { expect } from "@playwright/test";
 import { MCP_APPS_METHODS } from "../protocol/mcp-apps.js";
 const SETTLE_MS = 800;
+/** What a served shell is given to draw (`ServedConformanceHost.show`'s `content`). */
+const SHELL_CONTENT = '<p id="porthole-probe-content">Porthole conformance probe</p>';
 /** What the frame can see of its host: everything here must be closed to it. */
 async function reachIntoHost(frame) {
     return frame.evaluate(() => {
@@ -109,21 +111,23 @@ export function servedTests(host, options = {}) {
             ["domain", (scope) => host.shell(scope)],
             ["url", (scope) => host.app(scope)],
         ];
+        // A served shell draws (and has a height to click in) once its host gives it content.
+        const showMode = (page, mode, instance) => host.show(page, instance, mode === "domain" ? { content: SHELL_CONTENT } : {});
         for (const [mode, instance] of modes) {
             define(`served.${mode}.origin`, "content runs on its own origin, never the host's", async ({ page }) => {
-                const display = await host.show(page, instance(`${mode}-origin`));
+                const display = await showMode(page, mode, instance(`${mode}-origin`));
                 const frame = await display.frame();
                 const origin = await frame.evaluate(() => window.origin);
                 expect(origin).toBe(display.origin);
                 expect(origin).not.toBe(new URL(page.url()).origin);
             });
             define(`served.${mode}.no-reach`, "content can't reach the host's DOM, storage, cookies or URL", async ({ page }) => {
-                const display = await host.show(page, instance(`${mode}-reach`));
+                const display = await showMode(page, mode, instance(`${mode}-reach`));
                 await plantHostSecrets(page);
                 expect(await reachIntoHost(await display.frame())).toEqual(CLOSED);
             });
             define(`served.${mode}.no-top-navigation`, "content can't navigate the host's page, even after a click", async ({ page }) => {
-                const display = await host.show(page, instance(`${mode}-top`));
+                const display = await showMode(page, mode, instance(`${mode}-top`));
                 const frame = await display.frame();
                 const before = page.url();
                 const target = await host.canary(`${mode}-top`);
@@ -153,7 +157,7 @@ export function servedTests(host, options = {}) {
                 expect(await host.canaryHits(`${mode}-top`)).toBe(0);
             });
             define(`served.${mode}.no-popups`, "content can't open a window, even after a click", async ({ page }) => {
-                const display = await host.show(page, instance(`${mode}-popup`));
+                const display = await showMode(page, mode, instance(`${mode}-popup`));
                 const frame = await display.frame();
                 const target = await host.canary(`${mode}-popup`);
                 const opened = [];
@@ -186,13 +190,13 @@ export function servedTests(host, options = {}) {
             });
         }
         define("served.domain.storage-scope", "storage persists within a scope and is never shared across scopes", async ({ page }) => {
-            const first = await host.show(page, host.shell("scope-a"));
+            const first = await host.show(page, host.shell("scope-a"), { content: SHELL_CONTENT });
             await (await first.frame()).evaluate(() => localStorage.setItem("kept", "a"));
             await first.destroy();
-            const again = await host.show(page, host.shell("scope-a"));
+            const again = await host.show(page, host.shell("scope-a"), { content: SHELL_CONTENT });
             expect(await (await again.frame()).evaluate(() => localStorage.getItem("kept"))).toBe("a");
             expect(again.origin).toBe(first.origin);
-            const other = await host.show(page, host.shell("scope-b"));
+            const other = await host.show(page, host.shell("scope-b"), { content: SHELL_CONTENT });
             expect(other.origin).not.toBe(first.origin);
             expect(await (await other.frame()).evaluate(() => localStorage.getItem("kept"))).toBeNull();
         });
@@ -247,7 +251,7 @@ export function servedTests(host, options = {}) {
             }
         });
         define("served.domain.egress", "the CSP in the document's headers closes egress", async ({ page }) => {
-            const display = await host.show(page, host.shell("egress"));
+            const display = await host.show(page, host.shell("egress"), { content: SHELL_CONTENT });
             const frame = await display.frame();
             const fetched = await frame.evaluate(async (url) => {
                 try {

package/dist/guide/guide.js

@@ -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: () => "",
 };
@@ -202,7 +206,9 @@ function interactive(c) {
         .filter((entry) => entry !== "");
     const state = config.isolation === "opaque"
         ? `- State isn't saved: localStorage works but lasts only while the ${noun} is on screen, and a reload or another device starts fresh. Keep what matters in the ${noun}'s code.`
-        : `- localStorage is kept for this ${noun} in this browser; another device starts fresh.`;
+        : config.storage?.shared === undefined
+            ? `- localStorage is kept for this ${noun} in this browser; another device starts fresh.`
+            : `- localStorage is shared by every ${noun} in this ${config.storage.shared}, in this browser (another device starts fresh): prefix your keys with a name of this ${noun}'s own ("budget:filters", not "filters"), or ${noun}s overwrite each other.`;
     const none = entries.length === 0
         ? `- It can only draw: it has no way to send anything to you or the app.`
         : null;

package/dist/host/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 });
+        }
+    }
+}