@agent-native/core 0.22.19 → 0.22.21

package/docs/content/actions.md

@@ -199,13 +199,24 @@ export default defineAction({
 This advertises the MCP Apps extension (`io.modelcontextprotocol/ui`), exposes the HTML via MCP resources/templates, and includes standard MCP Apps plus ChatGPT Apps SDK widget metadata for compatible hosts. Keep `link` as the fallback for CLI and non-UI MCP clients; see [External Agents](/docs/external-agents#mcp-apps).
 
 The helper launches the action's `link` target through `/_agent-native/embed/start` with a short-lived browser session, so routes such as full dashboards, filtered inboxes, drafts, and extension pages can reuse the app's React components directly.
+Standard hosts navigate the MCP App frame directly to that signed route.
+Claude web uses a single-frame transplant path that hydrates the signed app
+HTML inside Claude's MCP App iframe because Claude does not reliably allow
+app-owned child iframes or external frame navigation. ChatGPT web uses a
+controlled route iframe for stable `window.openai` host APIs and bounded height
+control.
 
 Embedded routes can use the exported client helpers for the MCP App host
-bridge. Under the hood, routes receive `agentNative.mcpHostContext` and may
-post `agentNative.mcpHost.updateModelContext`,
-`agentNative.mcpHost.openLink`, or
-`agentNative.mcpHost.requestDisplayMode`; the wrapper replies with
-`agentNative.mcpHost.response`.
+bridge. Direct route embeds and Claude's transplanted route post standard
+`ui/*` JSON-RPC messages to the host, while the ChatGPT controlled-frame path
+and explicit diagnostic iframe path proxy `agentNative.mcpHost.*` messages
+through the launch wrapper.
+When a submitted app prompt should continue the host chat, call
+`sendToAgentChat()` from the embedded route; it sends hidden model context and
+then posts a visible user message through the host bridge where supported.
+Design those routes with their own scrolling, because the MCP resource reports
+a bounded inline height rather than asking the host to size itself to the full
+app document.
 
 ## Standard actions {#standard-actions}
 

package/docs/content/external-agents.md

@@ -219,38 +219,64 @@ Claude Code and other CLI-first clients still receive the same resources and met
 
 MCP App embeds are route embeds, not separate mini-products. `embedApp()`
 starts from the action's `link` target, creates a short-lived embed session,
-and by default navigates the MCP App frame itself to that app route. That keeps
-Claude and ChatGPT on a single iframe instead of relying on a nested app iframe.
-Design embedded routes so a reload with the same URL reconstructs the same view.
+and launches that signed app route. Standard MCP Apps hosts can navigate the
+MCP App frame itself when the host can hydrate the route directly. Claude web
+uses a single-frame transplant path: the resource document fetches the signed
+app HTML and hydrates it inside Claude's MCP App iframe because Claude does not
+reliably allow app-owned child iframes or external frame navigation. ChatGPT
+web gets a controlled route iframe because its Apps bridge gives us stable
+`window.openai` host APIs and bounded height control. All paths point at the
+same signed app route and render the normal route and React components. Design
+embedded routes so a reload with the same signed URL reconstructs the same
+view.
 
 ChatGPT gets a dedicated compatibility path through `window.openai`: the launch
 document reads `toolInput`, `toolOutput`, and `toolResponseMetadata` directly,
 then calls `create_embed_session` via `window.openai.callTool(...)`. Standard
-MCP Apps hosts use the `ui/*` JSON-RPC bridge. After the direct navigation, the
-loaded app route can still call `ui/update-model-context`, `ui/message`,
-`ui/open-link`, and `ui/request-display-mode` through the host bridge helpers.
-Keep the result shape identical for both paths: return a focused `link` and
-concise structured content.
-
-An explicit nested iframe diagnostic path remains available with
+MCP Apps hosts use the `ui/*` JSON-RPC bridge. Directly hydrated routes can
+call `ui/update-model-context`, `ui/message`, `ui/open-link`, and
+`ui/request-display-mode` through the host bridge helpers. Claude's
+transplanted route uses the same direct `ui/*` host bridge after hydration.
+When the ChatGPT or explicit diagnostic iframe path is used, the wrapper
+relays the same host actions over `agentNative.mcpHost.*` postMessage
+requests. Keep the result shape identical for both paths: return a focused
+`link` and concise structured content.
+
+The resource shell owns the outer host size. Keep embedded app routes
+internally scrollable and let the launcher report a bounded intrinsic height
+rather than the full document height; otherwise host auto-resize can turn a
+normal app page into a very tall chat artifact. A changed shell only affects
+new MCP App resources and new tool calls. Old ChatGPT/Claude conversation
+frames can keep the previous resource behavior, so verify sizing with a fresh
+inline render before judging a fix.
+
+Claude uses the single-frame transplant path by default. You can also force it
+in other hosts with `embedMode: "transplant"` or `frame: "transplant"` when
+debugging host module-loading behavior. You can force the nested diagnostic iframe with
 `embedMode: "iframe"`, `renderMode: "iframe"`, `nested: true`, or
-`frame: "iframe"`. Use it only when debugging host behavior. If that diagnostic
-iframe is blocked, `embedApp()` replaces it with an open-app fallback: the user
-can retry inline, open a freshly minted embed session through the host, or use
-the visible route URL. Keep the action's `link` target useful on its own because
-it is still the universal escape hatch.
+`frame: "iframe"`. If the iframe is blocked, `embedApp()` replaces it with an
+open-app fallback: the user can retry inline, open a freshly minted embed
+session through the host, or use the visible route URL. Keep the action's
+`link` target useful on its own because it is still the universal escape hatch.
+
+When testing Claude through ngrok, use a production build (`agent-native build`
+then `agent-native start`) or a deployed preview/production URL. Claude's
+single-frame transplant path works with production asset chunks; raw Vite dev
+modules such as `/app/root.tsx` can be protected by app auth and fail dynamic
+imports from the Claude resource origin.
 
 The host bridge is deliberately small:
 
-| Mode              | Message type                          | Use it for                               |
-| ----------------- | ------------------------------------- | ---------------------------------------- |
-| direct            | `ui/update-model-context`             | Hidden context for the host model        |
-| direct            | `ui/message`                          | Post a visible user turn into the host   |
-| direct            | `ui/open-link`                        | Open an external or app URL via the host |
-| direct            | `ui/request-display-mode`             | Request `inline`, `fullscreen`, or `pip` |
-| nested diagnostic | `agentNative.mcpHostContext`          | Theme, locale, host platform, dimensions |
-| nested diagnostic | `agentNative.embeddedAppReady`        | Confirm the route iframe loaded          |
-| nested diagnostic | `agentNative.mcpHost.*` / `.response` | Wrapper relay for host requests          |
+| Mode                   | Message type                          | Use it for                               |
+| ---------------------- | ------------------------------------- | ---------------------------------------- |
+| direct host route      | `ui/update-model-context`             | Hidden context for the host model        |
+| direct host route      | `ui/message`                          | Post a visible user turn into the host   |
+| direct host route      | `ui/open-link`                        | Open an external or app URL via the host |
+| direct host route      | `ui/request-display-mode`             | Request `inline`, `fullscreen`, or `pip` |
+| Claude transplant      | `ui/*`                                | Same direct host bridge after hydration  |
+| ChatGPT / iframe route | `agentNative.mcpHostContext`          | Theme, locale, host platform, dimensions |
+| ChatGPT / iframe route | `agentNative.embeddedAppReady`        | Confirm the route iframe loaded          |
+| ChatGPT / iframe route | `agentNative.mcpHost.*` / `.response` | Wrapper relay for host requests          |
 
 Embedded routes can use `updateMcpAppModelContext()`,
 `openMcpAppHostLink()`, `requestMcpAppDisplayMode()`,
@@ -352,7 +378,6 @@ export default defineAction({
       description: "Open the generated draft in the real Mail compose UI.",
       iframeTitle: "Agent-Native Mail",
       openLabel: "Open in Mail",
-      frameDomains: ["https:", "http://localhost:*", "http://127.0.0.1:*"],
     }),
   },
 });
