feat: Add screenshot and click support to SDK

- Add McpUiScreenshotRequest/Result and McpUiClickRequest/Result types
- Add onscreenshot and onclick handlers to App class
- Add screenshot() and click() methods to AppBridge class
- Generate updated Zod schemas

Author: ochafik

package-lock.json

@@ -81,6 +81,12 @@ import {
   McpUiRequestDisplayModeRequestSchema,
   McpUiRequestDisplayModeResult,
   McpUiResourcePermissions,
+  McpUiScreenshotRequest,
+  McpUiScreenshotResult,
+  McpUiScreenshotResultSchema,
+  McpUiClickRequest,
+  McpUiClickResult,
+  McpUiClickResultSchema,
 } from "./types";
 export * from "./types";
 export { RESOURCE_URI_META_KEY, RESOURCE_MIME_TYPE } from "./app";
@@ -1352,6 +1358,76 @@ export class AppBridge extends Protocol<
     );
   }
 
+  /**
+   * Capture a screenshot of the Guest UI.
+   *
+   * Requests the App to render and capture its current visual state. The App
+   * returns the image as a base64-encoded string.
+   *
+   * @param params - Screenshot options (format, quality)
+   * @param options - Request options (timeout, etc.)
+   * @returns Promise resolving to the screenshot data
+   *
+   * @throws {Error} If the App does not support screenshots
+   * @throws {Error} If the request times out or the connection is lost
+   *
+   * @example Capture a PNG screenshot
+   * ```typescript
+   * const result = await bridge.screenshot({ format: "png" });
+   * const img = document.createElement("img");
+   * img.src = `data:${result.mimeType};base64,${result.data}`;
+   * document.body.appendChild(img);
+   * ```
+   */
+  async screenshot(
+    params?: McpUiScreenshotRequest["params"],
+    options?: RequestOptions,
+  ): Promise<McpUiScreenshotResult> {
+    return this.request(
+      {
+        method: "ui/screenshot" as const,
+        params: params ?? {},
+      },
+      McpUiScreenshotResultSchema,
+      options,
+    );
+  }
+
+  /**
+   * Simulate a click at a specific position in the Guest UI.
+   *
+   * Requests the App to dispatch a mouse event at the specified coordinates.
+   * The App should handle this as if the user clicked at that position.
+   *
+   * @param params - Click coordinates and options
+   * @param options - Request options (timeout, etc.)
+   * @returns Promise resolving to the click result
+   *
+   * @throws {Error} If the App does not support click simulation
+   * @throws {Error} If the request times out or the connection is lost
+   *
+   * @example Simple left click
+   * ```typescript
+   * const result = await bridge.click({ x: 100, y: 200 });
+   * if (result.success) {
+   *   console.log(`Clicked on: ${result.targetElement}`);
+   * }
+   * ```
+   */
+  async click(
+    params: McpUiClickRequest["params"],
+    options?: RequestOptions,
+  ): Promise<McpUiClickResult> {
+    return this.request(
+      {
+        method: "ui/click" as const,
+        params,
+      },
+      McpUiClickResultSchema,
+      options,
+    );
+  }
+
   /**
    * Connect to the Guest UI via transport and optionally set up message forwarding.
    *

src/app-bridge.ts

@@ -28,6 +28,9 @@ import { PostMessageTransport } from "./message-transport";
 import {
   LATEST_PROTOCOL_VERSION,
   McpUiAppCapabilities,
+  McpUiClickRequest,
+  McpUiClickRequestSchema,
+  McpUiClickResult,
   McpUiUpdateModelContextRequest,
   McpUiHostCapabilities,
   McpUiHostContext,
@@ -43,6 +46,9 @@ import {
   McpUiResourceTeardownRequest,
   McpUiResourceTeardownRequestSchema,
   McpUiResourceTeardownResult,
+  McpUiScreenshotRequest,
+  McpUiScreenshotRequestSchema,
+  McpUiScreenshotResult,
   McpUiSizeChangedNotification,
   McpUiToolCancelledNotification,
   McpUiToolCancelledNotificationSchema,
@@ -731,6 +737,77 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
     );
   }
 
+  /**
+   * Handler for screenshot requests from the host.
+   *
+   * Set this property to register a handler that captures the current visual
+   * state of the App. The handler should render the App and return the image
+   * data as a base64-encoded string.
+   *
+   * @param callback - Async function that captures the screenshot
+   *
+   * @example Capture a screenshot of the App
+   * ```typescript
+   * app.onscreenshot = async (params, extra) => {
+   *   const canvas = await html2canvas(document.body);
+   *   const dataUrl = canvas.toDataURL(params.format ?? "image/png", params.quality);
+   *   const [mimeType, data] = dataUrl.replace("data:", "").split(";base64,");
+   *   return { data, mimeType, width: canvas.width, height: canvas.height };
+   * };
+   * ```
+   *
+   * @see {@link McpUiScreenshotRequest} for the request structure
+   * @see {@link McpUiScreenshotResult} for the result structure
+   */
+  set onscreenshot(
+    callback: (
+      params: McpUiScreenshotRequest["params"],
+      extra: RequestHandlerExtra,
+    ) => Promise<McpUiScreenshotResult>,
+  ) {
+    this.setRequestHandler(McpUiScreenshotRequestSchema, (request, extra) =>
+      callback(request.params, extra),
+    );
+  }
+
+  /**
+   * Handler for click simulation requests from the host.
+   *
+   * Set this property to register a handler that simulates a click at the
+   * specified coordinates in the App. The handler should dispatch appropriate
+   * mouse events to the target element.
+   *
+   * @param callback - Async function that simulates the click
+   *
+   * @example Handle click simulation
+   * ```typescript
+   * app.onclick = async ({ x, y, type = "click", button = "left" }, extra) => {
+   *   const element = document.elementFromPoint(x, y);
+   *   if (!element) {
+   *     return { success: false, isError: true };
+   *   }
+   *   element.dispatchEvent(new MouseEvent(type, {
+   *     clientX: x, clientY: y, bubbles: true, cancelable: true,
+   *     button: button === "left" ? 0 : button === "right" ? 2 : 1
+   *   }));
+   *   return { success: true, targetElement: element.tagName.toLowerCase() };
+   * };
+   * ```
+   *
+   * @see {@link McpUiClickRequest} for the request structure
+   * @see {@link McpUiClickResult} for the result structure
+   */
+  set onclick(
+    callback: (
+      params: McpUiClickRequest["params"],
+      extra: RequestHandlerExtra,
+    ) => Promise<McpUiClickResult>,
+  ) {
+    this.setRequestHandler(McpUiClickRequestSchema, (request, extra) =>
+      callback(request.params, extra),
+    );
+  }
+
   /**
    * Convenience handler for tool call requests from the host.
    *