@botiverse/porthole 0.1.2 → 0.1.3

package/src/react/dialog.tsx

@@ -66,6 +66,8 @@ function words(request: ConfirmRequest): Words {
       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/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 { 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
@@ -50,6 +54,8 @@ interface PageState {
   readonly confirm?: Confirm;
   readonly hostInfo?: { readonly name: string; readonly version: string };
   readonly locator?: InstanceLocator;
+  /** 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 +75,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;
 }
 
@@ -96,16 +104,26 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
           ),
     [],
   );
+  // 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), []);
   const { hostInfo, locator } = props;
   const value = useMemo<PageState>(
     () => ({
       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 (
@@ -125,6 +143,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>
   );
 }
@@ -186,6 +215,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;
@@ -371,6 +415,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 +444,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 {
@@ -435,10 +490,14 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
       "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 });
     }
@@ -455,6 +514,39 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
       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) 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;
+    if (annotates && display !== null && typeof focusedAnnotation === "string") {
+      attempt(() => display.annotations.focus(focusedAnnotation), latest());
+    }
+  }, [annotates, focusedAnnotation]);
   useEffect(() => {
     handle.current?.setTheme(scheme);
   }, [scheme]);
@@ -484,3 +576,27 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
     </div>
   );
 }
+
+/** Runs an annotation call, telling the frame's `onError` what it threw (a bad anchor, say). */
+function attempt(run: () => void, frame: PortholeFrameProps): void {
+  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: DisplayHandle, frame: PortholeFrameProps): void {
+  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/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>
+  );
+}