@botiverse/porthole 0.0.1 → 0.1.1

package/dist/protocol/shell-adapter.js

@@ -0,0 +1,228 @@
+import { JSON_RPC_ERRORS, parseJsonRpc, } from "./jsonrpc.js";
+import { MCP_APPS_METHODS as M, MCP_APPS_PROTOCOL_VERSION } from "./mcp-apps.js";
+/**
+ * The core's adapter: the host side of the MCP Apps subset the shell speaks, which content using
+ * the official App SDK speaks too. Every message is checked before use; every power goes through
+ * the bridge. Content goes as `tool-input-partial` while it is written and `tool-input` once,
+ * after the view has initialized.
+ */
+const LOG_ERRORS = new Set(["error", "critical", "alert", "emergency"]);
+/** Requests that are capability calls, and how their params become the capability's args. */
+const REQUESTS = {
+    [M.message]: {
+        capability: "sendPrompt",
+        args: (params) => ({
+            text: Array.isArray(params.content)
+                ? params.content
+                    .map((part) => {
+                    const block = part;
+                    return block !== null &&
+                        typeof block === "object" &&
+                        block.type === "text" &&
+                        typeof block.text === "string"
+                        ? block.text
+                        : "";
+                })
+                    .join("")
+                : undefined,
+        }),
+    },
+    [M.openLink]: { capability: "openLink", args: (params) => ({ url: params.url }) },
+    [M.downloadFile]: {
+        capability: "downloadFile",
+        args: (params) => ({ contents: params.contents }),
+    },
+    [M.callTool]: {
+        capability: "callTool",
+        args: (params) => ({ name: params.name, arguments: params.arguments }),
+    },
+    [M.readResource]: { capability: "readData", args: (params) => ({ uri: params.uri }) },
+    [M.updateModelContext]: {
+        capability: "setModelContext",
+        args: (params) => ({ content: params.content, structuredContent: params.structuredContent }),
+    },
+};
+/** What a capability's outcome looks like to the view. */
+function answer(capability, outcome) {
+    const flagged = capability === "sendPrompt" || capability === "openLink" || capability === "downloadFile";
+    if (!outcome.ok) {
+        return flagged
+            ? { result: { isError: true } }
+            : { error: { code: -32000, message: `Refused (${outcome.refusal})` } };
+    }
+    if (flagged) {
+        return { result: outcome.value === true ? {} : { isError: true } };
+    }
+    return { result: outcome.value ?? {} };
+}
+/** What the host offers, from the declared capabilities (MCP Apps `hostCapabilities`). */
+export function hostCapabilities(declared) {
+    const offered = {};
+    if (declared("openLink")) {
+        offered.openLinks = {};
+    }
+    if (declared("sendPrompt")) {
+        offered.message = { text: {} };
+    }
+    if (declared("downloadFile")) {
+        offered.downloadFile = {};
+    }
+    if (declared("callTool")) {
+        offered.serverTools = {};
+    }
+    if (declared("readData")) {
+        offered.serverResources = {};
+    }
+    if (declared("setModelContext")) {
+        offered.updateModelContext = { text: {} };
+    }
+    if (declared("reportError")) {
+        offered.logging = {};
+    }
+    return offered;
+}
+export const shellAdapter = {
+    name: "porthole-shell",
+    connect(session) {
+        const { transport, bridge } = session;
+        let initialized = false;
+        let closed = false;
+        let drafted = null;
+        let content = null;
+        let sentWhole = false;
+        let nextId = 1;
+        const pending = new Map();
+        const respond = (id, body) => transport.send({ jsonrpc: "2.0", id, ...body });
+        const notify = (method, params) => transport.send({ jsonrpc: "2.0", method, params });
+        const flush = () => {
+            if (!initialized || closed || content === null || sentWhole) {
+                return;
+            }
+            if (content.partial) {
+                if (drafted !== content.html) {
+                    drafted = content.html;
+                    notify(M.toolInputPartial, { arguments: { html: content.html } });
+                }
+                return;
+            }
+            sentWhole = true;
+            notify(M.toolInput, { arguments: { html: content.html } });
+        };
+        const onRequest = async (request) => {
+            const params = request.params ?? {};
+            if (request.method === M.initialize) {
+                respond(request.id, {
+                    result: {
+                        protocolVersion: MCP_APPS_PROTOCOL_VERSION,
+                        hostInfo: session.hostInfo,
+                        hostCapabilities: hostCapabilities((name) => bridge.declared(name)),
+                        hostContext: session.hostContext(),
+                    },
+                });
+                return;
+            }
+            if (request.method === "ping") {
+                respond(request.id, { result: {} });
+                return;
+            }
+            if (request.method === M.requestDisplayMode) {
+                respond(request.id, { result: { mode: "inline" } });
+                return;
+            }
+            const mapped = REQUESTS[request.method];
+            if (mapped === undefined) {
+                respond(request.id, {
+                    error: {
+                        code: JSON_RPC_ERRORS.methodNotFound,
+                        message: `${request.method} isn't offered here`,
+                    },
+                });
+                return;
+            }
+            const outcome = await bridge.call(mapped.capability, mapped.args(params));
+            if (!closed) {
+                respond(request.id, answer(mapped.capability, outcome));
+            }
+        };
+        const onNotification = (method, params) => {
+            switch (method) {
+                case M.initialized:
+                    if (!initialized) {
+                        initialized = true;
+                        session.emit({ type: "initialized" });
+                        flush();
+                    }
+                    return;
+                case M.sizeChanged:
+                    void bridge.call("resize", { height: params.height, width: params.width });
+                    return;
+                case M.log:
+                    if (LOG_ERRORS.has(String(params.level))) {
+                        const data = params.data;
+                        void bridge.call("reportError", {
+                            message: typeof data === "string" ? data : JSON.stringify(data ?? null).slice(0, 2_000),
+                        });
+                    }
+                    return;
+                case M.requestTeardown:
+                    session.emit({ type: "teardown-requested" });
+                    return;
+                default:
+                    return;
+            }
+        };
+        const stop = transport.listen((raw) => {
+            const message = parseJsonRpc(raw);
+            if (message === null || closed) {
+                return;
+            }
+            if ("method" in message) {
+                if ("id" in message) {
+                    void onRequest(message);
+                }
+                else {
+                    onNotification(message.method, message.params ?? {});
+                }
+                return;
+            }
+            pending.get(message.id)?.(message);
+            pending.delete(message.id);
+        });
+        return {
+            setContent(html, options) {
+                if (sentWhole) {
+                    return;
+                }
+                content = { html, partial: options?.partial === true };
+                flush();
+            },
+            hostContextChanged(context) {
+                if (initialized && !closed) {
+                    notify(M.hostContextChanged, { ...context });
+                }
+            },
+            teardown() {
+                if (!initialized || closed) {
+                    return Promise.resolve();
+                }
+                const id = `teardown-${nextId++}`;
+                return new Promise((resolve) => {
+                    const timer = setTimeout(() => {
+                        pending.delete(id);
+                        resolve();
+                    }, 500);
+                    pending.set(id, () => {
+                        clearTimeout(timer);
+                        resolve();
+                    });
+                    transport.send({ jsonrpc: "2.0", id, method: M.resourceTeardown, params: {} });
+                });
+            },
+            close() {
+                closed = true;
+                stop();
+                pending.clear();
+            },
+        };
+    },
+};

