@botiverse/porthole 0.1.2 → 0.1.4

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,36 @@ 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 }])), []);
-    const { hostInfo, locator } = props;
+    // 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), []);
+    // Compared by value, and read when used: an inline hostInfo or locator doesn't start every
+    // frame again on each render.
+    const hostInfo = useByValue(props.hostInfo);
+    const ownLocator = useRef(props.locator);
+    useLayoutEffect(() => {
+        ownLocator.current = props.locator;
+    });
+    const locate = useCallback((instance, signal) => ownLocator.current === undefined
+        ? Promise.reject(new Error("No locator (PortholeProvider.locator)"))
+        : ownLocator.current.locate(instance, signal), []);
+    const locates = props.locator !== undefined;
+    const { nonce } = props;
     const value = useMemo(() => ({
         live,
         heights,
         confirm,
+        copyText,
         ...(hostInfo === undefined ? {} : { hostInfo }),
-        ...(locator === undefined ? {} : { locator }),
-    }), [live, heights, confirm, hostInfo, locator]);
+        ...(locates ? { locate } : {}),
+        ...(nonce === undefined ? {} : { nonce }),
+    }), [live, heights, confirm, copyText, hostInfo, locates, locate, nonce]);
     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 +68,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",
@@ -119,6 +146,8 @@ export function PortholeFrame(props) {
     return (_jsx("div", { ref: box, className: props.className, "data-porthole-display": props.displayId, "data-porthole-state": state, style: {
             position: "relative",
             width: "100%",
+            // A display that fills takes its parent's height (the host sizes the parent, or this box).
+            ...(props.fill === true || props.config.mode === "url" ? { height: "100%" } : {}),
             ...(state === "running" ? {} : { minHeight: Math.max(height, PLACEHOLDER_HEIGHT_PX) }),
             ...props.style,
         }, children: state === "running" ? (_jsx(Mount, { frame: props, page: page, initialHeightPx: height, placeholder: placeholder, run: run }, String(props.generation ?? 0))) : (placeholder({ state, title: props.title, run })) }));
@@ -130,8 +159,11 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
     const [ready, setReady] = useState(false);
     // 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";
+    const { document: view, content, partial, scheme } = frame;
+    // By value: a config or instance made inline (each render) is the same display.
+    const config = useByValue(frame.config);
+    const instance = useByValue(frame.instance);
+    const fills = config.mode === "url" || frame.fill === true;
     // The latest props, read when the display calls back (never during render).
     const latest = useEffectEvent(() => frame);
     const notify = useEffectEvent((event, detail) => {
@@ -146,9 +178,17 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
                 frame.onResize?.(size);
                 return;
             }
-            case "error":
-                frame.onError?.(detail.message);
+            case "contentError":
+                frame.onContentError?.(detail.message);
+                return;
+            case "hostError":
+                frame.onHostError?.(detail);
+                return;
+            case "error": {
+                const { message, source } = detail;
+                frame.onError?.(message, source);
                 return;
+            }
             case "navigated":
                 frame.onNavigated?.();
                 return;
@@ -163,6 +203,9 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
             case "outcome":
                 frame.onOutcome?.(detail);
                 return;
+            case "annotation":
+                frame.onAnnotation?.(detail);
+                return;
         }
     });
     useEffect(() => {
@@ -183,6 +226,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 {
@@ -195,7 +245,8 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
                     : {}),
                 theme: (each) => latest().theme?.(each) ?? {},
                 ...(page.hostInfo === undefined ? {} : { hostInfo: page.hostInfo }),
-                ...(page.locator === undefined ? {} : { locator: page.locator }),
+                ...(page.locate === undefined ? {} : { locator: { locate: page.locate } }),
+                ...(page.nonce === undefined ? {} : { nonce: page.nonce }),
             }).mount(container, {
                 displayId: first.displayId,
                 title: first.title,
@@ -203,10 +254,11 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
                 initialHeightPx: startHeight,
                 ...(view === undefined ? {} : { document: view }),
                 ...(instance === undefined ? {} : { instance }),
+                ...(fills ? { fill: true } : {}),
             });
         }
         catch (error) {
-            first.onError?.(error instanceof Error ? error.message : String(error));
+            hostFailed(first, error, "mount");
             return;
         }
         handle.current = display;
@@ -218,10 +270,16 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
             "refused",
             "muted",
             "outcome",
+            "annotation",
+            "contentError",
+            "hostError",
         ];
         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 });
         }
@@ -231,12 +289,49 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
         };
         // A new display only for a new config, document, instance or page (or generation, by key);
         // content, theme, handlers, id and title are fed to the running one.
