@ggui-ai/mcp-apps-react-native 0.0.1-placeholder → 0.9.0

package/src/context/GguiContext.ts

@@ -0,0 +1,121 @@
+import { createContext, useContext } from 'react';
+import type { AdapterPermissions, PermissionStatus, InterfaceContext, EndUserIdentity, AppDisplayConfig } from '@ggui-ai/protocol';
+
+/**
+ * Open interface — host runtime registry of **client/device adapter
+ * implementations**. Empty on purpose: capability packages or host
+ * apps augment this interface via TypeScript declaration merging so
+ * the slot for each adapter lands with its concrete type.
+ *
+ * Example (host app or downstream capability package):
+ * ```ts
+ * declare module '@ggui-ai/mcp-apps-react-native' {
+ *   interface AdapterRegistry {
+ *     printer?: PrinterAdapter;
+ *   }
+ * }
+ * ```
+ *
+ * Mirrors {@link AdapterRegistry} in `@ggui-ai/mcp-apps-react`. The augmenting
+ * party can augment one or both registries depending on which SDKs
+ * the adapter ships against. (Browser-capability hooks — camera,
+ * geolocation, clipboard, filePicker, notifications, microphone —
+ * are better served by the gadget pattern in `@ggui-ai/gadgets`,
+ * which doesn't need a Provider-wired adapter; generated UI imports
+ * the hook directly.)
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface AdapterRegistry {}
+
+/**
+ * Shape of the value provided by {@link GguiContext}.
+ *
+ * Contains app identity, WebSocket configuration, adapter permissions,
+ * interface context, and optional auth/session state consumed by hooks.
+ * Extends the web version with `reactVersion` and `designSystemUrl` for
+ * WebView import map configuration.
+ */
+export interface GguiContextValue {
+  appId: string;
+  wsEndpoint?: string;
+  adapterPermissions: AdapterPermissions;
+  requestPermission: (adapter: string) => Promise<PermissionStatus>;
+  /** Host-registered adapter implementations, keyed by capability name.
+   * Generated UI reads from this registry via {@link useAdapter} (or
+   * capability-specific hooks exposed by host apps that augment
+   * {@link AdapterRegistry}). Grant decisions live on
+   * `clientCapabilities.gadgets[*].permission` — this registry is
+   * purely the runtime implementation slot. */
+  adapterImpls: AdapterRegistry;
+  /** Current interface context (device/viewport info) */
+  interfaceContext: InterfaceContext;
+  /** Auth context surfaced to embedding hosts and renderer surfaces. */
+  auth?: {
+    currentUser?: EndUserIdentity;
+    userId?: string;
+    token?: string;
+    isAuthenticated: boolean;
+  };
+  /**
+   * Conversation envelope identity. Forwarded by {@link useInvoke} as
+   * the `X-Ggui-Host-Session-Id` header so the agent threads multi-turn
+   * invokes through its own keyed conversation state. Names the chat
+   * thread, not a render.
+   */
+  hostSessionId?: string;
+  /** React version for WebView import map (default: '18.2.0') */
+  reactVersion?: string;
+  /** Base URL for design system modules in WebView import map */
+  designSystemUrl?: string;
+  /**
+   * App config (endpointUrl, defaultShellType, etc). Mirrors the web SDK's
+   * context field — `useInvoke` reads `endpointUrl` from here when the
+   * caller doesn't override it. Populated by {@link GguiProvider} via its
+   * `appConfig` prop.
+   */
+  appConfig?: AppDisplayConfig | null;
+}
+
+/**
+ * React context that carries ggui configuration to all descendant components.
+ *
+ * Provided by {@link GguiProvider}. Access the value with {@link useGguiContext}.
+ */
+export const GguiContext = createContext<GguiContextValue | null>(null);
+
+/**
+ * Access the nearest {@link GguiContext} value.
+ *
+ * Must be called inside a `<GguiProvider>`. Throws if no provider is found.
+ *
+ * @returns The current {@link GguiContextValue}
+ * @throws Error if called outside a GguiProvider
+ */
+export function useGguiContext(): GguiContextValue {
+  const ctx = useContext(GguiContext);
+  if (!ctx) {
+    throw new Error('useGguiContext must be used within a GguiProvider');
+  }
+  return ctx;
+}
+
+/**
+ * Read a host-registered adapter implementation by capability name.
+ *
+ * Returns `undefined` when the host hasn't wired an implementation
+ * for this capability — callers MUST handle that case (e.g. render
+ * a fallback UI). Grant decisions live on `clientCapabilities.gadgets
+ * [*].permission` and surface to the iframe via `Permissions-Policy`;
+ * the SDK context just exposes whatever the host wired into
+ * `adapterImpls`.
+ *
+ * Mirrors {@link useAdapter} in `@ggui-ai/mcp-apps-react`. Capability packages
+ * augment both {@link AdapterRegistry} surfaces via declaration
+ * merging.
+ */
+export function useAdapter<K extends keyof AdapterRegistry>(
+  name: K,
+): AdapterRegistry[K] | undefined {
+  const ctx = useGguiContext();
+  return ctx.adapterImpls[name];
+}