package/dist/react/dialog.d.ts

@@ -0,0 +1,20 @@
+import { type ReactElement } from "react";
+import type { ConfirmRequest } from "../bridge/types.ts";
+/**
+ * The default confirmation dialog (P019): drawn by the host's page, outside every frame, as a
+ * modal (the top layer covers the frames, so content can't draw over it or click it). It shows
+ * the call's whole effect (the prompt's full text, the link's full URL), the display's title as
+ * the host named it, Cancel focused, and ignores presses on its accept button for a moment after
+ * it opens (a click meant for the content mustn't land on it). Escape cancels. A host replaces it
+ * by passing its own `confirm`; it styles it through the `porthole-confirm` class and data
+ * attributes.
+ */
+/** How long the accept button ignores presses after the dialog opens. */
+export declare const ARM_DELAY_MS = 500;
+export interface ConfirmDialogProps {
+    /** The call to confirm, or null when nothing is asked. */
+    readonly request: ConfirmRequest | null;
+    readonly onAnswer: (accepted: boolean) => void;
+    readonly className?: string;
+}
+export declare function ConfirmDialog({ request, onAnswer, className }: ConfirmDialogProps): ReactElement;

package/dist/react/dialog.js

@@ -0,0 +1,98 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useRef, useState } from "react";
+/**
+ * The default confirmation dialog (P019): drawn by the host's page, outside every frame, as a
+ * modal (the top layer covers the frames, so content can't draw over it or click it). It shows
+ * the call's whole effect (the prompt's full text, the link's full URL), the display's title as
+ * the host named it, Cancel focused, and ignores presses on its accept button for a moment after
+ * it opens (a click meant for the content mustn't land on it). Escape cancels. A host replaces it
+ * by passing its own `confirm`; it styles it through the `porthole-confirm` class and data
+ * attributes.
+ */
+/** How long the accept button ignores presses after the dialog opens. */
+export const ARM_DELAY_MS = 500;
+const json = (value) => JSON.stringify(value, null, 2) ?? "";
+function words(request) {
+    switch (request.capability) {
+        case "sendPrompt":
+            return { heading: "Send this message?", accept: "Send", detail: request.args.text };
+        case "openLink": {
+            let host = "";
+            try {
+                host = new URL(request.args.url).host;
+            }
+            catch {
+                host = "";
+            }
+            return {
+                heading: "Open this link?",
+                accept: "Open link",
+                detail: request.args.url,
+                ...(host === "" ? {} : { note: `It opens ${host}.` }),
+            };
+        }
+        case "downloadFile":
+            return {
+                heading: "Download this file?",
+                accept: "Download",
+                detail: json(request.args.contents),
+            };
+        case "callTool":
+            return {
+                heading: "Run this tool?",
+                accept: "Run",
+                detail: `${request.args.name}\n${json(request.args.arguments)}`,
+            };
+        case "setModelContext":
+            return { heading: "Share this with the agent?", accept: "Share", detail: json(request.args) };
+        case "readData":
+            return { heading: "Let it read this?", accept: "Allow", detail: request.args.uri };
+        default:
+            return { heading: "Allow this?", accept: "Allow", detail: json(request.args) };
+    }
+}
+const STYLE = `.porthole-confirm{color-scheme:light dark;color:CanvasText;background:Canvas;border:1px solid color-mix(in srgb,CanvasText 18%,transparent);border-radius:12px;padding:20px;width:min(440px,calc(100vw - 32px));font:inherit;box-shadow:0 12px 40px rgb(0 0 0 / .28)}
+.porthole-confirm::backdrop{background:rgb(0 0 0 / .4)}
+.porthole-confirm h2{font-size:1.05em;margin:0 0 4px}
+.porthole-confirm [data-porthole-source],.porthole-confirm [data-porthole-note]{opacity:.72;font-size:.9em;margin:0 0 12px}
+.porthole-confirm [data-porthole-detail]{white-space:pre-wrap;overflow-wrap:anywhere;max-height:40vh;overflow:auto;padding:10px 12px;border-radius:8px;background:color-mix(in srgb,CanvasText 7%,transparent);margin:0 0 12px;font:inherit}
+.porthole-confirm menu{display:flex;justify-content:flex-end;gap:8px;margin:16px 0 0;padding:0}
+.porthole-confirm button{font:inherit;min-height:36px;padding:0 14px;border-radius:8px;border:1px solid color-mix(in srgb,CanvasText 25%,transparent);background:transparent;color:inherit;cursor:pointer}
+.porthole-confirm button[data-porthole-accept]{background:Highlight;background:AccentColor;color:HighlightText;color:AccentColorText;border-color:transparent}`;
+export function ConfirmDialog({ request, onAnswer, className }) {
+    const dialog = useRef(null);
+    const cancel = useRef(null);
+    // The request the accept button is armed for: a new one starts unarmed.
+    const [armedFor, setArmedFor] = useState(null);
+    const armed = request !== null && armedFor === request;
+    const heading = useId();
+    useEffect(() => {
+        const element = dialog.current;
+        if (element === null) {
+            return;
+        }
+        if (request === null) {
+            if (element.open) {
+                element.close();
+            }
+            return;
+        }
+        if (!element.open) {
+            element.showModal();
+        }
+        cancel.current?.focus();
+        const timer = setTimeout(() => setArmedFor(request), ARM_DELAY_MS);
+        return () => clearTimeout(timer);
+    }, [request]);
+    const said = request === null ? null : words(request);
+    return (_jsxs("dialog", { ref: dialog, className: className === undefined ? "porthole-confirm" : `porthole-confirm ${className}`, "aria-labelledby": heading, "data-porthole-confirm": request?.capability ?? "", onCancel: (event) => {
+            event.preventDefault();
+            if (request !== null) {
+                onAnswer(false);
+            }
+        }, children: [_jsx("style", { children: STYLE }), said === null || request === null ? null : (_jsxs(_Fragment, { children: [_jsx("h2", { id: heading, children: said.heading }), _jsx("p", { "data-porthole-source": "", children: `From “${request.display.title}”` }), _jsx("div", { "data-porthole-detail": "", children: said.detail }), said.note === undefined ? null : _jsx("p", { "data-porthole-note": "", children: said.note }), _jsxs("menu", { children: [_jsx("button", { type: "button", ref: cancel, autoFocus: true, "data-porthole-cancel": "", onClick: () => onAnswer(false), children: "Cancel" }), _jsx("button", { type: "button", "data-porthole-accept": "", "data-armed": String(armed), onClick: () => {
+                                    if (armed) {
+                                        onAnswer(true);
+                                    }
+                                }, children: said.accept })] })] }))] }));
+}

