@botiverse/porthole 0.0.1 → 0.1.1

package/src/host/create-host.ts

@@ -0,0 +1,335 @@
+import { createBridge, type BridgeEvent } from "../bridge/bridge.ts";
+import { compile } from "../compile/compile.ts";
+import { declaredCapabilities } from "../compile/policy.ts";
+import { capabilitySpec } from "../config/capabilities.ts";
+import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
+import { locateServed } from "./locate.ts";
+import { watchOutcome, type OutcomeWatch } from "./outcome.ts";
+import type { FrameSource } from "../isolation/types.ts";
+import { webPlatform } from "../platform/web.ts";
+import type { Surface } from "../platform/types.ts";
+import type { AdapterConnection, ProtocolAdapter, ShellConnection } from "../protocol/adapter.ts";
+import {
+  MCP_APPS_STYLE_VARIABLES,
+  PORTHOLE_STYLES,
+  type HostContext,
+} from "../protocol/mcp-apps.ts";
+import { shellAdapter } from "../protocol/shell-adapter.ts";
+import { resolveTheme } from "../theme/variables.ts";
+import type {
+  DisplayEvents,
+  DisplayHandle,
+  HostOptions,
+  MountOptions,
+  PortholeHost,
+} from "./types.ts";
+
+/** How long a display may take to load before its outcome is a timeout, by default. */
+const DEFAULT_LOAD_TIMEOUT_MS = 15_000;
+
+/** How many times a display is started again after its content navigated its frame away. */
+const MAX_RESTARTS = 3;
+
+const BASE_KEYS = new Set(["hostContextChanged", "teardown", "close"]);
+const STANDARD = new Set(MCP_APPS_STYLE_VARIABLES);
+
+/**
+ * Compiles `config` once and returns a host that mounts displays under it. Throws a `ConfigError`
+ * for a bad config.
+ */
+export function createHost<C extends AdapterConnection = ShellConnection>(
+  config: PortholeConfig,
+  options: HostOptions<C> = {},
+): PortholeHost<C> {
+  const compiled = compile(config);
+  if (
+    (config.isolation === "domain" || config.isolation === "external") &&
+    options.locator === undefined
+  ) {
+    throw new TypeError(`${config.isolation} isolation needs a locator (HostOptions.locator)`);
+  }
+  // A url frame is someone else's app: no shell, no protocol, and its navigations are its own.
+  const speaks = config.mode !== "url";
+  const adapter = (options.adapter ?? shellAdapter) as ProtocolAdapter<C>;
+  const platform = options.platform ?? webPlatform;
+  const hostInfo = options.hostInfo ?? { name: "porthole", version: "0" };
+
+  return {
+    compiled,
+    mount(container: HTMLElement, mount: MountOptions): DisplayHandle<C> {
+      const handlers = { ...options.handlers, ...mount.handlers };
+      const missing = declaredCapabilities(config).filter(
+        (name) =>
+          capabilitySpec(name).served === "handler" &&
+          (handlers as Record<string, unknown>)[name] === undefined,
+      );
+      if (missing.length > 0) {
+        throw new TypeError(`No handler for the declared capabilities: ${missing.join(", ")}`);
+      }
+      if (config.isolation !== "opaque" && mount.instance === undefined) {
+        throw new TypeError(`${config.isolation} isolation needs MountOptions.instance`);
+      }
+
+      const listeners = new Map<keyof DisplayEvents, Set<(detail: never) => void>>();
+      const emit = <E extends keyof DisplayEvents>(event: E, detail: DisplayEvents[E]) => {
+        for (const listener of listeners.get(event) ?? []) {
+          (listener as (detail: DisplayEvents[E]) => void)(detail);
+        }
+      };
+
+      let scheme: ColorScheme = mount.scheme;
+      let height = mount.initialHeightPx ?? 0;
+      let surface: Surface | null = null;
+      let connection: C | null = null;
+      let destroyed = false;
+      let restarts = 0;
+      let generation = 0;
+      let abort: AbortController | null = null;
+      let outcomeWatch: OutcomeWatch | null = null;
+      let themeFrame: number | null = null;
+      const view = container.ownerDocument.defaultView;
+      // The adapter's own operations, the last call of each, replayed into every new frame.
+      const replay = new Map<string, unknown[]>();
+
+      const hostContext = (): HostContext => {
+        const width = container.getBoundingClientRect().width;
+        // The spec's names in `styles` (the App SDK refuses others there), the rest in our field.
+        const variables = resolveTheme(config.theme, scheme, options.theme?.(scheme));
+        const standard: Record<string, string> = {};
+        const own: Record<string, string> = {};
+        for (const [name, value] of Object.entries(variables)) {
+          (STANDARD.has(name) ? standard : own)[name] = value;
+        }
+        return {
+          theme: scheme,
+          styles: { variables: standard },
+          ...(Object.keys(own).length === 0 ? {} : { [PORTHOLE_STYLES]: { variables: own } }),
+          displayMode: "inline",
+          availableDisplayModes: ["inline"],
+          ...(width > 0 ? { containerDimensions: { maxWidth: Math.round(width) } } : {}),
+          ...(view === null
+            ? {}
+            : {
+                locale: view.navigator.language,
+                timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+                platform: "web" as const,
+              }),
+          ...options.hostContext?.(),
+        };
+      };
+
+      const onBridge = (event: BridgeEvent) => {
+        switch (event.type) {
+          case "resize": {
+            const next = Math.min(
+              config.limits.maxHeightPx,
+              Math.max(config.limits.minHeightPx, Math.ceil(event.height)),
+            );
+            height = next;
+            surface?.setHeight(next);
+            emit("resize", {
+              height: next,
+              ...(event.width === undefined ? {} : { width: event.width }),
+            });
+            return;
+          }
+          case "error":
+            emit("error", { message: event.message });
+            return;
+          case "refused":
+            emit("refused", { capability: event.capability, refusal: event.refusal });
+            return;
+          case "muted":
+            emit("muted", undefined);
+            return;
+        }
+      };
+
+      const stop = () => {
+        abort?.abort();
+        abort = null;
+        outcomeWatch?.stop();
+        outcomeWatch = null;
+        connection?.close();
+        connection = null;
+        surface?.destroy();
+        surface = null;
+      };
+
+      const start = (source: FrameSource) => {
+        const created = platform.createSurface(container, {
+          source,
+          title: mount.title,
+          sandbox: compiled.sandbox,
+          allow: compiled.allow,
+          referrerPolicy: compiled.referrerPolicy,
+          colorScheme: scheme,
+          // An app reports no size: its frame fills the host's container, at least the minimum.
+          ...(speaks
+            ? { initialHeightPx: height }
+            : { fill: true, initialHeightPx: config.limits.minHeightPx }),
+        });
+        surface = created;
+        const watch = watchOutcome({
+          surface: created,
+          source,
+          speaks,
+          timeoutMs: config.limits.loadTimeoutMs ?? DEFAULT_LOAD_TIMEOUT_MS,
+          onOutcome: (outcome) => emit("outcome", outcome),
+        });
+        outcomeWatch = watch;
+        if (!speaks) {
+          // No handshake in url mode: the app's first document loading is as ready as it gets.
+          let ready = false;
+          created.onLoad(() => {
+            if (!ready) {
+              ready = true;
+              emit("initialized", undefined);
+            }
+          });
+          return;
+        }
+        const bridge = createBridge({
+          config,
+          display: { id: mount.displayId, title: mount.title },
+          handlers,
+          ...(options.confirm === undefined ? {} : { confirm: options.confirm }),
+          userActivation: () => created.userActivation(),
+          onEvent: onBridge,
+        });
+        const opened = adapter.connect({
+          display: { id: mount.displayId, title: mount.title },
+          compiled,
+          transport: created.transport,
+          bridge,
+          hostInfo,
+          hostContext,
+          emit: (event) => {
+            if (event.type === "initialized") {
+              watch.initialized();
+              emit("initialized", undefined);
+            }
+          },
+          ...(mount.document === undefined ? {} : { document: mount.document }),
+        });
+        connection = opened;
+        for (const [name, args] of replay) {
+          (opened as unknown as Record<string, (...each: unknown[]) => unknown>)[name]?.(...args);
+        }
+        created.onNavigated(() => {
+          emit("navigated", undefined);
+          if (restarts < MAX_RESTARTS) {
+            restarts += 1;
+            run();
+          } else {
+            stop();
+            emit("error", {
+              message: "The content kept navigating its frame away; it was stopped.",
+            });
+          }
+        });
+      };
+
+      const run = () => {
+        stop();
+        if (destroyed) {
+          return;
+        }
+        generation += 1;
+        if (config.isolation === "opaque") {
+          start({
+            kind: "srcdoc",
+            html: compiled.shellDocument({
+              origins: [container.ownerDocument.defaultView?.location.origin ?? ""],
+              title: mount.title,
+              ...(mount.document === undefined ? {} : { document: mount.document }),
+            }),
+          });
+          return;
+        }
+        const mine = generation;
+        const controller = new AbortController();
+        abort = controller;
+        const locator = options.locator;
+        const instance = mount.instance;
+        if (locator === undefined || instance === undefined) {
+          return;
+        }
+        const hostOrigin = container.ownerDocument.defaultView?.location.origin ?? "";
+        locateServed(locator, instance, config, hostOrigin, controller.signal).then(
+          (source) => {
+            if (mine === generation && !destroyed) {
+              start(source);
+            }
+          },
+          (error: unknown) => {
+            if (mine === generation && !controller.signal.aborted) {
+              emit("error", { message: error instanceof Error ? error.message : String(error) });
+            }
+          },
+        );
+      };
+
+      run();
+
+      const controls = {
+        displayId: mount.displayId,
+        setTheme(next: ColorScheme) {
+          scheme = next;
+          surface?.setColorScheme(next);
+          // Read the host's values two frames later: a host that restyles its page for the new
+          // scheme on its next frame has done so by then.
+          if (view === null) {
+            connection?.hostContextChanged(hostContext());
+            return;
+          }
+          if (themeFrame !== null) {
+            view.cancelAnimationFrame(themeFrame);
+          }
+          themeFrame = view.requestAnimationFrame(() => {
+            themeFrame = view.requestAnimationFrame(() => {
+              themeFrame = null;
+              connection?.hostContextChanged(hostContext());
+            });
+          });
+        },
+        refreshTheme() {
+          connection?.hostContextChanged(hostContext());
+        },
+        on<E extends keyof DisplayEvents>(event: E, listener: (detail: DisplayEvents[E]) => void) {
+          const set = listeners.get(event) ?? new Set();
+          set.add(listener);
+          listeners.set(event, set);
+          return () => set.delete(listener);
+        },
+        reload() {
+          restarts = 0;
+          run();
+        },
+        destroy() {
+          destroyed = true;
+          stop();
+          listeners.clear();
+        },
+      };
+
+      // The adapter's own operations (`setContent` for the shell adapter): forwarded to the frame
+      // running now, and remembered (the last call of each) for a frame started again.
+      return new Proxy(controls, {
+        get(target, key, receiver) {
+          if (typeof key === "string" && !(key in target) && !BASE_KEYS.has(key)) {
+            return (...args: unknown[]) => {
+              replay.delete(key);
+              replay.set(key, args);
+              const operation = (connection as unknown as Record<string, unknown> | null)?.[key];
+              return typeof operation === "function"
+                ? (operation as (...each: unknown[]) => unknown).apply(connection, args)
+                : undefined;
+            };
+          }
+          return Reflect.get(target, key, receiver);
+        },
+      }) as unknown as DisplayHandle<C>;
+    },
+  };
+}