-    }, [config, view, instance, page, startHeight]);
+    }, [config, view, instance, page, startHeight, fills]);
     useEffect(() => {
         if (content !== undefined) {
             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 } = frame;
+    const focusedAnnotation = focusOf(frame.focusedAnnotation);
+    const focusToken = focusedAnnotation === null
+        ? ""
+        : typeof frame.focusedAnnotation === "object" && frame.focusedAnnotation !== null
+            ? JSON.stringify([frame.focusedAnnotation.id, frame.focusedAnnotation.key])
+            : JSON.stringify([focusedAnnotation]);
+    // By value: the same marks given again don't mark them again.
+    const annotations = useByValue(frame.annotations);
+    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;
+        const id = focusOf(latest().focusedAnnotation);
+        if (annotates && display !== null && focusToken !== "" && id !== null) {
+            attempt(() => display.annotations.focus(id), latest());
+        }
+    }, [annotates, focusToken]);
     useEffect(() => {
         handle.current?.setTheme(scheme);
     }, [scheme]);
@@ -253,3 +348,50 @@ 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 })] }));
 }
+/** Tells the frame's props what failed on the host's side. */
+function hostFailed(frame, error, kind) {
+    const message = error instanceof Error ? error.message : String(error);
+    frame.onHostError?.({ message, kind });
+    frame.onError?.(message, "host");
+}
+/** Runs an annotation call, telling the frame's props what it threw (a bad anchor, say). */
+function attempt(run, frame) {
+    try {
+        run();
+    }
+    catch (error) {
+        hostFailed(frame, error, "annotations");
+    }
+}
+/** 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);
+        }
+        const focused = focusOf(frame.focusedAnnotation);
+        if (focused !== null) {
+            display.annotations.focus(focused);
+        }
+        if (frame.annotating !== undefined && frame.annotating !== null) {
+            display.annotations.start(frame.annotating);
+        }
+    }, frame);
+}
+/**
+ * `value` as long as it is equal by value (as JSON): plain data a host builds inline on each
+ * render (a config, an instance, marks, hostInfo) keeps one identity, so effects keyed on it run
+ * only when it really changes.
+ */
+function useByValue(value) {
+    const key = value === undefined ? "" : JSON.stringify(value);
+    return useMemo(() => (key === "" ? undefined : JSON.parse(key)), [key]);
+}
+/** The id `focusedAnnotation` names, if any. */
+function focusOf(value) {
+    return typeof value === "string"
+        ? value
+        : value === null || value === undefined
+            ? null
+            : value.id;
+}

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

@@ -15,3 +15,9 @@ export declare function isHostLabel(label: unknown): label is string;
  * than being folded into another scope's name.
  */
 export declare function prefixedName(prefix: string): (scope: string) => string;
+/**
+ * Whether a label is reserved (`ContentDomain.reserved`): a whole label, a prefix ending in `*`
+ * (`p-*`), or the host's own function. Entries are checked once, here; a function that throws
+ * reserves the label (fail closed: the request goes to the host's routes, never served as ours).
+ */
+export declare function reservedLabels(reserved: readonly string[] | ((label: string) => boolean) | undefined): (label: string) => boolean;

package/dist/server/naming.js

@@ -32,3 +32,41 @@ export function prefixedName(prefix) {
         return label;
     };
 }
+const PREFIX_ENTRY = /^[a-z0-9]([a-z0-9-]{0,61})?\*$/u;
+/**
+ * Whether a label is reserved (`ContentDomain.reserved`): a whole label, a prefix ending in `*`
+ * (`p-*`), or the host's own function. Entries are checked once, here; a function that throws
+ * reserves the label (fail closed: the request goes to the host's routes, never served as ours).
+ */
+export function reservedLabels(reserved) {
+    if (reserved === undefined) {
+        return () => false;
+    }
+    if (typeof reserved === "function") {
+        return (label) => {
+            try {
+                return reserved(label);
+            }
+            catch {
+                return true;
+            }
+        };
+    }
+    if (!Array.isArray(reserved)) {
+        throw new TypeError("content.reserved: a list of labels and prefixes, or a function");
+    }
+    const whole = new Set();
+    const prefixes = [];
+    for (const entry of reserved) {
+        if (typeof entry === "string" && PREFIX_ENTRY.test(entry)) {
+            prefixes.push(entry.slice(0, -1));
+        }
+        else if (isHostLabel(entry)) {
+            whole.add(entry);
+        }
+        else {
+            throw new TypeError(`content.reserved: ${JSON.stringify(entry)} is not a lowercase DNS label or a prefix ending in *`);
+        }
+    }
+    return (label) => whole.has(label) || prefixes.some((prefix) => label.startsWith(prefix));
+}

package/dist/server/pages.js