package/dist/react/frame.d.ts

@@ -0,0 +1,91 @@
+import { type CSSProperties, type ReactElement, type ReactNode } from "react";
+import type { CapabilityHandlers, Confirm, Refusal } from "../bridge/types.ts";
+import type { CapabilityName } from "../config/capabilities.ts";
+import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
+import type { FrameOutcome } from "../host/types.ts";
+import type { InstanceLocator, InstanceRef } from "../isolation/types.ts";
+/** The height a display holds before it has reported its own. */
+export declare const PLACEHOLDER_HEIGHT_PX = 96;
+export interface PortholeProviderProps {
+    /**
+     * Who confirms gated calls for every frame below. Omitted: the default dialog (`ConfirmDialog`).
+     * Pass your own function to replace it.
+     */
+    readonly confirm?: Confirm;
+    /** How the host names itself in the handshake. */
+    readonly hostInfo?: {
+        readonly name: string;
+        readonly version: string;
+    };
+    /** Where domain and external frames load from (see `InstanceLocator`). */
+    readonly locator?: InstanceLocator;
+    /** A class for the default dialog, to restyle it. */
+    readonly dialogClassName?: string;
+    readonly children?: ReactNode;
+}
+export declare function PortholeProvider(props: PortholeProviderProps): ReactElement;
+/** What a placeholder shows: a display not yet running, loading, or stopped for others. */
+export interface PlaceholderProps {
+    readonly state: "waiting" | "loading" | "stopped";
+    readonly title: string;
+    /** Runs the display again (a stopped one), stopping another if the page is at its most. */
+    readonly run: () => void;
+}
+export interface PortholeFrameProps {
+    /** A preset's config. Keep it stable (module scope or memoized): a new one remounts the frame. */
+    readonly config: PortholeConfig;
+    /** The host's id for this display: what its height is remembered by, and calls name. */
+    readonly displayId: string;
+    /** The frame's accessible name, and the title its confirmations show (the host's words). */
+    readonly title: string;
+    /** The content so far (inline and artifact modes). */
+    readonly content?: string;
+    /** The content is still being written: drawn inert as it grows, run once when whole. */
+    readonly partial?: boolean;
+    /** A whole document to start with (an MCP Apps view). */
+    readonly document?: string;
+    /** Domain and external isolation: the instance to show. */
+    readonly instance?: InstanceRef;
+    readonly scheme: ColorScheme;
+    /** The host's live values for the config's theme variables (from its design tokens). */
+    readonly theme?: (scheme: ColorScheme) => Readonly<Record<string, string | null | undefined>>;
+    /** Handlers for the declared capabilities (the latest ones are called). */
+    readonly handlers?: CapabilityHandlers;
+    /** Who confirms this frame's gated calls, over the provider's. */
+    readonly confirm?: Confirm;
+    /** Bump to run the content again from the start. */
+    readonly generation?: number;
+    /** Run at once, without waiting to near the screen (it still counts toward the page's most). */
+    readonly eager?: boolean;
+    readonly onInitialized?: () => void;
+    readonly onResize?: (size: {
+        readonly height: number;
+        readonly width?: number;
+    }) => void;
+    readonly onError?: (message: string) => void;
+    /** The content navigated its frame away; it was started again (or stopped, after a few). */
+    readonly onNavigated?: () => void;
+    readonly onRefused?: (capability: CapabilityName, refusal: Refusal) => void;
+    /** Too many declines: the display stops asking until it runs again. */
+    readonly onMuted?: () => void;
+    /**
+     * How the frame's first document went: loaded, blocked (and why), or a timeout. A host shows its
+     * own fallback (a url-mode app "Open in a new tab") on anything but loaded.
+     */
+    readonly onOutcome?: (outcome: FrameOutcome) => void;
+    /**
+     * Other ids this display had (the call's id, before the display's own settled): its remembered
+     * height is found under them, for a frame that mounts again under its new id.
+     */
+    readonly aliases?: readonly string[];
+    /**
+     * Change it when the host's theme values change without a scheme flip (or after an async
+     * restyle): the running frame reads them again.
+     */
+    readonly themeKey?: string | number;
+    /** Draws the placeholder instead of the default one. */
+    readonly renderPlaceholder?: (props: PlaceholderProps) => ReactNode;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+}
+export declare function PortholeFrame(props: PortholeFrameProps): ReactElement;