@botiverse/porthole 0.1.2 → 0.1.4

package/src/react/frame.tsx

@@ -14,8 +14,10 @@ import {
   type ReactElement,
   type ReactNode,
 } from "react";
+import type { AnnotateMode, AnnotationMark, AnnotationReport } from "../annotate/types.ts";
 import type {
   CallContext,
+  CapabilityHandler,
   CapabilityHandlers,
   Confirm,
   ConfirmAnswer,
@@ -25,11 +27,13 @@ import type {
 } from "../bridge/types.ts";
 import type { CapabilityName } from "../config/capabilities.ts";
 import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
+import { writeClipboard } from "../host/clipboard.ts";
 import { createHost } from "../host/create-host.ts";
-import type { DisplayEvents, DisplayHandle, FrameOutcome } from "../host/types.ts";
+import type { DisplayEvents, DisplayHandle, FrameOutcome, HostErrorKind } from "../host/types.ts";
 import type { InstanceLocator, InstanceRef } from "../isolation/types.ts";
 import { ConfirmDialog } from "./dialog.tsx";
 import { createLiveFrames, type FrameState, type LiveFrames } from "./live.ts";
+import { CopyToast, type CopyNotice } from "./toast.tsx";
 
 /**
  * The React binding: a `<PortholeProvider>` near the root owns what is per page (which frames
@@ -49,7 +53,11 @@ interface PageState {
   readonly heights: Map<string, number>;
   readonly confirm?: Confirm;
   readonly hostInfo?: { readonly name: string; readonly version: string };
-  readonly locator?: InstanceLocator;
+  readonly nonce?: string;
+  /** The provider's locator, read when a frame locates (so an inline one restarts nothing). */
+  readonly locate?: InstanceLocator["locate"];
+  /** The default `copyText`: copies on the host's page and shows the toast (P052). */
+  readonly copyText?: CapabilityHandler<"copyText">;
 }
 
 /** Without a provider: one registry for the page, and no one to confirm (gated calls refused). */
@@ -69,6 +77,13 @@ 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;
+  /**
+   * The page's CSP nonce, where its `script-src` is nonce-based: opaque frames inherit the page's
+   * policy, so their shell carries it (P054).
+   */
+  readonly nonce?: string;
   readonly children?: ReactNode;
 }
 
@@ -96,16 +111,42 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
           ),
     [],
   );
-  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<CopyNotice | null>(null);
+  const copyText = useCallback<CapabilityHandler<"copyText">>(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<InstanceLocator["locate"]>(
+    (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<PageState>(
     () => ({
       live,
       heights,
       confirm,
+      copyText,
       ...(hostInfo === undefined ? {} : { hostInfo }),
-      ...(locator === undefined ? {} : { locator }),
+      ...(locates ? { locate } : {}),
+      ...(nonce === undefined ? {} : { nonce }),
     }),
-    [live, heights, confirm, hostInfo, locator],
+    [live, heights, confirm, copyText, hostInfo, locates, locate, nonce],
   );
   const current = queue[0] ?? null;
   return (
@@ -125,6 +166,17 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
           }}
         />
       ) : null}
+      <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 }),
+          );
+        }}
+      />
     </Page.Provider>
   );
 }
@@ -163,9 +215,28 @@ export interface PortholeFrameProps {
   readonly generation?: number;
   /** Run at once, without waiting to near the screen (it still counts toward the page's most). */
   readonly eager?: boolean;
+  /**
+   * Fill the box (give it, or its parent, a height) and let the content scroll inside, instead of
+   * growing with the content: an artifact viewer's page. A url-mode app always fills.
+   */
+  readonly fill?: boolean;
   readonly onInitialized?: () => void;
   readonly onResize?: (size: { readonly height: number; readonly width?: number }) => void;
-  readonly onError?: (message: string) => void;
+  /**
+   * What the content did wrong (what it threw, what the sandbox blocked, that it kept navigating
+   * away): the agent's to hear and fix.
+   */
+  readonly onContentError?: (message: string) => void;
+  /**
+   * What failed on the host's side: its locator (`locate`), a display that couldn't be made
+   * (`mount`), an annotation call refused (`annotations`). Never the agent's.
+   */
+  readonly onHostError?: (error: {
+    readonly message: string;
+    readonly kind: HostErrorKind;
+  }) => void;
+  /** Both, with their source (as before 0.1.4). Prefer `onContentError` and `onHostError`. */
+  readonly onError?: (message: string, source: "content" | "host") => 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;
@@ -186,6 +257,27 @@ 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. To focus the
+   * same mark again (a second click on its comment), give `{ id, key }` with a new key.
+   */
+  readonly focusedAnnotation?:
+    | string
+    | { readonly id: string; readonly key: string | number }
+    | 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;
@@ -299,6 +391,8 @@ export function PortholeFrame(props: PortholeFrameProps): ReactElement {
       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,
       }}
