@mostra/react 0.0.0-stage → 0.2.0

package/src/server-hooks.ts

@@ -0,0 +1,291 @@
+"use client";
+
+/**
+ * Server functions and live data in the page (INTERFACES §2.3, D54, D56): `useAction` turns calls
+ * of a `"use server"` function into durable action runs, and `useLive` reads a live source. Both
+ * share the page's runtime, its view and its event stream, so a run started in one tab or before a
+ * reload is followed the same way, and every component showing one source shares one value.
+ */
+import { isFinalRunStatus, type RunProgress, type RunStatus } from "@mostra/protocol";
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { useStore } from "./hooks.ts";
+import { MostraError } from "./runtime/errors.ts";
+import { serverFunctionId } from "./runtime/server-client.ts";
+
+// ── useAction ─────────────────────────────────────────────────────────────────────────────
+
+/** What `useAction` shows of its run (INTERFACES §2.3). */
+export interface ActionHandle<A extends unknown[], R> {
+  /**
+   * Runs the action: a durable run (D24) whose result this resolves with, or whose failure it
+   * rejects with as a `MostraError`. While this hook's run is in flight, another call joins it; with
+   * a `key`, every call anywhere joins the one run of that key, so it happens at most once.
+   */
+  run(...args: A): Promise<R>;
+  /**
+   * `idle` before any run, then the run's state. `waiting` is reserved for a run waiting for its
+   * owner's instance (a hosted artifact, WP-28).
+   */
+  readonly status: "idle" | RunStatus;
+  /** Whether a run is starting or in flight. */
+  readonly isPending: boolean;
+  /** The result, once the run succeeded. */
+  readonly data?: R;
+  /** Why the run failed, was cancelled or couldn't start. */
+  readonly error?: { readonly code: string; readonly message: string };
+  /** The run's latest progress (`progress()` in the action). */
+  readonly progress?: RunProgress;
+  /** The run's log lines (`log()` and the console in the action), capped at 1 MB. */
+  readonly log: readonly string[];
+  /** For an action that returns an async iterable: the items it yielded so far. */
+  readonly partial: readonly (R extends AsyncIterable<infer T> ? T : unknown)[];
+  /** Cancels the run: the action's `abortSignal` fires (AC-04). */
+  cancel(): void;
+  /** The run's `run_` ID, once it has one. */
+  readonly runId?: string;
+}
+
+const NO_LOG: readonly string[] = [];
+
+/** What `useAction` knows of one function and key. */
+interface IdentityState {
+  readonly runId?: string | undefined;
+  readonly starting: boolean;
+  readonly startError?: { code: string; message: string } | undefined;
+}
+
+const IDLE: IdentityState = { starting: false };
+const NO_STATES: ReadonlyMap<string, IdentityState> = new Map();
+
+/**
+ * Runs a `"use server"` function as durable action runs (D24, D54): each call is recorded before
+ * it runs, streams progress, log lines and partial results, survives the tab closing, and is
+ * found again after a reload. Without a `key`, a call while this hook's run is in flight joins it,
+ * so a double click runs once; with a `key`, the run of that key happens at most once across
+ * clicks, tabs, reloads and devices, and a page that opens later shows it.
+ *
+ * ```tsx
+ * const send = useAction(sendReply, { key: `send.${message.id}` });
+ * <button disabled={send.isPending || send.status === "succeeded"} onClick={() => send.run(message.id, reply)}>
+ *   {send.status === "succeeded" ? "Sent" : (send.progress?.message ?? "Send")}
+ * </button>
+ * ```
+ */
+export function useAction<A extends unknown[], R>(
+  fn: (...args: A) => Promise<R>,
+  options?: { readonly key?: string },
+): ActionHandle<A, Awaited<R>> {
+  const store = useStore();
+  const server = store.server;
+  const fnId = serverFunctionId(fn);
+  const key = options?.key;
+  // Everything the hook knows belongs to one function and key: a component that changes either
+  // shows the new one's run, never the old one's, and a late answer for the old one lands under
+  // the old identity, where the hook no longer looks.
+  const identity = `${fnId ?? ""}\u0000${key ?? ""}`;
+  const [states, setStates] = useState<ReadonlyMap<string, IdentityState>>(NO_STATES);
+  const current = states.get(identity) ?? IDLE;
+  const { runId, starting, startError } = current;
+  const update = useCallback((of: string, patch: Partial<IdentityState>): void => {
+    setStates((previous) => {
+      const next = new Map(previous);
+      next.set(of, { ...(previous.get(of) ?? IDLE), ...patch });
+      return next;
+    });
+  }, []);
+  const inFlight = useRef(new Map<string, Promise<unknown>>());
+  useSyncExternalStore(server.subscribe, server.version, server.version);
+
+  // A keyed run started earlier, in another tab or before a reload, is shown again (AC-02).
+  useEffect(() => {
+    if (key === undefined || fnId === undefined || store.mode !== "live") return;
+    let active = true;
+    server.attach({ keyed: [{ fnId, key }] }).then(
+      (runs) => {
+        const [found] = runs;
+        if (active && found) update(identity, { runId: found.runId });
+      },
+      () => {},
+    );
+    return () => {
+      active = false;
+    };
+  }, [server, store.mode, fnId, key, identity, update]);
+
+  const view = runId === undefined ? undefined : server.run(runId);
+
+  const run = useCallback(
+    (...args: A): Promise<Awaited<R>> => {
+      if (fnId === undefined) {
+        return Promise.reject(
+          new TypeError(
+            'useAction needs a server function: import it from a module that starts with "use server".',
+          ),
+        );
+      }
+      // One run in flight per hook instance and function and key (D54): a second click joins it.
+      const joined = inFlight.current.get(identity);
+      if (joined) return joined as Promise<Awaited<R>>;
+      update(identity, { starting: true, startError: undefined });
+      const started = (async () => {
+        let state: Awaited<ReturnType<typeof server.startRun>>;
+        try {
+          state = await server.startRun(fnId, args, key);
+        } catch (error) {
+          // The run never started (a refused link, a parked worker, the network): say why.
+          update(identity, {
+            starting: false,
+            startError:
+              error instanceof MostraError
+                ? { code: error.code, message: error.message }
+                : { code: "MOSTRA_ACTION_THREW", message: (error as Error).message },
+          });
+          throw error;
+        }
+        update(identity, { starting: false, runId: state.runId });
+        return server.settled(state.runId);
+      })();
+      inFlight.current.set(identity, started);
+      const settle = (): void => {
+        if (inFlight.current.get(identity) === started) inFlight.current.delete(identity);
+      };
+      started.then(settle, settle);
+      return started as Promise<Awaited<R>>;
+    },
+    [server, fnId, key, identity, update],
+  );
+
+  const cancel = useCallback(() => {
+    if (runId === undefined) return;
+    const current = server.run(runId);
+    if (current && !isFinalRunStatus(current.status)) void server.cancel(runId).catch(() => {});
+  }, [server, runId]);
+
+  return useMemo(() => {
+    const status: ActionHandle<A, Awaited<R>>["status"] = view?.status ?? "idle";
+    const error =
+      view?.error && (view.status === "failed" || view.status === "cancelled")
+        ? { code: view.error.code ?? "MOSTRA_ACTION_THREW", message: view.error.message }
+        : view?.status === "cancelled"
+          ? { code: "MOSTRA_ACTION_CANCELLED", message: "The run was cancelled." }
+          : startError;
+    return {
+      run,
+      cancel,
+      status,
+      isPending: starting || status === "queued" || status === "running" || status === "waiting",
+      ...(view?.status === "succeeded" && view.data !== undefined
+        ? { data: view.data as Awaited<R> }
+        : {}),
+      ...(error ? { error } : {}),
+      ...(view?.progress ? { progress: view.progress } : {}),
+      log: view?.log ?? NO_LOG,
+      partial: (view?.partial ?? []) as ActionHandle<A, Awaited<R>>["partial"],
+      ...(runId !== undefined ? { runId } : {}),
+    };
+  }, [run, cancel, view, starting, startError, runId]);
+}
+
+// ── useLive ───────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The live sources of the artifact, by key, with their value types. A generated declaration
+ * (`mostra-env.d.ts`, written by `mostra new`) fills it from `live.ts`:
+ *
+ * ```ts
+ * declare module "@mostra/react" {
+ *   interface LiveSources extends LiveValuesOf<typeof import("./live")> {}
+ * }
+ * ```
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: augmented by each artifact's declaration.
+export interface LiveSources {}
+
+/** The value types of a `live.ts` module's sources, by export name (D56). */
+export type LiveValuesOf<M> = {
+  [K in keyof M as M[K] extends { readonly "~mostra.live": unknown } ? K : never]: M[K] extends {
+    readonly __value?: infer T;
+  }
+    ? T
+    : never;
+};
+
+/** A live source's key: one of `LiveSources`, or any string before the declaration exists. */
+export type LiveKey = [keyof LiveSources] extends [never] ? string : keyof LiveSources & string;
+
+/** A live source's value type. */
+export type LiveValue<K extends string> = K extends keyof LiveSources ? LiveSources[K] : unknown;
+
+/** What `useLive` shows (INTERFACES §2.3). */
+export interface LiveResult<T> {
+  /** The latest value; in append mode, the values kept, oldest first. */
+  readonly data: T | undefined;
+  /** Whether no value has arrived yet. */
+  readonly isLoading: boolean;
+  /** The producer's last failure; the last good value stays in `data` (FAILURE_MODEL §6). */
+  readonly error?: Error;
+  /** Asks the producer to load again now. */
+  refresh(): void;
+  /** The value's revision, which only grows. */
+  readonly revision?: string;
+  /** When the value was produced. */
+  readonly at?: string;
+}
+
+/** How long append mode keeps values without a `window`. */
+const DEFAULT_WINDOW = 1024;
+
+/**
+ * Reads a live source of `live.ts`, or one an agent or host pushes to (D56): the latest value, or
+ * in append mode the recent values for a high-rate chart. The value is shared by every component
+ * that shows it and updates without a reload; nothing of it is a durable event (D63).
+ *
+ * ```tsx
+ * const { data, isLoading, error } = useLive("inbox");
+ * const { data: points } = useLive("cpu", { mode: "append", window: 600 });
+ * ```
+ */
+export function useLive<K extends LiveKey>(
+  key: K,
+  options: { readonly mode: "append"; readonly window?: number },
+): LiveResult<LiveValue<K>[]>;
+/** Reads a live source's latest value (D56). See the first signature. */
+export function useLive<K extends LiveKey>(
+  key: K,
+  options?: { readonly mode?: "latest"; readonly window?: number },
+): LiveResult<LiveValue<K>>;
+export function useLive<K extends LiveKey>(
+  key: K,
+  options?: { readonly mode?: "latest" | "append"; readonly window?: number },
+): LiveResult<unknown> {
+  const store = useStore();
+  const server = store.server;
+  const append = options?.mode === "append";
+  const window = append ? (options?.window ?? DEFAULT_WINDOW) : undefined;
+  useSyncExternalStore(server.subscribe, server.version, server.version);
+  useEffect(() => server.watchLive(key, window), [server, key, window]);
+  const view = server.liveView(key);
+  const refresh = useCallback(() => server.refreshLive(key), [server, key]);
+  return useMemo(() => {
+    const data = append
+      ? view?.ring.length
+        ? view.ring.slice(-(window ?? 0))
+        : undefined
+      : view?.data;
+    return {
+      data,
+      isLoading: data === undefined && (view?.loading ?? true),
+      ...(view?.error
+        ? {
+            error: new MostraError(
+              view.error.code ?? "MOSTRA_LIVE_SOURCE_FAILED",
+              view.error.message,
+            ),
+          }
+        : {}),
+      refresh,
+      ...(view?.revision !== undefined ? { revision: view.revision } : {}),
+      ...(view?.at !== undefined ? { at: view.at } : {}),
+    };
+  }, [view, append, window, refresh]);
+}

