feat(ui): add ext-apps v0.4.0 support

Add support for ext-apps v0.4.0 features:

- Add updateModelContext() method to inform AI model about app state
  without triggering follow-up actions
  - MCP Apps: Uses native protocol feature
  - ChatGPT: Uses setState/setWidgetState (which exposes to AI context)
- Add containerDimensions type for new viewport semantics (fixed vs flexible)
- Add new HostCapabilities: updateModelContext, message, sandbox
- Add useUpdateModelContext() React hook for model context updates
- Add tests for all new functionality

Breaking changes in ext-apps handled:
- containerDimensions replaces viewport (we derive viewport for backward compat)
- New capability types for content block modalities

Note: On ChatGPT, both setState and updateModelContext expose state to the
AI model. Use setState for persistence-focused use cases, updateModelContext
for context-focused use cases.

Author: claude

packages/ui-react/src/hooks.ts

@@ -14,6 +14,7 @@ import type {
   ModalResult,
   HostCapabilities,
   HostVersion,
+  UpdateModelContextParams,
 } from "@mcp-apps-kit/ui";
 import { clientDebugLogger, type ClientDebugLogger } from "@mcp-apps-kit/ui";
 import { useAppsContext } from "./context";
@@ -250,6 +251,57 @@ export function useWidgetState<S>(defaultValue: S): [S, (newState: S | ((prev: S
   return [state, setState];
 }
 
+// =============================================================================
+// MODEL CONTEXT HOOKS
+// =============================================================================
+
+/**
+ * Hook to update the host's model context
+ *
+ * Unlike sendMessage which triggers follow-up actions, context updates
+ * inform the model about app state without triggering responses.
+ *
+ * On MCP Apps: Sends context to host via updateModelContext
+ * On ChatGPT: Silent no-op (graceful degradation)
+ *
+ * @returns Function to update model context
+ *
+ * @example
+ * ```tsx
+ * function ShoppingCart({ items }) {
+ *   const updateContext = useUpdateModelContext();
+ *
+ *   // Keep the model informed about cart state
+ *   useEffect(() => {
+ *     updateContext({
+ *       structuredContent: {
+ *         itemCount: items.length,
+ *         total: calculateTotal(items),
+ *         currency: "USD"
+ *       }
+ *     });
+ *   }, [items, updateContext]);
+ *
+ *   return <CartUI items={items} />;
+ * }
+ * ```
+ */
+export function useUpdateModelContext(): (params: UpdateModelContextParams) => Promise<void> {
+  const { client } = useAppsContext();
+
+  return useCallback(
+    async (params: UpdateModelContextParams) => {
+      if (!client) {
+        // eslint-disable-next-line no-console
+        console.warn("[useUpdateModelContext] Client not available");
+        return;
+      }
+      await client.updateModelContext(params);
+    },
+    [client]
+  );
+}
+
 // =============================================================================
 // UTILITY HOOKS
 // =============================================================================

packages/ui-react/src/index.ts

@@ -17,6 +17,10 @@ export type {
   AppToolDefinition,
   CallToolHandler,
   ListToolsHandler,
+  // Model context types (ext-apps v0.4.0+)
+  ContainerDimensions,
+  ContentBlock,
+  UpdateModelContextParams,
 } from "@mcp-apps-kit/ui";
 
 // Context
@@ -51,6 +55,8 @@ export {
   useHostCapabilities,
   useHostVersion,
   useSizeChangedNotifications,
+  // Model context (ext-apps v0.4.0+)
+  useUpdateModelContext,
 } from "./hooks";
 
 // File operation types

packages/ui/src/adapters/mcp.ts

@@ -44,6 +44,8 @@ import type {
   SizeChangedParams,
   CallToolHandler,
   ListToolsHandler,
+  UpdateModelContextParams,
+  ContainerDimensions,
 } from "../types";
 
 /**
@@ -248,6 +250,7 @@ export class McpAdapter implements ProtocolAdapter {
       displayMode?: unknown;
       availableDisplayModes?: unknown;
       viewport?: unknown;
+      containerDimensions?: unknown;
       locale?: unknown;
       timeZone?: unknown;
       platform?: unknown;
@@ -274,11 +277,22 @@ export class McpAdapter implements ProtocolAdapter {
       ? ctx.availableDisplayModes.filter((m): m is string => typeof m === "string")
       : base.availableDisplayModes;
 
-    const isViewportObject = (v: unknown): v is Record<string, unknown> =>
+    const isObjectLike = (v: unknown): v is Record<string, unknown> =>
       v !== null && typeof v === "object" && !Array.isArray(v);
-    const viewport = isViewportObject(ctx.viewport)
-      ? { ...base.viewport, ...ctx.viewport }
-      : base.viewport;
+
+    // Parse containerDimensions (ext-apps v0.4.0+)
+    const containerDimensions = isObjectLike(ctx.containerDimensions)
+      ? (ctx.containerDimensions as ContainerDimensions)
+      : undefined;
+
+    // Derive viewport from containerDimensions for backward compatibility,
+    // or fall back to explicit viewport or defaults
+    let viewport = base.viewport;
+    if (containerDimensions) {
+      viewport = this.deriveViewportFromContainerDimensions(containerDimensions, base.viewport);
+    } else if (isObjectLike(ctx.viewport)) {
+      viewport = { ...base.viewport, ...ctx.viewport };
+    }
 
     const locale = typeof ctx.locale === "string" ? ctx.locale : base.locale;
     const timeZone = typeof ctx.timeZone === "string" ? ctx.timeZone : base.timeZone;
@@ -292,6 +306,7 @@ export class McpAdapter implements ProtocolAdapter {
       displayMode,
       availableDisplayModes,
       viewport,
+      containerDimensions,
       locale,
       timeZone,
       platform,
@@ -303,6 +318,23 @@ export class McpAdapter implements ProtocolAdapter {
     };
   }
 
+  /**
+   * Derive viewport dimensions from containerDimensions for backward compatibility.
+   * containerDimensions uses fixed (height/width) vs flexible (maxHeight/maxWidth) semantics.
+   */
+  private deriveViewportFromContainerDimensions(
+    dims: ContainerDimensions,
+    defaults: HostContext["viewport"]
+  ): HostContext["viewport"] {
+    const d = dims as Record<string, unknown>;
+    return {
+      width: typeof d.width === "number" ? d.width : defaults.width,
+      height: typeof d.height === "number" ? d.height : defaults.height,
+      maxWidth: typeof d.maxWidth === "number" ? d.maxWidth : undefined,
+      maxHeight: typeof d.maxHeight === "number" ? d.maxHeight : undefined,
+    };
+  }
+
   private extractToolMeta(rawHostContext: unknown): Record<string, unknown> | undefined {
     if (rawHostContext === null || typeof rawHostContext !== "object") return undefined;
     const hc = rawHostContext as { toolInfo?: unknown };
@@ -388,6 +420,42 @@ export class McpAdapter implements ProtocolAdapter {
     });
   }
 
+  // === Model Context ===
+
+  async updateModelContext(params: UpdateModelContextParams): Promise<void> {
+    if (!this.app) {
+      throw new UIError(UIErrorCode.NOT_CONNECTED, "MCP Apps adapter not connected");
+    }
+
+    // Map our content blocks to ext-apps format
+    const content = params.content?.map((block) => {
+      switch (block.type) {
+        case "text":
+          return { type: "text" as const, text: block.text ?? "" };
+        case "image":
+          return {
+            type: "image" as const,
+            data: block.data ?? "",
+            mimeType: block.mimeType ?? "image/png",
+          };
+        case "audio":
+          return {
+            type: "audio" as const,
+            data: block.data ?? "",
+            mimeType: block.mimeType ?? "audio/wav",
+          };
+        default:
+          // For resource types, fall back to text representation
+          return { type: "text" as const, text: block.text ?? block.uri ?? "" };
+      }
+    });
+
+    await this.app.updateModelContext({
+      content,
+      structuredContent: params.structuredContent,
+    });
+  }
+
   // === Navigation ===
 
   async openLink(url: string): Promise<void> {
@@ -548,19 +616,19 @@ export class McpAdapter implements ProtocolAdapter {
     // Map MCP Apps SDK capabilities to our unified interface.
     // MCP SDK already provides: logging, openLinks, serverResources, serverTools
     // We augment with common abstraction fields for protocol-agnostic usage.
-    const sdkCaps = mcpCaps as HostCapabilities;
+    const sdkCaps = mcpCaps as Record<string, unknown>;
 
     // Extract available display modes from host context if provided
     const hostContext = this.app.getHostContext();
     const availableModes = hostContext?.availableDisplayModes as string[] | undefined;
 
     return {
       // MCP SDK native capabilities (priority)
-      logging: sdkCaps.logging,
-      openLinks: sdkCaps.openLinks,
-      serverResources: sdkCaps.serverResources,
-      serverTools: sdkCaps.serverTools,
-      experimental: sdkCaps.experimental,
+      logging: sdkCaps.logging as HostCapabilities["logging"],
+      openLinks: sdkCaps.openLinks as HostCapabilities["openLinks"],
+      serverResources: sdkCaps.serverResources as HostCapabilities["serverResources"],
+      serverTools: sdkCaps.serverTools as HostCapabilities["serverTools"],
+      experimental: sdkCaps.experimental as HostCapabilities["experimental"],
 
       // Common capabilities derived from host context when available
       theming: {
@@ -578,6 +646,11 @@ export class McpAdapter implements ProtocolAdapter {
       sizeNotifications: {},
       partialToolInput: {},
       appTools: { listChanged: false },
+
+      // ext-apps v0.4.0+ capabilities
+      updateModelContext: sdkCaps.updateModelContext as HostCapabilities["updateModelContext"],
+      message: sdkCaps.message as HostCapabilities["message"],
+      sandbox: sdkCaps.sandbox as HostCapabilities["sandbox"],
     };
   }
 

packages/ui/src/adapters/mock.ts

@@ -17,6 +17,7 @@ import type {
   SizeChangedParams,
   CallToolHandler,
   ListToolsHandler,
+  UpdateModelContextParams,
 } from "../types";
 
 /**
@@ -135,6 +136,24 @@ export class MockAdapter implements ProtocolAdapter {
     console.log("[MockAdapter] sendMessage:", content);
   }
 
+  // === Model Context ===
+
+  /** Last model context params (for testing) */
+  private lastModelContext?: UpdateModelContextParams;
+
+  async updateModelContext(params: UpdateModelContextParams): Promise<void> {
+    this.lastModelContext = params;
+    // eslint-disable-next-line no-console
+    console.log("[MockAdapter] updateModelContext:", params);
+  }
+
+  /**
+   * Get the last model context params (for testing)
+   */
+  getLastModelContext(): UpdateModelContextParams | undefined {
+    return this.lastModelContext;
+  }
+
   // === Navigation ===
 
   async openLink(url: string): Promise<void> {

packages/ui/src/adapters/openai.ts

@@ -16,6 +16,7 @@ import type {
   SizeChangedParams,
   CallToolHandler,
   ListToolsHandler,
+  UpdateModelContextParams,
 } from "../types";
 import type { DebugTransport, LogEntry } from "../debug/logger";
 import { clientDebugLogger } from "../debug/logger";
@@ -523,6 +524,45 @@ export class OpenAIAdapter implements ProtocolAdapter {
     }
   }
 
+  // === Model Context ===
+
+  /**
+   * Update model context (ext-apps v0.4.0+)
+   *
+   * On ChatGPT, we use setState (which calls setWidgetState) to expose data
+   * to the model. setWidgetState in ChatGPT flows into AI context - anything
+   * passed to it will be shown to the model.
+   *
+   * Note: Unlike MCP Apps where this is purely context, on ChatGPT
+   * this also persists the state for the widget session.
+   */
+  async updateModelContext(params: UpdateModelContextParams): Promise<void> {
+    // Build a context object to send to the model via setState/setWidgetState
+    const modelContext: Record<string, unknown> = {
+      _type: "modelContext",
+    };
+
+    // Add structured content directly
+    if (params.structuredContent) {
+      Object.assign(modelContext, params.structuredContent);
+    }
+
+    // Convert content blocks to text representation for the model
+    if (params.content && params.content.length > 0) {
+      const textContent = params.content
+        .filter((block) => block.type === "text" && block.text)
+        .map((block) => block.text)
+        .join("\n");
+      if (textContent) {
+        modelContext._textContent = textContent;
+      }
+    }
+
+    // Use existing setState which calls setWidgetState
+    this.setState(modelContext);
+    clientDebugLogger.debug("[OpenAI Adapter] updateModelContext via setState:", modelContext);
+  }
+
   // === Navigation ===
 
   async openLink(url: string): Promise<void> {

packages/ui/src/adapters/types.ts

@@ -15,6 +15,7 @@ import type {
   SizeChangedParams,
   CallToolHandler,
   ListToolsHandler,
+  UpdateModelContextParams,
 } from "../types";
 import type { LogEntry } from "../debug/logger";
 
@@ -68,6 +69,18 @@ export interface ProtocolAdapter {
    */
   sendMessage(content: { type: string; text: string }): Promise<void>;
 
+  // === Model Context ===
+
+  /**
+   * Update the host's model context with app state (ext-apps v0.4.0+)
+   *
+   * On MCP Apps: Calls app.updateModelContext()
+   * On ChatGPT: Silent no-op (graceful degradation)
+   *
+   * @param params - Context content and/or structured content
+   */
+  updateModelContext(params: UpdateModelContextParams): Promise<void>;
+
   // === Navigation ===
 
   /**

packages/ui/src/client.ts

@@ -20,6 +20,7 @@ import type {
   CallToolHandler,
   ListToolsHandler,
   ToolMethods,
+  UpdateModelContextParams,
 } from "./types";
 import type { ProtocolAdapter } from "./adapters/types";
 
@@ -117,6 +118,12 @@ export function createAppsClient<T extends ToolDefs = ToolDefs>(
       await adapter.sendMessage({ type: "text", text: prompt });
     },
 
+    // === Model Context ===
+
+    async updateModelContext(params: UpdateModelContextParams): Promise<void> {
+      await adapter.updateModelContext(params);
+    },
+
     // === Navigation ===
 
     async openLink(url: string): Promise<void> {

packages/ui/src/index.ts

@@ -26,6 +26,7 @@
 
 export type {
   Viewport,
+  ContainerDimensions,
   SafeAreaInsets,
   DeviceCapabilities,
   HostStyles,
@@ -52,6 +53,9 @@ export type {
   AppToolDefinition,
   CallToolHandler,
   ListToolsHandler,
+  // Model context types (ext-apps v0.4.0+)
+  ContentBlock,
+  UpdateModelContextParams,
 } from "./types";
 
 // Constants