@saga-a2ui/react-mcp-stack 0.0.0-stage → 0.7.6

package/src/faithful-card/start-faithful-card-app.tsx

@@ -0,0 +1,288 @@
+import {
+  readCardResult,
+  type CardResultOutcome,
+  type FaithfulCardAppDefinition,
+} from '@saga-a2ui/components/faithful-card';
+import type { HostContext, ToolResult } from '@saga-a2ui/mcp/view';
+import {
+  deliveredResultFromToolResult,
+  hostLinksFromApp,
+} from '@saga-a2ui/mcp/view';
+import {
+  createFaithfulCardView,
+  FaithfulCardProvider,
+  FaithfulCardSurface,
+  openFaithfulCardSurface,
+  type CardSurface,
+  type FaithfulCardView,
+} from '@saga-a2ui/react/faithful-card';
+import {
+  createElement,
+  Fragment,
+  useSyncExternalStore,
+  type ComponentType,
+  type ReactElement,
+} from 'react';
+import { claimContainer } from '../container-claim.js';
+import { connectToHost, type HostConnection } from '../host-connection.js';
+import { openStackRoot } from '../initial-render.js';
+import {
+  runView,
+  viewFailedBeforeConnecting,
+  viewThatNeverStarted,
+  type RunningView,
+} from '../running-view.js';
+import { StartFailure, type ErrorPhase } from '../start-failure.js';
+import {
+  contentPolicyFromDocument,
+  documentContentSecurityPolicies,
+} from './document-policy.js';
+
+/** What the application’s chrome is told about the card, and what to say beside it. */
+export type CardViewState =
+  | { readonly kind: 'waiting'; readonly text: string }
+  | {
+      readonly kind: 'answer';
+      readonly heading: string | undefined;
+      /** Advances with every presented answer, including one whose text equals the last. */
+      readonly presentation: number;
+    }
+  | { readonly kind: 'problem'; readonly text: string };
+
+/** What the chrome component receives: the card to place, and the state to word around it. */
+export interface CardChromeProps {
+  /** The card. Place it exactly once; it is empty until the first answer. */
+  readonly card: ReactElement;
+  readonly state: CardViewState;
+}
+
+export interface StartFaithfulCardOptions {
+  /** The element the view is rendered into. Must be attached to the document and free. */
+  readonly container: Element;
+  /** `own`: the view tells the host its size. `host`: the bridge reports it. */
+  readonly sizing: 'own' | 'host';
+  /** Optional. Work the view needs before it shows anything (for example fonts); `signal` aborts when the view ends. */
+  readonly readyWhen?: (signal: AbortSignal) => Promise<void>;
+  /** Optional. The negotiated host context and the host’s name, before the first answer and on change. */
+  readonly hostContext?: (
+    context: HostContext | undefined,
+    hostName: string | undefined,
+  ) => void;
+  /** Optional. The application’s chrome around the card. By default the status text, then the card. */
+  readonly chrome?: ComponentType<CardChromeProps>;
+  /** Optional. Receives a throw from a callback after the view was ready. Defaults to `console.error`. */
+  readonly onError?: (error: unknown, phase: ErrorPhase) => void;
+}
+
+const DefaultChrome = (props: CardChromeProps): ReactElement => {
+  const { state } = props;
+  return createElement(
+    Fragment,
+    null,
+    state.kind === 'answer'
+      ? state.heading === undefined
+        ? null
+        : createElement('h2', null, state.heading)
+      : createElement('p', { role: 'status' }, state.text),
+    props.card,
+  );
+};
+
+/** The state the chrome renders, readable by React and settable by the stack. */
+function createStateStore(initial: CardViewState) {
+  let current = initial;
+  const listeners = new Set<() => void>();
+  return {
+    set(next: CardViewState): void {
+      current = next;
+      for (const listener of [...listeners]) listener();
+    },
+    get: (): CardViewState => current,
+    subscribe(listener: () => void): () => void {
+      listeners.add(listener);
+      return () => void listeners.delete(listener);
+    },
+  };
+}
+type StateStore = ReturnType<typeof createStateStore>;
+
+function CardApp(props: {
+  readonly view: FaithfulCardView | undefined;
+  readonly card: CardSurface | undefined;
+  readonly store: StateStore;
+  readonly Chrome: ComponentType<CardChromeProps>;
+}): ReactElement {
+  const state = useSyncExternalStore(props.store.subscribe, props.store.get);
+  const { view, card, Chrome } = props;
+  const cardElement =
+    card === undefined
+      ? createElement(Fragment)
+      : createElement(FaithfulCardSurface, { of: card });
+  const chrome = createElement(Chrome, { card: cardElement, state });
+  return view === undefined
+    ? chrome
+    : createElement(FaithfulCardProvider, { view, children: chrome });
+}
+
+/**
+ * Starts a card application in `options.container` and returns it at once. The embedded policy is
+ * read from the container’s document, the host is connected with its handlers installed first,
+ * and each delivered result is read by the definition’s one `result` reader and shown in the card: a new
+ * presentation each time, even for equal text. Throws `StartError` (`container-missing`,
+ * `container-busy`) before connecting to anything. The first render happens before the host is
+ * connected: a `chrome` that throws in it does not throw out of `start`, it fails startup (`ready`
+ * rejects with `StartFailure` of kind `application`) after the stack took back what it made and
+ * freed the container. A throw in a later render goes to `onError` with phase
+ * `result`, the render a delivered result caused (default `console.error`); `ready` stays resolved.
+ */
+export function startFaithfulCardApp(
+  definition: FaithfulCardAppDefinition,
+  options: StartFaithfulCardOptions,
+): RunningView {
+  return startFaithfulCardAppOn(
+    () => connectToHost(definition.identity, options.sizing),
+    definition,
+    options,
+  );
+}
+
+/** {@link startFaithfulCardApp} over a connection the caller supplies: the seam the stack’s own tests use. */
+export function startFaithfulCardAppOn(
+  connect: () => HostConnection,
+  definition: FaithfulCardAppDefinition,
+  options: StartFaithfulCardOptions,
+): RunningView {
+  const claim = claimContainer(options.container);
+  let root: ReturnType<typeof openStackRoot> | undefined;
+  try {
+    const { texts } = definition;
+    const Chrome = options.chrome ?? DefaultChrome;
+    const store = createStateStore({ kind: 'waiting', text: texts.waiting });
+    const mounted = (root = openStackRoot(claim.container, options.onError));
+    const unmount = (): void => mounted.root.unmount();
+    /** The first render, now: the chrome is the application's, and a throw in it fails the start. */
+    const renderInitially = (view?: FaithfulCardView, card?: CardSurface) =>
+      mounted.renderInitially(
+        createElement(CardApp, { view, card, store, Chrome }),
+      );
+
+    const policy = contentPolicyFromDocument(claim.container.ownerDocument);
+    if (!policy.ok) {
+      store.set({ kind: 'problem', text: texts.policyFailure });
+      const failed = renderInitially();
+      if (failed !== undefined) {
+        // The chrome threw while showing why the start failed: that is the failure to report.
+        unmount();
+        claim.release();
+        return viewThatNeverStarted(failed.cause);
+      }
+      return viewFailedBeforeConnecting({
+        failure: new StartFailure('policy', policy.failure),
+        unmount,
+        releaseContainer: claim.release,
+        ...(options.onError === undefined ? {} : { onError: options.onError }),
+      });
+    }
+
+    const connection = connect();
+    const lifetime = new AbortController();
+    const view = createFaithfulCardView({
+      ...definition.reader,
+      policy: policy.policy,
+      contentSecurityPolicies: documentContentSecurityPolicies(
+        claim.container.ownerDocument,
+      ),
+      hostLinks: hostLinksFromApp(connection.app, lifetime.signal),
+    });
+    const card = openFaithfulCardSurface();
+    const failed = renderInitially(view, card);
+    if (failed !== undefined) {
+      // The chrome threw on its first render. Nothing connected: take back what this start made.
+      lifetime.abort();
+      view.consent.retire();
+      card.dispose();
+      unmount();
+      claim.release();
+      return viewThatNeverStarted(failed.cause);
+    }
+
+    const report =
+      options.onError ?? ((error: unknown) => console.error(error));
+    let presentation = 0;
+    const problem = (text: string): void => {
+      card.clear();
+      store.set({ kind: 'problem', text });
+    };
+    /**
+     * The definition's one reader decides what the whole result means. A throw from the reader or
+     * from mapping the delivery's result is reported (phase `result`) and rejects the result.
+     */
+    const read = (result: ToolResult): CardResultOutcome =>
+      readCardResult(
+        definition,
+        () => deliveredResultFromToolResult(result),
+        (error) => {
+          try {
+            report(error, 'result');
+          } catch {
+            // A reporter that throws must not stop the answer from clearing.
+          }
+        },
+      );
+
+    return runView({
+      connection,
+      lifetime,
+      releaseContainer: claim.release,
+      sizing: options.sizing,
+      ...(options.readyWhen === undefined
+        ? {}
+        : { readyWhen: options.readyWhen }),
+      ...(options.hostContext === undefined
+        ? {}
+        : { hostContext: options.hostContext }),
+      // Every result is a new selection: `present` ends the earlier presentation, image consent
+      // included, even when the Markdown equals the previous one.
+      onToolResult(result) {
+        const outcome = read(result);
+        if (outcome.kind === 'rejected') {
+          // The application's wording for this rejection, else the definition's.
+          problem(outcome.text ?? texts.problem);
+          return;
+        }
+        if (!card.present(outcome.content).ok) {
+          problem(texts.problem);
+          return;
+        }
+        presentation += 1;
+        store.set({
+          kind: 'answer',
+          heading: outcome.content.heading,
+          presentation,
+        });
+      },
+      ...(options.onError === undefined ? {} : { onError: options.onError }),
+      retire() {
+        view.consent.retire();
+        card.dispose();
+      },
+      unmount,
+      showFailure(failure) {
+        const text = {
+          policy: texts.policyFailure,
+          connect: texts.connectFailure,
+          ready: texts.readyFailure,
+          application: texts.problem,
+          disposed: texts.problem,
+        }[failure.kind];
+        store.set({ kind: 'problem', text });
+        return true;
+      },
+    });
+  } catch (error) {
+    // Nothing connected: take back what this start rendered and free the container.
+    root?.root.unmount();
+    claim.release();
+    throw error;
+  }
+}