package/src/server-reference.ts

@@ -0,0 +1,54 @@
+"use client";
+
+/**
+ * The client side of `"use server"` functions (D19 seam 2, D54). The builder compiles every export
+ * of a `"use server"` module in client code into a server reference: a function that carries the
+ * server function's ID and hands the call to the page's runtime, as React's own server references
+ * hand theirs to the callback `setServerCallback` installs. The runtime calls Mostra (a plain
+ * call: no record, the result streamed back); where there is no Mostra server, such as a static
+ * export, the call rejects with `MOSTRA_TARGET_UNAVAILABLE`.
+ */
+
+/** A `"use server"` function as client code sees it. */
+export interface ServerReference<A extends unknown[] = unknown[], R = unknown> {
+  /** Calls the server function with `args`; resolves with its result. */
+  (...args: A): Promise<R>;
+  /** The server function's ID: its module path, `#` and its export name (`actions.ts#sendReply`). */
+  readonly mostraServerFunctionId: string;
+}
+
+/** How the page's runtime calls a server function. */
+export type CallServer = (id: string, args: unknown[]) => Promise<unknown>;
+
+const unavailable: CallServer = async (id) => {
+  const error = new Error(
+    `The server function ${id} can't run here: this delivery target has no Mostra server. Open the artifact through its Mostra link to use it.`,
+  ) as Error & { code: string };
+  error.code = "MOSTRA_TARGET_UNAVAILABLE";
+  throw error;
+};
+
+let callServer: CallServer = unavailable;
+
+/**
+ * Installs how server references call the server: the runtime does it when the page starts (a
+ * live page calls Mostra; a static export keeps the default, which rejects). Returns the function
+ * that restores the previous one.
+ */
+export function setServerCallback(callback: CallServer): () => void {
+  const previous = callServer;
+  callServer = callback;
+  return () => {
+    callServer = previous;
+  };
+}
+
+/**
+ * Creates the client stub of one server function. The builder emits these calls; artifact code
+ * imports the server module as usual and never calls this itself.
+ */
+export function createServerReference(id: string): ServerReference {
+  const reference = (...args: unknown[]): Promise<unknown> => callServer(id, args);
+  Object.defineProperty(reference, "mostraServerFunctionId", { value: id, enumerable: true });
+  return reference as unknown as ServerReference;
+}

