@modelcontextprotocol/ext-apps 0.4.0 → 0.4.2

package/dist/src/app.d.ts

@@ -7,52 +7,61 @@ export { PostMessageTransport } from "./message-transport";
 export * from "./types";
 export { applyHostStyleVariables, applyHostFonts, getDocumentTheme, applyDocumentTheme, } from "./styles";
 /**
- * Metadata key for associating a resource URI with a tool call.
+ * Metadata key for associating a UI resource URI with a tool.
  *
- * MCP servers include this key in tool call result metadata to indicate which
- * UI resource should be displayed for the tool. When hosts receive a tool result
- * containing this metadata, they resolve and render the corresponding App.
+ * MCP servers include this key in tool definition metadata (via `tools/list`)
+ * to indicate which UI resource should be displayed when the tool is called.
+ * When hosts see a tool with this metadata, they fetch and render the
+ * corresponding {@link App `App`}.
  *
- * **Note**: This constant is provided for reference. MCP servers set this metadata
- * in their tool handlers; App developers typically don't need to use it directly.
+ * **Note**: This constant is provided for reference. App developers typically
+ * don't need to use it directly. Prefer using {@link server-helpers!registerAppTool `registerAppTool`}
+ * with the `_meta.ui.resourceUri` format instead.
  *
  * @example How MCP servers use this key (server-side, not in Apps)
- * ```typescript
- * // In an MCP server's tool handler:
- * return {
- *   content: [{ type: "text", text: "Result" }],
- *   _meta: {
- *     [RESOURCE_URI_META_KEY]: "ui://weather/forecast"
- *   }
- * };
+ * ```ts source="./app.examples.ts#RESOURCE_URI_META_KEY_serverSide"
+ * server.registerTool(
+ *   "weather",
+ *   {
+ *     description: "Get weather forecast",
+ *     _meta: {
+ *       [RESOURCE_URI_META_KEY]: "ui://weather/forecast",
+ *     },
+ *   },
+ *   handler,
+ * );
  * ```
  *
  * @example How hosts check for this metadata (host-side)
- * ```typescript
- * const result = await mcpClient.callTool({ name: "weather", arguments: {} });
- * const uiUri = result._meta?.[RESOURCE_URI_META_KEY];
- * if (uiUri) {
- *   // Load and display the UI resource
+ * ```ts source="./app.examples.ts#RESOURCE_URI_META_KEY_hostSide"
+ * // Check tool definition metadata (from tools/list response):
+ * const uiUri = tool._meta?.[RESOURCE_URI_META_KEY];
+ * if (typeof uiUri === "string" && uiUri.startsWith("ui://")) {
+ *   // Fetch the resource and display the UI
  * }
  * ```
  */
 export declare const RESOURCE_URI_META_KEY = "ui/resourceUri";
 /**
  * MIME type for MCP UI resources.
+ *
+ * Identifies HTML content as an MCP App UI resource.
+ *
+ * Used by {@link server-helpers!registerAppResource `registerAppResource`} as the default MIME type for app resources.
  */
 export declare const RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
 /**
- * Options for configuring App behavior.
+ * Options for configuring {@link App `App`} behavior.
  *
- * Extends ProtocolOptions from the MCP SDK with App-specific configuration.
+ * Extends `ProtocolOptions` from the MCP SDK with `App`-specific configuration.
  *
- * @see ProtocolOptions from @modelcontextprotocol/sdk for inherited options
+ * @see `ProtocolOptions` from @modelcontextprotocol/sdk for inherited options
  */
 type AppOptions = ProtocolOptions & {
     /**
-     * Automatically report size changes to the host using ResizeObserver.
+     * Automatically report size changes to the host using `ResizeObserver`.
      *
-     * When enabled, the App monitors `document.body` and `document.documentElement`
+     * When enabled, the {@link App `App`} monitors `document.body` and `document.documentElement`
      * for size changes and automatically sends `ui/notifications/size-changed`
      * notifications to the host.
      *
@@ -64,14 +73,14 @@ type RequestHandlerExtra = Parameters<Parameters<App["setRequestHandler"]>[1]>[1
 /**
  * Main class for MCP Apps to communicate with their host.
  *
- * The App class provides a framework-agnostic way to build interactive MCP Apps
- * that run inside host applications. It extends the MCP SDK's Protocol class and
+ * The `App` class provides a framework-agnostic way to build interactive MCP Apps
+ * that run inside host applications. It extends the MCP SDK's `Protocol` class and
  * handles the connection lifecycle, initialization handshake, and bidirectional
  * communication with the host.
  *
  * ## Architecture
  *
- * Guest UIs (Apps) act as MCP clients connecting to the host via {@link PostMessageTransport}.
+ * Views (Apps) act as MCP clients connecting to the host via {@link PostMessageTransport `PostMessageTransport`}.
  * The host proxies requests to the actual MCP server and forwards
  * responses back to the App.
  *
@@ -84,59 +93,38 @@ type RequestHandlerExtra = Parameters<Parameters<App["setRequestHandler"]>[1]>[1
  *
  * ## Inherited Methods
  *
- * As a subclass of Protocol, App inherits key methods for handling communication:
+ * As a subclass of `Protocol`, `App` inherits key methods for handling communication:
  * - `setRequestHandler()` - Register handlers for requests from host
  * - `setNotificationHandler()` - Register handlers for notifications from host
  *
- * @see Protocol from @modelcontextprotocol/sdk for all inherited methods
+ * @see `Protocol` from @modelcontextprotocol/sdk for all inherited methods
  *
  * ## Notification Setters
  *
- * For common notifications, the App class provides convenient setter properties
+ * For common notifications, the `App` class provides convenient setter properties
  * that simplify handler registration:
  * - `ontoolinput` - Complete tool arguments from host
  * - `ontoolinputpartial` - Streaming partial tool arguments
  * - `ontoolresult` - Tool execution results
+ * - `ontoolcancelled` - Tool execution was cancelled by user or host
  * - `onhostcontextchanged` - Host context changes (theme, locale, etc.)
  *
  * These setters are convenience wrappers around `setNotificationHandler()`.
  * Both patterns work; use whichever fits your coding style better.
  *
  * @example Basic usage with PostMessageTransport
- * ```typescript
- * import {
- *   App,
- *   PostMessageTransport,
- *   McpUiToolInputNotificationSchema
- * } from '@modelcontextprotocol/ext-apps';
- *
+ * ```ts source="./app.examples.ts#App_basicUsage"
  * const app = new App(
  *   { name: "WeatherApp", version: "1.0.0" },
- *   {} // capabilities
+ *   {}, // capabilities
  * );
  *
- * // Register notification handler using setter (simpler)
+ * // Register handlers before connecting to ensure no notifications are missed
  * app.ontoolinput = (params) => {
  *   console.log("Tool arguments:", params.arguments);
  * };
  *
- * // OR using inherited setNotificationHandler (more explicit)
- * app.setNotificationHandler(
- *   McpUiToolInputNotificationSchema,
- *   (notification) => {
- *     console.log("Tool arguments:", notification.params.arguments);
- *   }
- * );
- *
- * await app.connect(new PostMessageTransport(window.parent));
- * ```
- *
- * @example Sending a message to the host's chat
- * ```typescript
- * await app.sendMessage({
- *   role: "user",
- *   content: [{ type: "text", text: "Weather updated!" }]
- * });
+ * await app.connect();
  * ```
  */
 export declare class App extends Protocol<AppRequest, AppNotification, AppResult> {
@@ -151,14 +139,14 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      *
      * @param _appInfo - App identification (name and version)
      * @param _capabilities - Features and capabilities this app provides
-     * @param options - Configuration options including autoResize behavior
+     * @param options - Configuration options including `autoResize` behavior
      *
      * @example
-     * ```typescript
+     * ```ts source="./app.examples.ts#App_constructor_basic"
      * const app = new App(
      *   { name: "MyApp", version: "1.0.0" },
      *   { tools: { listChanged: true } }, // capabilities
-     *   { autoResize: true } // options
+     *   { autoResize: true }, // options
      * );
      * ```
      */
@@ -167,49 +155,40 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      * Get the host's capabilities discovered during initialization.
      *
      * Returns the capabilities that the host advertised during the
-     * {@link connect} handshake. Returns `undefined` if called before
+     * {@link connect `connect`} handshake. Returns `undefined` if called before
      * connection is established.
      *
      * @returns Host capabilities, or `undefined` if not yet connected
      *
      * @example Check host capabilities after connection
-     * ```typescript
-     * await app.connect(transport);
-     * const caps = app.getHostCapabilities();
-     * if (caps === undefined) {
-     *   console.error("Not connected");
-     *   return;
-     * }
-     * if (caps.serverTools) {
+     * ```ts source="./app.examples.ts#App_getHostCapabilities_checkAfterConnection"
+     * await app.connect();
+     * if (app.getHostCapabilities()?.serverTools) {
      *   console.log("Host supports server tool calls");
      * }
      * ```
      *
-     * @see {@link connect} for the initialization handshake
-     * @see {@link McpUiHostCapabilities} for the capabilities structure
+     * @see {@link connect `connect`} for the initialization handshake
+     * @see {@link McpUiHostCapabilities `McpUiHostCapabilities`} for the capabilities structure
      */
     getHostCapabilities(): McpUiHostCapabilities | undefined;
     /**
      * Get the host's implementation info discovered during initialization.
      *
      * Returns the host's name and version as advertised during the
-     * {@link connect} handshake. Returns `undefined` if called before
+     * {@link connect `connect`} handshake. Returns `undefined` if called before
      * connection is established.
      *
      * @returns Host implementation info, or `undefined` if not yet connected
      *
      * @example Log host information after connection
-     * ```typescript
+     * ```ts source="./app.examples.ts#App_getHostVersion_logAfterConnection"
      * await app.connect(transport);
-     * const host = app.getHostVersion();
-     * if (host === undefined) {
-     *   console.error("Not connected");
-     *   return;
-     * }
-     * console.log(`Connected to ${host.name} v${host.version}`);
+     * const { name, version } = app.getHostVersion() ?? {};
+     * console.log(`Connected to ${name} v${version}`);
      * ```
      *
-     * @see {@link connect} for the initialization handshake
+     * @see {@link connect `connect`} for the initialization handshake
      */
     getHostVersion(): Implementation | undefined;
     /**
@@ -225,24 +204,20 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      * @returns Host context, or `undefined` if not yet connected
      *
      * @example Access host context after connection
-     * ```typescript
+     * ```ts source="./app.examples.ts#App_getHostContext_accessAfterConnection"
      * await app.connect(transport);
      * const context = app.getHostContext();
-     * if (context === undefined) {
-     *   console.error("Not connected");
-     *   return;
-     * }
-     * if (context.theme === "dark") {
+     * if (context?.theme === "dark") {
      *   document.body.classList.add("dark-theme");
      * }
-     * if (context.toolInfo) {
+     * if (context?.toolInfo) {
      *   console.log("Tool:", context.toolInfo.tool.name);
      * }
      * ```
      *
-     * @see {@link connect} for the initialization handshake
-     * @see {@link onhostcontextchanged} for context change notifications
-     * @see {@link McpUiHostContext} for the context structure
+     * @see {@link connect `connect`} for the initialization handshake
+     * @see {@link onhostcontextchanged `onhostcontextchanged`} for context change notifications
+     * @see {@link McpUiHostContext `McpUiHostContext`} for the context structure
      */
     getHostContext(): McpUiHostContext | undefined;
     /**
@@ -255,32 +230,22 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      * This setter is a convenience wrapper around `setNotificationHandler()` that
      * automatically handles the notification schema and extracts the params for you.
      *
-     * Register handlers before calling {@link connect} to avoid missing notifications.
+     * Register handlers before calling {@link connect `connect`} to avoid missing notifications.
      *
-     * @param callback - Function called with the tool input params
+     * @param callback - Function called with the tool input params ({@link McpUiToolInputNotification.params `McpUiToolInputNotification.params`})
      *
-     * @example Using the setter (simpler)
-     * ```typescript
+     * @example
+     * ```ts source="./app.examples.ts#App_ontoolinput_setter"
      * // Register before connecting to ensure no notifications are missed
      * app.ontoolinput = (params) => {
      *   console.log("Tool:", params.arguments);
      *   // Update your UI with the tool arguments
      * };
-     * await app.connect(transport);
+     * await app.connect();
      * ```
      *
-     * @example Using setNotificationHandler (more explicit)
-     * ```typescript
-     * app.setNotificationHandler(
-     *   McpUiToolInputNotificationSchema,
-     *   (notification) => {
-     *     console.log("Tool:", notification.params.arguments);
-     *   }
-     * );
-     * ```
-     *
-     * @see {@link setNotificationHandler} for the underlying method
-     * @see {@link McpUiToolInputNotification} for the notification structure
+     * @see {@link setNotificationHandler `setNotificationHandler`} for the underlying method
+     * @see {@link McpUiToolInputNotification `McpUiToolInputNotification`} for the notification structure
      */
     set ontoolinput(callback: (params: McpUiToolInputNotification["params"]) => void);
     /**
@@ -290,24 +255,46 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      * streams partial tool arguments during tool call initialization. This enables
      * progressive rendering of tool arguments before they're complete.
      *
+     * **Important:** Partial arguments are "healed" JSON — the host closes unclosed
+     * brackets/braces to produce valid JSON. This means objects may be incomplete
+     * (e.g., the last item in an array may be truncated). Use partial data only
+     * for preview UI, not for critical operations.
+     *
      * This setter is a convenience wrapper around `setNotificationHandler()` that
      * automatically handles the notification schema and extracts the params for you.
      *
-     * Register handlers before calling {@link connect} to avoid missing notifications.
+     * Register handlers before calling {@link connect `connect`} to avoid missing notifications.
      *
-     * @param callback - Function called with each partial tool input update
+     * @param callback - Function called with each partial tool input update ({@link McpUiToolInputPartialNotification.params `McpUiToolInputPartialNotification.params`})
      *
      * @example Progressive rendering of tool arguments
-     * ```typescript
+     * ```ts source="./app.examples.ts#App_ontoolinputpartial_progressiveRendering"
+     * let toolInputs: Record<string, unknown> | null = null;
+     * let toolInputsPartial: Record<string, unknown> | null = null;
+     *
      * app.ontoolinputpartial = (params) => {
-     *   console.log("Partial args:", params.arguments);
-     *   // Update your UI progressively as arguments stream in
+     *   toolInputsPartial = params.arguments as Record<string, unknown>;
+     *   render();
+     * };
+     *
+     * app.ontoolinput = (params) => {
+     *   toolInputs = params.arguments as Record<string, unknown>;
+     *   toolInputsPartial = null;
+     *   render();
      * };
+     *
+     * function render() {
+     *   if (toolInputs) {
+     *     renderFinalUI(toolInputs);
+     *   } else {
+     *     renderLoadingUI(toolInputsPartial); // e.g., shimmer with partial preview
+     *   }
+     * }
      * ```
      *
-     * @see {@link setNotificationHandler} for the underlying method
-     * @see {@link McpUiToolInputPartialNotification} for the notification structure
-     * @see {@link ontoolinput} for the complete tool input handler
+     * @see {@link setNotificationHandler `setNotificationHandler`} for the underlying method
+     * @see {@link McpUiToolInputPartialNotification `McpUiToolInputPartialNotification`} for the notification structure
+     * @see {@link ontoolinput `ontoolinput`} for the complete tool input handler
      */
     set ontoolinputpartial(callback: (params: McpUiToolInputPartialNotification["params"]) => void);
     /**
@@ -320,25 +307,24 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      * This setter is a convenience wrapper around `setNotificationHandler()` that
      * automatically handles the notification schema and extracts the params for you.
      *
-     * Register handlers before calling {@link connect} to avoid missing notifications.
+     * Register handlers before calling {@link connect `connect`} to avoid missing notifications.
      *
-     * @param callback - Function called with the tool result
+     * @param callback - Function called with the tool result ({@link McpUiToolResultNotification.params `McpUiToolResultNotification.params`})
      *
      * @example Display tool execution results
-     * ```typescript
+     * ```ts source="./app.examples.ts#App_ontoolresult_displayResults"
      * app.ontoolresult = (params) => {
-     *   if (params.content) {
-     *     console.log("Tool output:", params.content);
-     *   }
      *   if (params.isError) {
-     *     console.error("Tool execution failed");
+     *     console.error("Tool execution failed:", params.content);
+     *   } else if (params.content) {
+     *     console.log("Tool output:", params.content);
      *   }
      * };
      * ```
      *
-     * @see {@link setNotificationHandler} for the underlying method
-     * @see {@link McpUiToolResultNotification} for the notification structure
-     * @see {@link ontoolinput} for the initial tool input handler
+     * @see {@link setNotificationHandler `setNotificationHandler`} for the underlying method
+     * @see {@link McpUiToolResultNotification `McpUiToolResultNotification`} for the notification structure
+     * @see {@link ontoolinput `ontoolinput`} for the initial tool input handler
      */
     set ontoolresult(callback: (params: McpUiToolResultNotification["params"]) => void);
     /**
@@ -352,21 +338,21 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      * This setter is a convenience wrapper around `setNotificationHandler()` that
      * automatically handles the notification schema and extracts the params for you.
      *
-     * Register handlers before calling {@link connect} to avoid missing notifications.
+     * Register handlers before calling {@link connect `connect`} to avoid missing notifications.
      *
-     * @param callback - Function called when tool execution is cancelled
+     * @param callback - Function called when tool execution is cancelled. Receives optional cancellation reason — see {@link McpUiToolCancelledNotification.params `McpUiToolCancelledNotification.params`}.
      *
      * @example Handle tool cancellation
-     * ```typescript
+     * ```ts source="./app.examples.ts#App_ontoolcancelled_handleCancellation"
      * app.ontoolcancelled = (params) => {
      *   console.log("Tool cancelled:", params.reason);
-     *   showCancelledMessage(params.reason ?? "Operation was cancelled");
+     *   // Update your UI to show cancellation state
      * };
      * ```
      *
-     * @see {@link setNotificationHandler} for the underlying method
-     * @see {@link McpUiToolCancelledNotification} for the notification structure
-     * @see {@link ontoolresult} for successful tool completion
+     * @see {@link setNotificationHandler `setNotificationHandler`} for the underlying method
+     * @see {@link McpUiToolCancelledNotification `McpUiToolCancelledNotification`} for the notification structure
+     * @see {@link ontoolresult `ontoolresult`} for successful tool completion
      */
     set ontoolcancelled(callback: (params: McpUiToolCancelledNotification["params"]) => void);
     /**
@@ -380,12 +366,16 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      * This setter is a convenience wrapper around `setNotificationHandler()` that
      * automatically handles the notification schema and extracts the params for you.
      *
-     * Register handlers before calling {@link connect} to avoid missing notifications.
+     * Notification params are automatically merged into the internal host context
+     * before the callback is invoked. This means {@link getHostContext `getHostContext`} will
+     * return the updated values even before your callback runs.
+     *
+     * Register handlers before calling {@link connect `connect`} to avoid missing notifications.
      *
      * @param callback - Function called with the updated host context
      *
      * @example Respond to theme changes
-     * ```typescript
+     * ```ts source="./app.examples.ts#App_onhostcontextchanged_respondToTheme"
      * app.onhostcontextchanged = (params) => {
      *   if (params.theme === "dark") {
      *     document.body.classList.add("dark-theme");
@@ -395,9 +385,9 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      * };
      * ```
      *
-     * @see {@link setNotificationHandler} for the underlying method
-     * @see {@link McpUiHostContextChangedNotification} for the notification structure
-     * @see {@link McpUiHostContext} for the full context structure
+     * @see {@link setNotificationHandler `setNotificationHandler`} for the underlying method
+     * @see {@link McpUiHostContextChangedNotification `McpUiHostContextChangedNotification`} for the notification structure
+     * @see {@link McpUiHostContext `McpUiHostContext`} for the full context structure
      */
     set onhostcontextchanged(callback: (params: McpUiHostContextChangedNotification["params"]) => void);
     /**
@@ -413,22 +403,23 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      * This setter is a convenience wrapper around `setRequestHandler()` that
      * automatically handles the request schema.
      *
-     * Register handlers before calling {@link connect} to avoid missing requests.
+     * Register handlers before calling {@link connect `connect`} to avoid missing requests.
      *
      * @param callback - Function called when teardown is requested.
-     *   Can return void or a Promise that resolves when cleanup is complete.
+     *   Must return `McpUiResourceTeardownResult` (can be an empty object `{}`) or a Promise resolving to it.
      *
      * @example Perform cleanup before teardown
-     * ```typescript
+     * ```ts source="./app.examples.ts#App_onteardown_performCleanup"
      * app.onteardown = async () => {
      *   await saveState();
      *   closeConnections();
      *   console.log("App ready for teardown");
+     *   return {};
      * };
      * ```
      *
-     * @see {@link setRequestHandler} for the underlying method
-     * @see {@link McpUiResourceTeardownRequest} for the request structure
+     * @see {@link setRequestHandler `setRequestHandler`} for the underlying method
+     * @see {@link McpUiResourceTeardownRequest `McpUiResourceTeardownRequest`} for the request structure
      */
     set onteardown(callback: (params: McpUiResourceTeardownRequest["params"], extra: RequestHandlerExtra) => McpUiResourceTeardownResult | Promise<McpUiResourceTeardownResult>);
     /**
@@ -443,14 +434,14 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      * This setter is a convenience wrapper around `setRequestHandler()` that
      * automatically handles the request schema and extracts the params for you.
      *
-     * Register handlers before calling {@link connect} to avoid missing requests.
+     * Register handlers before calling {@link connect `connect`} to avoid missing requests.
      *
      * @param callback - Async function that executes the tool and returns the result.
      *   The callback will only be invoked if the app declared tool capabilities
      *   in the constructor.
      *
      * @example Handle tool calls from the host
-     * ```typescript
+     * ```ts source="./app.examples.ts#App_oncalltool_handleFromHost"
      * app.oncalltool = async (params, extra) => {
      *   if (params.name === "greet") {
      *     const name = params.arguments?.name ?? "World";
@@ -460,7 +451,7 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      * };
      * ```
      *
-     * @see {@link setRequestHandler} for the underlying method
+     * @see {@link setRequestHandler `setRequestHandler`} for the underlying method
      */
     set oncalltool(callback: (params: CallToolRequest["params"], extra: RequestHandlerExtra) => Promise<CallToolResult>);
     /**
@@ -475,23 +466,23 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      * This setter is a convenience wrapper around `setRequestHandler()` that
      * automatically handles the request schema and extracts the params for you.
      *
-     * Register handlers before calling {@link connect} to avoid missing requests.
+     * Register handlers before calling {@link connect `connect`} to avoid missing requests.
      *
-     * @param callback - Async function that returns the list of available tools.
-     *   The callback will only be invoked if the app declared tool capabilities
-     *   in the constructor.
+     * @param callback - Async function that returns tool names as strings (simplified
+     *   from full `ListToolsResult` with `Tool` objects). Registration is always
+     *   allowed; capability validation occurs when handlers are invoked.
      *
      * @example Return available tools
-     * ```typescript
+     * ```ts source="./app.examples.ts#App_onlisttools_returnTools"
      * app.onlisttools = async (params, extra) => {
      *   return {
-     *     tools: ["calculate", "convert", "format"]
+     *     tools: ["greet", "calculate", "format"],
      *   };
      * };
      * ```
      *
-     * @see {@link setRequestHandler} for the underlying method
-     * @see {@link oncalltool} for handling tool execution
+     * @see {@link setRequestHandler `setRequestHandler`} for the underlying method
+     * @see {@link oncalltool `oncalltool`} for handling tool execution
      */
     set onlisttools(callback: (params: ListToolsRequest["params"], extra: RequestHandlerExtra) => Promise<{
         tools: string[];
@@ -540,11 +531,11 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      * between transport failures (thrown) and tool execution failures (returned).
      *
      * @example Fetch updated weather data
-     * ```typescript
+     * ```ts source="./app.examples.ts#App_callServerTool_fetchWeather"
      * try {
      *   const result = await app.callServerTool({
      *     name: "get_weather",
-     *     arguments: { location: "Tokyo" }
+     *     arguments: { location: "Tokyo" },
      *   });
      *   if (result.isError) {
      *     console.error("Tool returned error:", result.content);
@@ -565,24 +556,47 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      *
      * @param params - Message role and content
      * @param options - Request options (timeout, etc.)
-     * @returns Result indicating success or error (no message content returned)
+     * @returns Result with optional `isError` flag indicating host rejection
      *
-     * @throws {Error} If the host rejects the message
+     * @throws {Error} If the request times out or the connection is lost
      *
      * @example Send a text message from user interaction
-     * ```typescript
+     * ```ts source="./app.examples.ts#App_sendMessage_textFromInteraction"
      * try {
-     *   await app.sendMessage({
+     *   const result = await app.sendMessage({
      *     role: "user",
-     *     content: [{ type: "text", text: "Show me details for item #42" }]
+     *     content: [{ type: "text", text: "Show me details for item #42" }],
      *   });
+     *   if (result.isError) {
+     *     console.error("Host rejected the message");
+     *     // Handle rejection appropriately for your app
+     *   }
      * } catch (error) {
      *   console.error("Failed to send message:", error);
-     *   // Handle error appropriately for your app
+     *   // Handle transport/protocol error
      * }
      * ```
      *
-     * @see {@link McpUiMessageRequest} for request structure
+     * @example Send follow-up message after offloading large data to model context
+     * ```ts source="./app.examples.ts#App_sendMessage_withLargeContext"
+     * const markdown = `---
+     * word-count: ${fullTranscript.split(/\s+/).length}
+     * speaker-names: ${speakerNames.join(", ")}
+     * ---
+     *
+     * ${fullTranscript}`;
+     *
+     * // Offload long transcript to model context
+     * await app.updateModelContext({ content: [{ type: "text", text: markdown }] });
+     *
+     * // Send brief trigger message
+     * await app.sendMessage({
+     *   role: "user",
+     *   content: [{ type: "text", text: "Summarize the key points" }],
+     * });
+     * ```
+     *
+     * @see {@link McpUiMessageRequest `McpUiMessageRequest`} for request structure
      */
     sendMessage(params: McpUiMessageRequest["params"], options?: RequestOptions): Promise<{
         [x: string]: unknown;
@@ -597,11 +611,11 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      * @param params - Log level and message
      *
      * @example Log app state for debugging
-     * ```typescript
+     * ```ts source="./app.examples.ts#App_sendLog_debugState"
      * app.sendLog({
      *   level: "info",
      *   data: "Weather data refreshed",
-     *   logger: "WeatherApp"
+     *   logger: "WeatherApp",
      * });
      * ```
      *
@@ -611,31 +625,52 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
     /**
      * Update the host's model context with app state.
      *
-     * Unlike `sendLog`, which is for debugging/telemetry, context updates
-     * are intended to be available to the model in future reasoning,
-     * without requiring a follow-up action (like `sendMessage`).
+     * Context updates are intended to be available to the model in future
+     * turns, without triggering an immediate model response (unlike {@link sendMessage `sendMessage`}).
      *
      * The host will typically defer sending the context to the model until the
-     * next user message (including `ui/message`), and will only send the last
-     * update received. Each call overwrites any previous context update.
+     * next user message — either from the actual user or via `sendMessage`. Only
+     * the last update is sent; each call overwrites any previous context.
      *
      * @param params - Context content and/or structured content
      * @param options - Request options (timeout, etc.)
      *
      * @throws {Error} If the host rejects the context update (e.g., unsupported content type)
+     * @throws {Error} If the request times out or the connection is lost
      *
      * @example Update model context with current app state
-     * ```typescript
+     * ```ts source="./app.examples.ts#App_updateModelContext_appState"
+     * const markdown = `---
+     * item-count: ${itemList.length}
+     * total-cost: ${totalCost}
+     * currency: ${currency}
+     * ---
+     *
+     * User is viewing their shopping cart with ${itemList.length} items selected:
+     *
+     * ${itemList.map((item) => `- ${item}`).join("\n")}`;
+     *
      * await app.updateModelContext({
-     *   content: [{ type: "text", text: "User selected 3 items totaling $150.00" }]
+     *   content: [{ type: "text", text: markdown }],
      * });
      * ```
      *
-     * @example Update with structured content
-     * ```typescript
-     * await app.updateModelContext({
-     *   structuredContent: { selectedItems: 3, total: 150.00, currency: "USD" }
-     * });
+     * @example Report runtime error to model
+     * ```ts source="./app.examples.ts#App_updateModelContext_reportError"
+     * try {
+     *   const _stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+     *   // ... use _stream for transcription
+     * } catch (err) {
+     *   // Inform the model that the app is in a degraded state
+     *   await app.updateModelContext({
+     *     content: [
+     *       {
+     *         type: "text",
+     *         text: "Error: transcription unavailable",
+     *       },
+     *     ],
+     *   });
+     * }
      * ```
      *
      * @returns Promise that resolves when the context update is acknowledged
@@ -653,32 +688,32 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      * Request the host to open an external URL in the default browser.
      *
      * The host may deny this request based on user preferences or security policy.
-     * Apps should handle rejection gracefully.
+     * Apps should handle rejection gracefully by checking `result.isError`.
      *
      * @param params - URL to open
      * @param options - Request options (timeout, etc.)
-     * @returns Result indicating success or error
+     * @returns Result with `isError: true` if the host denied the request (e.g., blocked domain, user cancelled)
      *
-     * @throws {Error} If the host denies the request (e.g., blocked domain, user cancelled)
      * @throws {Error} If the request times out or the connection is lost
      *
      * @example Open documentation link
-     * ```typescript
-     * try {
-     *   await app.openLink({ url: "https://docs.example.com" });
-     * } catch (error) {
-     *   console.error("Failed to open link:", error);
+     * ```ts source="./app.examples.ts#App_openLink_documentation"
+     * const { isError } = await app.openLink({ url: "https://docs.example.com" });
+     * if (isError) {
+     *   // Host denied the request (e.g., blocked domain, user cancelled)
      *   // Optionally show fallback: display URL for manual copy
+     *   console.warn("Link request denied");
      * }
      * ```
      *
-     * @see {@link McpUiOpenLinkRequest} for request structure
+     * @see {@link McpUiOpenLinkRequest `McpUiOpenLinkRequest`} for request structure
+     * @see {@link McpUiOpenLinkResult `McpUiOpenLinkResult`} for result structure
      */
     openLink(params: McpUiOpenLinkRequest["params"], options?: RequestOptions): Promise<{
         [x: string]: unknown;
         isError?: boolean | undefined;
     }>;
-    /** @deprecated Use {@link openLink} instead */
+    /** @deprecated Use {@link openLink `openLink`} instead */
     sendOpenLink: App["openLink"];
     /**
      * Request a change to the display mode.
@@ -692,17 +727,18 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      * @param options - Request options (timeout, etc.)
      * @returns Result containing the actual display mode that was set
      *
-     * @example Request fullscreen mode
-     * ```typescript
-     * const context = app.getHostContext();
-     * if (context?.availableDisplayModes?.includes("fullscreen")) {
-     *   const result = await app.requestDisplayMode({ mode: "fullscreen" });
-     *   console.log("Display mode set to:", result.mode);
+     * @example Toggle display mode
+     * ```ts source="./app.examples.ts#App_requestDisplayMode_toggle"
+     * const ctx = app.getHostContext();
+     * if (ctx?.availableDisplayModes?.includes("fullscreen")) {
+     *   const target = ctx.displayMode === "fullscreen" ? "inline" : "fullscreen";
+     *   const result = await app.requestDisplayMode({ mode: target });
+     *   console.log("Now in:", result.mode);
      * }
      * ```
      *
-     * @see {@link McpUiRequestDisplayModeRequest} for request structure
-     * @see {@link McpUiHostContext} for checking availableDisplayModes
+     * @see {@link McpUiRequestDisplayModeRequest `McpUiRequestDisplayModeRequest`} for request structure
+     * @see {@link McpUiHostContext `McpUiHostContext`} for checking availableDisplayModes
      */
     requestDisplayMode(params: McpUiRequestDisplayModeRequest["params"], options?: RequestOptions): Promise<{
         [x: string]: unknown;
@@ -717,16 +753,16 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      * @param params - New width and height in pixels
      *
      * @example Manually notify host of size change
-     * ```typescript
+     * ```ts source="./app.examples.ts#App_sendSizeChanged_manual"
      * app.sendSizeChanged({
      *   width: 400,
-     *   height: 600
+     *   height: 600,
      * });
      * ```
      *
      * @returns Promise that resolves when the notification is sent
      *
-     * @see {@link McpUiSizeChangedNotification} for notification structure
+     * @see {@link McpUiSizeChangedNotification `McpUiSizeChangedNotification`} for notification structure
      */
     sendSizeChanged(params: McpUiSizeChangedNotification["params"]): Promise<void>;
     /**
@@ -743,8 +779,12 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      * @returns Cleanup function to disconnect the observer
      *
      * @example Manual setup for custom scenarios
-     * ```typescript
-     * const app = new App(appInfo, capabilities, { autoResize: false });
+     * ```ts source="./app.examples.ts#App_setupAutoResize_manual"
+     * const app = new App(
+     *   { name: "MyApp", version: "1.0.0" },
+     *   {},
+     *   { autoResize: false },
+     * );
      * await app.connect(transport);
      *
      * // Later, enable auto-resize manually
@@ -763,34 +803,31 @@ export declare class App extends Protocol<AppRequest, AppNotification, AppResult
      * 2. Sends `ui/initialize` request with app info and capabilities
      * 3. Receives host capabilities and context in response
      * 4. Sends `ui/notifications/initialized` notification
-     * 5. Sets up auto-resize using {@link setupSizeChangedNotifications} if enabled (default)
+     * 5. Sets up auto-resize using {@link setupSizeChangedNotifications `setupSizeChangedNotifications`} if enabled (default)
      *
      * If initialization fails, the connection is automatically closed and an error
      * is thrown.
      *
-     * @param transport - Transport layer (typically PostMessageTransport)
+     * @param transport - Transport layer (typically {@link PostMessageTransport `PostMessageTransport`})
      * @param options - Request options for the initialize request
      *
      * @throws {Error} If initialization fails or connection is lost
      *
      * @example Connect with PostMessageTransport
-     * ```typescript
-     * const app = new App(
-     *   { name: "MyApp", version: "1.0.0" },
-     *   {}
-     * );
+     * ```ts source="./app.examples.ts#App_connect_withPostMessageTransport"
+     * const app = new App({ name: "MyApp", version: "1.0.0" }, {});
      *
      * try {
-     *   await app.connect(new PostMessageTransport(window.parent));
+     *   await app.connect(new PostMessageTransport(window.parent, window.parent));
      *   console.log("Connected successfully!");
      * } catch (error) {
      *   console.error("Failed to connect:", error);
      * }
      * ```
      *
-     * @see {@link McpUiInitializeRequest} for the initialization request structure
-     * @see {@link McpUiInitializedNotification} for the initialized notification
-     * @see {@link PostMessageTransport} for the typical transport implementation
+     * @see {@link McpUiInitializeRequest `McpUiInitializeRequest`} for the initialization request structure
+     * @see {@link McpUiInitializedNotification `McpUiInitializedNotification`} for the initialized notification
+     * @see {@link PostMessageTransport `PostMessageTransport`} for the typical transport implementation
      */
     connect(transport?: Transport, options?: RequestOptions): Promise<void>;
 }