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

package/src/chat-helpers/message-groups.ts

@@ -0,0 +1,124 @@
+import type { ContentBlock, InvokeTurn } from '@ggui-ai/protocol';
+import type { ConversationMessage } from '../invoke/useInvoke';
+import { extractRenderFromToolResult } from './render';
+
+/**
+ * A "content group" is one durable-renderable unit from an invoke message:
+ *   - a contiguous run of text blocks (one text bubble)
+ *   - one tool_use + its paired tool_result (one card bubble)
+ *
+ * Integrators persist content groups to their storage and reconstruct
+ * ConversationMessages from them on thread reopen.
+ */
+export interface ContentGroup {
+  /** Deterministic from `${invokeMessageId}-${startBlockIdx}`. Key for idempotency. */
+  key: string;
+  kind: 'text' | 'card' | 'other';
+  authorRole: 'user' | 'agent';
+  blocks: ContentBlock[];
+  /** For kind='card' only — a frozen GguiSession extracted from the tool_result. */
+  cardSnapshot: unknown | null;
+  /** Human-readable ~160-char preview (for chat-list lastMessagePreview). */
+  textPreview: string;
+}
+
+/**
+ * Split a finalized invoke ConversationMessage into ContentGroups.
+ * Returns [] when the message is still streaming (nothing durable yet).
+ */
+export function invokeMessageToContentGroups(message: ConversationMessage): ContentGroup[] {
+  if (message.isStreaming) return [];
+  const authorRole: 'user' | 'agent' = message.role === 'user' ? 'user' : 'agent';
+  const groups: ContentGroup[] = [];
+  let i = 0;
+  while (i < message.content.length) {
+    const b = message.content[i]!;
+    if (b.type === 'text') {
+      const startIdx = i;
+      const textBlocks: ContentBlock[] = [b];
+      let j = i + 1;
+      while (j < message.content.length && message.content[j]!.type === 'text') {
+        textBlocks.push(message.content[j]!);
+        j++;
+      }
+      const preview = textBlocks
+        .map((t) => (t.type === 'text' ? t.text : ''))
+        .join(' ')
+        .slice(0, 160);
+      groups.push({
+        key: `${message.id}-${startIdx}`,
+        kind: 'text',
+        authorRole,
+        blocks: textBlocks,
+        cardSnapshot: null,
+        textPreview: preview,
+      });
+      i = j;
+    } else if (b.type === 'tool_use') {
+      const paired = message.content.find(
+        (x) => x.type === 'tool_result' && x.tool_use_id === b.id,
+      );
+      const resultBlock = paired ?? null;
+      const cardSnapshot = resultBlock ? extractRenderFromToolResult(resultBlock) : null;
+      const blocks: ContentBlock[] = resultBlock ? [b, resultBlock] : [b];
+      // A render-bearing result IS a card, whatever the tool was named —
+      // agent frameworks surface renders under their own tool names
+      // (`render_card`, `mcp__cards__update_card`, …) with the payload
+      // recognized by extractRenderFromToolResult. The name arm keeps
+      // ggui's own render tools folding as cards even when the result
+      // block is absent (e.g. still in flight).
+      groups.push({
+        key: `${message.id}-${i}`,
+        kind:
+          cardSnapshot !== null || b.name === 'ggui_render' || b.name === 'ggui_update'
+            ? 'card'
+            : 'other',
+        authorRole,
+        blocks,
+        cardSnapshot,
+        textPreview: '[UI card]',
+      });
+      i++;
+    } else {
+      // Standalone tool_result (already absorbed) + other kinds — skip.
+      i++;
+    }
+  }
+  return groups;
+}
+
+/**
+ * Inverse: reassemble ConversationMessages from persisted content groups.
+ * Groups sharing the same `${invokeMessageId}` prefix collapse back into
+ * a single message — used on thread reopen to seed useInvoke.
+ */
+export function contentGroupsToConversationMessages(
+  groups: ContentGroup[],
+): ConversationMessage[] {
+  const byInvokeMessageId = new Map<string, ConversationMessage>();
+  for (const g of groups) {
+    const invokeMessageId = g.key.split('-').slice(0, -1).join('-') || g.key;
+    const role: 'user' | 'assistant' = g.authorRole === 'user' ? 'user' : 'assistant';
+    const existing = byInvokeMessageId.get(invokeMessageId);
+    if (existing) {
+      existing.content.push(...g.blocks);
+    } else {
+      byInvokeMessageId.set(invokeMessageId, {
+        id: invokeMessageId,
+        role,
+        content: [...g.blocks],
+        isStreaming: false,
+      });
+    }
+  }
+  return Array.from(byInvokeMessageId.values());
+}
+
+/** Build wire history from in-memory messages, stripping streaming turns. */
+export function conversationMessagesToInvokeHistory(
+  messages: ConversationMessage[],
+): InvokeTurn[] {
+  return messages
+    .filter((m) => !(m.role === 'assistant' && m.isStreaming))
+    .map((m) => ({ role: m.role, content: m.content }));
+}