package/src/host-connection.ts

@@ -0,0 +1,39 @@
+import { App, PostMessageTransport } from '@modelcontextprotocol/ext-apps';
+
+/**
+ * The two halves of a connection to the MCP Apps host: the bridge and the transport it will connect
+ * over. Making them is the stack’s job so that no application imports the bridge package; a start
+ * takes the pair as a value so a test can supply a bridge joined to an in-memory host.
+ */
+export interface HostConnection {
+  readonly app: App;
+  readonly transport: NonNullable<Parameters<App['connect']>[0]>;
+}
+
+/** What a server tool call answers: the reply type of the bridge’s own `callServerTool`. */
+export type ServerReply = Awaited<ReturnType<App['callServerTool']>>;
+
+export interface HostIdentity {
+  readonly name: string;
+  readonly version: string;
+}
+
+/**
+ * The connection a view uses in a host’s iframe: a bridge named for the application and the
+ * `postMessage` transport to the embedding window. With `own` sizing the view tells the host its
+ * size itself (`startOwnSizing`), so the bridge’s automatic resizing is turned off and sizing has
+ * exactly one owner.
+ */
+export function connectToHost(
+  identity: HostIdentity,
+  sizing: 'own' | 'host',
+): HostConnection {
+  return {
+    app: new App(
+      { name: identity.name, version: identity.version },
+      {},
+      sizing === 'own' ? { autoResize: false } : undefined,
+    ),
+    transport: new PostMessageTransport(window.parent, window.parent),
+  };
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+// The React and MCP Apps stack, main entry: an application's own catalog and nothing else. It
+// imports nothing from `@saga-a2ui/components`, so an own-catalog application's emitted browser
+// bundle holds neither the FaithfulCard nor a Markdown parser. (Its installed tree does include
+// them, as declared dependencies of the stack; the card application's entry is `/faithful-card`.)
+//
+// An application that installs this stack and React writes its view, its catalog and its actions
+// against the names below and declares no other SDK or upstream package for them. The list is
+// what the qualifying consumers use, no more.
+export {
+  startA2uiView,
+  type RunningA2uiView,
+  type StartA2uiViewOptions,
+  type ViewHost,
+} from './start-a2ui-view.js';
+// What a start can fail with and the phase an `onError` callback is told; the card entry shares them.
+export {
+  StartError,
+  StartFailure,
+  type ErrorPhase,
+  type StartFailureKind,
+  type StartMisuse,
+} from './start-failure.js';
+export type { RunningView } from './running-view.js';
+// The shapes of the two notifications an application's handlers receive.
+export type { ToolInput, ToolResult } from '@saga-a2ui/mcp/view';
+// How the reader meets the host (device or desktop), for an application that maps its own tokens.
+export { readingProfile, type ReadingProfile } from '@saga-a2ui/mcp/view';
+// The authoring surface of an own-catalog application: the layout and its schemas.
+export { defineSurface } from '@saga-a2ui/core/protocols/a2ui/v0_9';
+export type { SurfaceLayout } from '@saga-a2ui/core/protocols/a2ui/v0_9';
+export { z } from '@saga-a2ui/core/protocols/a2ui/zod3';
+// The catalog an application builds: its components over upstream's component contracts, kept in
+// the renderer package's own dependency context.
+export {
+  Catalog,
+  ColumnApi,
+  CommonSchemas,
+  createComponentImplementation,
+  ListApi,
+  RowApi,
+  type ReactCatalogComponent,
+} from '@saga-a2ui/react/a2ui';
+// The actions an application attaches to the controls it renders.
+export {
+  ActionButton,
+  ActionButtonEntry,
+  createReactActions,
+  type ActionButtonActivation,
+  type ReactActions,
+  type ReactActionsOptions,
+} from '@saga-a2ui/react/actions';
+export { Action, type ActionBinding } from '@saga-a2ui/core/actions';
+export type { BoundSurface } from '@saga-a2ui/react/a2ui';

package/src/initial-render.ts

@@ -0,0 +1,61 @@
+import type { ReactNode } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { flushSync } from 'react-dom';
+import type { ErrorPhase } from './start-failure.js';
+
+// A view's first render is part of starting it: the application's chrome or catalog components
+// run in it, and a throw there is an application callback that threw during startup. React reports
+// such a throw asynchronously (to `window` by default) and unmounts the tree, so left alone the
+// view would be "ready" with nothing on screen. This renders the first tree synchronously and
+// hands the throw back, so the caller can end the start as `StartFailure('application')` after
+// its own cleanup.
+//
+// A throw in a later render (the chrome or a component rendering a result) is an application
+// callback that threw after the view was ready: it goes to the view's `onError` with phase
+// `result`, the render that the delivered result caused. React still unmounts the tree it could
+// not render, and nothing the application already changed is rolled back.
+
+export interface StackRoot {
+  readonly root: Root;
+  /**
+   * Renders `tree` now. Returns the throw that React reported while doing so, if any; the root
+   * is then empty and the caller owns the cleanup.
+   */
+  renderInitially(tree: ReactNode): { readonly cause: unknown } | undefined;
+}
+
+export function openStackRoot(
+  container: Element,
+  onError: ((error: unknown, phase: ErrorPhase) => void) | undefined,
+): StackRoot {
+  let initial: { readonly cause: unknown } | undefined;
+  let rendering = false;
+  const root = createRoot(container, {
+    onUncaughtError(error) {
+      if (rendering) {
+        initial ??= { cause: error };
+        return;
+      }
+      try {
+        (onError ?? ((reported: unknown) => console.error(reported)))(
+          error,
+          'result',
+        );
+      } catch {
+        // A reporter that throws must not break React's own cleanup of the failed tree.
+      }
+    },
+  });
+  return {
+    root,
+    renderInitially(tree) {
+      rendering = true;
+      try {
+        flushSync(() => root.render(tree));
+      } finally {
+        rendering = false;
+      }
+      return initial;
+    },
+  };
+}

package/src/running-view.ts

@@ -0,0 +1,221 @@
+import {
+  runToolResultView,
+  startOwnSizing,
+  ViewStartFailure,
+  type HostContext,
+  type ToolInput,
+  type ToolResult,
+} from '@saga-a2ui/mcp/view';
+import { applicationFailureOf } from './application-call.js';
+import type { HostConnection } from './host-connection.js';
+import { StartFailure, type ErrorPhase } from './start-failure.js';
+
+// What both entries of the stack share once they have something to show: one view in one container
+// whose lifetime is `runToolResultView`'s. It adds what is the stack’s alone: the typed failure,
+// own sizing that starts only once the host can be told, the claim on the container, and when a
+// view that has ended leaves the screen. It decides nothing about what is shown.
+
+/** The handle both entries return, synchronously. */
+export interface RunningView {
+  /**
+   * Settles when the embedded policy was valid, the host connected with the handlers installed
+   * first, the latest host context was applied and the application's readiness work finished.
+   * Rejects with a {@link StartFailure} otherwise. Ignoring it never causes an unhandled rejection.
+   */
+  readonly ready: Promise<void>;
+  /**
+   * Ends the view and removes what it showed, whatever state it is in: ready, still starting, or
+   * failed (a failed view keeps its failure text on screen until it is disposed). Idempotent;
+   * settles after cleanup and never rejects. Afterwards the container may be started again.
+   */
+  dispose(): Promise<void>;
+}
+
+export interface RunViewOptions {
+  readonly connection: HostConnection;
+  /** Aborts when the view ends. Anything the view started for the host (links, sizing) listens to it. */
+  readonly lifetime: AbortController;
+  /** Frees the container; called once, after `unmount`. */
+  readonly releaseContainer: () => void;
+  readonly sizing: 'own' | 'host';
+  readonly readyWhen?: (signal: AbortSignal) => Promise<void>;
+  readonly hostContext?: (
+    context: HostContext | undefined,
+    hostName: string | undefined,
+  ) => void;
+  /** Called for each delivered result once the view is ready (the held one at that moment). */
+  readonly onToolResult: (result: ToolResult) => void;
+  /** Called for the tool call that is starting, once the view is ready and before the held result. */
+  readonly onToolInput?: (input: ToolInput) => void;
+  readonly onError?: (error: unknown, phase: ErrorPhase) => void;
+  /** The first step of ending, once, before the connection ends: retire consent and the surface. */
+  readonly retire: () => void;
+  /** Removes everything the view rendered. Called once. */
+  readonly unmount: () => void;
+  /**
+   * Shows why the view did not start. Returns true when the failure is now on screen, which keeps
+   * the view mounted until it is disposed. Not asked for `disposed`, which shows nothing.
+   */
+  readonly showFailure?: (failure: StartFailure) => boolean;
+}
+
+function startFailureOf(failure: unknown): StartFailure {
+  if (failure instanceof ViewStartFailure) {
+    // Readiness work the stack itself holds for an application callback (the action setup).
+    const own = applicationFailureOf(failure.cause);
+    return own === undefined
+      ? new StartFailure(failure.kind, failure.cause)
+      : new StartFailure('application', own.cause);
+  }
+  return new StartFailure('application', failure);
+}
+
+export function runView(options: RunViewOptions): RunningView {
+  const { app, transport } = options.connection;
+  const report = options.onError ?? ((error: unknown) => console.error(error));
+  let onScreen = true;
+  let failureShown = false;
+  let sizingStarted = false;
+
+  const reportError = (error: unknown, phase: ErrorPhase): void => {
+    try {
+      report(error, phase);
+    } catch {
+      // A reporter that throws must not stop cleanup.
+    }
+  };
+
+  /** The view is gone from the screen: unmount, then free the container, whatever unmount did. */
+  const leave = (): void => {
+    if (!onScreen) return;
+    onScreen = false;
+    try {
+      options.unmount();
+    } finally {
+      options.releaseContainer();
+    }
+  };
+
+  const running = runToolResultView({
+    app,
+    transport,
+    ...(options.readyWhen === undefined
+      ? {}
+      : { readyWhen: options.readyWhen }),
+    onToolResult: options.onToolResult,
+    ...(options.onToolInput === undefined
+      ? {}
+      : { onToolInput: options.onToolInput }),
+    onHostContext(context, hostName) {
+      // Told only once the host can hear it: sizing before the handshake would be dropped, and the
+      // size it measured would then count as sent.
+      if (options.sizing === 'own' && !sizingStarted) {
+        sizingStarted = true;
+        startOwnSizing(app, options.lifetime.signal);
+      }
+      options.hostContext?.(context, hostName);
+    },
+    onTeardown(startupFailure) {
+      options.lifetime.abort();
+      const failures: unknown[] = [];
+      try {
+        options.retire();
+      } catch (error) {
+        failures.push(error);
+      }
+      // Whatever ended the view, nothing it showed may outlast its connection. Only a start that
+      // failed keeps something on screen: the failure, which is known only after the connection
+      // has ended (see below).
+      if (startupFailure === undefined) {
+        try {
+          leave();
+        } catch (error) {
+          reportError(error, 'teardown');
+        }
+      }
+      queueMicrotask(() => {
+        void running.dispose().then(() => {
+          if (!failureShown) {
+            try {
+              leave();
+            } catch (error) {
+              reportError(error, 'teardown');
+            }
+          }
+        });
+      });
+      // Every step ran; the runner reports the first thing that threw and still ends the connection.
+      if (failures.length > 0) throw failures[0];
+    },
+    onFailure(failure) {
+      const startFailure = startFailureOf(failure);
+      if (startFailure.kind !== 'disposed')
+        failureShown = options.showFailure?.(startFailure) ?? false;
+    },
+    onError: options.onError ?? ((error, phase) => reportError(error, phase)),
+  });
+
+  const readiness = running.ready.then(
+    () => undefined,
+    (failure: unknown) => {
+      throw startFailureOf(failure);
+    },
+  );
+  readiness.catch(() => undefined);
+
+  return {
+    ready: readiness,
+    async dispose() {
+      await running.dispose();
+      try {
+        leave();
+      } catch (error) {
+        reportError(error, 'teardown');
+      }
+    },
+  };
+}
+
+/**
+ * The view of a start that failed before it connected to anything (an invalid embedded policy):
+ * its failure is already on screen, `ready` rejects with it, and disposing it removes it.
+ */
+export function viewFailedBeforeConnecting(options: {
+  readonly failure: StartFailure;
+  readonly unmount: () => void;
+  readonly releaseContainer: () => void;
+  readonly onError?: (error: unknown, phase: ErrorPhase) => void;
+}): RunningView {
+  let onScreen = true;
+  const ready = Promise.reject<void>(options.failure);
+  ready.catch(() => undefined);
+  return {
+    ready,
+    async dispose() {
+      if (!onScreen) return;
+      onScreen = false;
+      try {
+        options.unmount();
+      } catch (error) {
+        try {
+          (options.onError ?? ((e) => console.error(e)))(error, 'teardown');
+        } catch {
+          // Nothing more to do for a reporter that throws.
+        }
+      } finally {
+        options.releaseContainer();
+      }
+    },
+  };
+}
+
+/**
+ * The view of a start whose application callback threw before anything ran: the stack already took
+ * back what it had made and freed the container, so `ready` rejects with the failure and there is
+ * nothing left to dispose.
+ */
+export function viewThatNeverStarted(cause: unknown): RunningView {
+  const ready = Promise.reject<void>(new StartFailure('application', cause));
+  ready.catch(() => undefined);
+  return { ready, dispose: () => Promise.resolve() };
+}

package/src/server/index.ts

@@ -0,0 +1,14 @@
+// The server entry of the stack: what an application's MCP server composes to serve a card or an
+// own-catalog view, from the same package it installs for the view. It re-exports the delivery
+// owner's named operations and nothing from a renderer, `@saga-a2ui/components` or the browser
+// entries, so a server never loads a renderer and a browser bundle never loads a server module.
+// The operations, their failures and their lifetimes are specified in `@saga-a2ui/mcp/server`.
+export {
+  attachRequestLifetime,
+  createServerBudgets,
+  operationViewFromHtml,
+  registerPublicOperation,
+  viewUriForHtml,
+  type OperationView,
+  type RequestLifetime,
+} from '@saga-a2ui/mcp/server';