@@ -336,8 +430,11 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
   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);
@@ -354,9 +451,17 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
           frame.onResize?.(size);
           return;
         }
-        case "error":
-          frame.onError?.((detail as DisplayEvents["error"]).message);
+        case "contentError":
+          frame.onContentError?.((detail as DisplayEvents["contentError"]).message);
           return;
+        case "hostError":
+          frame.onHostError?.(detail as DisplayEvents["hostError"]);
+          return;
+        case "error": {
+          const { message, source } = detail as DisplayEvents["error"];
+          frame.onError?.(message, source);
+          return;
+        }
         case "navigated":
           frame.onNavigated?.();
           return;
@@ -371,6 +476,9 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
         case "outcome":
           frame.onOutcome?.(detail as DisplayEvents["outcome"]);
           return;
+        case "annotation":
+          frame.onAnnotation?.(detail as DisplayEvents["annotation"]);
+          return;
       }
     },
   );
@@ -397,6 +505,14 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
           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 as { readonly text: string }, named(context));
+      }
+    }
     const asks = first.confirm !== undefined || page.confirm !== undefined;
     let display: DisplayHandle;
     try {
@@ -413,7 +529,8 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
           : {}),
         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,
@@ -421,9 +538,10 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
         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;
@@ -435,10 +553,16 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
       "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 });
     }
@@ -448,13 +572,56 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
     };
     // 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) as [boolean, boolean]);
+    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]);
@@ -484,3 +651,54 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
     </div>
   );
 }
+
+/** Tells the frame's props what failed on the host's side. */
+function hostFailed(frame: PortholeFrameProps, error: unknown, kind: HostErrorKind): void {
+  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: () => void, frame: PortholeFrameProps): void {
+  try {
+    run();
+  } catch (error) {
+    hostFailed(frame, error, "annotations");
+  }
+}
+
+/** A new display's annotations, from the props as they are. */
+function applyAnnotations(display: DisplayHandle, frame: PortholeFrameProps): void {
+  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<T>(value: T): T {
+  const key = value === undefined ? "" : JSON.stringify(value);
+  return useMemo(() => (key === "" ? undefined : JSON.parse(key)) as T, [key]);
+}
+
+/** The id `focusedAnnotation` names, if any. */
+function focusOf(value: PortholeFrameProps["focusedAnnotation"]): string | null {
+  return typeof value === "string"
+    ? value
+    : value === null || value === undefined
+      ? null
+      : value.id;
+}

package/src/react/index.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} />
@@ -17,4 +17,12 @@ export {
   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/src/react/toast.tsx

@@ -0,0 +1,96 @@
+import { useEffect, 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 const TOAST_MS = 5_000;
+/** The most of the copied text a toast shows. */
+export const TOAST_CHARS = 280;
+const TOAST_LINES = 4;
+
+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 function clipped(text: string): { readonly shown: string; readonly clipped: boolean } {
+  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 }: CopyToastProps): ReactElement {
+  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 (
+    <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}
+    >
+      <style>{STYLE}</style>
+      {notice === null || view === null ? null : (
+        <>
+          <p>
+            <strong>{notice.copied ? "Copied" : "Not copied yet"}</strong>{" "}
+            <span data-porthole-source="">{`from “${notice.title}”`}</span>
+          </p>
+          <pre data-porthole-copied-text="">{view.shown}</pre>
+          {view.clipped ? (
+            <p data-porthole-length="">{`${notice.text.length.toLocaleString("en-US")} characters in all`}</p>
+          ) : null}
+          <menu>
+            {notice.copied ? null : (
+              <button type="button" data-porthole-copy="" onClick={() => onCopy(notice)}>
+                Copy
+              </button>
+            )}
+            <button type="button" data-porthole-close="" onClick={onClose}>
+              {notice.copied ? "OK" : "Close"}
+            </button>
+          </menu>
+        </>
+      )}
+    </div>
+  );
+}

package/src/server/naming.ts

@@ -40,3 +40,44 @@ export function prefixedName(prefix: string): (scope: string) => string {
     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: readonly string[] | ((label: string) => boolean) | undefined,
+): (label: string) => boolean {
+  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<string>();
+  const prefixes: string[] = [];
+  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/src/server/pages.ts

@@ -93,6 +93,8 @@ const pageHeaders = (frameAncestors: string, connect: boolean) => ({
   "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(