package/src/chat-helpers/render.ts

@@ -0,0 +1,65 @@
+import type { ContentBlock } from '@ggui-ai/protocol';
+
+/**
+ * Pull a durable render payload out of a `tool_result` block's
+ * `content` payload. Tolerant of shapes:
+ *   - Direct: { id, componentCode, props, ... }                (GguiSession itself)
+ *   - Wrapped: { render: {...} }
+ *   - Nested: { result: { render: {...} } }
+ *   - Nested direct: { result: { id, componentCode, ... } }
+ *   - MCP-Apps bootstrap: { _meta: { ui: { resourceUri } }, ... }
+ *     (SEP-1865) — a tool result whose `_meta.ui.resourceUri` is set IS
+ *     a render; the result itself is the durable card payload (it
+ *     carries `structuredContent` plus the full `_meta.ui` block,
+ *     including any inlined resource). Same recognition rule as the
+ *     `useMcpAppsChat` walker — agent framework streams (Claude Agent
+ *     SDK, ADK, OpenAI Agents) deliver renders in exactly this shape.
+ *
+ * Returns `null` if no render can be found — caller falls back to
+ * placeholder rendering.
+ *
+ * Post-Phase-B: the legacy `stackItem` wrapper is gone — every tool
+ * result carries a single flat `sessionId`. This stays a tolerant
+ * heuristic over the remaining shapes (the `render` wrapper key, the
+ * direct GguiSession object, the spec-canonical `_meta.ui` bootstrap)
+ * rather than pinning one producer's envelope.
+ */
+export function extractRenderFromToolResult(block: ContentBlock): unknown | null {
+  if (block.type !== 'tool_result') return null;
+  const content = block.content as unknown;
+  if (typeof content !== 'object' || content === null) return null;
+  const rec = content as Record<string, unknown>;
+  if (rec.render && typeof rec.render === 'object') return rec.render;
+  if (typeof rec.id === 'string' && typeof rec.componentCode === 'string') return rec;
+  if (rec._meta !== null && typeof rec._meta === 'object') {
+    const ui = (rec._meta as Record<string, unknown>).ui;
+    if (ui !== null && typeof ui === 'object') {
+      const uri = (ui as Record<string, unknown>).resourceUri;
+      if (typeof uri === 'string' && uri.length > 0) return rec;
+    }
+  }
+  for (const v of Object.values(rec)) {
+    if (typeof v === 'object' && v !== null) {
+      const inner = v as Record<string, unknown>;
+      if (inner.render && typeof inner.render === 'object') return inner.render;
+      if (typeof inner.id === 'string' && typeof inner.componentCode === 'string') return inner;
+    }
+  }
+  return null;
+}
+
+/** Same traversal looking for just a sessionId field. */
+export function extractSessionIdFromToolResult(block: ContentBlock): string | null {
+  if (block.type !== 'tool_result') return null;
+  const content = block.content as unknown;
+  if (typeof content !== 'object' || content === null) return null;
+  const rec = content as Record<string, unknown>;
+  if (typeof rec.sessionId === 'string') return rec.sessionId;
+  for (const v of Object.values(rec)) {
+    if (typeof v === 'object' && v !== null) {
+      const inner = v as Record<string, unknown>;
+      if (typeof inner.sessionId === 'string') return inner.sessionId;
+    }
+  }
+  return null;
+}

