@botiverse/porthole 0.0.1 → 0.1.1

package/src/react/frame.tsx

@@ -0,0 +1,486 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useEffectEvent,
+  useId,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore,
+  type CSSProperties,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import type {
+  CallContext,
+  CapabilityHandlers,
+  Confirm,
+  ConfirmAnswer,
+  ConfirmRequest,
+  Proceed,
+  Refusal,
+} from "../bridge/types.ts";
+import type { CapabilityName } from "../config/capabilities.ts";
+import type { ColorScheme, PortholeConfig } from "../config/schema.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";
+
+/**
+ * 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
+ * display mounts it when it nears the screen, streams its content, flips its theme, and remembers
+ * its height. All the isolation is the core's (`createHost`); this is mounting and lifecycle.
+ */
+
+/** How far off screen a frame starts (and keeps) running. */
+const NEAR_SCREEN = "800px 0px";
+/** The height a display holds before it has reported its own. */
+export const PLACEHOLDER_HEIGHT_PX = 96;
+
+interface PageState {
+  readonly live: LiveFrames;
+  /** Heights displays reported, by display id: a frame mounting again starts at its last. */
+  readonly heights: Map<string, number>;
+  readonly confirm?: Confirm;
+  readonly hostInfo?: { readonly name: string; readonly version: string };
+  readonly locator?: InstanceLocator;
+}
+
+/** Without a provider: one registry for the page, and no one to confirm (gated calls refused). */
+const PAGE: PageState = { live: createLiveFrames(), heights: new Map() };
+
+const Page = createContext<PageState>(PAGE);
+
+export interface PortholeProviderProps {
+  /**
+   * Who confirms gated calls for every frame below. Omitted: the default dialog (`ConfirmDialog`).
+   * Pass your own function to replace it.
+   */
+  readonly confirm?: Confirm;
+  /** How the host names itself in the handshake. */
+  readonly hostInfo?: { readonly name: string; readonly version: string };
+  /** Where domain and external frames load from (see `InstanceLocator`). */
+  readonly locator?: InstanceLocator;
+  /** A class for the default dialog, to restyle it. */
+  readonly dialogClassName?: string;
+  readonly children?: ReactNode;
+}
+
+interface Pending {
+  readonly request: ConfirmRequest;
+  readonly resolve: (answer: ConfirmAnswer) => void;
+  readonly proceed: Proceed;
+}
+
+export function PortholeProvider(props: PortholeProviderProps): ReactElement {
+  const live = useMemo(() => createLiveFrames(), []);
+  const heights = useMemo(() => new Map<string, number>(), []);
+  const [queue, setQueue] = useState<readonly Pending[]>([]);
+  // The host's confirm as of the last render, read when a frame asks (never during render).
+  const own = useRef(props.confirm);
+  useLayoutEffect(() => {
+    own.current = props.confirm;
+  });
+  const confirm = useCallback<Confirm>(
+    (request, proceed) =>
+      own.current !== undefined
+        ? own.current(request, proceed)
+        : new Promise<ConfirmAnswer>((resolve) =>
+            setQueue((waiting) => [...waiting, { request, resolve, proceed }]),
+          ),
+    [],
+  );
+  const { hostInfo, locator } = props;
+  const value = useMemo<PageState>(
+    () => ({
+      live,
+      heights,
+      confirm,
+      ...(hostInfo === undefined ? {} : { hostInfo }),
+      ...(locator === undefined ? {} : { locator }),
+    }),
+    [live, heights, confirm, hostInfo, locator],
+  );
+  const current = queue[0] ?? null;
+  return (
+    <Page.Provider value={value}>
+      {props.children}
+      {props.confirm === undefined ? (
+        <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).
+            if (accepted) {
+              current?.proceed();
+            }
+            current?.resolve(accepted ? "accepted" : "declined");
+            setQueue((waiting) => waiting.slice(1));
+          }}
+        />
+      ) : null}
+    </Page.Provider>
+  );
+}
+
+/** What a placeholder shows: a display not yet running, loading, or stopped for others. */
+export interface PlaceholderProps {
+  readonly state: "waiting" | "loading" | "stopped";
+  readonly title: string;
+  /** Runs the display again (a stopped one), stopping another if the page is at its most. */
+  readonly run: () => void;
+}
+
+export interface PortholeFrameProps {
+  /** A preset's config. Keep it stable (module scope or memoized): a new one remounts the frame. */
+  readonly config: PortholeConfig;
+  /** The host's id for this display: what its height is remembered by, and calls name. */
+  readonly displayId: string;
+  /** The frame's accessible name, and the title its confirmations show (the host's words). */
+  readonly title: string;
+  /** The content so far (inline and artifact modes). */
+  readonly content?: string;
+  /** The content is still being written: drawn inert as it grows, run once when whole. */
+  readonly partial?: boolean;
+  /** A whole document to start with (an MCP Apps view). */
+  readonly document?: string;
+  /** Domain and external isolation: the instance to show. */
+  readonly instance?: InstanceRef;
+  readonly scheme: ColorScheme;
+  /** The host's live values for the config's theme variables (from its design tokens). */
+  readonly theme?: (scheme: ColorScheme) => Readonly<Record<string, string | null | undefined>>;
+  /** Handlers for the declared capabilities (the latest ones are called). */
+  readonly handlers?: CapabilityHandlers;
+  /** Who confirms this frame's gated calls, over the provider's. */
+  readonly confirm?: Confirm;
+  /** Bump to run the content again from the start. */
+  readonly generation?: number;
+  /** Run at once, without waiting to near the screen (it still counts toward the page's most). */
+  readonly eager?: boolean;
+  readonly onInitialized?: () => void;
+  readonly onResize?: (size: { readonly height: number; readonly width?: number }) => void;
+  readonly onError?: (message: string) => void;
+  /** The content navigated its frame away; it was started again (or stopped, after a few). */
+  readonly onNavigated?: () => void;
+  readonly onRefused?: (capability: CapabilityName, refusal: Refusal) => void;
+  /** Too many declines: the display stops asking until it runs again. */
+  readonly onMuted?: () => void;
+  /**
+   * How the frame's first document went: loaded, blocked (and why), or a timeout. A host shows its
+   * own fallback (a url-mode app "Open in a new tab") on anything but loaded.
+   */
+  readonly onOutcome?: (outcome: FrameOutcome) => void;
+  /**
+   * Other ids this display had (the call's id, before the display's own settled): its remembered
+   * height is found under them, for a frame that mounts again under its new id.
+   */
+  readonly aliases?: readonly string[];
+  /**
+   * Change it when the host's theme values change without a scheme flip (or after an async
+   * restyle): the running frame reads them again.
+   */
+  readonly themeKey?: string | number;
+  /** Draws the placeholder instead of the default one. */
+  readonly renderPlaceholder?: (props: PlaceholderProps) => ReactNode;
+  readonly className?: string;
+  readonly style?: CSSProperties;
+}
+
+const PLACEHOLDER_STYLE: CSSProperties = {
+  position: "absolute",
+  inset: 0,
+  display: "flex",
+  flexDirection: "column",
+  alignItems: "center",
+  justifyContent: "center",
+  gap: 8,
+  fontSize: "0.8em",
+  opacity: 0.7,
+};
+
+function DefaultPlaceholder({ state, title, run }: PlaceholderProps): ReactElement {
+  return (
+    <div
+      data-porthole-placeholder={state}
+      style={{ ...PLACEHOLDER_STYLE, pointerEvents: state === "stopped" ? "auto" : "none" }}
+    >
+      <span>{state === "stopped" ? "Stopped while others run" : title}</span>
+      {state === "stopped" ? (
+        <button type="button" data-porthole-run="" onClick={run}>
+          Run again
+        </button>
+      ) : null}
+    </div>
+  );
+}
+
+/** A display's remembered height: under its id, else under the first of its other ids that has one. */
+function rememberedHeight(
+  heights: ReadonlyMap<string, number>,
+  displayId: string,
+  aliases: readonly string[] | undefined,
+): number {
+  for (const id of [displayId, ...(aliases ?? [])]) {
+    const height = heights.get(id);
+    if (height !== undefined) {
+      return height;
+    }
+  }
+  return 0;
+}
+
+export function PortholeFrame(props: PortholeFrameProps): ReactElement {
+  const page = useContext(Page);
+  const key = useId();
+  const box = useRef<HTMLDivElement>(null);
+  const max = props.config.limits.maxLiveFrames;
+  const state = useSyncExternalStore(
+    (listener) => page.live.subscribe(listener),
+    () => page.live.state(key),
+    (): FrameState => "waiting",
+  );
+  const { eager } = props;
+
+  useEffect(() => {
+    const element = box.current;
+    if (element === null) {
+      return;
+    }
+    if (eager === true || typeof IntersectionObserver !== "function") {
+      page.live.near(key, true);
+      page.live.admit(key, max);
+      return () => page.live.release(key);
+    }
+    const observer = new IntersectionObserver(
+      (entries) => {
+        const entry = entries.at(-1);
+        if (entry === undefined) {
+          return;
+        }
+        page.live.near(key, entry.isIntersecting);
+        if (entry.isIntersecting) {
+          page.live.admit(key, max);
+        }
+      },
+      { rootMargin: NEAR_SCREEN },
+    );
+    observer.observe(element);
+    return () => {
+      observer.disconnect();
+      page.live.release(key);
+    };
+  }, [page, key, max, eager]);
+
+  const height = rememberedHeight(page.heights, props.displayId, props.aliases);
+  // A display renamed while it runs (its id settled) keeps its height under its new id.
+  const previousId = useRef(props.displayId);
+  useLayoutEffect(() => {
+    const before = previousId.current;
+    previousId.current = props.displayId;
+    const kept = page.heights.get(before);
+    if (before !== props.displayId && kept !== undefined && !page.heights.has(props.displayId)) {
+      page.heights.set(props.displayId, kept);
+    }
+  }, [page, props.displayId]);
+  const run = () => page.live.admit(key, max);
+  const placeholder = props.renderPlaceholder ?? DefaultPlaceholder;
+  return (
+    <div
+      ref={box}
+      className={props.className}
+      data-porthole-display={props.displayId}
+      data-porthole-state={state}
+      style={{
+        position: "relative",
+        width: "100%",
+        ...(state === "running" ? {} : { minHeight: Math.max(height, PLACEHOLDER_HEIGHT_PX) }),
+        ...props.style,
+      }}
+    >
+      {state === "running" ? (
+        <Mount
+          key={String(props.generation ?? 0)}
+          frame={props}
+          page={page}
+          initialHeightPx={height}
+          placeholder={placeholder}
+          run={run}
+        />
+      ) : (
+        placeholder({ state, title: props.title, run })
+      )}
+    </div>
+  );
+}
+
+interface MountProps {
+  readonly frame: PortholeFrameProps;
+  readonly page: PageState;
+  readonly initialHeightPx: number;
+  readonly placeholder: (props: PlaceholderProps) => ReactNode;
+  readonly run: () => void;
+}
+
+type AnyHandler = (args: unknown, context: CallContext) => unknown;
+
+/** One running display: created when mounted, torn down when unmounted, fed as props change. */
+function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps): ReactElement {
+  const holder = useRef<HTMLDivElement>(null);
+  const handle = useRef<DisplayHandle | null>(null);
+  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";
+
+  // The latest props, read when the display calls back (never during render).
+  const latest = useEffectEvent(() => frame);
+  const notify = useEffectEvent(
+    <E extends keyof DisplayEvents>(event: E, detail: DisplayEvents[E]): void => {
+      switch (event) {
+        case "initialized":
+          setReady(true);
+          frame.onInitialized?.();
+          return;
+        case "resize": {
+          const size = detail as DisplayEvents["resize"];
+          page.heights.set(frame.displayId, size.height);
+          frame.onResize?.(size);
+          return;
+        }
+        case "error":
+          frame.onError?.((detail as DisplayEvents["error"]).message);
+          return;
+        case "navigated":
+          frame.onNavigated?.();
+          return;
+        case "refused": {
+          const { capability, refusal } = detail as DisplayEvents["refused"];
+          frame.onRefused?.(capability, refusal);
+          return;
+        }
+        case "muted":
+          frame.onMuted?.();
+          return;
+        case "outcome":
+          frame.onOutcome?.(detail as DisplayEvents["outcome"]);
+          return;
+      }
+    },
+  );
+
+  useEffect(() => {
+    const container = holder.current;
+    if (container === null) {
+      return;
+    }
+    const first = latest();
+    // A display keeps running when the host renames it (a streamed display's id and title can
+    // settle after it starts): calls and confirmations name it as the latest props do.
+    const named = (context: CallContext): CallContext => ({
+      ...context,
+      displayId: latest().displayId,
+      title: latest().title,
+    });
+    // The handlers present now (a declared one must be), each calling the latest prop's.
+    const handlers: Record<string, AnyHandler> = {};
+    for (const name of Object.keys(first.handlers ?? {})) {
+      handlers[name] = (args, context) =>
+        (latest().handlers as Record<string, AnyHandler | undefined> | undefined)?.[name]?.(
+          args,
+          named(context),
+        );
+    }
+    const asks = first.confirm !== undefined || page.confirm !== undefined;
+    let display: DisplayHandle;
+    try {
+      display = createHost(config, {
+        handlers,
+        ...(asks
+          ? {
+              confirm: (request: ConfirmRequest, proceed: Proceed) =>
+                (latest().confirm ?? page.confirm ?? (() => Promise.resolve(false)))(
+                  { ...request, display: { id: latest().displayId, title: latest().title } },
+                  proceed,
+                ),
+            }
+          : {}),
+        theme: (each) => latest().theme?.(each) ?? {},
+        ...(page.hostInfo === undefined ? {} : { hostInfo: page.hostInfo }),
+        ...(page.locator === undefined ? {} : { locator: page.locator }),
+      }).mount(container, {
+        displayId: first.displayId,
+        title: first.title,
+        scheme: first.scheme,
+        initialHeightPx: startHeight,
+        ...(view === undefined ? {} : { document: view }),
+        ...(instance === undefined ? {} : { instance }),
+      });
+    } catch (error) {
+      first.onError?.(error instanceof Error ? error.message : String(error));
+      return;
+    }
+    handle.current = display;
+    const events: (keyof DisplayEvents)[] = [
+      "initialized",
+      "resize",
+      "error",
+      "navigated",
+      "refused",
+      "muted",
+      "outcome",
+    ];
+    for (const event of events) {
+      display.on(event, (detail) => notify(event, detail));
+    }
+    if (first.content !== undefined) {
+      display.setContent(first.content, { partial: first.partial === true });
+    }
+    return () => {
+      display.destroy();
+      handle.current = null;
+    };
+    // 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]);
+
+  useEffect(() => {
+    if (content !== undefined) {
+      handle.current?.setContent(content, { partial: partial === true });
+    }
+  }, [content, partial]);
+  useEffect(() => {
+    handle.current?.setTheme(scheme);
+  }, [scheme]);
+  const { themeKey } = frame;
+  useEffect(() => {
+    if (themeKey !== undefined) {
+      handle.current?.refreshTheme();
+    }
+  }, [themeKey]);
+
+  return (
+    <div
+      data-porthole-ready={String(ready)}
+      style={{
+        position: "relative",
+        // A url-mode app fills the frame's box (give PortholeFrame a height); the rest size to content.
+        ...(fills ? { height: "100%" } : {}),
+        ...(ready ? {} : { minHeight: Math.max(startHeight, PLACEHOLDER_HEIGHT_PX) }),
+      }}
+    >
+      <div
+        ref={holder}
+        data-porthole-mount=""
+        style={{ opacity: ready ? 1 : 0, ...(fills ? { height: "100%" } : {}) }}
+      />
+      {ready ? null : placeholder({ state: "loading", title: frame.title, run })}
+    </div>
+  );
+}

package/src/react/index.ts

@@ -0,0 +1,20 @@
+/**
+ * `@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
+ *     <PortholeFrame config={widgetConfig} displayId={id} title={title} scheme={scheme}
+ *       content={code} partial={streaming} handlers={{ sendPrompt, openLink }}
+ *       theme={tokensFor} onError={report} />
+ *   </PortholeProvider>
+ */
+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 { admitFrame, createLiveFrames, type FrameState, type LiveFrames } from "./live.ts";

package/src/react/live.ts

@@ -0,0 +1,76 @@
+/**
+ * Which frames run on a page: each runs a display's scripts, so a page runs at most a few at once.
+ * A frame runs when it comes near the screen (or is asked to run); past the most, the frames that
+ * went off screen longest ago stop, and show a placeholder at their last height until they come
+ * near again. Framework-free, so it is tested on its own.
+ */
+
+export type FrameState = "waiting" | "running" | "stopped";
+
+/**
+ * Which frames run once `key` comes near the screen or is asked to run. `live` is the frames
+ * running, the least recently admitted first. `key` runs; past `max`, the frames that are not near
+ * the screen stop first, oldest first (one near the screen stops only when all are near).
+ */
+export function admitFrame(
+  live: readonly string[],
+  near: ReadonlySet<string>,
+  key: string,
+  max: number,
+): string[] {
+  const next = [...live.filter((other) => other !== key), key];
+  while (next.length > Math.max(1, max)) {
+    const far = next.findIndex((other) => other !== key && !near.has(other));
+    next.splice(far === -1 ? 0 : far, 1);
+  }
+  return next;
+}
+
+export interface LiveFrames {
+  subscribe(listener: () => void): () => void;
+  state(key: string): FrameState;
+  /** The frame came near the screen, or left it. */
+  near(key: string, isNear: boolean): void;
+  /** `key` runs (near the screen, or asked to run again); others past `max` stop. */
+  admit(key: string, max: number): void;
+  /** The frame is gone. */
+  release(key: string): void;
+}
+
+export function createLiveFrames(): LiveFrames {
+  let live: readonly string[] = [];
+  const nearScreen = new Set<string>();
+  const ran = new Set<string>();
+  const listeners = new Set<() => void>();
+  const changed = (next: readonly string[]) => {
+    live = next;
+    for (const listener of listeners) {
+      listener();
+    }
+  };
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    state: (key) => (live.includes(key) ? "running" : ran.has(key) ? "stopped" : "waiting"),
+    near(key, isNear) {
+      if (isNear) {
+        nearScreen.add(key);
+      } else {
+        nearScreen.delete(key);
+      }
+    },
+    admit(key, max) {
+      ran.add(key);
+      changed(admitFrame(live, nearScreen, key, max));
+    },
+    release(key) {
+      nearScreen.delete(key);
+      ran.delete(key);
+      if (live.includes(key)) {
+        changed(live.filter((other) => other !== key));
+      }
+    },
+  };
+}

package/src/server/index.ts

@@ -0,0 +1,37 @@
+/**
+ * `@botiverse/porthole/server`: serving content on origins of its own (domain mode, artifact
+ * pages, the MCP Apps sandbox proxy, and url mode's access gate). A host's backend mounts it as a
+ * fetch-style handler in front of its own routes, for every request whose host is under the
+ * content domain:
+ *
+ *   const porthole = createServer({ content: { domain: "example-usercontent.com", scheme: "https" }, … });
+ *   app.all("*", async (c, next) => (await porthole.handle(c.req.raw)) ?? next());   // Hono
+ *
+ * and calls `issue` from its own authenticated API when a viewer opens served content.
+ *
+ * Origins: each storage scope gets `<label>.<domain>`, the label keyed from the scope by the
+ * secret (stable, DNS-safe, not guessable from the scope). The domain is a registrable domain the
+ * host uses for nothing else, so no content origin is ever same-site with the host. Documents go
+ * out with their CSP (from the config) plus `frame-ancestors` (the host origins) in headers.
+ *
+ * Tickets: `issue` mints a one-time ticket for an instance and a viewer, good for a short time;
+ * the frame's first request carries it, and the content origin takes it (once). A served document
+ * comes back in that same answer, with a cookie of that origin only (`__Host-`, `Secure`,
+ * `HttpOnly`, `SameSite=None; Partitioned` in a frame) for what follows; a url-mode app's ticket
+ * buys the cookie and redirects to the app's landing path without the ticket (P025). Private
+ * content without a valid ticket or cookie gets nothing of the content.
+ */
+export { createServer } from "./server.ts";
+export { memoryTicketStore } from "./tickets.ts";
+export { proxyTo, type ProxyOptions } from "./proxy.ts";
+export type {
+  Access,
+  ArtifactStore,
+  ContentDomain,
+  Grant,
+  PortholeServer,
+  ServerOptions,
+  TicketRecord,
+  TicketStore,
+  Upstream,
+} from "./types.ts";