@@ -77,6 +77,8 @@ const pageHeaders = (frameAncestors, connect) => ({
     "content-security-policy": policy(frameAncestors, connect),
     "referrer-policy": "no-referrer",
     "x-content-type-options": "nosniff",
+    // Content origins are behind tickets: nothing on them is for search engines.
+    "x-robots-tag": "noindex, nofollow",
 });
 export function statusPage(status, title, detail, frameAncestors, method = "GET", reason = "error", hostOrigins = [], code) {
     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)}"${code === undefined ? "" : ` data-porthole-code="${escape(code)}"`} data-porthole-hosts="${escape(JSON.stringify(hostOrigins))}"><h1>${escape(title)}</h1><p>${escape(detail)}</p></main><script src="${STATUS_SCRIPT_PATH}"></script></body></html>`;

package/dist/server/server.js

@@ -2,7 +2,7 @@ import { compile } from "../compile/compile.js";
 import { hostOriginProblem, maybeSameSite, originMatchesSource, parseOrigin, } from "../isolation/served.js";
 import { sandboxProxyDocument } from "../mcp/proxy.js";
 import { createKeys, newTicket, ticketId } from "./keys.js";
-import { isHostLabel } from "./naming.js";
+import { isHostLabel, reservedLabels } from "./naming.js";
 import { enterPage, pageScript, SESSION_PATH, statusPage } from "./pages.js";
 import { memoryTicketStore } from "./tickets.js";
 /**
@@ -26,6 +26,17 @@ const DEFAULT_SESSION_SECONDS = 3_600;
 const MAX_SESSION_SECONDS = 30 * 24 * 3_600;
 /** Browsers keep a cookie of up to 4 KB, name and attributes included. */
 const MAX_COOKIE_BYTES = 3_800;
+/** A host (and port) as it compares: lowercase, no trailing dot, no default port. */
+function normalHost(value, protocol) {
+    const host = value
+        .trim()
+        .toLowerCase()
+        .replace(/\.(?=:\d+$|$)/u, "");
+    const defaultPort = protocol === "https:" ? ":443" : protocol === "http:" ? ":80" : "";
+    return defaultPort !== "" && host.endsWith(defaultPort)
+        ? host.slice(0, -defaultPort.length)
+        : host;
+}
 const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 /** Which configs a kind of served document may be served under. */
 const MODES = {
@@ -148,25 +159,20 @@ export function createServer(options) {
         throw new TypeError("content.port must be a port number");
     }
     const keys = createKeys(options.secret);
-    const reserved = new Set(content.reserved ?? []);
-    for (const label of reserved) {
-        if (!isHostLabel(label)) {
-            throw new TypeError(`content.reserved: ${JSON.stringify(label)} is not a lowercase DNS label`);
-        }
-    }
+    const isReserved = reservedLabels(content.reserved);
     /** The label a scope is served on: the host's naming, checked, or the keyed default. */
     const nameOf = (scope) => {
         if (content.name === undefined) {
             return keys.label(scope);
         }
         const label = content.name(scope);
-        if (!isHostLabel(label) || reserved.has(label)) {
+        if (!isHostLabel(label) || isReserved(label)) {
             throw new TypeError(`content.name gave ${JSON.stringify(label)} for a scope: it must be one lowercase DNS label (a-z 0-9 -, at most 63, not xn--), not reserved`);
         }
         return label;
     };
     /** Whether a request's label may be one this server named. */
-    const ours = (label) => !reserved.has(label) && (content.name === undefined ? LABEL.test(label) : isHostLabel(label));
+    const ours = (label) => !isReserved(label) && (content.name === undefined ? LABEL.test(label) : isHostLabel(label));
     const secure = content.scheme === "https";
     const defaultPort = secure ? 443 : 80;
     const portPart = content.port === undefined || content.port === defaultPort ? "" : `:${content.port}`;
@@ -431,6 +437,7 @@ export function createServer(options) {
             "cache-control": "no-store",
             "referrer-policy": "no-referrer",
             "x-content-type-options": "nosniff",
+            "x-robots-tag": "noindex, nofollow",
         });
     }
     async function serveDocument(request, url, label, key) {
@@ -563,7 +570,16 @@ export function createServer(options) {
             return page(502, "The app didn't answer", "Its server couldn't be reached.", method);
         }
     }