package/src/chat-helpers/useRafThrottled.ts

@@ -0,0 +1,34 @@
+import { useEffect, useRef, useState } from 'react';
+
+/**
+ * Collapse rapid source updates into at most one downstream render per
+ * animation frame. Use on streaming content where per-delta re-renders
+ * would flicker composer focus or tank framerate.
+ *
+ * Usage:
+ *   const invoke = useInvoke();
+ *   const messages = useRafThrottled(invoke.messages);
+ */
+export function useRafThrottled<T>(source: T): T {
+  const [snapshot, setSnapshot] = useState(source);
+  const sourceRef = useRef(source);
+  const frameRef = useRef<number | null>(null);
+
+  sourceRef.current = source;
+
+  useEffect(() => {
+    if (frameRef.current !== null) return;
+    frameRef.current = requestAnimationFrame(() => {
+      frameRef.current = null;
+      setSnapshot(sourceRef.current);
+    });
+    return () => {
+      if (frameRef.current !== null) {
+        cancelAnimationFrame(frameRef.current);
+        frameRef.current = null;
+      }
+    };
+  }, [source]);
+
+  return snapshot;
+}

package/src/components/ErrorBoundary.tsx

@@ -0,0 +1,96 @@
+/**
+ * Error Boundary for React Native
+ *
+ * Catches runtime errors in generated components and displays
+ * a native error UI with retry capability.
+ */
+
+import React, { Component, type ReactNode, type ErrorInfo } from 'react';
+import { View, Text, Pressable, StyleSheet } from 'react-native';
+
+export interface ErrorBoundaryProps {
+  children: ReactNode;
+  onError?: (error: Error, componentStack?: string) => void;
+  fallback?: ReactNode;
+}
+
+interface ErrorBoundaryState {
+  hasError: boolean;
+  error: Error | null;
+}
+
+export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = { hasError: false, error: null };
+  }
+
+  static getDerivedStateFromError(error: Error): Partial<ErrorBoundaryState> {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo): void {
+    this.props.onError?.(error, errorInfo.componentStack || undefined);
+  }
+
+  reset = (): void => {
+    this.setState({ hasError: false, error: null });
+  };
+
+  render(): ReactNode {
+    const { children, fallback } = this.props;
+    const { hasError, error } = this.state;
+
+    if (!hasError) {
+      return children;
+    }
+
+    if (fallback) {
+      return fallback;
+    }
+
+    return (
+      <View style={styles.container}>
+        <Text style={styles.title}>Something went wrong</Text>
+        <Text style={styles.message}>{error?.message || 'An error occurred'}</Text>
+        <Pressable style={styles.retryButton} onPress={this.reset}>
+          <Text style={styles.retryText}>Try Again</Text>
+        </Pressable>
+      </View>
+    );
+  }
+}
+
+const styles = StyleSheet.create({
+  container: {
+    padding: 16,
+    backgroundColor: '#fee2e2',
+    borderWidth: 1,
+    borderColor: '#ef4444',
+    borderRadius: 8,
+    alignItems: 'center',
+    gap: 8,
+  },
+  title: {
+    fontWeight: '700',
+    color: '#991b1b',
+    fontSize: 16,
+  },
+  message: {
+    fontSize: 14,
+    color: '#991b1b',
+    textAlign: 'center',
+  },
+  retryButton: {
+    paddingHorizontal: 16,
+    paddingVertical: 8,
+    backgroundColor: '#dc2626',
+    borderRadius: 6,
+    marginTop: 4,
+  },
+  retryText: {
+    color: '#ffffff',
+    fontWeight: '600',
+    fontSize: 14,
+  },
+});