@@ -362,9 +387,16 @@ The MCP server advertises extension `io.modelcontextprotocol/ui`, adds `_meta.ui
 
 Keep the existing `link` builder even when adding `mcpApp`. CLI-only clients, older hosts, and any host that does not render MCP Apps will ignore the UI metadata and still need the `"Open in … →"` link. `embedApp()` uses that link as its launch target, calls the app-only `create_embed_session` helper, exchanges a one-time SQL ticket at `/_agent-native/embed/start`, and navigates the MCP App frame to the target route with a short-lived browser session plus a bearer fallback for same-origin fetches. `open_app({ app, path, embed: true })` is the generic escape hatch for routes such as full dashboards, filtered inboxes, calendar draft views, analyses, and extension pages, and should be used liberally when the full app is the clearest review/edit surface.
 
+`embedApp()` includes the MCP request origin in the resource CSP so the launcher
+can fetch and, when explicitly requested, frame the signed first-party app
+route. Only pass additional `frameDomains` for a custom MCP App that truly
+embeds a third-party player.
+
 Inside those `embedApp()` routes, `sendToAgentChat()` is embed-aware.
 Auto-submitted prompts relay to the MCP host as `ui/update-model-context` plus
-`ui/message`; `submit: false` remains local prefill/review behavior.
+`ui/message`, so a button in the embedded app can intentionally continue the
+Claude/ChatGPT conversation from the selected app state. `submit: false`
+remains local prefill/review behavior.
 
 ### The `link` contract {#link-contract}
 
@@ -509,6 +541,9 @@ The fallback hosted `connect` flow never copies the deployment's shared secret.
 - Test MCP Apps with the lightweight fixtures around `embedApp()` and
   `McpAppRenderer`; they cover CSP, host context, app launch, and bridge
   message behavior without needing a real external host.
+- When validating ChatGPT or Claude web, trigger a fresh tool call after shell
+  changes and measure the visible iframe. Previously rendered frames in the
+  same conversation may still show cached height or launch behavior.
 
 **Don't**
 

package/docs/content/mcp-protocol.md

@@ -78,11 +78,24 @@ If an action declares `mcpApp`, the server also advertises the official MCP Apps
 
 `embedApp()` is the low-level URL-first MCP App helper. It reads the action
 result's open link, asks the app-only `create_embed_session` tool to mint a
-route-scoped session, then navigates the MCP App frame itself to the resulting
-app route. For normal action authoring, use `embedRoute()` when the action's
+route-scoped session, then launches the resulting app route. Standard hosts
+hydrate the signed route by navigating the MCP App frame itself. Claude web
+uses a single-frame transplant path that fetches the signed app HTML and
+hydrates it inside Claude's MCP App iframe because Claude does not reliably
+allow app-owned child iframes or external frame navigation. ChatGPT web keeps
+the signed app URL in a controlled route iframe for stable `window.openai`
+host APIs and bounded height control.
+For normal action authoring, use `embedRoute()` when the action's
 `link` and `mcpApp` should come from the same pure route builder. The route
 itself should derive state from the URL and normal app data fetching.
 
+The outer MCP resource reports a bounded inline height to the host and the app
+route scrolls internally. Do not rely on host auto-resize measuring the full
+document; in ChatGPT and Claude this can make a normal full-app route appear as
+a huge chat artifact. Host conversations also keep already-rendered iframes, so
+after changing the resource shell or `ui://` version, test a fresh tool call
+rather than re-measuring an old frame.
+
 Default direct embeds talk to the MCP Apps host through standard `ui/*`
 JSON-RPC messages:
 