package/src/host/locate.ts

@@ -0,0 +1,25 @@
+import type { PortholeConfig } from "../config/schema.ts";
+import { checkFrameLocation } from "../isolation/served.ts";
+import type { FrameSource, InstanceLocator, InstanceRef } from "../isolation/types.ts";
+
+/**
+ * Where a served frame (domain or external isolation) loads from: the host's locator answers, and
+ * `checkFrameLocation` checks the answer (one of the config's content origins, never the host's
+ * own site) before any frame is made.
+ */
+export async function locateServed(
+  locator: InstanceLocator,
+  instance: InstanceRef,
+  config: PortholeConfig,
+  hostOrigin: string,
+  signal?: AbortSignal,
+): Promise<FrameSource> {
+  const location = await locator.locate(instance, signal);
+  checkFrameLocation(location, config.contentOrigins, hostOrigin);
+  return {
+    kind: "url",
+    url: new URL(location.url).href,
+    origin: location.origin,
+    ...(location.reports === true ? { reports: true } : {}),
+  };
+}

package/src/host/outcome.ts

@@ -0,0 +1,159 @@
+import { FRAME_STATUS_METHOD, type FrameSource } from "../isolation/types.ts";
+import type { Surface } from "../platform/types.ts";
+import type { FrameBlock, FrameOutcome } from "./types.ts";
+
+/**
+ * How a display's first document went (P040). A frame's content is another origin's, so the host
+ * can't look inside; it goes by what it can see:
+ *
+ * - a shell or view that speaks for itself is loaded when it finishes its handshake;
+ * - a page of Porthole's `/server` says how it went (`porthole/notifications/frame-status`): it is
+ *   entering an app, or blocked (its ticket used, no cookie kept in a frame, the app down); a url
+ *   app is loaded when its document loads after the entry page;
+ * - a load from which nothing ever spoke, where something should have, is a page that never ran:
+ *   framing refused;
+ * - an app from a host's own gateway is loaded on its first load, unless its page says it is
+ *   blocked (the gateway may send the same message);
+ * - nothing settled in `timeoutMs`: a timeout.
+ */
+
+/** How long after a load the frame's word may still arrive. */
+const SETTLE_MS = 400;
+
+const BLOCKS: readonly FrameBlock[] = [
+  "framing",
+  "cookies",
+  "session",
+  "upstream",
+  "not-found",
+  "error",
+];
+
+interface FrameStatus {
+  readonly state: "entering" | "blocked";
+  readonly reason?: FrameBlock;
+  readonly status?: number;
+}
+
+/** A frame-status message, or null for anything else. */
+export function parseFrameStatus(data: unknown): FrameStatus | null {
+  if (data === null || typeof data !== "object") {
+    return null;
+  }
+  const message = data as { jsonrpc?: unknown; method?: unknown; params?: unknown };
+  if (message.jsonrpc !== "2.0" || message.method !== FRAME_STATUS_METHOD) {
+    return null;
+  }
+  const params = message.params as { state?: unknown; reason?: unknown; status?: unknown } | null;
+  if (params === null || typeof params !== "object") {
+    return null;
+  }
+  if (params.state === "entering") {
+    return { state: "entering" };
+  }
+  if (params.state !== "blocked") {
+    return null;
+  }
+  const reason = BLOCKS.includes(params.reason as FrameBlock)
+    ? (params.reason as FrameBlock)
+    : "error";
+  return {
+    state: "blocked",
+    reason,
+    ...(typeof params.status === "number" && Number.isInteger(params.status)
+      ? { status: params.status }
+      : {}),
+  };
+}
+
+export interface OutcomeWatch {
+  /** The frame finished its handshake. */
+  initialized(): void;
+  stop(): void;
+}
+
+export function watchOutcome(options: {
+  readonly surface: Surface;
+  readonly source: FrameSource;
+  /** Whether the frame speaks for itself (a shell or a view): then its handshake is the proof. */
+  readonly speaks: boolean;
+  readonly timeoutMs: number;
+  readonly onOutcome: (outcome: FrameOutcome) => void;
+}): OutcomeWatch {
+  const { surface, source, speaks } = options;
+  const reports = source.kind === "url" && source.reports === true;
+  let decided = false;
+  let heard = false;
+  let entering = false;
+  let loads = 0;
+  const timers = new Set<ReturnType<typeof setTimeout>>();
+  const later = (ms: number, run: () => void) => {
+    const timer = setTimeout(() => {
+      timers.delete(timer);
+      run();
+    }, ms);
+    timers.add(timer);
+  };
+  const stop = () => {
+    for (const timer of timers) {
+      clearTimeout(timer);
+    }
+    timers.clear();
+    unlisten();
+    unload();
+  };
+  const decide = (outcome: FrameOutcome) => {
+    if (!decided) {
+      decided = true;
+      stop();
+      options.onOutcome(outcome);
+    }
+  };
+  const unlisten = surface.transport.listen((data) => {
+    heard = true;
+    const status = parseFrameStatus(data);
+    if (status?.state === "entering") {
+      entering = true;
+    } else if (status?.state === "blocked") {
+      decide({
+        state: "blocked",
+        reason: status.reason ?? "error",
+        ...(status.status === undefined ? {} : { status: status.status }),
+      });
+    }
+  });
+  const neverRan = () =>
+    later(SETTLE_MS, () => {
+      if (!heard) {
+        decide({ state: "blocked", reason: "framing" });
+      }
+    });
+  const unload = surface.onLoad(() => {
+    loads += 1;
+    if (decided) {
+      return;
+    }
+    if (speaks) {
+      // A served shell or view says something before its first load ends; one that never did
+      // never ran. (An opaque srcdoc frame always runs: its handshake decides.)
+      if (source.kind === "url") {
+        neverRan();
+      }
+      return;
+    }
+    if (!reports) {
+      later(SETTLE_MS, () => decide({ state: "loaded" }));
+      return;
+    }
+    if (entering && loads >= 2) {
+      decide({ state: "loaded" });
+    } else if (!entering) {
+      neverRan();
+    }
+  });
+  later(options.timeoutMs, () => decide({ state: "timeout" }));
+  return {
+    initialized: () => decide({ state: "loaded" }),
+    stop,
+  };
+}

