@botiverse/porthole 0.1.1 → 0.1.3

package/dist/index.d.ts

@@ -2,11 +2,12 @@
  * `@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_SANDBOX_EXTRAS, type UrlSandboxExtra } from "./config/schema.ts";
+export { URL_PERMISSIONS, URL_SANDBOX_EXTRAS, type UrlPermission, type UrlSandboxExtra, } from "./config/schema.ts";
 export { hostOriginProblem, isHostOrigin } from "./isolation/served.ts";
+export { FRAME_STATUS_METHOD } from "./isolation/types.ts";
 export { LIBRARY_CDNS, presets, type PresetName, type PresetOptions, type UrlPresetOptions, } from "./presets/presets.ts";
 export { compile, type CompiledConfig } from "./compile/compile.ts";
 export { allEgressOrigins, declaredCapabilities, effectiveGates, egressOrigins, embedderCsp, type CspDirective, type EgressKind, } from "./compile/policy.ts";
@@ -19,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, 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,10 +3,11 @@
  * 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_SANDBOX_EXTRAS } from "./config/schema.js";
+export { URL_PERMISSIONS, URL_SANDBOX_EXTRAS, } from "./config/schema.js";
 export { hostOriginProblem, isHostOrigin } from "./isolation/served.js";
+export { FRAME_STATUS_METHOD } from "./isolation/types.js";
 // Presets.
 export { LIBRARY_CDNS, presets, } from "./presets/presets.js";
 // The compiler.
@@ -17,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/presets/presets.d.ts

@@ -1,5 +1,5 @@
 import type { CapabilityName } from "../config/capabilities.ts";
-import type { CapabilityConfig, EgressConfig, EmbedderConfig, GuideConfig, IsolationKind, LayoutConfig, Limits, PortholeConfig, ThemeValue, UrlSandboxExtra } from "../config/schema.ts";
+import type { CapabilityConfig, EgressConfig, EmbedderConfig, GuideConfig, IsolationKind, LayoutConfig, Limits, PortholeConfig, ThemeValue, UrlPermission, UrlSandboxExtra } from "../config/schema.ts";
 /**
  * The preset policy layer (P001): named configs with safe defaults. Every preset starts with
  * egress closed and only the capabilities that carry nothing out of the frame (its size, its
@@ -36,6 +36,8 @@ export interface UrlPresetOptions {
     readonly contentOrigins: readonly string[];
     /** Sandbox tokens to add for the app (popups for an OAuth flow, modals, downloads; P037). */
     readonly sandbox?: readonly UrlSandboxExtra[];
+    /** Features to delegate to the app (clipboard writes, full screen; P049). */
+    readonly permissions?: readonly UrlPermission[];
     readonly limits?: Partial<Limits>;
     readonly layout?: Partial<LayoutConfig>;
     readonly embedder?: EmbedderConfig;

package/dist/presets/presets.js

@@ -136,5 +136,6 @@ export const presets = {
         contentOrigins: options.contentOrigins,
         embedder: options.embedder ?? {},
         ...(options.sandbox === undefined ? {} : { sandbox: options.sandbox }),
+        ...(options.permissions === undefined ? {} : { permissions: options.permissions }),
     }),
 };

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";

package/dist/protocol/shell-adapter.js

@@ -1,5 +1,5 @@
 import { JSON_RPC_ERRORS, parseJsonRpc, } from "./jsonrpc.js";
-import { MCP_APPS_METHODS as M, MCP_APPS_PROTOCOL_VERSION } from "./mcp-apps.js";
+import { COPY_TEXT_METHOD, 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
@@ -28,6 +28,7 @@ const REQUESTS = {
         }),
     },
     [M.openLink]: { capability: "openLink", args: (params) => ({ url: params.url }) },
+    [COPY_TEXT_METHOD]: { capability: "copyText", args: (params) => ({ text: params.text }) },
     [M.downloadFile]: {
         capability: "downloadFile",
         args: (params) => ({ contents: params.contents }),
@@ -44,7 +45,10 @@ const REQUESTS = {
 };
 /** What a capability's outcome looks like to the view. */
 function answer(capability, outcome) {
-    const flagged = capability === "sendPrompt" || capability === "openLink" || capability === "downloadFile";
+    const flagged = capability === "sendPrompt" ||
+        capability === "openLink" ||
+        capability === "downloadFile" ||
+        capability === "copyText";
     if (!outcome.ok) {
         return flagged
             ? { result: { isError: true } }

package/dist/react/dialog.js

@@ -47,6 +47,8 @@ function words(request) {
             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 };
+        case "copyText":
+            return { heading: "Copy this text?", accept: "Copy", detail: request.args.text };
         default:
             return { heading: "Allow this?", accept: "Allow", detail: json(request.args) };
     }

package/dist/react/frame.d.ts

@@ -1,4 +1,5 @@
 import { type CSSProperties, type ReactElement, type ReactNode } from "react";
+import type { AnnotateMode, AnnotationMark, AnnotationReport } from "../annotate/types.ts";
 import type { CapabilityHandlers, Confirm, Refusal } from "../bridge/types.ts";
 import type { CapabilityName } from "../config/capabilities.ts";
 import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
@@ -21,6 +22,8 @@ export interface PortholeProviderProps {
     readonly locator?: InstanceLocator;
     /** A class for the default dialog, to restyle it. */
     readonly dialogClassName?: string;
+    /** A class for the default copy toast, to restyle it. */
+    readonly toastClassName?: string;
     readonly children?: ReactNode;
 }
 export declare function PortholeProvider(props: PortholeProviderProps): ReactElement;
@@ -83,6 +86,21 @@ export interface PortholeFrameProps {
      * restyle): the running frame reads them again.
      */
     readonly themeKey?: string | number;
+    /**
+     * Annotations, where the config declares `annotate` (P053): what the person may point at now
+     * (elements, text, or both), or null to stop. A picked element ends element picking: set it
+     * again to pick again.
+     */
+    readonly annotating?: AnnotateMode | null;
+    /** The anchors to mark in the frame (the host's comments). Keep it stable (memoized). */
+    readonly annotations?: readonly AnnotationMark[];
+    /** The mark to bring into view and make the active one; each new id focuses it. */
+    readonly focusedAnnotation?: string | null;
+    /**
+     * What the frame reported: a selection (an anchor and where it is), its clearing, a cancelled
+     * pick, where marks are. The content's word: UI hints, never permissions.
+     */
+    readonly onAnnotation?: (report: AnnotationReport) => void;
     /** Draws the placeholder instead of the default one. */
     readonly renderPlaceholder?: (props: PlaceholderProps) => ReactNode;
     readonly className?: string;

package/dist/react/frame.js

@@ -1,8 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { createContext, useCallback, useContext, useEffect, useEffectEvent, useId, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
+import { writeClipboard } from "../host/clipboard.js";
 import { createHost } from "../host/create-host.js";
 import { ConfirmDialog } from "./dialog.js";
 import { createLiveFrames } from "./live.js";
+import { CopyToast } from "./toast.js";
 /**
  * The React binding: a `<PortholeProvider>` near the root owns what is per page (which frames
  * run, the heights displays reported, and the default confirmation dialog); a `<PortholeFrame>` per
@@ -28,14 +30,24 @@ export function PortholeProvider(props) {
     const confirm = useCallback((request, proceed) => own.current !== undefined
         ? own.current(request, proceed)
         : new Promise((resolve) => setQueue((waiting) => [...waiting, { request, resolve, proceed }])), []);
+    // The default copyText: the host's page writes the clipboard (in the frame's click, which
+    // activated this page too) and shows the person what went on it, or offers to copy it.
+    const [notice, setNotice] = useState(null);
+    const copyText = useCallback(async ({ text }, context) => {
+        const copied = await writeClipboard(text, globalThis.document);
+        setNotice({ text, copied, title: context.title });
+        return copied;
+    }, []);
+    const closeNotice = useCallback(() => setNotice(null), []);
     const { hostInfo, locator } = props;
     const value = useMemo(() => ({
         live,
         heights,
         confirm,
+        copyText,
         ...(hostInfo === undefined ? {} : { hostInfo }),
         ...(locator === undefined ? {} : { locator }),
-    }), [live, heights, confirm, hostInfo, locator]);
+    }), [live, heights, confirm, copyText, 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) => {
                     // A yes runs the effect inside this very click (a window it opens is the person's).
@@ -44,7 +56,10 @@ export function PortholeProvider(props) {
                     }
                     current?.resolve(accepted ? "accepted" : "declined");
                     setQueue((waiting) => waiting.slice(1));
-                } })) : null] }));
+                } })) : null, _jsx(CopyToast, { notice: notice, ...(props.toastClassName === undefined ? {} : { className: props.toastClassName }), onClose: closeNotice, onCopy: (failed) => {
+                    // A click on the host's own page: the write has the gesture it needs now.
+                    void writeClipboard(failed.text, globalThis.document).then((copied) => setNotice({ ...failed, copied }));
+                } })] }));
 }
 const PLACEHOLDER_STYLE = {
     position: "absolute",
@@ -163,6 +178,9 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
             case "outcome":
                 frame.onOutcome?.(detail);
                 return;
+            case "annotation":
+                frame.onAnnotation?.(detail);
+                return;
         }
     });
     useEffect(() => {
@@ -183,6 +201,13 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
         for (const name of Object.keys(first.handlers ?? {})) {
             handlers[name] = (args, context) => latest().handlers?.[name]?.(args, named(context));
         }
+        // Copy buttons without a handler of the host's: the provider's, which shows a toast.
+        if (config.capabilities.copyText !== undefined && handlers.copyText === undefined) {
+            const fallback = page.copyText;
+            if (fallback !== undefined) {
+                handlers.copyText = (args, context) => fallback(args, named(context));
+            }
+        }
         const asks = first.confirm !== undefined || page.confirm !== undefined;
         let display;
         try {
@@ -218,10 +243,14 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
             "refused",
             "muted",
             "outcome",
+            "annotation",
         ];
         for (const event of events) {
             display.on(event, (detail) => notify(event, detail));
         }
+        if (config.capabilities.annotate !== undefined) {
+            applyAnnotations(display, first);
+        }
         if (first.content !== undefined) {
             display.setContent(first.content, { partial: first.partial === true });
         }
@@ -237,6 +266,34 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
             handle.current?.setContent(content, { partial: partial === true });
         }
     }, [content, partial]);
+    // Annotations follow their props (a new display gets them all when it is made, above).
+    const annotates = config.capabilities.annotate !== undefined;
+    const { annotating, annotations, focusedAnnotation } = frame;
+    const mode = annotating === undefined || annotating === null
+        ? ""
+        : JSON.stringify([annotating.elements ?? true, annotating.text ?? true]);
+    useEffect(() => {
+        const display = handle.current;
+        if (!annotates || display === null) {
+            return;
+        }
+        const wanted = mode === "" ? null : JSON.parse(mode);
+        attempt(() => wanted === null
+            ? display.annotations.stop()
+            : display.annotations.start({ elements: wanted[0], text: wanted[1] }), latest());
+    }, [annotates, mode]);
+    useEffect(() => {
+        const display = handle.current;
+        if (annotates && display !== null) {
+            attempt(() => display.annotations.show(annotations ?? []), latest());
+        }
+    }, [annotates, annotations]);
+    useEffect(() => {
+        const display = handle.current;
+        if (annotates && display !== null && typeof focusedAnnotation === "string") {
+            attempt(() => display.annotations.focus(focusedAnnotation), latest());
+        }
+    }, [annotates, focusedAnnotation]);
     useEffect(() => {
         handle.current?.setTheme(scheme);
     }, [scheme]);
@@ -253,3 +310,26 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
             ...(ready ? {} : { minHeight: Math.max(startHeight, PLACEHOLDER_HEIGHT_PX) }),
         }, 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 })] }));
 }
+/** Runs an annotation call, telling the frame's `onError` what it threw (a bad anchor, say). */
+function attempt(run, frame) {
+    try {
+        run();
+    }
+    catch (error) {
+        frame.onError?.(error instanceof Error ? error.message : String(error));
+    }
+}
+/** A new display's annotations, from the props as they are. */
+function applyAnnotations(display, frame) {
+    attempt(() => {
+        if (frame.annotations !== undefined && frame.annotations.length > 0) {
+            display.annotations.show(frame.annotations);
+        }
+        if (typeof frame.focusedAnnotation === "string") {
+            display.annotations.focus(frame.focusedAnnotation);
+        }
+        if (frame.annotating !== undefined && frame.annotating !== null) {
+            display.annotations.start(frame.annotating);
+        }
+    }, frame);
+}

package/dist/react/index.d.ts

@@ -2,7 +2,7 @@
  * `@botiverse/porthole/react`: the thin React binding (TSX: a host's bundler compiles it, or the
  * package's `dist`). Peer: `react` (19.2+, for `useEffectEvent`).
  *
- *   <PortholeProvider>                         // per page: live-frame cap, heights, the dialog
+ *   <PortholeProvider>                         // per page: live-frame cap, heights, the dialog, the copy toast
  *     <PortholeFrame config={widgetConfig} displayId={id} title={title} scheme={scheme}
  *       content={code} partial={streaming} handlers={{ sendPrompt, openLink }}
  *       theme={tokensFor} onError={report} />
@@ -10,4 +10,5 @@
  */
 export { PLACEHOLDER_HEIGHT_PX, PortholeFrame, PortholeProvider, type PlaceholderProps, type PortholeFrameProps, type PortholeProviderProps, } from "./frame.tsx";
 export { ARM_DELAY_MS, ConfirmDialog, type ConfirmDialogProps } from "./dialog.tsx";
+export { CopyToast, TOAST_CHARS, TOAST_MS, clipped, type CopyNotice, type CopyToastProps, } from "./toast.tsx";
 export { admitFrame, createLiveFrames, type FrameState, type LiveFrames } from "./live.ts";

package/dist/react/index.js

@@ -2,7 +2,7 @@
  * `@botiverse/porthole/react`: the thin React binding (TSX: a host's bundler compiles it, or the
  * package's `dist`). Peer: `react` (19.2+, for `useEffectEvent`).
  *
- *   <PortholeProvider>                         // per page: live-frame cap, heights, the dialog
+ *   <PortholeProvider>                         // per page: live-frame cap, heights, the dialog, the copy toast
  *     <PortholeFrame config={widgetConfig} displayId={id} title={title} scheme={scheme}
  *       content={code} partial={streaming} handlers={{ sendPrompt, openLink }}
  *       theme={tokensFor} onError={report} />
@@ -10,4 +10,5 @@
  */
 export { PLACEHOLDER_HEIGHT_PX, PortholeFrame, PortholeProvider, } from "./frame.js";
 export { ARM_DELAY_MS, ConfirmDialog } from "./dialog.js";
+export { CopyToast, TOAST_CHARS, TOAST_MS, clipped, } from "./toast.js";
 export { admitFrame, createLiveFrames } from "./live.js";

package/dist/react/toast.d.ts

@@ -0,0 +1,33 @@
+import { type ReactElement } from "react";
+/**
+ * The default copy notice (P052): when content's `copyText` copied something, the host's page
+ * shows the person what went on their clipboard, clipped, in a small toast outside every frame.
+ * If the write failed (no recent gesture), it says so and offers a Copy button: a click on the
+ * host's own page, which writes it. A host replaces it by passing its own `copyText` handler; it
+ * styles it through the `porthole-toast` class and data attributes.
+ */
+/** How long a toast for a copy that worked stays. */
+export declare const TOAST_MS = 5000;
+/** The most of the copied text a toast shows. */
+export declare const TOAST_CHARS = 280;
+export interface CopyNotice {
+    /** The whole text copied (or to copy). */
+    readonly text: string;
+    /** Whether it is on the clipboard. */
+    readonly copied: boolean;
+    /** The display's title, as the host named it. */
+    readonly title: string;
+}
+export interface CopyToastProps {
+    readonly notice: CopyNotice | null;
+    /** The person asked to copy it again (it failed), from this click. */
+    readonly onCopy: (notice: CopyNotice) => void;
+    readonly onClose: () => void;
+    readonly className?: string;
+}
+/** The text as the toast shows it: at most a few lines and `TOAST_CHARS` characters. */
+export declare function clipped(text: string): {
+    readonly shown: string;
+    readonly clipped: boolean;
+};
+export declare function CopyToast({ notice, onCopy, onClose, className }: CopyToastProps): ReactElement;

package/dist/react/toast.js

@@ -0,0 +1,42 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect } from "react";
+/**
+ * The default copy notice (P052): when content's `copyText` copied something, the host's page
+ * shows the person what went on their clipboard, clipped, in a small toast outside every frame.
+ * If the write failed (no recent gesture), it says so and offers a Copy button: a click on the
+ * host's own page, which writes it. A host replaces it by passing its own `copyText` handler; it
+ * styles it through the `porthole-toast` class and data attributes.
+ */
+/** How long a toast for a copy that worked stays. */
+export const TOAST_MS = 5_000;
+/** The most of the copied text a toast shows. */
+export const TOAST_CHARS = 280;
+const TOAST_LINES = 4;
+/** The text as the toast shows it: at most a few lines and `TOAST_CHARS` characters. */
+export function clipped(text) {
+    const lines = text.split("\n");
+    let shown = lines.slice(0, TOAST_LINES).join("\n");
+    if (shown.length > TOAST_CHARS) {
+        shown = shown.slice(0, TOAST_CHARS);
+    }
+    return shown.length < text.length
+        ? { shown: `${shown}…`, clipped: true }
+        : { shown, clipped: false };
+}
+const STYLE = `.porthole-toast{position:fixed;left:50%;bottom:24px;transform:translateX(-50%);z-index:2147483647;color-scheme:light dark;color:CanvasText;background:Canvas;border:1px solid color-mix(in srgb,CanvasText 18%,transparent);border-radius:12px;padding:12px 14px;width:min(420px,calc(100vw - 32px));box-shadow:0 8px 28px rgb(0 0 0 / .25);font:inherit;font-size:.9em}
+.porthole-toast p{margin:0 0 6px}
+.porthole-toast [data-porthole-source]{opacity:.72}
+.porthole-toast pre{margin:0;white-space:pre-wrap;overflow-wrap:anywhere;max-height:8em;overflow:hidden;padding:8px 10px;border-radius:8px;background:color-mix(in srgb,CanvasText 7%,transparent);font:12px/1.45 ui-monospace,SFMono-Regular,Menlo,monospace}
+.porthole-toast menu{display:flex;justify-content:flex-end;gap:8px;margin:8px 0 0;padding:0}
+.porthole-toast button{font:inherit;min-height:32px;padding:0 12px;border-radius:8px;border:1px solid color-mix(in srgb,CanvasText 25%,transparent);background:transparent;color:inherit;cursor:pointer}`;
+export function CopyToast({ notice, onCopy, onClose, className }) {
+    useEffect(() => {
+        if (notice === null || !notice.copied) {
+            return;
+        }
+        const timer = setTimeout(onClose, TOAST_MS);
+        return () => clearTimeout(timer);
+    }, [notice, onClose]);
+    const view = notice === null ? null : clipped(notice.text);
+    return (_jsxs("div", { role: "status", "aria-live": "polite", className: className === undefined ? "porthole-toast" : `porthole-toast ${className}`, "data-porthole-toast": "", "data-porthole-copied": notice === null ? "" : String(notice.copied), hidden: notice === null, children: [_jsx("style", { children: STYLE }), notice === null || view === null ? null : (_jsxs(_Fragment, { children: [_jsxs("p", { children: [_jsx("strong", { children: notice.copied ? "Copied" : "Not copied yet" }), " ", _jsx("span", { "data-porthole-source": "", children: `from “${notice.title}”` })] }), _jsx("pre", { "data-porthole-copied-text": "", children: view.shown }), view.clipped ? (_jsx("p", { "data-porthole-length": "", children: `${notice.text.length.toLocaleString("en-US")} characters in all` })) : null, _jsxs("menu", { children: [notice.copied ? null : (_jsx("button", { type: "button", "data-porthole-copy": "", onClick: () => onCopy(notice), children: "Copy" })), _jsx("button", { type: "button", "data-porthole-close": "", onClick: onClose, children: notice.copied ? "OK" : "Close" })] })] }))] }));
+}

package/dist/server/crypto.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The hashing `/server` needs, in plain JavaScript over web-standard types (`Uint8Array`,
+ * `TextEncoder`, `crypto.getRandomValues`), so it runs the same on Node, Cloudflare Workers and
+ * any other runtime (P044). Synchronous on purpose: Web Crypto's HMAC is async, and an origin
+ * (`originFor`) is computed synchronously. SHA-256 per FIPS 180-4, HMAC per RFC 2104; checked
+ * against the standard vectors and `node:crypto` in `test/crypto.test.ts`.
+ */
+export declare function sha256(data: Uint8Array): Uint8Array;
+export declare function hmacSha256(key: Uint8Array, message: Uint8Array): Uint8Array;
+export declare const utf8: (text: string) => Uint8Array;
+export declare const fromUtf8: (bytes: Uint8Array) => string;
+/** Base64url without padding (RFC 4648 §5). */
+export declare function base64url(bytes: Uint8Array): string;
+/** Decodes base64url without padding; null for anything else. */
+export declare function fromBase64url(text: string): Uint8Array | null;
+/** Equal bytes, compared in time that depends only on the length. */
+export declare function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean;
+/** Random bytes from the runtime's CSPRNG (`crypto.getRandomValues`: Node, Workers, browsers). */
+export declare function randomBytes(length: number): Uint8Array;

package/dist/server/crypto.js

@@ -0,0 +1,144 @@
+/**
+ * The hashing `/server` needs, in plain JavaScript over web-standard types (`Uint8Array`,
+ * `TextEncoder`, `crypto.getRandomValues`), so it runs the same on Node, Cloudflare Workers and
+ * any other runtime (P044). Synchronous on purpose: Web Crypto's HMAC is async, and an origin
+ * (`originFor`) is computed synchronously. SHA-256 per FIPS 180-4, HMAC per RFC 2104; checked
+ * against the standard vectors and `node:crypto` in `test/crypto.test.ts`.
+ */
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+const rotr = (x, n) => (x >>> n) | (x << (32 - n));
+export function sha256(data) {
+    const length = data.length;
+    // Padded to a multiple of 64 bytes: a 1 bit, zeros, then the length in bits (64-bit big-endian).
+    const padded = new Uint8Array(Math.ceil((length + 9) / 64) * 64);
+    padded.set(data);
+    padded[length] = 0x80;
+    const view = new DataView(padded.buffer);
+    view.setUint32(padded.length - 8, Math.floor(length / 0x20000000), false);
+    view.setUint32(padded.length - 4, (length * 8) >>> 0, false);
+    const h = new Uint32Array([
+        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+    ]);
+    const w = new Uint32Array(64);
+    for (let offset = 0; offset < padded.length; offset += 64) {
+        for (let i = 0; i < 16; i += 1) {
+            w[i] = view.getUint32(offset + i * 4, false);
+        }
+        for (let i = 16; i < 64; i += 1) {
+            const a = w[i - 15];
+            const b = w[i - 2];
+            const s0 = rotr(a, 7) ^ rotr(a, 18) ^ (a >>> 3);
+            const s1 = rotr(b, 17) ^ rotr(b, 19) ^ (b >>> 10);
+            w[i] = (w[i - 16] + s0 + w[i - 7] + s1) >>> 0;
+        }
+        let [a, b, c, d, e, f, g, hh] = h;
+        for (let i = 0; i < 64; i += 1) {
+            const s1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+            const ch = (e & f) ^ (~e & g);
+            const t1 = (hh + s1 + ch + K[i] + w[i]) >>> 0;
+            const s0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+            const maj = (a & b) ^ (a & c) ^ (b & c);
+            const t2 = (s0 + maj) >>> 0;
+            hh = g;
+            g = f;
+            f = e;
+            e = (d + t1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) >>> 0;
+        }
+        const next = [a, b, c, d, e, f, g, hh];
+        for (let i = 0; i < 8; i += 1) {
+            h[i] = (h[i] + next[i]) >>> 0;
+        }
+    }
+    const out = new Uint8Array(32);
+    const outView = new DataView(out.buffer);
+    for (let i = 0; i < 8; i += 1) {
+        outView.setUint32(i * 4, h[i], false);
+    }
+    return out;
+}
+const BLOCK = 64;
+export function hmacSha256(key, message) {
+    const block = new Uint8Array(BLOCK);
+    block.set(key.length > BLOCK ? sha256(key) : key);
+    const inner = new Uint8Array(BLOCK + message.length);
+    const outer = new Uint8Array(BLOCK + 32);
+    for (let i = 0; i < BLOCK; i += 1) {
+        inner[i] = block[i] ^ 0x36;
+        outer[i] = block[i] ^ 0x5c;
+    }
+    inner.set(message, BLOCK);
+    outer.set(sha256(inner), BLOCK);
+    return sha256(outer);
+}
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+export const utf8 = (text) => encoder.encode(text);
+export const fromUtf8 = (bytes) => decoder.decode(bytes);
+const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+/** Base64url without padding (RFC 4648 §5). */
+export function base64url(bytes) {
+    let out = "";
+    for (let i = 0; i < bytes.length; i += 3) {
+        const n = (bytes[i] << 16) | ((bytes[i + 1] ?? 0) << 8) | (bytes[i + 2] ?? 0);
+        out += B64[(n >>> 18) & 63];
+        out += B64[(n >>> 12) & 63];
+        if (i + 1 < bytes.length) {
+            out += B64[(n >>> 6) & 63];
+        }
+        if (i + 2 < bytes.length) {
+            out += B64[n & 63];
+        }
+    }
+    return out;
+}
+/** Decodes base64url without padding; null for anything else. */
+export function fromBase64url(text) {
+    if (!/^[A-Za-z0-9_-]*$/u.test(text) || text.length % 4 === 1) {
+        return null;
+    }
+    const out = new Uint8Array(Math.floor((text.length * 3) / 4));
+    let bits = 0;
+    let buffer = 0;
+    let index = 0;
+    for (const char of text) {
+        buffer = (buffer << 6) | B64.indexOf(char);
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            out[index] = (buffer >>> bits) & 0xff;
+            index += 1;
+        }
+    }
+    // The leftover bits of a canonical encoding are zero.
+    return (buffer & ((1 << bits) - 1)) === 0 ? out : null;
+}
+/** Equal bytes, compared in time that depends only on the length. */
+export function timingSafeEqual(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    let difference = 0;
+    for (let i = 0; i < a.length; i += 1) {
+        difference |= a[i] ^ b[i];
+    }
+    return difference === 0;
+}
+/** Random bytes from the runtime's CSPRNG (`crypto.getRandomValues`: Node, Workers, browsers). */
+export function randomBytes(length) {
+    const bytes = new Uint8Array(length);
+    globalThis.crypto.getRandomValues(bytes);
+    return bytes;
+}