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

package/src/components/UiFeedback.tsx

@@ -0,0 +1,233 @@
+/**
+ * UiFeedback — a small, dismissable rating affordance for the render
+ * shell chrome ("did this generated UI work for you?").
+ *
+ * Platform delta (vs `ggui-react/src/components/UiFeedback.tsx`):
+ *   - DOM elements (`div` / `button` / `form` / `input`) become RN
+ *     primitives (`View` / `Pressable` / `Text` / `TextInput`).
+ *   - Inline styles with `--ggui-*` CSS-variable hooks become
+ *     `StyleSheet.create` constants carrying the same neutral palette
+ *     the web copy uses as its variable fallbacks (RN has no CSS
+ *     variable layer).
+ *   - `data-ggui-ui-feedback*` styling/test hooks become `testID`s
+ *     (`ggui-ui-feedback`, `ggui-ui-feedback-verdict-<verdict>`, …).
+ *   - The comment `<form>` submit becomes a Send `Pressable` plus the
+ *     `TextInput`'s `onSubmitEditing` (keyboard return key).
+ *   - `role` / `aria-label` become `accessibilityLabel` /
+ *     `accessibilityRole` props.
+ * The exported surface is identical to the web copy — pinned by the
+ * twin-parity gate (`DOCUMENTED_DELTA_TWINS`).
+ *
+ * Three verdicts — Love / Dislike / Other (free-text comment) — plus a
+ * dismiss control. Entirely host-driven: the component renders NOTHING
+ * unless the host passes `onUiFeedback`, so deployments that don't
+ * collect feedback never show a dead affordance. Where the payload
+ * goes is the host's choice — a logger, an analytics client, a support
+ * inbox; this component only builds the typed {@link UiFeedbackPayload}
+ * and hands it over.
+ *
+ * Zero wire surface: feedback never crosses the agent ↔ UI contract.
+ * It is host-app chrome (Data vs Behavior — the agent cannot observe
+ * it from the wire, so it is not protocol data), which is why the
+ * payload leaves through a host callback rather than a contract spec.
+ *
+ * Two mount surfaces exist for this affordance (ggui#244):
+ *
+ *   1. THIS component — chrome in the host's own tree, next to a
+ *      render surface the host controls; the payload leaves through
+ *      `onUiFeedback`.
+ *   2. The in-iframe twin the `@ggui-ai/iframe-runtime` boot path
+ *      mounts inside a served render iframe whenever a parent window
+ *      exists (`window.parent !== window` — top-level tabs get
+ *      neither surface); its payload leaves as a `ui-feedback`
+ *      observability event on the `ggui:observe` postMessage seam,
+ *      surfaced to hosts via `<McpAppIframe onObserve>`.
+ *
+ * Hosts wire exactly ONE surface — either pass `onUiFeedback` here
+ * and ignore the `ui-feedback` observe arm, or handle the observe arm
+ * and omit `onUiFeedback`. Wiring both shows the user two affordances
+ * for one render. The render-nothing-without-a-sink default makes the
+ * choice safe: omitting `onUiFeedback` fully disables this surface.
+ */
+import { useCallback, useState } from 'react';
+import { Pressable, StyleSheet, Text, TextInput, View } from 'react-native';
+
+/** The three feedback verdicts the affordance can emit. */
+export type UiFeedbackVerdict = 'love' | 'dislike' | 'other';
+
+/**
+ * Payload handed to {@link UiFeedbackProps.onUiFeedback}. Context
+ * fields are present exactly when the host supplied them as props;
+ * `comment` is present only for `verdict: 'other'` with a non-empty
+ * trimmed comment.
+ */
+export interface UiFeedbackPayload {
+  verdict: UiFeedbackVerdict;
+  comment?: string;
+  /** GguiSession id of the render the feedback is about. */
+  sessionId?: string;
+  /** Tool that produced the render (e.g. `ggui_render`). */
+  toolName?: string;
+}
+
+export interface UiFeedbackProps {
+  /**
+   * Feedback sink. Absent = the affordance renders nothing at all —
+   * zero-config hosts never show a dead control.
+   */
+  onUiFeedback?: (feedback: UiFeedbackPayload) => void;
+  /** GguiSession id to stamp onto every emitted payload. */
+  sessionId?: string;
+  /** Producing tool name to stamp onto every emitted payload. */
+  toolName?: string;
+}
+
+type Phase = 'idle' | 'comment' | 'sent' | 'dismissed';
+
+export function UiFeedback({ onUiFeedback, sessionId, toolName }: UiFeedbackProps) {
+  const [phase, setPhase] = useState<Phase>('idle');
+  const [comment, setComment] = useState('');
+
+  const emit = useCallback(
+    (verdict: UiFeedbackVerdict, commentText?: string) => {
+      if (!onUiFeedback) return;
+      const trimmed = commentText?.trim();
+      onUiFeedback({
+        verdict,
+        ...(trimmed !== undefined && trimmed.length > 0 ? { comment: trimmed } : {}),
+        ...(sessionId !== undefined ? { sessionId } : {}),
+        ...(toolName !== undefined ? { toolName } : {}),
+      });
+      setPhase('sent');
+    },
+    [onUiFeedback, sessionId, toolName],
+  );
+
+  const onCommentSubmit = useCallback(() => {
+    emit('other', comment);
+  }, [emit, comment]);
+
+  // Hidden entirely: no sink wired, or the user dismissed it.
+  if (!onUiFeedback || phase === 'dismissed') return null;
+
+  return (
+    <View
+      testID="ggui-ui-feedback"
+      accessibilityLabel="Share feedback on this UI"
+      style={styles.root}
+    >
+      {phase === 'sent' ? (
+        <Text testID="ggui-ui-feedback-thanks" style={styles.thanksText}>
+          Thanks for the feedback
+        </Text>
+      ) : phase === 'comment' ? (
+        <View style={styles.commentForm} testID="ggui-ui-feedback-comment-form">
+          <TextInput
+            value={comment}
+            onChangeText={setComment}
+            onSubmitEditing={onCommentSubmit}
+            placeholder="What happened?"
+            accessibilityLabel="Feedback comment"
+            testID="ggui-ui-feedback-comment"
+            style={styles.commentInput}
+            autoFocus
+          />
+          <Pressable
+            accessibilityRole="button"
+            style={styles.verdictButton}
+            testID="ggui-ui-feedback-send"
+            onPress={onCommentSubmit}
+          >
+            <Text style={styles.verdictText}>Send</Text>
+          </Pressable>
+        </View>
+      ) : (
+        <>
+          <Pressable
+            accessibilityRole="button"
+            style={styles.verdictButton}
+            testID="ggui-ui-feedback-verdict-love"
+            onPress={() => emit('love')}
+          >
+            <Text style={styles.verdictText}>Love</Text>
+          </Pressable>
+          <Pressable
+            accessibilityRole="button"
+            style={styles.verdictButton}
+            testID="ggui-ui-feedback-verdict-dislike"
+            onPress={() => emit('dislike')}
+          >
+            <Text style={styles.verdictText}>Dislike</Text>
+          </Pressable>
+          <Pressable
+            accessibilityRole="button"
+            style={styles.verdictButton}
+            testID="ggui-ui-feedback-verdict-other"
+            onPress={() => setPhase('comment')}
+          >
+            <Text style={styles.verdictText}>Other…</Text>
+          </Pressable>
+        </>
+      )}
+      <Pressable
+        accessibilityRole="button"
+        accessibilityLabel="Dismiss feedback"
+        style={styles.dismissButton}
+        testID="ggui-ui-feedback-dismiss"
+        onPress={() => setPhase('dismissed')}
+      >
+        <Text style={styles.dismissText}>{'×'}</Text>
+      </Pressable>
+    </View>
+  );
+}
+
+// Neutral palette mirrors the web copy's CSS-variable fallbacks.
+const styles = StyleSheet.create({
+  root: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    alignSelf: 'flex-start',
+    gap: 4,
+  },
+  thanksText: {
+    fontSize: 12,
+    color: '#6b7280',
+  },
+  verdictButton: {
+    backgroundColor: '#f9fafb',
+    borderWidth: 1,
+    borderColor: '#e5e7eb',
+    borderRadius: 4,
+    paddingVertical: 2,
+    paddingHorizontal: 8,
+  },
+  verdictText: {
+    fontSize: 12,
+    color: '#4b5563',
+  },
+  dismissButton: {
+    paddingVertical: 2,
+    paddingHorizontal: 4,
+  },
+  dismissText: {
+    fontSize: 12,
+    color: '#9ca3af',
+  },
+  commentForm: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: 4,
+  },
+  commentInput: {
+    fontSize: 12,
+    paddingVertical: 2,
+    paddingHorizontal: 6,
+    minWidth: 140,
+    borderWidth: 1,
+    borderColor: '#e5e7eb',
+    borderRadius: 4,
+    backgroundColor: '#ffffff',
+    color: '#1f2937',
+  },
+});