@@ -93,8 +106,14 @@ JSON-RPC messages:
 | `ui/open-link`            | `{ url }`                          |
 | `ui/request-display-mode` | `{ mode }`                         |
 
-An explicit `embedMode: "iframe"` / `renderMode: "iframe"` diagnostic path
-keeps the old wrapper-to-route postMessage relay:
+Claude's transplanted route uses the same `ui/*` bridge after hydration. Test
+Claude against deployed/preview URLs or a local production build served with
+`agent-native start`; raw Vite dev modules can be app-auth protected and fail
+dynamic imports from Claude's resource origin.
+
+The ChatGPT controlled-frame path and any explicit `embedMode: "iframe"` /
+`renderMode: "iframe"` diagnostic path use the wrapper-to-route postMessage
+relay:
 
 | Direction       | Type                                     | Payload shape                                 |
 | --------------- | ---------------------------------------- | --------------------------------------------- |
@@ -104,8 +123,17 @@ keeps the old wrapper-to-route postMessage relay:
 | route → wrapper | `agentNative.mcpHost.requestDisplayMode` | `{ requestId, mode }`                         |
 | wrapper → route | `agentNative.mcpHost.response`           | `{ requestId, ok, result?, error? }`          |
 
+`embedApp()` includes the MCP request origin in the resource CSP so the
+launcher can fetch and, when explicitly requested, frame the signed first-party
+route. Pass additional `frameDomains` only for custom third-party frames.
+
 Host-mediated open links keep the iframe from choosing its own browser target.
 Model context updates are opt-in and hidden from the user-facing transcript.
+`ui/message` is the portable way for an embedded app button to ask the host to
+post a visible user message and continue the chat. In agent-native routes,
+`sendToAgentChat()` uses `ui/update-model-context` plus `ui/message` when
+called from a submitted MCP App embed, while `submit: false` remains an
+in-route draft/prefill path.
 Display mode requests are best-effort: a host can honor, ignore, or reject the
 request. Embedded routes must remain functional in the default inline mode.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.22.19",
+  "version": "0.22.21",
   "type": "module",
   "description": "Framework for agent-native application development — where AI agents and UI share state via files",
   "license": "MIT",