@botiverse/porthole 0.1.0 → 0.1.1

package/dist/react/frame.js

@@ -25,9 +25,9 @@ export function PortholeProvider(props) {
     useLayoutEffect(() => {
         own.current = props.confirm;
     });
-    const confirm = useCallback((request) => own.current !== undefined
-        ? own.current(request)
-        : new Promise((resolve) => setQueue((waiting) => [...waiting, { request, resolve }])), []);
+    const confirm = useCallback((request, proceed) => own.current !== undefined
+        ? own.current(request, proceed)
+        : new Promise((resolve) => setQueue((waiting) => [...waiting, { request, resolve, proceed }])), []);
     const { hostInfo, locator } = props;
     const value = useMemo(() => ({
         live,
@@ -38,7 +38,11 @@ export function PortholeProvider(props) {
     }), [live, heights, confirm, hostInfo, locator]);
     const current = queue[0] ?? null;
     return (_jsxs(Page.Provider, { value: value, children: [props.children, props.confirm === undefined ? (_jsx(ConfirmDialog, { request: current?.request ?? null, ...(props.dialogClassName === undefined ? {} : { className: props.dialogClassName }), onAnswer: (accepted) => {
-                    current?.resolve(accepted);
+                    // A yes runs the effect inside this very click (a window it opens is the person's).
+                    if (accepted) {
+                        current?.proceed();
+                    }
+                    current?.resolve(accepted ? "accepted" : "declined");
                     setQueue((waiting) => waiting.slice(1));
                 } })) : null] }));
 }
@@ -56,6 +60,16 @@ const PLACEHOLDER_STYLE = {
 function DefaultPlaceholder({ state, title, run }) {
     return (_jsxs("div", { "data-porthole-placeholder": state, style: { ...PLACEHOLDER_STYLE, pointerEvents: state === "stopped" ? "auto" : "none" }, children: [_jsx("span", { children: state === "stopped" ? "Stopped while others run" : title }), state === "stopped" ? (_jsx("button", { type: "button", "data-porthole-run": "", onClick: run, children: "Run again" })) : null] }));
 }
+/** A display's remembered height: under its id, else under the first of its other ids that has one. */
+function rememberedHeight(heights, displayId, aliases) {
+    for (const id of [displayId, ...(aliases ?? [])]) {
+        const height = heights.get(id);
+        if (height !== undefined) {
+            return height;
+        }
+    }
+    return 0;
+}
 export function PortholeFrame(props) {
     const page = useContext(Page);
     const key = useId();
@@ -89,7 +103,17 @@ export function PortholeFrame(props) {
             page.live.release(key);
         };
     }, [page, key, max, eager]);
-    const height = page.heights.get(props.displayId) ?? 0;
+    const height = rememberedHeight(page.heights, props.displayId, props.aliases);
+    // A display renamed while it runs (its id settled) keeps its height under its new id.
+    const previousId = useRef(props.displayId);
+    useLayoutEffect(() => {
+        const before = previousId.current;
+        previousId.current = props.displayId;
+        const kept = page.heights.get(before);
+        if (before !== props.displayId && kept !== undefined && !page.heights.has(props.displayId)) {
+            page.heights.set(props.displayId, kept);
+        }
+    }, [page, props.displayId]);
     const run = () => page.live.admit(key, max);
     const placeholder = props.renderPlaceholder ?? DefaultPlaceholder;
     return (_jsx("div", { ref: box, className: props.className, "data-porthole-display": props.displayId, "data-porthole-state": state, style: {
@@ -107,6 +131,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
     // The height this display started at: later reports don't make it start again.
     const [startHeight] = useState(initialHeightPx);
     const { config, document: view, instance, content, partial, scheme } = frame;
+    const fills = config.mode === "url";
     // The latest props, read when the display calls back (never during render).
     const latest = useEffectEvent(() => frame);
     const notify = useEffectEvent((event, detail) => {
@@ -135,6 +160,9 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
             case "muted":
                 frame.onMuted?.();
                 return;
+            case "outcome":
+                frame.onOutcome?.(detail);
+                return;
         }
     });
     useEffect(() => {
@@ -162,10 +190,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
                 handlers,
                 ...(asks
                     ? {
-                        confirm: (request) => (latest().confirm ?? page.confirm ?? (() => Promise.resolve(false)))({
-                            ...request,
-                            display: { id: latest().displayId, title: latest().title },
-                        }),
+                        confirm: (request, proceed) => (latest().confirm ?? page.confirm ?? (() => Promise.resolve(false)))({ ...request, display: { id: latest().displayId, title: latest().title } }, proceed),
                     }
                     : {}),
                 theme: (each) => latest().theme?.(each) ?? {},
@@ -192,6 +217,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
             "navigated",
             "refused",
             "muted",
+            "outcome",
         ];
         for (const event of events) {
             display.on(event, (detail) => notify(event, detail));
@@ -214,8 +240,16 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
     useEffect(() => {
         handle.current?.setTheme(scheme);
     }, [scheme]);
+    const { themeKey } = frame;
+    useEffect(() => {
+        if (themeKey !== undefined) {
+            handle.current?.refreshTheme();
+        }
+    }, [themeKey]);
     return (_jsxs("div", { "data-porthole-ready": String(ready), style: {
             position: "relative",
+            // A url-mode app fills the frame's box (give PortholeFrame a height); the rest size to content.
+            ...(fills ? { height: "100%" } : {}),
             ...(ready ? {} : { minHeight: Math.max(startHeight, PLACEHOLDER_HEIGHT_PX) }),
-        }, children: [_jsx("div", { ref: holder, "data-porthole-mount": "", style: { opacity: ready ? 1 : 0 } }), ready ? null : placeholder({ state: "loading", title: frame.title, run })] }));
+        }, children: [_jsx("div", { ref: holder, "data-porthole-mount": "", style: { opacity: ready ? 1 : 0, ...(fills ? { height: "100%" } : {}) } }), ready ? null : placeholder({ state: "loading", title: frame.title, run })] }));
 }

package/dist/server/pages.d.ts

@@ -1,6 +1,11 @@
-/**
- * The server's own pages on a content origin: why it shows nothing of the content. Plain, no
- * script, framable only by the host origins, never cached. Their words are the host-agnostic
- * mechanism's; a host that wants its own wording serves its own page in front.
- */
-export declare function statusPage(status: number, title: string, detail: string, frameAncestors: string, method?: string): Response;
+import type { FrameBlock } from "../host/types.ts";
+/** Where the pages' scripts are served, on every content origin. */
+export declare const STATUS_SCRIPT_PATH = "/__porthole/status.js";
+export declare const ENTER_SCRIPT_PATH = "/__porthole/enter.js";
+/** Answers 204 when the request carries a good session for its origin's app, 401 otherwise. */
+export declare const SESSION_PATH = "/__porthole/session";
+/** The pages' scripts, by path: served with the pages' own policy in mind (`script-src 'self'`). */
+export declare function pageScript(pathname: string): Response | null;
+export declare function statusPage(status: number, title: string, detail: string, frameAncestors: string, method?: string, reason?: FrameBlock, hostOrigins?: readonly string[]): Response;
+/** The page a framed app is entered through (its answer also sets the session cookie). */
+export declare function enterPage(target: string, frameAncestors: string, hostOrigins: readonly string[], cookie: string): Response;

package/dist/server/pages.js

@@ -1,20 +1,86 @@
+import { FRAME_STATUS_METHOD } from "../isolation/types.js";
 /**
- * The server's own pages on a content origin: why it shows nothing of the content. Plain, no
- * script, framable only by the host origins, never cached. Their words are the host-agnostic
- * mechanism's; a host that wants its own wording serves its own page in front.
+ * The server's own pages on a content origin: why it shows nothing of the content, and the page a
+ * framed app is entered through. Plain, framable only by the host origins, never cached. Each tells
+ * the page that frames it how loading went (`porthole/notifications/frame-status`, P040), posted to
+ * the host origins only, so a host can show its own fallback ("Open in a new tab"). Their words are
+ * the host-agnostic mechanism's; a host that wants its own wording serves its own page in front.
  */
 const escape = (text) => text.replace(/[&<>"']/gu, (char) => `&#${char.charCodeAt(0)};`);
 const STYLE = ":root{color-scheme:light dark;font-family:system-ui,sans-serif}body{margin:0;min-height:100vh;display:grid;place-items:center;background:Canvas;color:CanvasText}main{max-width:420px;padding:24px}h1{font-size:17px;margin:0 0 8px}p{margin:0;opacity:.75;line-height:1.5}";
-export function statusPage(status, title, detail, frameAncestors, method = "GET") {
-    const body = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${escape(title)}</title><style>${STYLE}</style></head><body><main data-porthole-status="${status}"><h1>${escape(title)}</h1><p>${escape(detail)}</p></main></body></html>`;
+/** Where the pages' scripts are served, on every content origin. */
+export const STATUS_SCRIPT_PATH = "/__porthole/status.js";
+export const ENTER_SCRIPT_PATH = "/__porthole/enter.js";
+/** Answers 204 when the request carries a good session for its origin's app, 401 otherwise. */
+export const SESSION_PATH = "/__porthole/session";
+const say = () => `const say = (params) => { if (window.parent === window) return; for (const origin of hosts) window.parent.postMessage({ jsonrpc: "2.0", method: ${JSON.stringify(FRAME_STATUS_METHOD)}, params }, origin); };`;
+/** Tells the host the page is blocked, and why (from the page's data attributes). */
+const STATUS_SCRIPT = `(() => {
+  const main = document.querySelector("[data-porthole-status]");
+  if (main === null) return;
+  const hosts = JSON.parse(main.dataset.portholeHosts || "[]");
+  ${say()}
+  say({ state: "blocked", reason: main.dataset.portholeReason || "error", status: Number(main.dataset.portholeStatus) });
+})();`;
+/**
+ * Enters a framed app: says so, checks that the browser kept the session cookie this page's own
+ * answer set (WebKit keeps none in a cross-site frame, P025), then goes on to the app, or says it
+ * is blocked and why.
+ */
+const ENTER_SCRIPT = `(async () => {
+  const main = document.querySelector("[data-porthole-enter]");
+  if (main === null) return;
+  const hosts = JSON.parse(main.dataset.portholeHosts || "[]");
+  ${say()}
+  say({ state: "entering" });
+  let kept = false;
+  try {
+    kept = (await fetch(${JSON.stringify(SESSION_PATH)}, { credentials: "same-origin", cache: "no-store" })).ok;
+  } catch (_) {}
+  if (kept) {
+    location.replace(main.dataset.portholeTarget || "/");
+    return;
+  }
+  say({ state: "blocked", reason: "cookies", status: 401 });
+  main.querySelector("h1").textContent = "Open this app in a new tab";
+  main.querySelector("p").textContent = "This browser keeps no sign-in for it inside a frame.";
+})();`;
+/** The pages' scripts, by path: served with the pages' own policy in mind (`script-src 'self'`). */
+export function pageScript(pathname) {
+    const body = pathname === STATUS_SCRIPT_PATH
+        ? STATUS_SCRIPT
+        : pathname === ENTER_SCRIPT_PATH
+            ? ENTER_SCRIPT
+            : null;
+    return body === null
+        ? null
+        : new Response(body, {
+            headers: {
+                "content-type": "text/javascript; charset=utf-8",
+                "cache-control": "no-store",
+                "x-content-type-options": "nosniff",
+            },
+        });
+}
+const policy = (frameAncestors, connect) => `default-src 'none'; style-src 'unsafe-inline'; script-src 'self'; ${connect ? "connect-src 'self'; " : ""}base-uri 'none'; form-action 'none'; frame-ancestors ${frameAncestors}`;
+const pageHeaders = (frameAncestors, connect) => ({
+    "content-type": "text/html; charset=utf-8",
+    "cache-control": "no-store",
+    "content-security-policy": policy(frameAncestors, connect),
+    "referrer-policy": "no-referrer",
+    "x-content-type-options": "nosniff",
+});
+export function statusPage(status, title, detail, frameAncestors, method = "GET", reason = "error", hostOrigins = []) {
+    const body = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${escape(title)}</title><style>${STYLE}</style></head><body><main data-porthole-status="${status}" data-porthole-reason="${escape(reason)}" data-porthole-hosts="${escape(JSON.stringify(hostOrigins))}"><h1>${escape(title)}</h1><p>${escape(detail)}</p></main><script src="${STATUS_SCRIPT_PATH}"></script></body></html>`;
     return new Response(method === "HEAD" ? null : body, {
         status,
-        headers: {
-            "content-type": "text/html; charset=utf-8",
-            "cache-control": "no-store",
-            "content-security-policy": `default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'; frame-ancestors ${frameAncestors}`,
-            "referrer-policy": "no-referrer",
-            "x-content-type-options": "nosniff",
-        },
+        headers: pageHeaders(frameAncestors, false),
     });
 }
+/** The page a framed app is entered through (its answer also sets the session cookie). */
+export function enterPage(target, frameAncestors, hostOrigins, cookie) {
+    const body = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Opening the app</title><style>${STYLE}</style></head><body><main data-porthole-enter="" data-porthole-target="${escape(target)}" data-porthole-hosts="${escape(JSON.stringify(hostOrigins))}"><h1>Opening the app…</h1><p></p></main><script src="${ENTER_SCRIPT_PATH}"></script></body></html>`;
+    const headers = new Headers(pageHeaders(frameAncestors, true));
+    headers.set("set-cookie", cookie);
+    return new Response(body, { status: 200, headers });
+}

package/dist/server/server.js

@@ -1,8 +1,8 @@
 import { compile } from "../compile/compile.js";
-import { isExactOrigin, maybeSameSite, originMatchesSource, parseOrigin, } from "../isolation/served.js";
+import { hostOriginProblem, maybeSameSite, originMatchesSource, parseOrigin, } from "../isolation/served.js";
 import { sandboxProxyDocument } from "../mcp/proxy.js";
 import { createKeys, newTicket, ticketId } from "./keys.js";
-import { statusPage } from "./pages.js";
+import { enterPage, pageScript, SESSION_PATH, statusPage } from "./pages.js";
 import { memoryTicketStore } from "./tickets.js";
 /**
  * Paths on a content origin. Porthole's own live under `/__porthole/`; on a url-mode app's origin
@@ -155,9 +155,14 @@ export function createServer(options) {
         throw new TypeError("hostOrigins must name the origins that embed content");
     }
     for (const origin of options.hostOrigins) {
-        const parsed = isExactOrigin(origin) ? parseOrigin(origin) : null;
+        const problem = hostOriginProblem(origin);
+        if (problem !== null) {
+            throw new TypeError(`hostOrigins: ${problem}`);
+        }
+        // A desktop app's own scheme (ferry://app) is never the same site as web content.
+        const parsed = parseOrigin(origin);
         if (parsed === null) {
-            throw new TypeError(`hostOrigins: ${JSON.stringify(origin)} is not an exact origin`);
+            continue;
         }
         if (parsed.host === domain ||
             parsed.host.endsWith(`.${domain}`) ||
@@ -171,7 +176,8 @@ export function createServer(options) {
         compiled.set(name, compile(config));
     }
     const tickets = options.tickets ?? memoryTicketStore();
-    const page = (status, title, detail, method) => statusPage(status, title, detail, frameAncestors, method);
+    /** A page saying why there is nothing to show, told to the host too (its reason, P040). */
+    const page = (status, title, detail, method, reason = status === 404 ? "not-found" : status === 502 ? "upstream" : "error") => statusPage(status, title, detail, frameAncestors, method, reason, options.hostOrigins);
     /** The config a served document is served under, checked to fit it and this server. */
     function configFor(name, kind) {
         const each = compiled.get(name);
@@ -357,7 +363,7 @@ export function createServer(options) {
         }
         access ??= accessOf(request, label, key);
         if (access === null) {
-            return page(401, "This link has been used", "Content here opens once per link. Open it again from the app that showed it.", method);
+            return page(401, "This link has been used", "Content here opens once per link. Open it again from the app that showed it.", method, "session");
         }
         const served = await documentOf(access.instance);
         if (served === null) {
@@ -376,13 +382,20 @@ export function createServer(options) {
         }
         const record = await take(url.searchParams.get("ticket"), label);
         if (record === null || record.instance.document.kind !== "external") {
-            return page(403, "This link has been used", "A link into an app works once, for a short time. Open it again from the app that showed it.");
+            return page(403, "This link has been used", "A link into an app works once, for a short time. Open it again from the app that showed it.", method, "session");
         }
         const target = new URL(record.instance.document.url);
+        const landing = `${target.pathname}${target.search}${target.hash}`;
+        // In a frame, a page enters the app: it can tell whether the browser kept the cookie (and tell
+        // the host), where a redirect would leave a frame without one showing a refusal. On a tab of
+        // its own, a redirect.
+        if (request.headers.get("sec-fetch-dest") !== "document") {
+            return enterPage(landing, frameAncestors, options.hostOrigins, sessionCookie(request, record));
+        }
         return new Response(null, {
             status: 303,
             headers: {
-                location: `${target.pathname}${target.search}${target.hash}`,
+                location: landing,
                 "set-cookie": sessionCookie(request, record),
                 "cache-control": "no-store",
                 "referrer-policy": "no-referrer",
@@ -425,7 +438,7 @@ export function createServer(options) {
         const method = request.method.toUpperCase();
         const access = accessOf(request, label, null);
         if (access === null) {
-            return page(401, "Open this from the app", "This address shows an app only to the people the app opens it for.", method);
+            return page(401, "Open this from the app", "This address shows an app only to the people the app opens it for.", method, "session");
         }
         if (options.upstream === undefined) {
             return page(502, "Nothing serves this app", "The server has no upstream for apps.", method);
@@ -481,7 +494,7 @@ export function createServer(options) {
             const path = clean.document.kind === "external"
                 ? `${ENTER_PATH}?ticket=${ticket}`
                 : `${PREFIX}d/${key}?ticket=${ticket}`;
-            return { url: `${origin}${path}`, origin };
+            return { url: `${origin}${path}`, origin, reports: true };
         },
         async access(request) {
             const at = labelOf(request);
@@ -501,6 +514,17 @@ export function createServer(options) {
                 if (url.pathname === ENTER_PATH) {
                     return await enter(request, url, label);
                 }
+                const script = pageScript(url.pathname);
+                if (script !== null) {
+                    return script;
+                }
+                if (url.pathname === SESSION_PATH) {
+                    // Whether this request's cookie opens its origin's app: the entry page asks.
+                    return new Response(null, {
+                        status: accessOf(request, label, null) === null ? 401 : 204,
+                        headers: { "cache-control": "no-store" },
+                    });
+                }
                 const document = DOCUMENT_PATH.exec(url.pathname);
                 if (document?.[1] !== undefined) {
                     return await serveDocument(request, url, label, document[1]);

package/dist/shell/document.d.ts

@@ -2,8 +2,9 @@ import type { ShellPlan } from "./plan.ts";
 export interface ShellDocumentOptions {
     /**
      * The origins the shell takes messages from: the embedding page's own (`location.origin`), or
-     * every host origin a served document may be embedded by. Exact origins, no wildcards. The
-     * sender must also be the frame's parent.
+     * every host origin a served document may be embedded by. Exact origins of any scheme (a
+     * desktop app's own, `ferry://app`), no wildcards, never "null". The sender must also be the
+     * frame's parent.
      */
     readonly origins: readonly string[];
     /** The frame document's title (for assistive technology inside the frame). */

package/dist/shell/document.js

@@ -1,5 +1,5 @@
+import { hostOriginProblem } from "../isolation/served.js";
 import { SHELL_RUNTIME } from "./runtime.js";
-const EXACT_ORIGIN = /^(https?:\/\/[a-z0-9.-]+(:\d{1,5})?|https?:\/\/\[::1\](:\d{1,5})?)$/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 `<!--`. */
@@ -47,8 +47,9 @@ body {
  */
 export function shellDocument(plan, csp, options) {
     for (const origin of options.origins) {
-        if (!EXACT_ORIGIN.test(origin)) {
-            throw new TypeError(`shellDocument: ${JSON.stringify(origin)} is not an exact origin`);
+        const problem = hostOriginProblem(origin);
+        if (problem !== null) {
+            throw new TypeError(`shellDocument: ${problem}`);
         }
     }
     const runtime = SHELL_RUNTIME.replace("__PLAN__", () => scriptJson({

package/dist/shell/plan.d.ts

@@ -26,6 +26,8 @@ export interface ShellPlan {
     readonly themeVariables: readonly string[];
     /** The window event fired after a theme change. */
     readonly themeEvent: string;
+    /** Whether a whole document takes the person's scheme: when it declares it, or always. */
+    readonly themeDocuments: "declared" | "always";
     /** `memory`: an opaque origin has no storage, so a map stands in for the frame's life. */
     readonly storage: "memory" | "native";
     readonly maxErrorReports: number;

package/dist/shell/plan.js

@@ -26,6 +26,7 @@ export function shellPlan(config) {
         globals,
         themeVariables: Object.keys(config.theme.variables),
         themeEvent: config.theme.event,
+        themeDocuments: config.theme.documents ?? "declared",
         storage: config.isolation === "opaque" ? "memory" : "native",
         maxErrorReports: config.limits.maxErrorReports,
         maxPromptChars: config.limits.maxPromptChars,

package/dist/shell/runtime.js

@@ -487,6 +487,21 @@ export const SHELL_RUNTIME = String.raw `(() => {
     window.dispatchEvent(new Event("load"));
   };
 
+  // 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;
+  let themed = plan.content !== "document";
+  const schemeFollows = () => {
+    const root = document.documentElement;
+    const theme = lastContext && lastContext.theme;
+    if (themed && (theme === "light" || theme === "dark")) {
+      root.style.colorScheme = theme;
+      root.setAttribute("data-theme", theme);
+    } else {
+      root.style.removeProperty("color-scheme");
+      root.removeAttribute("data-theme");
+    }
+  };
   // A whole document, parsed inert (no scripts run, no declarative shadow roots built), guarded,
   // imported in place of the shell's, then its scripts run in order. The theme on the root stays.
   const renderDocument = async (html) => {
@@ -502,6 +517,9 @@ export const SHELL_RUNTIME = String.raw `(() => {
     document.head.replaceChildren(...Array.from(parsed.head.childNodes, (node) => document.importNode(node, true)));
     document.body.replaceWith(document.importNode(parsed.body, true));
     root = null;
+    const declaredScheme = parsed.querySelector('meta[name="color-scheme" i]');
+    themed = plan.themeDocuments === "always" || (declaredScheme !== null && /\bdark\b/i.test(declaredScheme.getAttribute("content") || ""));
+    schemeFollows();
     await runScripts(scripts);
     announceLoaded();
   };
@@ -554,10 +572,8 @@ export const SHELL_RUNTIME = String.raw `(() => {
         }
       }
     }
-    if (context.theme === "light" || context.theme === "dark") {
-      document.documentElement.style.colorScheme = context.theme;
-      document.documentElement.setAttribute("data-theme", context.theme);
-    }
+    lastContext = context;
+    schemeFollows();
     window.dispatchEvent(new CustomEvent(plan.themeEvent, { detail: { theme: context.theme } }));
   };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botiverse/porthole",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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": [
@@ -46,19 +46,11 @@
     "typescript": "7.0.2"
   },
   "peerDependencies": {
-    "@modelcontextprotocol/ext-apps": ">=2.0.0",
-    "@playwright/test": ">=1.63.0",
     "react": ">=19"
   },
   "peerDependenciesMeta": {
-    "@playwright/test": {
-      "optional": true
-    },
     "react": {
       "optional": true
-    },
-    "@modelcontextprotocol/ext-apps": {
-      "optional": true
     }
   },
   "engines": {

package/src/bridge/bridge.ts

@@ -11,6 +11,7 @@ import type {
   CapabilityHandler,
   CapabilityHandlers,
   Confirm,
+  ConfirmAnswer,
   ConfirmRequest,
   HostFunctionBridge,
   Refusal,
@@ -204,17 +205,28 @@ export function createBridge(options: BridgeOptions): HostFunctionBridge {
           return refuse<Result>(capability, "no-user-activation");
         }
       }
+      // The effect, run once: when the person's "yes" calls `proceed` (inside its own click, so an
+      // effect that needs a gesture gets one), or after `confirm` resolves accepted.
+      let effect: Promise<CallOutcome<Result>> | null = null;
+      const run = (): Promise<CallOutcome<Result>> => (effect ??= perform(capability, args));
       if (confirms) {
         if (options.confirm === undefined) {
           return refuse<Result>(capability, "no-confirm");
         }
-        let accepted = false;
+        let answer: ConfirmAnswer = false;
         try {
-          accepted = await options.confirm({ capability, args, display } as ConfirmRequest);
+          answer = await options.confirm(
+            { capability, args, display } as ConfirmRequest,
+            () => void run(),
+          );
         } catch {
-          accepted = false;
+          answer = effect === null ? false : "accepted";
         }
-        if (!accepted) {
+        if (effect === null && answer !== true && answer !== "accepted") {
+          if (answer === "redirected") {
+            return refuse<Result>(capability, "redirected");
+          }
+          // Declines in a row mute the display; a yes starts the count again.
           declines += 1;
           if (declines >= config.limits.declinesBeforeMute && !muted) {
             muted = true;
@@ -222,8 +234,18 @@ export function createBridge(options: BridgeOptions): HostFunctionBridge {
           }
           return refuse<Result>(capability, "declined");
         }
+        declines = 0;
       }
+      return run();
+    },
+  };
 
+  async function perform<N extends CapabilityName>(
+    capability: N,
+    args: CapabilityArgs[N],
+  ): Promise<CallOutcome<CapabilityResults[N]>> {
+    type Result = CapabilityResults[N];
+    {
       if (capabilitySpec(capability).served === "event") {
         if (capability === "resize") {
           const size = args as CapabilityArgs["resize"];
@@ -251,6 +273,6 @@ export function createBridge(options: BridgeOptions): HostFunctionBridge {
           error instanceof Error ? error.message : String(error),
         );
       }
-    },
-  };
+    }
+  }
 }

package/src/bridge/types.ts

@@ -38,10 +38,26 @@ export type ConfirmRequest = {
 }[CapabilityName];
 
 /**
- * Asks a person. Resolves true only if they accept. The host's UI, or the React binding's default
- * dialog; drawn outside the frame, never inside it.
+ * What the person chose. `true`/`"accepted"`: the call goes. `false`/`"declined"`: it doesn't,
+ * and the decline counts toward muting the display. `"redirected"`: it doesn't go, but the person
+ * took it elsewhere (edited the prompt first, say), so it neither counts as a decline nor resets
+ * the count. The host decides which its UI's choices are.
  */
-export type Confirm = (request: ConfirmRequest) => Promise<boolean>;
+export type ConfirmAnswer = boolean | "accepted" | "declined" | "redirected";
+
+/**
+ * Runs the call's effect now, inside the caller's own gesture, and counts as accepted. A host
+ * whose effect needs the person's gesture (opening a window) calls it from the click handler of
+ * its own "yes" button, rather than resolving the promise and letting the effect run after.
+ */
+export type Proceed = () => void;
+
+/**
+ * Asks a person. Resolves with their answer. The host's UI, or the React binding's default
+ * dialog; drawn outside the frame, never inside it. `proceed` (optional to use) runs the effect
+ * within the "yes" click itself.
+ */
+export type Confirm = (request: ConfirmRequest, proceed: Proceed) => Promise<ConfirmAnswer>;
 
 /** Why a call didn't run. */
 export type Refusal =
@@ -55,6 +71,8 @@ export type Refusal =
   | "no-confirm"
   /** The person declined. */
   | "declined"
+  /** The person took it elsewhere (edited it first): not sent, not counted as a decline. */
+  | "redirected"
   /** The display was muted after too many declines (until it runs again). */
   | "muted"
   | "rate-limited"

package/src/compile/policy.ts

@@ -93,7 +93,8 @@ export function sandboxTokens(config: PortholeConfig): string[] {
     case "domain":
       return ["allow-scripts", "allow-same-origin"];
     case "external":
-      return ["allow-scripts", "allow-same-origin", "allow-forms"];
+      // The host may add a documented few (popups, modals, downloads), never top navigation.
+      return ["allow-scripts", "allow-same-origin", "allow-forms", ...(config.sandbox ?? [])];
   }
 }
 
@@ -119,15 +120,11 @@ export function embedderFrameSources(config: PortholeConfig): string[] {
 
 /**
  * The CSP the embedding page sends (a header, or the host's own document's policy), for every kind
- * of display it shows. It sets no `default-src`: it restricts frames only, leaving the host's own
- * scripts, styles and fetches to the host's policy. `child-src` repeats `frame-src` for engines
- * that read frames from it.
+ * of display it shows. Frames only: no `default-src`, so the host's own scripts, styles and
+ * fetches stay its policy's; and no `child-src`, which the host's workers would fall back to (every
+ * engine Porthole supports reads frames from `frame-src`, P038).
  */
 export function embedderCsp(configs: readonly PortholeConfig[]): string {
   const sources = unique(configs.flatMap(embedderFrameSources));
-  const all = sources.length === 0 ? ["'none'"] : sources;
-  return serializeCsp([
-    ["frame-src", ...all],
-    ["child-src", ...all],
-  ]);
+  return serializeCsp([["frame-src", ...(sources.length === 0 ? ["'none'"] : sources)]]);
 }