package/src/components/mcp-apps-bridge.ts

@@ -0,0 +1,388 @@
+/**
+ * Generic MCP-Apps host-role bridge helpers — the transport-agnostic
+ * JSON-RPC dispatcher plus the native WebView shim builders.
+ *
+ * Extracted from the (now-deleted) `McpAppsGguiSessionRenderer` component
+ * so the spec-canonical `<McpAppIframe>` can still reuse the bridge
+ * surface without dragging in the render-bound legacy renderer.
+ *
+ * Both transports — the web iframe postMessage bridge and the native
+ * `react-native-webview` `onMessage`/`injectJavaScript` bridge —
+ * compute responses to embedded views' JSON-RPC requests via the
+ * single {@link handleHostBridgeRequest} switch. Keeping one dispatcher
+ * keeps the protocol surface identical across platforms; the
+ * transports differ, the methods do not.
+ *
+ * Adapter boundary rule — ENFORCED:
+ *   - Lifecycle messages from the embedded view do NOT mutate outer
+ *     ggui render state, actionSpec, streamSpec, or any core contract.
+ *   - Everything the view can do reduces to (a) self-render, and
+ *     (b) call source-server tools through the ggui server's
+ *     `/mcp-apps/tools-call` proxy. No side channels.
+ */
+
+import { Linking, Platform } from 'react-native';
+import type { McpAppsGguiSession } from '@ggui-ai/protocol/integrations/mcp-apps';
+import {
+  LATEST_PROTOCOL_VERSION,
+  McpUiUpdateModelContextRequestSchema,
+  type McpUiInitializeResult,
+  type McpUiUpdateModelContextRequest,
+} from '@modelcontextprotocol/ext-apps';
+
+interface JsonRpcRequest {
+  jsonrpc?: '2.0';
+  id?: number | string;
+  method?: string;
+  params?: Record<string, unknown>;
+}
+
+interface JsonRpcResponse {
+  jsonrpc: '2.0';
+  id: number | string;
+  result?: Record<string, unknown>;
+  error?: { code: number; message: string };
+}
+
+interface JsonRpcNotification {
+  jsonrpc: '2.0';
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+export interface HostBridgeContext {
+  readonly sessionId: string;
+  readonly render: McpAppsGguiSession;
+  readonly toolsCallUrl: string;
+  readonly locale?: string;
+  readonly containerDimensions?: McpAppsGguiSession['containerDimensions'];
+  /**
+   * Optional `ui/update-model-context` sink — see the McpAppIframe
+   * prop of the same name. Absent ⇒ the honest `method_not_supported`.
+   */
+  readonly onUpdateModelContext?: (
+    params: McpUiUpdateModelContextRequest['params'],
+  ) => Promise<void> | void;
+}
+
+/**
+ * Shared host-role method dispatcher. Returns a JSON-RPC response or
+ * `null` when the request is a malformed / untrusted frame the host
+ * should drop silently (no response).
+ *
+ * Exported for test coverage; production callers come through the web
+ * iframe listener or the native `onMessage` handler in
+ * {@link McpAppIframe}.
+ */
+export async function handleHostBridgeRequest(
+  req: JsonRpcRequest,
+  ctx: HostBridgeContext,
+): Promise<JsonRpcResponse | null> {
+  if (!req || typeof req !== 'object') return null;
+  if (req.jsonrpc !== '2.0' || typeof req.method !== 'string') return null;
+  // Notifications (no `id`) get no response — they're fire-and-forget.
+  const id = req.id;
+
+  switch (req.method) {
+    case 'ping': {
+      return {
+        jsonrpc: '2.0',
+        id: id ?? 0,
+        result: { pong: true },
+      };
+    }
+    case 'ui/initialize': {
+      // Spec-canonical `McpUiInitializeResult` — the ext-apps
+      // `App.connect` inside the embedded page zod-requires
+      // `protocolVersion` + `hostInfo` + `hostCapabilities` +
+      // `hostContext`; the pre-App draft shape fails that gate and
+      // kills the mount before the renderer boots. Adapter boundary —
+      // `hostContext` carries `{locale, containerDimensions}` ONLY,
+      // NO outer render state leaks here (ggui theming rides the
+      // `ai.ggui/render.theme` slice, never this handshake).
+      const requestedRaw = req.params?.protocolVersion;
+      const requested =
+        typeof requestedRaw === 'string' && requestedRaw.length > 0
+          ? requestedRaw
+          : LATEST_PROTOCOL_VERSION;
+      const result: McpUiInitializeResult = {
+        protocolVersion: requested,
+        // Diagnostic-only; no build-stamp machinery in this tsc-built
+        // package — see the McpAppIframe dispatcher's identical note.
+        hostInfo: { name: 'ggui-react-native', version: 'unstamped' },
+        hostCapabilities: {},
+        hostContext: {
+          locale:
+            ctx.locale ??
+            (typeof navigator !== 'undefined' ? navigator.language : 'en-US'),
+          containerDimensions: ctx.containerDimensions ?? {},
+        },
+      };
+      return { jsonrpc: '2.0', id: id ?? 0, result };
+    }
+    case 'ui/open-link': {
+      // iframe asks the host to open a URL out-of-band (system browser
+      // on native, new tab on web). ENFORCEMENT stays at the proxy —
+      // this method does NOT call any MCP tool and does NOT carry
+      // credentials; it's a platform-level link hand-off.
+      const url = typeof req.params?.url === 'string' ? req.params.url : '';
+      // Validate scheme. Anything other than http(s) is rejected so an
+      // iframe can't trick the host into opening `file://`, `javascript:`,
+      // arbitrary URI schemes, etc.
+      if (!/^https?:\/\//i.test(url)) {
+        return {
+          jsonrpc: '2.0',
+          id: id ?? 0,
+          error: { code: -32602, message: 'ui/open-link requires http(s) url' },
+        };
+      }
+      try {
+        if (Platform.OS === 'web') {
+          if (typeof window !== 'undefined') {
+            window.open(url, '_blank', 'noopener,noreferrer');
+          }
+        } else {
+          await Linking.openURL(url);
+        }
+        return { jsonrpc: '2.0', id: id ?? 0, result: { opened: true } };
+      } catch (err) {
+        return {
+          jsonrpc: '2.0',
+          id: id ?? 0,
+          error: { code: -32000, message: `open_link_failed: ${String(err)}` },
+        };
+      }
+    }
+    case 'tools/call': {
+      const tool = typeof req.params?.name === 'string' ? req.params.name : '';
+      const args =
+        req.params?.arguments && typeof req.params.arguments === 'object'
+          ? (req.params.arguments as Record<string, unknown>)
+          : {};
+      if (!tool) {
+        return {
+          jsonrpc: '2.0',
+          id: id ?? 0,
+          error: { code: -32602, message: 'tools/call requires params.name' },
+        };
+      }
+      try {
+        const resp = await fetch(ctx.toolsCallUrl, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            session: ctx.sessionId,
+            tool,
+            arguments: args,
+          }),
+        });
+        if (!resp.ok) {
+          const body = (await resp.json().catch(() => ({}))) as {
+            error?: string;
+          };
+          return {
+            jsonrpc: '2.0',
+            id: id ?? 0,
+            error: {
+              code: resp.status === 403 ? -32003 : -32000,
+              message: body.error ?? `proxy_error_${resp.status}`,
+            },
+          };
+        }
+        const result = (await resp.json()) as Record<string, unknown>;
+        return { jsonrpc: '2.0', id: id ?? 0, result };
+      } catch (err) {
+        return {
+          jsonrpc: '2.0',
+          id: id ?? 0,
+          error: {
+            code: -32000,
+            message: `proxy_fetch_failed: ${String(err)}`,
+          },
+        };
+      }
+    }
+    case 'ui/update-model-context': {
+      // Forwarded to the caller's sink when wired; without one the
+      // honest answer stays `method_not_supported` — acking context
+      // we did not carry anywhere would mislead the app
+      // (first-integrator report, ggui#425 fourth finding).
+      if (ctx.onUpdateModelContext === undefined) {
+        return {
+          jsonrpc: '2.0',
+          id: id ?? 0,
+          error: { code: -32601, message: 'method_not_supported' },
+        };
+      }
+      const parsed = McpUiUpdateModelContextRequestSchema.safeParse({
+        method: 'ui/update-model-context',
+        params: req.params,
+      });
+      if (!parsed.success) {
+        return {
+          jsonrpc: '2.0',
+          id: id ?? 0,
+          error: { code: -32602, message: 'invalid ui/update-model-context params' },
+        };
+      }
+      await ctx.onUpdateModelContext(parsed.data.params);
+      return { jsonrpc: '2.0', id: id ?? 0, result: {} };
+    }
+    default: {
+      return {
+        jsonrpc: '2.0',
+        id: id ?? 0,
+        error: { code: -32601, message: 'method_not_supported' },
+      };
+    }
+  }
+}
+
+// =============================================================================
+// Native WebView bridge
+// =============================================================================
+//
+// The injected shim aliases `window.parent.postMessage` onto
+// `window.ReactNativeWebView.postMessage` so MCP Apps pages authored
+// against the iframe-host contract work unchanged in a top-level
+// WebView (where `window.parent === window`).
+//
+// Wire format — wrap the original payload so the RN side can
+// distinguish MCP Apps traffic from other message events the embedded
+// page might legitimately generate.
+export const NATIVE_BRIDGE_ENVELOPE_KEY = '__ggui_mcp_apps';
+
+/** Script injected BEFORE the page's own scripts run. */
+export function buildInjectedBridgeScript(): string {
+  // The `true;` trailer is required by react-native-webview on iOS for
+  // injected strings; without it iOS's JS runtime returns an `undefined`
+  // result that confuses the loader.
+  return `
+(function() {
+  try {
+    if (window.__gguiMcpAppsBridge) return;
+    window.__gguiMcpAppsBridge = { version: 1 };
+
+    function forward(msg) {
+      try {
+        if (window.ReactNativeWebView && typeof window.ReactNativeWebView.postMessage === 'function') {
+          window.ReactNativeWebView.postMessage(JSON.stringify({
+            ${JSON.stringify(NATIVE_BRIDGE_ENVELOPE_KEY)}: true,
+            payload: msg,
+          }));
+        }
+      } catch (_e) {}
+    }
+
+    // Intercept page → host posts.
+    //
+    // MCP Apps hosted as iframes use \`window.parent.postMessage(msg, '*')\`.
+    // Inside react-native-webview \`window.parent === window\`, so calls
+    // hit \`window.postMessage\`. Override it to forward to the RN bridge
+    // instead of firing a same-window message event.
+    var origPostMessage = window.postMessage;
+    window.postMessage = function(data /*, targetOrigin */) {
+      forward(data);
+    };
+    // ONE stable parent proxy — first-integrator device finding
+    // (ggui#425): a getter that mints a fresh object per access breaks
+    // every transport that checks \`event.source === window.parent\`
+    // (two reads can never be equal).
+    var parentProxy = { postMessage: forward };
+    // Explicit \`parent.postMessage\` aliasing — some engines reify
+    // \`window.parent\` lazily, so overriding it on \`window\` is the
+    // canonical safety net.
+    try {
+      Object.defineProperty(window, 'parent', {
+        configurable: true,
+        get: function() {
+          return parentProxy;
+        },
+      });
+    } catch (_e) {
+      // If \`parent\` is non-configurable on this engine, leave the
+      // \`window.postMessage\` override in place — it covers the
+      // \`window.parent === window\` loopback for us.
+    }
+
+    // Host → page delivery channel. WebKit rejects a synthesized
+    // \`MessageEvent\` whose \`source\` is a plain object (must be a
+    // WindowProxy / MessagePort / null) — the TypeError was swallowed
+    // and no host response ever reached the renderer (first-integrator
+    // device finding, ggui#425). Sidestep event-construction legality
+    // entirely: capture \`message\` listeners at document-start (this
+    // script runs via injectedJavaScriptBeforeContentLoaded, so the
+    // wrappers are in place before any page script registers) and
+    // deliver by direct invocation with an event-shaped object whose
+    // \`source\` IS the stable parent proxy.
+    var messageListeners = [];
+    var origAdd = window.addEventListener ? window.addEventListener.bind(window) : null;
+    window.addEventListener = function(type, fn, opts) {
+      if (type === 'message' && typeof fn === 'function') messageListeners.push(fn);
+      if (origAdd) return origAdd(type, fn, opts);
+    };
+    var origRemove = window.removeEventListener ? window.removeEventListener.bind(window) : null;
+    window.removeEventListener = function(type, fn, opts) {
+      if (type === 'message') {
+        var i = messageListeners.indexOf(fn);
+        if (i !== -1) messageListeners.splice(i, 1);
+      }
+      if (origRemove) return origRemove(type, fn, opts);
+    };
+    window.__gguiDeliver = function(data) {
+      var ev = { type: 'message', data: data, source: parentProxy, origin: '' };
+      var snapshot = messageListeners.slice();
+      for (var i = 0; i < snapshot.length; i++) {
+        try { snapshot[i](ev); } catch (_e) {}
+      }
+      if (typeof window.onmessage === 'function') {
+        try { window.onmessage(ev); } catch (_e) {}
+      }
+    };
+
+    // Mark that the shim loaded; tests and diagnostics may read this.
+    window.__gguiMcpAppsBridge.ready = true;
+  } catch (_e) {}
+})();
+true;
+`;
+}
+
+/**
+ * Build a script that delivers a host → WebView JSON-RPC message to the
+ * embedded page. Escaped for safe injection — every caller-controlled
+ * string lands inside a JSON.parse'd literal, never as a JS identifier.
+ *
+ * Delivery goes through the injected bridge's `window.__gguiDeliver`
+ * (direct listener invocation with `source` = the stable parent proxy)
+ * rather than a synthesized `MessageEvent`: WebKit rejects a
+ * `MessageEvent` whose `source` is a plain object, and the resulting
+ * TypeError was silently swallowed — no host response ever reached the
+ * renderer (first-integrator device finding, ggui#425). The
+ * `dispatchEvent` fallback below only runs when the bridge failed to
+ * inject; it omits `source` (null is legal everywhere) as a
+ * best-effort path for transports that don't check event provenance.
+ */
+export function buildDeliveryScript(
+  message: JsonRpcResponse | JsonRpcNotification,
+): string {
+  // JSON.stringify produces valid JS when re-embedded as the argument
+  // to JSON.parse. This is the canonical safe-injection pattern for
+  // WebView.injectJavaScript — no string concatenation of untrusted
+  // fields into executable JS.
+  const json = JSON.stringify(JSON.stringify(message));
+  return `
+(function() {
+  try {
+    var data = JSON.parse(${json});
+    if (typeof window.__gguiDeliver === 'function') {
+      window.__gguiDeliver(data);
+    } else {
+      var ev = new MessageEvent('message', { data: data });
+      window.dispatchEvent(ev);
+    }
+  } catch (_e) {}
+})();
+true;
+`;
+}