package/src/hooks/useAppState.ts

@@ -0,0 +1,24 @@
+import { useEffect, useRef, useState } from 'react';
+import { AppState, type AppStateStatus } from 'react-native';
+
+/**
+ * Hook to track React Native AppState (active, background, inactive).
+ * Useful for pausing/resuming connections and animations.
+ */
+export function useAppState(): AppStateStatus {
+  const [appState, setAppState] = useState<AppStateStatus>(AppState.currentState);
+  const appStateRef = useRef(AppState.currentState);
+
+  useEffect(() => {
+    const subscription = AppState.addEventListener('change', (nextState) => {
+      appStateRef.current = nextState;
+      setAppState(nextState);
+    });
+
+    return () => {
+      subscription.remove();
+    };
+  }, []);
+
+  return appState;
+}

package/src/index.ts

@@ -0,0 +1,150 @@
+/**
+ * @ggui-ai/mcp-apps-react-native - React Native SDK for ggui
+ *
+ * Provides React Native components, hooks, and utilities for embedding ggui
+ * agent interfaces in mobile applications. The host primitive is
+ * `<McpAppIframe>` — the WebView-backed MCP Apps host (RN analog of the
+ * web's `<AppRenderer>` from `@mcp-ui/client`) — surrounded by the
+ * message-grouping helpers (`chat-helpers` subpath), the Streamable
+ * Invoke hook (`useInvoke`), and a React Native theme system that
+ * mirrors the web design tokens.
+ *
+ * @packageDocumentation
+ */
+
+// Theme System
+export { ThemeProvider, useTheme, buildTheme } from './theme';
+export type { ThemeProviderProps, RNTheme, RNThemeColors, RNThemeSemantic, RNShadow, RNTransitionPreset, RNAccessibility } from './theme';
+export {
+  rnColors,
+  rnSemantic,
+  rnSpacing,
+  rnSpacingNamed,
+  rnFontSize,
+  rnFontWeight,
+  rnLineHeight,
+  rnFontFamily,
+  rnRadius,
+  rnShadow,
+  rnDuration,
+  rnEasing,
+  rnTransition,
+  rnAccessibility,
+} from './theme';
+
+// Re-export transport types from the transport subpath
+export type {
+  ConnectionStatus,
+  WebSocketMessage,
+  WebSocketMessageType,
+} from '@ggui-ai/protocol/transport/websocket';
+
+// Re-export types from protocol
+export type {
+  ActionEnvelope,
+  EventType,
+  // Single GguiSession union (ComponentGguiSession, SystemGguiSession, McpAppsGguiSession)
+  // keyed by the flat `sessionId`.
+  GguiSession,
+  ComponentGguiSession,
+  SystemGguiSession,
+  GguiSessionStatus,
+  AdapterPermissions,
+  PermissionStatus,
+  SubscribePayload,
+  AckPayload,
+  StreamEnvelope,
+  ErrorPayload,
+  RenderPayload,
+  PropsUpdatePayload,
+  ShellType,
+  InterfaceContext,
+  DeviceCategory,
+  EndUserIdentity,
+} from '@ggui-ai/protocol';
+export { BRIDGE_EVENTS, detectInterfaceContext, getDeviceCategory } from '@ggui-ai/protocol';
+
+// Invoke protocol message block types — re-exported at root so facade
+// consumers can pull them from the same import path as useInvoke.
+// Parity: identical type re-export block exists on @ggui-ai/mcp-apps-react.
+export type {
+  ContentBlock,
+  TextBlock,
+  ToolUseBlock,
+  ToolResultBlock,
+  InvokeTurn,
+} from '@ggui-ai/protocol';
+
+// ProtocolError typed union — the canonical shape for every failure
+// the renderer classifies outward. `<McpAppIframe onError>` surfaces
+// it; embedding apps pattern-match on `err.kind`. The sibling package
+// `@ggui-ai/iframe-runtime` owns the declaration; the RN SDK re-exports
+// it at parity with `@ggui-ai/mcp-apps-react` so consumers have a single import
+// point per platform.
+export type {
+  ProtocolError,
+  ProtocolErrorEmitter,
+  BootstrapFailureReason,
+  // Bootstrap-failure postMessage envelope shape — the parent receives
+  // `{type:'ggui:bootstrap-failed', reason, message}` from the iframe /
+  // WebView on any pre-renderer or post-renderer boot failure. RN
+  // hosts reading this via WebView `onMessage` pattern-match on the
+  // `type` tag to classify iframe-origin failures.
+  RendererBootFailedMessage,
+} from '@ggui-ai/iframe-runtime';
+
+// Provider
+export { GguiProvider, useGguiContext, useAdapter } from './components/GguiProvider';
+export type { GguiProviderProps } from './components/GguiProvider';
+export type { AdapterRegistry } from './context/GguiContext';
+
+// Shared host-role MCP-Apps bridge helpers — exported for composition by
+// callers that want to embed the bridge in a custom WebView wrapper
+// (e.g., custom error overlays, in-app navigation headers). The
+// switch implements the canonical set: ui/initialize, tools/call,
+// ping, ui/open-link, ui/resource-teardown.
+export {
+  handleHostBridgeRequest,
+  buildInjectedBridgeScript,
+  buildDeliveryScript,
+  NATIVE_BRIDGE_ENVELOPE_KEY,
+} from './components/mcp-apps-bridge';
+export type { HostBridgeContext } from './components/mcp-apps-bridge';
+
+// `<McpAppIframe>` — generic MCP Apps iframe host for React Native.
+// Zero ggui-specific coupling; a mirror of the web host exported from
+// `@ggui-ai/mcp-apps-react`. Any MCP Apps host (Claude Desktop,
+// ChatGPT, VS Code, console, third-party playgrounds) uses this to
+// embed a ggui (or any MCP Apps-conformant) session on RN.
+export { McpAppIframe } from './McpAppIframe/index';
+export type {
+  McpAppIframeProps,
+  McpAppIframeRef,
+  McpAppIframeDimensions,
+  McpAppIframePermissions,
+} from './McpAppIframe/index';
+
+// Error Boundary
+export { ErrorBoundary } from './components/ErrorBoundary';
+export type { ErrorBoundaryProps } from './components/ErrorBoundary';
+
+// UI Feedback affordance — host-side render-shell chrome. Hidden
+// entirely unless the host wires `onUiFeedback`; the payload leaves
+// through that callback only (never the agent ↔ UI wire). An
+// in-iframe twin lives in `@ggui-ai/iframe-runtime` (emitting a
+// `ui-feedback` event on the `ggui:observe` seam) — hosts wire
+// exactly ONE of the two surfaces, never both.
+export { UiFeedback } from './components/UiFeedback';
+export type {
+  UiFeedbackProps,
+  UiFeedbackPayload,
+  UiFeedbackVerdict,
+} from './components/UiFeedback';
+
+// Streamable Invoke Protocol (v1.1) hook
+export { useInvoke, parseSseStream } from './invoke/index';
+export type { UseInvokeOptions, UseInvokeReturn, ConversationMessage, InvokeError } from './invoke/index';
+
+// Hooks
+export { useAppState } from './hooks/useAppState';
+