package/src/host/types.ts

@@ -0,0 +1,126 @@
+import type { Confirm, CapabilityHandlers, Refusal } from "../bridge/types.ts";
+import type { CompiledConfig } from "../compile/compile.ts";
+import type { CapabilityName } from "../config/capabilities.ts";
+import type { ColorScheme } from "../config/schema.ts";
+import type { InstanceLocator, InstanceRef } from "../isolation/types.ts";
+import type { PlatformHost } from "../platform/types.ts";
+import type { AdapterConnection, ProtocolAdapter, ShellConnection } from "../protocol/adapter.ts";
+import type { HostContext } from "../protocol/mcp-apps.ts";
+
+/**
+ * The host-side API (framework-agnostic; the web platform by default). A host compiles a config
+ * once (`createHost`), then mounts a display per piece of content. Everything here is mechanism;
+ * the host passes policy: its handlers, who confirms, its theme values.
+ */
+
+export interface HostOptions<C extends AdapterConnection = ShellConnection> {
+  /** Handlers for the declared capabilities; a mount may pass its own over these. */
+  readonly handlers?: CapabilityHandlers;
+  /** Who confirms `confirm`-gated calls. Absent: those calls are refused. */
+  readonly confirm?: Confirm;
+  /**
+   * The host's live values for the config's theme variables, for `scheme` (read from its own
+   * design tokens). A name it leaves out, or answers empty, gets the config's default.
+   */
+  readonly theme?: (scheme: ColorScheme) => Readonly<Record<string, string | null | undefined>>;
+  /** The host's own context fields (locale, time zone, platform): merged into the host context. */
+  readonly hostContext?: () => Partial<HostContext>;
+  /** How the host names itself in the handshake. */
+  readonly hostInfo?: { readonly name: string; readonly version: string };
+  /** The protocol adapter. Default: the core's shell adapter (inline and artifact modes). */
+  readonly adapter?: ProtocolAdapter<C>;
+  /** The platform host. Default: the web's iframe host. */
+  readonly platform?: PlatformHost;
+  /** Required for domain and external isolation: where an instance's frame loads from. */
+  readonly locator?: InstanceLocator;
+}
+
+export interface MountOptions {
+  /** The host's id for this display: what its height is remembered by, and calls name. */
+  readonly displayId: string;
+  /** The display's accessible name and the title its confirmations show (the host's words). */
+  readonly title: string;
+  readonly scheme: ColorScheme;
+  /** Handlers for this display only, over the host's. */
+  readonly handlers?: CapabilityHandlers;
+  /** Domain and external isolation: the instance to locate. */
+  readonly instance?: InstanceRef;
+  /** A whole document the frame starts with (an MCP Apps view), hardened by the shell. */
+  readonly document?: string;
+  /** The height to start at, before the content reports its own. */
+  readonly initialHeightPx?: number;
+}
+
+/** What a display reports, by event name. */
+/** Why a display's frame showed nothing of its content (`FrameOutcome`). */
+export type FrameBlock =
+  /** The page that frames it isn't one its server allows (frame-ancestors), or it never ran. */
+  | "framing"
+  /** The browser keeps no cookie for it inside a frame (WebKit, P025): open it on a tab. */
+  | "cookies"
+  /** Its ticket was used or its session ended. */
+  | "session"
+  /** Its app didn't answer. */
+  | "upstream"
+  | "not-found"
+  | "error";
+
+/**
+ * How a display's first document went, once per run: it loaded (a shell or view finished its
+ * handshake; a url-mode app's document loaded), it was blocked (and why), or nothing settled in
+ * `limits.loadTimeoutMs`. A host shows its own fallback ("Open in a new tab") on anything but
+ * loaded.
+ */
+export type FrameOutcome =
+  | { readonly state: "loaded" }
+  | { readonly state: "blocked"; readonly reason: FrameBlock; readonly status?: number }
+  | { readonly state: "timeout" };
+
+export interface DisplayEvents {
+  /** The frame finished its handshake (url mode, which has none: its first document loaded). */
+  readonly initialized: undefined;
+  /** How the frame's first document went (`FrameOutcome`). */
+  readonly outcome: FrameOutcome;
+  /** The content's size, after the config's limits. */
+  readonly resize: { readonly height: number; readonly width?: number };
+  /** What the content threw, or what the sandbox blocked (its own words: untrusted). */
+  readonly error: { readonly message: string };
+  /** The content navigated its frame away; the frame was started again from its content. */
+  readonly navigated: undefined;
+  /** A call didn't run. */
+  readonly refused: { readonly capability: CapabilityName; readonly refusal: Refusal };
+  /** Too many declines: the display stops asking until it runs again. */
+  readonly muted: undefined;
+}
+
+export interface DisplayControls {
+  readonly displayId: string;
+  /**
+   * The theme flipped: the frame is re-themed in place, without a reload. The host's values are
+   * read two animation frames later, once a host that restyles its page asynchronously has.
+   */
+  setTheme(scheme: ColorScheme): void;
+  /** The host's theme values changed (same scheme): read them now and re-theme the frame. */
+  refreshTheme(): void;
+  on<E extends keyof DisplayEvents>(
+    event: E,
+    listener: (detail: DisplayEvents[E]) => void,
+  ): () => void;
+  /** Runs the content again from the start, in a new frame. */
+  reload(): void;
+  /** Tears the view down and removes the frame. */
+  destroy(): void;
+}
+
+/** A mounted display: the framework's controls plus the adapter's own operations. */
+export type DisplayHandle<C extends AdapterConnection = ShellConnection> = DisplayControls &
+  Omit<C, keyof AdapterConnection>;
+
+export interface PortholeHost<C extends AdapterConnection = ShellConnection> {
+  readonly compiled: CompiledConfig;
+  /**
+   * Creates a display in `container`. Throws if a declared capability served by a handler has
+   * none (here or in the host's options), so a manual never teaches a function nobody serves.
+   */
+  mount(container: HTMLElement, options: MountOptions): DisplayHandle<C>;
+}