package/src/shell-bridge.ts

@@ -0,0 +1,212 @@
+"use client";
+
+/**
+ * The artifact's end of the shell bridge (INTERFACES §5, SH-04). The client runtime starts it:
+ * when the page runs inside Mostra's shell, it learns the shell's exact origin and its link's
+ * scopes from its own session (`GET /_mostra/session`, readable only by this origin), introduces
+ * itself with MCP Apps' `ui/initialize`, whose answer names the view this frame load is (D104),
+ * and reports `mostra/ready` once the page has rendered. Messages from any other window or origin
+ * are dropped. Outside a shell (a static export, the page opened on its own) it does nothing.
+ */
+import {
+  type AnyBridgeMessage,
+  type Bridge,
+  connectBridge,
+  MCP_APPS_PROTOCOL_VERSION,
+  mostraReady,
+  OPEN_LINK_SCHEMES,
+  type UiInitializeResult,
+  uiInitialize,
+  uiInitialized,
+  uiOpenLink,
+  type Viewer,
+} from "@mostra/protocol";
+
+/**
+ * The version this page's build belongs to: its `<meta name="mostra-version">`, which Mostra's
+ * builder writes (WP-07). `undefined` for a build that has none. @internal
+ */
+export function builtVersion(): string | undefined {
+  if (typeof document === "undefined") return undefined;
+  const content = document.querySelector('meta[name="mostra-version"]')?.getAttribute("content");
+  return content ? content : undefined;
+}
+
+/** `ui/initialize`'s `mostra` params: the page's version, when the build names it. */
+function versionParams(): { mostra?: { versionId: string } } {
+  const versionId = builtVersion();
+  return versionId === undefined ? {} : { mostra: { versionId } };
+}
+
+/** The shell connection of this page, once it is established. */
+export interface ShellConnection {
+  /** The shell's origin. */
+  readonly shellOrigin: string;
+  /** What the shell said about where the page is shown, and the view (`host.mostra`). */
+  readonly host: UiInitializeResult;
+  /** The bridge, for the client runtime's messages. */
+  readonly bridge: Bridge;
+  /**
+   * The frame session's facts: its CSRF token, the link's scopes (D97, D98) and, from gateways
+   * since WP-07, the viewer it acts as.
+   */
+  readonly session: {
+    readonly csrf: string;
+    readonly scopes: readonly string[];
+    readonly viewer?: Viewer;
+  };
+}
+
+interface FrameSession {
+  readonly shellOrigin?: unknown;
+  readonly csrf?: unknown;
+  readonly scopes?: unknown;
+  readonly viewer?: unknown;
+}
+
+/** Hears what the shell sends: requests answered by the first handler that returns a value. */
+export interface ShellListener {
+  readonly request?: (message: AnyBridgeMessage, params: unknown) => unknown;
+  readonly notification?: (message: AnyBridgeMessage, params: unknown) => void;
+}
+
+const listeners = new Set<ShellListener>();
+let connecting: Promise<ShellConnection | undefined> | undefined;
+
+/**
+ * Listens to the shell's requests and notifications on this page's bridge; returns the function
+ * that stops. The client runtime answers `mostra/flush` and hears `mostra/version.available`.
+ */
+export function listenShell(listener: ShellListener): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/**
+ * Connects this page to the shell that frames it, once; later calls return the same connection.
+ * Resolves `undefined` when the page isn't framed by a Mostra shell. The client runtime calls it;
+ * artifact code doesn't need to.
+ */
+export function connectShell(): Promise<ShellConnection | undefined> {
+  connecting ??= (async () => {
+    if (typeof window === "undefined" || window.parent === window) return undefined;
+    let session: FrameSession;
+    try {
+      const response = await fetch("/_mostra/session", {
+        credentials: "same-origin",
+        cache: "no-store",
+        signal: AbortSignal.timeout(HANDSHAKE_TIMEOUT_MS),
+      });
+      if (!response.ok) return undefined;
+      session = (await response.json()) as FrameSession;
+    } catch {
+      return undefined;
+    }
+    if (typeof session.shellOrigin !== "string") return undefined;
+    const shellOrigin = session.shellOrigin;
+    const bridge = connectBridge({
+      side: "artifact",
+      receiver: window,
+      peer: () => window.parent,
+      peerOrigin: shellOrigin,
+      onRequest: async (message, params) => {
+        for (const listener of listeners) {
+          const answer = await listener.request?.(message, params);
+          if (answer !== undefined) return answer;
+        }
+        throw new Error(`The page doesn't answer ${message.method}.`);
+      },
+      onNotification: (message, params) => {
+        for (const listener of listeners) listener.notification?.(message, params);
+      },
+    });
+    let host: UiInitializeResult;
+    try {
+      host = await bridge.call(
+        uiInitialize,
+        {
+          appInfo: { name: "mostra-artifact", version: "0" },
+          appCapabilities: {},
+          protocolVersion: MCP_APPS_PROTOCOL_VERSION,
+          ...versionParams(),
+        },
+        { timeoutMs: HANDSHAKE_TIMEOUT_MS },
+      );
+    } catch (error) {
+      bridge.close();
+      throw error;
+    }
+    bridge.notify(uiInitialized, {});
+    return {
+      shellOrigin,
+      host,
+      bridge,
+      session: {
+        csrf: typeof session.csrf === "string" ? session.csrf : "",
+        scopes: Array.isArray(session.scopes)
+          ? session.scopes.filter((scope): scope is string => typeof scope === "string")
+          : [],
+        ...(isViewer(session.viewer) ? { viewer: session.viewer } : {}),
+      },
+    };
+  })().then(
+    (connection) => {
+      // A framed page that didn't connect may try again (the daemon restarting during the
+      // frame's load, a slow handshake): only a connection is kept (Claude review finding 4).
+      if (connection === undefined) connecting = undefined;
+      return connection;
+    },
+    () => {
+      connecting = undefined;
+      return undefined;
+    },
+  );
+  return connecting;
+}
+
+/** Whether the session's `viewer` looks like a viewer (a light check: the gateway sends it). */
+function isViewer(value: unknown): value is Viewer {
+  const viewer = value as { id?: unknown; kind?: unknown } | null | undefined;
+  return typeof viewer?.id === "string" && typeof viewer.kind === "string";
+}
+
+/** How long one attempt at the shell's handshake may take. */
+const HANDSHAKE_TIMEOUT_MS = 10_000;
+
+/**
+ * Tells the shell the page has rendered (`mostra/ready`), after the next frame paints. The
+ * client runtime calls it right after mounting the page.
+ */
+export function reportReady(): void {
+  void connectShell().then((connection) => {
+    if (!connection) return;
+    requestAnimationFrame(() => connection.bridge.notify(mostraReady, {}));
+  });
+}
+
+/**
+ * Opens `url` for the viewer in a new tab. Inside Mostra's shell the frame can't navigate the
+ * viewer's tab (D98 item 7), so the shell opens it (`ui/open-link`, MCP Apps); on a page of its
+ * own, the browser does. Only `http:`, `https:`, `mailto:` and `tel:` URLs open. Resolves `true`
+ * when the URL was handed to the browser.
+ */
+export async function openLink(url: string): Promise<boolean> {
+  const connection = await connectShell();
+  if (connection) {
+    try {
+      const result = await connection.bridge.call(uiOpenLink, { url });
+      return result.isError !== true;
+    } catch {
+      return false;
+    }
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(url, window.location.href);
+  } catch {
+    return false;
+  }
+  if (!OPEN_LINK_SCHEMES.includes(parsed.protocol)) return false;
+  window.open(parsed.href, "_blank", "noopener,noreferrer");
+  return true;
+}