Refine JSDoc examples for consistency and type safety

Follow-up to the examples extraction: pass dependencies as function
parameters instead of using global stub declarations, rename region
names to match method names (e.g., `AppBridge_guestCapabilities_*` →
`AppBridge_getAppCapabilities_*`), and simplify examples using optional
chaining.

Also clarifies `RESOURCE_URI_META_KEY` documentation to indicate it's
for tool definition metadata (from `tools/list`), not tool result
metadata, and removes the redundant `setNotificationHandler` example
in favor of the simpler event setter approach.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

src/react/useApp.examples.tsx

@@ -4,10 +4,12 @@
  * @module
  */
 
-import { useApp, McpUiToolInputNotificationSchema } from "./index.js";
+import { useState } from "react";
+import type { McpUiHostContext } from "../types.js";
+import { useApp } from "./index.js";
 
 /**
- * Example: Register a notification handler in onAppCreated.
+ * Example: Register an event handler in onAppCreated.
  */
 function useApp_registerHandler() {
   //#region useApp_registerHandler
@@ -15,40 +17,49 @@ function useApp_registerHandler() {
     appInfo: { name: "MyApp", version: "1.0.0" },
     capabilities: {},
     onAppCreated: (app) => {
-      app.setNotificationHandler(
-        McpUiToolInputNotificationSchema,
-        (notification) => {
-          console.log("Tool input:", notification.params.arguments);
-        },
-      );
+      app.ontoolresult = (result) => {
+        console.log("Tool result:", result);
+      };
     },
   });
   //#endregion useApp_registerHandler
 }
 
 /**
- * Example: Basic usage of useApp hook.
+ * Example: Basic usage of useApp hook with common event handlers.
  */
 function useApp_basicUsage() {
   //#region useApp_basicUsage
   function MyApp() {
+    const [hostContext, setHostContext] = useState<
+      McpUiHostContext | undefined
+    >(undefined);
+
     const { app, isConnected, error } = useApp({
       appInfo: { name: "MyApp", version: "1.0.0" },
       capabilities: {},
       onAppCreated: (app) => {
-        // Register handlers before connection
-        app.setNotificationHandler(
-          McpUiToolInputNotificationSchema,
-          (notification) => {
-            console.log("Tool input:", notification.params.arguments);
-          },
-        );
+        app.ontoolinput = (input) => {
+          console.log("Tool input:", input);
+        };
+        app.ontoolresult = (result) => {
+          console.log("Tool result:", result);
+        };
+        app.ontoolcancelled = (params) => {
+          console.log("Tool cancelled:", params.reason);
+        };
+        app.onerror = (error) => {
+          console.log("Error:", error);
+        };
+        app.onhostcontextchanged = (params) => {
+          setHostContext((prev) => ({ ...prev, ...params }));
+        };
       },
     });
 
     if (error) return <div>Error: {error.message}</div>;
     if (!isConnected) return <div>Connecting...</div>;
-    return <div>Connected!</div>;
+    return <div>Theme: {hostContext?.theme}</div>;
   }
   //#endregion useApp_basicUsage
 }

src/react/useApp.tsx

@@ -29,7 +29,7 @@ export interface UseAppOptions {
    *
    * @param app - The newly created `App` instance
    *
-   * @example Register a notification handler
+   * @example Register an event handler
    * {@includeCode ./useApp.examples.tsx#useApp_registerHandler}
    */
   onAppCreated?: (app: App) => void;
@@ -69,7 +69,7 @@ export interface AppState {
  *   initialization, the `error` field will contain the error (typically connection
  *   timeouts, initialization handshake failures, or transport errors).
  *
- * @example Basic usage
+ * @example Basic usage of useApp hook with common event handlers
  * {@includeCode ./useApp.examples.tsx#useApp_basicUsage}
  *
  * @see {@link App.connect} for the underlying connection method

src/react/useHostStyles.examples.tsx

@@ -4,15 +4,12 @@
  * @module
  */
 
-import { useState } from "react";
 import {
   useApp,
   useHostStyleVariables,
   useHostFonts,
   useHostStyles,
-  App,
 } from "./index.js";
-import type { McpUiHostContext } from "../types.js";
 
 /**
  * Example: Basic usage of useHostStyleVariables.
@@ -20,7 +17,7 @@ import type { McpUiHostContext } from "../types.js";
 function useHostStyleVariables_basicUsage() {
   //#region useHostStyleVariables_basicUsage
   function MyApp() {
-    const { app, isConnected } = useApp({
+    const { app } = useApp({
       appInfo: { name: "MyApp", version: "1.0.0" },
       capabilities: {},
     });
@@ -43,44 +40,37 @@ function useHostStyleVariables_basicUsage() {
 function useHostFonts_basicUsage() {
   //#region useHostFonts_basicUsage
   function MyApp() {
-    const { app, isConnected } = useApp({
+    const { app } = useApp({
       appInfo: { name: "MyApp", version: "1.0.0" },
       capabilities: {},
     });
 
-    // Automatically apply host fonts
-    useHostFonts(app);
+    // Apply host fonts - pass initial context to apply fonts from connect() immediately
+    useHostFonts(app, app?.getHostContext());
 
     return <div style={{ fontFamily: "var(--font-sans)" }}>Hello!</div>;
   }
   //#endregion useHostFonts_basicUsage
 }
 
-/**
- * Example: useHostFonts with initial context.
- */
-function useHostFonts_withInitialContext(app: App) {
-  //#region useHostFonts_withInitialContext
-  const [hostContext, setHostContext] = useState<McpUiHostContext | null>(null);
-
-  // ... get initial context from app.connect() result
-
-  useHostFonts(app, hostContext);
-  //#endregion useHostFonts_withInitialContext
-}
-
 /**
  * Example: Basic usage of useHostStyles.
  */
 function useHostStyles_basicUsage() {
-  const appInfo = { name: "MyApp", version: "1.0.0" };
   //#region useHostStyles_basicUsage
   function MyApp() {
-    const { app } = useApp({ appInfo, capabilities: {} });
+    const { app } = useApp({
+      appInfo: { name: "MyApp", version: "1.0.0" },
+      capabilities: {},
+    });
+
+    // Apply all host styles - pass initial context to apply styles from connect() immediately
     useHostStyles(app, app?.getHostContext());
 
     return (
-      <div style={{ background: "var(--color-background-primary)" }}>...</div>
+      <div style={{ background: "var(--color-background-primary)" }}>
+        Hello!
+      </div>
     );
   }
   //#endregion useHostStyles_basicUsage

src/react/useHostStyles.ts

@@ -91,9 +91,6 @@ export function useHostStyleVariables(
  * @example Basic usage with useApp
  * {@includeCode ./useHostStyles.examples.tsx#useHostFonts_basicUsage}
  *
- * @example With initial context
- * {@includeCode ./useHostStyles.examples.tsx#useHostFonts_withInitialContext}
- *
  * @see {@link applyHostFonts} for the underlying fonts function
  * @see {@link useHostStyleVariables} for applying style variables and theme
  */