-    /** The label a request is for: null when it isn't under the content domain at all. */
+    const underDomain = (host) => host === domain || host.endsWith(`.${domain}`);
+    /**
+     * The label a request is for: null when it isn't under the content domain at all (or is in a
+     * reserved namespace), "mismatch" when its Host header names another host than its URL does
+     * and either is under the content domain. A Node adapter may build the URL from an
+     * absolute-form request target (`GET http://other/…`) while a host routes by the Host header
+     * (and a cache keys on it): the two must agree before anything is served. A Host that is a
+     * local server address (an IP literal, `localhost`), as a test runner or a dev proxy sends, is
+     * not a name and isn't compared.
+     */
     function labelOf(request) {
         let url;
         try {
@@ -573,13 +589,25 @@ export function createServer(options) {
             return null;
         }
         const host = url.hostname.toLowerCase().replace(/\.$/u, "");
-        if (host !== domain && !host.endsWith(`.${domain}`)) {
+        const header = request.headers.get("host");
+        if (header !== null) {
+            const named = normalHost(header, url.protocol);
+            const name = named.replace(/:\d+$/u, "");
+            const local = name === "localhost" || /^[\d.]+$/u.test(name) || name.startsWith("[");
+            if (!local &&
+                named !== normalHost(url.host, url.protocol) &&
+                (underDomain(host) || underDomain(name))) {
+                return "mismatch";
+            }
+        }
+        if (!underDomain(host)) {
             return null;
         }
         const label = host.slice(0, Math.max(0, host.length - domain.length - 1));
-        // A reserved label is another server's namespace (`f` for `<x>.f.<domain>`): it and the names
-        // under it go to the host's own routes. Any other deeper name is ours to refuse.
-        if (reserved.has(label.split(".").at(-1) ?? "")) {
+        // A reserved label is another server's namespace (`f` for `<x>.f.<domain>`), or the host's
+        // own: it and the names under it go to the host's own routes. Any other deeper name is ours
+        // to refuse.
+        if (isReserved(label.split(".").at(-1) ?? "")) {
             return null;
         }
         return { url, label };
@@ -639,7 +667,7 @@ export function createServer(options) {
         },
         async access(request) {
             const at = labelOf(request);
-            if (at === null || !ours(at.label)) {
+            if (at === null || at === "mismatch" || !ours(at.label)) {
                 return null;
             }
             const access = accessOf(request, at.label, null);
@@ -650,8 +678,11 @@ export function createServer(options) {
             if (at === null) {
                 return null;
             }
-            const { url, label } = at;
             const method = request.method.toUpperCase();
+            if (at === "mismatch") {
+                return page(400, "Bad request", "The request's Host header and its URL name different hosts.", method);
+            }
+            const { url, label } = at;
             try {
                 if (!ours(label)) {
                     return page(404, "Nothing here", "This address names no content.", method);
@@ -673,7 +704,8 @@ export function createServer(options) {
                 if (document?.[1] !== undefined) {
                     return await serveDocument(request, url, label, document[1]);
                 }
-                if (url.pathname.startsWith(PREFIX)) {
+                // Without an upstream, only Porthole's own paths are served here: any other is nothing.
+                if (url.pathname.startsWith(PREFIX) || options.upstream === undefined) {
                     return page(404, "Nothing here", "This address names no content.", method);
                 }
                 return await serveApp(request, label);

package/dist/server/types.d.ts

@@ -18,10 +18,13 @@ export interface ContentDomain {
      */
     readonly name?: (scope: string) => string;
     /**
-     * Labels this server never serves or names (another server's namespace under the same domain,
-     * `f` for `<instance>.f.<domain>`, or `www`). Requests for them get null (the host's routes).
+     * Labels this server never serves or names: another server's namespace under the same domain
+     * (`f` for `<instance>.f.<domain>`, `www`), or the host's own (`p-*`: every label starting
+     * `p-`). Each entry is a whole label, or a prefix ending in `*`; or a function that says
+     * whether a label is reserved. Requests for them, and for the names under them, get null (the
+     * host's routes), so a host routes them without wrapping `handle`.
      */
-    readonly reserved?: readonly string[];
+    readonly reserved?: readonly string[] | ((label: string) => boolean);
 }
 /**
  * Who may open an instance, decided by the host before it calls `issue`: a viewer the host

package/dist/shell/annotate.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The shell's annotation runtime (P053), spliced into the shell's runtime (`__ANNOTATE__`) when
+ * the config declares `annotate`, so it runs before any content does, with the DOM's own
+ * functions as they were. Plain ES2020 like the rest of the shell; no template literals (it sits
+ * in one).
+ *
+ * The host drives it (`porthole/annotate.start|stop|show|focus|clear`) and it reports
+ * (`porthole/annotate.selected|unselected|cancelled|anchored`):
+ * - picking an element: the element under the pointer (or finger) is outlined with its name; a
+ *   click or tap picks it, and the content's own handlers never see that click; Escape cancels;
+ * - selecting text: each selection that settles is reported, with where it is, and its clearing;
+ * - marks: each anchor is found in the content as it is now (its CSS selector, its text where it
+ *   was, its text anywhere, its words with any spacing) and drawn over it, in a layer of the
+ *   shell's own (a closed shadow root), again whenever the content changes; what can't be found
+ *   is reported `orphaned`.
+ *
+ * It shares the realm with the content, which can interfere with all of it: the host takes its
+ * reports as UI hints only.
+ */
+export declare const ANNOTATE_RUNTIME: string;