package/src/invoke/index.ts

@@ -0,0 +1,8 @@
+export { useInvoke } from './useInvoke';
+export type {
+  UseInvokeOptions,
+  UseInvokeReturn,
+  ConversationMessage,
+  InvokeError,
+} from './useInvoke';
+export { parseSseStream } from './sse-parse';

package/src/invoke/sse-parse.ts

@@ -0,0 +1,79 @@
+/**
+ * SSE frame parser for the streamable invoke protocol (React Native).
+ *
+ * Reads a `Response.body` chunk by chunk, yields parsed + validated
+ * `InvokeEvent`s as they arrive. Buffers partial frames across chunk
+ * boundaries — chunks from `fetch` do NOT align with `\n\n` separators.
+ *
+ * This is a near-exact port of the web implementation
+ * (`@ggui-ai/mcp-apps-react/src/invoke/sse-parse.ts`). The only platform concern is
+ * `TextDecoder`: modern React Native (Hermes, RN 0.74+) ships it natively,
+ * and Expo SDK 50+ polyfills it for older runtimes. If consumers target an
+ * older setup they must polyfill `TextDecoder` in their entry file.
+ */
+import { invokeEventSchema, type InvokeEvent } from '@ggui-ai/protocol';
+
+const DECODER = new TextDecoder();
+const FRAME_SEP = '\n\n';
+
+/**
+ * Async generator yielding one `InvokeEvent` per SSE frame in the stream.
+ *
+ * Malformed frames (non-JSON data, schema validation failure) are dropped
+ * silently — agents emit a wide variety of frames and a single bad one
+ * shouldn't kill the whole turn. Caller handles `event: error` for explicit
+ * upstream failures.
+ */
+export async function* parseSseStream(
+  body: ReadableStream<Uint8Array>,
+  signal?: AbortSignal,
+): AsyncGenerator<InvokeEvent> {
+  const reader = body.getReader();
+  let buffer = '';
+
+  try {
+    while (true) {
+      if (signal?.aborted) break;
+      const { value, done } = await reader.read();
+      if (done) break;
+
+      buffer += DECODER.decode(value, { stream: true });
+
+      let sepIdx: number;
+      while ((sepIdx = buffer.indexOf(FRAME_SEP)) !== -1) {
+        const frame = buffer.slice(0, sepIdx);
+        buffer = buffer.slice(sepIdx + FRAME_SEP.length);
+        const event = parseFrame(frame);
+        if (event) yield event;
+      }
+    }
+
+    // Flush trailing frame (no terminator) — agent that closed cleanly will
+    // have sent message_stop with the separator, but be lenient.
+    if (buffer.length > 0) {
+      const event = parseFrame(buffer);
+      if (event) yield event;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+function parseFrame(frame: string): InvokeEvent | null {
+  // Frames are `event: NAME\ndata: JSON` (newlines are spec-strict but
+  // forgiving here). We only need the data line.
+  const dataIdx = frame.indexOf('data: ');
+  if (dataIdx === -1) return null;
+  const json = frame.slice(dataIdx + 'data: '.length).trim();
+  if (!json) return null;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return null;
+  }
+
+  const result = invokeEventSchema.safeParse(parsed);
+  return result.success ? result.data : null;
+}