package/src/components/GguiProvider.tsx

@@ -0,0 +1,188 @@
+/**
+ * GguiProvider — React Native twin of `@ggui-ai/mcp-apps-react`'s
+ * `components/GguiProvider.tsx`.
+ *
+ * The provider surface mirrors the web copy: permission requests gate
+ * on `KNOWN_PERMISSION_NAMES`, `adapterImpls` is the runtime
+ * implementation slot only, and the context value shape feeds the
+ * same `GguiContext`.
+ *
+ * Platform delta (every intentional divergence from the web copy):
+ *
+ *   - Interface-context detection reads RN `Dimensions` / `PixelRatio`
+ *     (with rotation / split-screen change updates) instead of
+ *     `window`-based `detectInterfaceContext` + resize listener.
+ *   - RN-only props `reactVersion` / `designSystemUrl` feed the
+ *     WebView import map.
+ *   - No `apiBaseUrl` / `appMetadata` props and no app-config fetch —
+ *     RN hosts pass a pre-fetched `appConfig`; the web provider can
+ *     fetch it from the platform itself.
+ *
+ * Guarded by the structural twin gate in `../twin-parity.test.ts`
+ * (`DOCUMENTED_DELTA_TWINS`): exported surface must match the web
+ * copy.
+ */
+import { useState, useCallback, useEffect, useMemo, type ReactNode } from 'react';
+import { Dimensions, PixelRatio } from 'react-native';
+import type { AdapterPermissions, PermissionStatus, InterfaceContext, EndUserIdentity, AppDisplayConfig } from '@ggui-ai/protocol';
+import { KNOWN_PERMISSION_NAMES, UnknownPermissionNameError } from '@ggui-ai/protocol';
+import { GguiContext, type AdapterRegistry, type GguiContextValue } from '../context/GguiContext';
+
+const KNOWN_PERMISSION_NAMES_SET: ReadonlySet<string> = new Set(KNOWN_PERMISSION_NAMES);
+
+export { useGguiContext, useAdapter, type AdapterRegistry } from '../context/GguiContext';
+
+/**
+ * Props for the {@link GguiProvider} component.
+ */
+export interface GguiProviderProps {
+  appId: string;
+  wsEndpoint?: string;
+  /** Host-provided adapter implementations. Host apps or downstream
+   * capability packages augment {@link AdapterRegistry} via
+   * declaration merging so each slot is strongly typed. The grant
+   * model lives entirely on `clientCapabilities.gadgets[*].permission`
+   * — this is just the runtime implementation slot. */
+  adapterImpls?: AdapterRegistry;
+  /** Override auto-detected interface context */
+  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;
+  /**
+   * Custom handler for permission requests (e.g., camera, microphone).
+   *
+   * By default, all permissions are granted immediately. Provide a custom
+   * `permissionHandler` to integrate with your app's permission flow
+   * (e.g., react-native-permissions, expo-permissions, or a custom dialog).
+   *
+   * @param permission - The Web Permissions API name being requested
+   *   (e.g., `'camera'`, `'microphone'`, `'geolocation'`). The SDK
+   *   pre-validates the name against `KNOWN_PERMISSION_NAMES` before
+   *   invoking this handler, so an unknown name surfaces as a
+   *   `UnknownPermissionNameError` to the caller without ever
+   *   reaching the host's permission flow.
+   * @returns The resulting permission status
+   */
+  permissionHandler?: (permission: string) => Promise<PermissionStatus>;
+  /**
+   * App config (endpointUrl, defaultShellType, etc). Consumed by
+   * `useInvoke` for the Streamable Invoke Protocol v1.1 — pass this when
+   * you have a pre-fetched `AppDisplayConfig` (e.g. when the host fetches
+   * it from an API before mounting). Mirrors the web provider's
+   * `appConfig` prop.
+   */
+  appConfig?: AppDisplayConfig | null;
+  children: ReactNode;
+}
+
+function detectRNInterfaceContext(): InterfaceContext {
+  const { width, height } = Dimensions.get('window');
+  // Align breakpoints with getDeviceCategory() in interface-context.ts:
+  //   width < 768  -> phone
+  //   width < 1024 -> tablet
+  //   width >= 1024 -> desktop
+  const deviceType: 'phone' | 'tablet' | 'desktop' =
+    width < 768 ? 'phone' : width < 1024 ? 'tablet' : 'desktop';
+  return {
+    viewport: { width, height },
+    platform: 'mobile',
+    deviceType,
+    orientation: width >= height ? 'landscape' : 'portrait',
+    devicePixelRatio: PixelRatio.get(),
+    touchPrimary: true,
+  };
+}
+
+/**
+ * Root provider for the ggui React Native SDK.
+ *
+ * Wraps the application with shared configuration needed by all ggui hooks
+ * and components. Auto-detects interface context from React Native Dimensions
+ * and updates on rotation/split-screen changes.
+ *
+ * @example
+ * ```tsx
+ * <GguiProvider appId="my-app" wsEndpoint="wss://your-ws-gateway.example/">
+ *   <App />
+ * </GguiProvider>
+ * ```
+ */
+export function GguiProvider({ appId, wsEndpoint, adapterImpls, interfaceContext: interfaceContextProp, auth, hostSessionId, reactVersion, designSystemUrl, permissionHandler, appConfig, children }: GguiProviderProps) {
+  const [adapterPermissions, setAdapterPermissions] = useState<AdapterPermissions>({});
+
+  // Auto-detect interface context from React Native Dimensions
+  const [detectedContext, setDetectedContext] = useState<InterfaceContext>(detectRNInterfaceContext);
+
+  // Update on dimension changes (rotation, split-screen, etc.)
+  useEffect(() => {
+    const subscription = Dimensions.addEventListener('change', () => {
+      setDetectedContext(detectRNInterfaceContext());
+    });
+    return () => subscription.remove();
+  }, []);
+
+  const interfaceContext = interfaceContextProp || detectedContext;
+
+  const requestPermission = useCallback(
+    async (permission: string): Promise<PermissionStatus> => {
+      // Gate on `KNOWN_PERMISSION_NAMES` (the Web Permissions API
+      // enum). With no host-advertised `AdapterType[]` allow-list,
+      // the SDK is the last line of defense against typos or
+      // unsupported names slipping into the runtime cache.
+      if (!KNOWN_PERMISSION_NAMES_SET.has(permission)) {
+        throw new UnknownPermissionNameError({ observedName: permission });
+      }
+      const status: PermissionStatus = permissionHandler
+        ? await permissionHandler(permission)
+        : 'granted';
+      const key = permission as keyof AdapterPermissions;
+      setAdapterPermissions((prev) => ({ ...prev, [key]: status }));
+      return status;
+    },
+    [permissionHandler]
+  );
+
+  // `adapterImpls` is the runtime implementation slot ONLY. There is
+  // no manifest-level allow-list — grant decisions live on
+  // `clientCapabilities.gadgets[*].permission`. Pass all impls
+  // verbatim.
+  const resolvedAdapterImpls = useMemo<AdapterRegistry>(
+    () => (adapterImpls ?? {}) as AdapterRegistry,
+    [adapterImpls],
+  );
+
+  const value = useMemo<GguiContextValue>(
+    () => ({
+      appId,
+      wsEndpoint,
+      adapterPermissions,
+      adapterImpls: resolvedAdapterImpls,
+      requestPermission,
+      interfaceContext,
+      auth,
+      hostSessionId,
+      reactVersion,
+      designSystemUrl,
+      appConfig,
+    }),
+    [appId, wsEndpoint, adapterPermissions, resolvedAdapterImpls, requestPermission, interfaceContext, auth, hostSessionId, reactVersion, designSystemUrl, appConfig]
+  );
+
+  return <GguiContext.Provider value={value}>{children}</GguiContext.Provider>;
+}