refactor: reduce comments, align with repo conventions

- Remove @example block from forHostIframe JSDoc (only constructors use it)
- Reduce example JSDoc to single line matching existing style
- Merge redundant test case, remove describe-level comment
- Move isInitializationTimeoutError to private static on App class
- Use DEFAULT_REQUEST_TIMEOUT_MSEC instead of hardcoded 60000
- Streamline quickstart docs: remove sub-headings and anti-pattern block,
  use [!CAUTION] callout matching existing doc style

Made-with: Cursor

Author: netanelavr

docs/quickstart.md

@@ -480,12 +480,7 @@ You've built your first MCP App!
 
 When building your own host (instead of using an existing MCP client), the order of operations matters. The host must start listening for messages **before** the View begins executing, otherwise the View's `ui/initialize` request will be lost.
 
-### Correct Order
-
-1. **Create and attach the iframe** to the document
-2. **Create the transport** using `PostMessageTransport.forHostIframe(iframe)`
-3. **Connect the bridge** with `await bridge.connect(transport)`
-4. **Then** set `iframe.srcdoc` or `iframe.src` to load the View
+`iframe.contentWindow` is available as soon as the iframe is in the DOM (it points to the initial `about:blank` document) — you do not need to wait for `onload` to create the transport.
 
 ```ts
 import {
@@ -497,33 +492,16 @@ const iframe = document.createElement("iframe");
 iframe.sandbox.add("allow-scripts");
 document.body.appendChild(iframe);
 
-// Create transport — contentWindow exists once iframe is in DOM
 const transport = PostMessageTransport.forHostIframe(iframe);
-
-// Connect bridge — now listening for messages
 const bridge = new AppBridge(mcpClient, hostInfo, hostCapabilities);
 await bridge.connect(transport);
 
-// NOW load the content — ui/initialize will be received
+// Set content AFTER connecting — view's ui/initialize will be received
 iframe.srcdoc = htmlContent;
 ```
 
-The `iframe.contentWindow` reference is available as soon as the iframe is in the DOM (it points to the initial `about:blank` document). You do **not** need to wait for `onload` to create the transport.
-
-### Anti-Pattern
-
-```ts
-// ❌ WRONG: Setting srcdoc before connecting
-iframe.srcdoc = htmlContent; // View sends ui/initialize immediately!
-const transport = PostMessageTransport.forHostIframe(iframe);
-await bridge.connect(transport); // Too late — message was already lost
-```
-
-If you see a timeout error like:
-
-> `ui/initialize: no response within 60s — host may have loaded the View before connecting its transport`
-
-This is the likely cause. Reorder your code to connect the transport first.
+> [!CAUTION]
+> Setting `srcdoc` or `src` **before** connecting the transport will cause the View's `ui/initialize` to be lost. If you see a timeout like `"no response within 60s"`, this is the likely cause.
 
 ## Next Steps
 

src/app.ts

@@ -2,6 +2,7 @@ import {
   type RequestOptions,
   mergeCapabilities,
   ProtocolOptions,
+  DEFAULT_REQUEST_TIMEOUT_MSEC,
 } from "@modelcontextprotocol/sdk/shared/protocol.js";
 
 import {
@@ -1989,11 +1990,8 @@ export class App extends ProtocolWithEvents<
       // Disconnect if initialization fails.
       void this.close();
 
-      // Improve timeout message with actionable diagnosis for host developers.
-      // This commonly happens when the host loads the View before connecting
-      // its transport, causing the ui/initialize message to be lost.
-      if (isInitializationTimeoutError(error)) {
-        const timeoutMs = options?.timeout ?? 60000;
+      if (App.isInitializationTimeoutError(error)) {
+        const timeoutMs = options?.timeout ?? DEFAULT_REQUEST_TIMEOUT_MSEC;
         const timeoutSec = Math.round(timeoutMs / 1000);
         throw new Error(
           `ui/initialize: no response within ${timeoutSec}s — ` +
@@ -2005,22 +2003,19 @@ export class App extends ProtocolWithEvents<
       throw error;
     }
   }
-}
 
-/**
- * Check if an error indicates the ui/initialize request timed out.
- */
-function isInitializationTimeoutError(error: unknown): boolean {
-  if (!(error instanceof Error)) {
-    return false;
+  private static isInitializationTimeoutError(error: unknown): boolean {
+    if (!(error instanceof Error)) {
+      return false;
+    }
+    const message = error.message.toLowerCase();
+    const name = error.name.toLowerCase();
+    return (
+      message.includes("timeout") ||
+      message.includes("timed out") ||
+      message.includes("requesttimeout") ||
+      name.includes("timeout") ||
+      name === "aborterror"
+    );
   }
-  const message = error.message.toLowerCase();
-  const name = error.name.toLowerCase();
-  return (
-    message.includes("timeout") ||
-    message.includes("timed out") ||
-    message.includes("requesttimeout") ||
-    name.includes("timeout") ||
-    name === "aborterror"
-  );
 }

src/message-transport.examples.ts

@@ -58,10 +58,7 @@ function PostMessageTransport_constructor_host() {
 }
 
 /**
- * Example: Host using forHostIframe helper (recommended).
- *
- * The helper validates the iframe is connected and returns a transport bound
- * to its contentWindow. Connect before setting srcdoc/src.
+ * Example: Host using forHostIframe helper.
  */
 async function PostMessageTransport_forHostIframe(bridge: AppBridge) {
   //#region PostMessageTransport_forHostIframe

src/message-transport.test.ts

@@ -392,9 +392,6 @@ describe("PostMessageTransport", () => {
   // forHostIframe() — static factory for host-side transport
   // ==========================================================================
   describe("forHostIframe()", () => {
-    // These tests require a real DOM environment. We create minimal fakes
-    // that satisfy the checks in forHostIframe().
-
     it("throws when iframe is not connected to the document", () => {
       const iframe = {
         isConnected: false,
@@ -404,14 +401,6 @@ describe("PostMessageTransport", () => {
       expect(() => PostMessageTransport.forHostIframe(iframe)).toThrow(
         /iframe must be in the document/,
       );
-    });
-
-    it("error message mentions appendChild", () => {
-      const iframe = {
-        isConnected: false,
-        contentWindow: {},
-      } as unknown as HTMLIFrameElement;
-
       expect(() => PostMessageTransport.forHostIframe(iframe)).toThrow(
         /appendChild/,
       );

src/message-transport.ts

@@ -204,20 +204,6 @@ export class PostMessageTransport implements Transport {
    * @returns A PostMessageTransport configured for host→iframe communication
    * @throws Error if the iframe is not connected to the document
    * @throws Error if contentWindow is unavailable
-   *
-   * @example Correct host construction order
-   * ```ts source="./message-transport.examples.ts#PostMessageTransport_forHostIframe"
-   * const iframe = document.createElement("iframe");
-   * iframe.sandbox.add("allow-scripts");
-   * document.body.appendChild(iframe);
-   *
-   * // Create transport BEFORE loading content
-   * const transport = PostMessageTransport.forHostIframe(iframe);
-   * await bridge.connect(transport);
-   *
-   * // NOW load the view — ui/initialize will be received
-   * iframe.srcdoc = "<html>...</html>";
-   * ```
    */
   static forHostIframe(iframe: HTMLIFrameElement): PostMessageTransport {
     if (!iframe.isConnected) {