docs: address adversarial-review findings

Accuracy:
- patterns: drop incorrect useAutoResize-with-element advice; useApp simply
  doesn't expose autoResize, so construct App manually
- patterns: add full host-driven height snippet using addEventListener and
  the containerDimensions union (with in-guards), plus a strategy decision table
- patterns/overview: align structuredContent visibility wording (model sees it
  only when content is empty) across both pages
- design-guidelines/patterns/troubleshooting: switch new content from deprecated
  on* setters to addEventListener; retitle troubleshooting section to event names
- design-guidelines: describe containerDimensions as fixed-or-max bounds, not
  plain {width,height}

Gaps:
- design-guidelines: cover toolcancelled as a terminal loading state; mention
  requestTeardown alongside the no-close-button guidance
- troubleshooting: surface basic-host repro tip at top of Blank iframe

Clarity/examples:
- patterns: openLink/downloadFile snippet now gates control rendering, not the
  call site; sharing-one-UI snippet guards isError before casting; fixed-height
  snippet uses bare app.connect(); dedupe 100vh warning
- design-guidelines: reword Scope intro to target application shells (resolve
  tabs contradiction); soften inline-height claim and cross-link to patterns

Author: localden

docs/design-guidelines.md

@@ -16,15 +16,15 @@ Hosts render a frame around your App that typically includes:
 - Display-mode controls (expand, collapse, close)
 - Attribution indicating which connector or server provided the App
 
-Do not duplicate these elements. Your App does not need its own close button, header bar, or "powered by" footer. Begin the layout with content.
+Do not duplicate these elements. Your App does not need its own close button, header bar, or "powered by" footer. Begin the layout with content. If the App should dismiss itself after a task completes, call {@link app!App.requestTeardown `app.requestTeardown()`}; the host decides whether to honor the request.
 
 A title inside the content area (for example, "Q3 Revenue by Region" above a chart) is acceptable. The App's brand name is not.
 
 ## Scope
 
-An MCP App answers one question or supports one task. Avoid building a full dashboard with tabs, sidebars, and settings panels.
+An MCP App answers one question or supports one task. Avoid building an application shell around it: global navigation, sidebars, and settings panels belong to the host, not the App.
 
-- Inline content can be tall, but it must scroll with the surrounding conversation. Do not introduce nested scroll containers in inline mode; a scrollable region inside a scrollable chat is difficult to use on every input device.
+- Inline content can be tall, but it must scroll with the surrounding conversation. Do not introduce nested scroll containers in inline mode; a scrollable region inside a scrollable chat is difficult to use on every input device. See [Supporting touch devices](./patterns.md#supporting-touch-devices).
 - Design the inline layout to remain usable at narrow widths. Chat columns can be as narrow as a mobile message bubble, so dense toolbars and side-by-side panels should collapse or move to fullscreen mode rather than overflow.
 - Avoid multi-page navigation (routes, wizards, tab stacks) in inline mode. The conversation already provides history and back-navigation. In-App search or filtering over the current data set is fine; navigating to a different document or view is better handled by a follow-up tool call, or reserved for fullscreen mode.
 
@@ -46,14 +46,16 @@ Brand colors are appropriate for content elements such as chart series or status
 
 ## Display modes
 
-Design for inline mode first. It is the default, and it is narrow (often the width of a chat message). Inline height is effectively unconstrained: hosts apply only a high safety cap, so the iframe will grow to whatever content height the App reports.
+Design for inline mode first. It is the default, and it is narrow (often the width of a chat message). Most hosts let inline height grow with content up to a high safety cap, but a host may also pin the iframe to a fixed height via `containerDimensions`; see [Controlling App height](./patterns.md#controlling-app-height).
 
 Treat fullscreen as a progressive enhancement for Apps that benefit from more space: editors, maps, large datasets. Check `hostContext.availableDisplayModes` before rendering a fullscreen toggle, since not every host supports it.
 
-When the display mode changes, update your layout: remove edge border radius and expand to fill the viewport. To size the App to the space the host provides, subscribe to `hostContext.containerDimensions` via {@link app!App.onhostcontextchanged `onhostcontextchanged`} and apply the reported width and height to your root element.
+When the display mode changes, update your layout: remove edge border radius and expand to fill the viewport. To size the App to the space the host provides, listen for `hostcontextchanged` via {@link app!App.addEventListener `app.addEventListener`} and read `containerDimensions` from the event payload, which reports either fixed `width`/`height` or `maxWidth`/`maxHeight` bounds depending on the host.
 
 ## Loading and empty states
 
-The App mounts before the tool result arrives, and even before the tool inputs are sent. Between `ui/initialize` and `ontoolresult`, render a loading indicator such as a skeleton, spinner, or neutral background. A blank rectangle looks broken.
+The App mounts before the tool result arrives, and even before the tool inputs are sent. Render a loading indicator such as a skeleton, spinner, or neutral background between `ui/initialize` and the first terminal event. A blank rectangle looks broken.
+
+The terminal events are `toolresult` (success or `isError`) and `toolcancelled` (user stopped the request). Handle both: an App that clears its loading state only on `toolresult` will spin indefinitely if the user cancels.
 
 If the tool result can be empty (no search results, empty cart), design an explicit empty state rather than rendering nothing.

docs/overview.md

@@ -94,7 +94,7 @@ sequenceDiagram
 
 1. **Discovery** — The Host learns about tools and their UI resources when connecting to the server.
 2. **Initialization** — When a UI tool is called, the Host renders the iframe. The View sends `ui/initialize` and receives host context (theme, capabilities, container dimensions). This handshake ensures the View is ready before receiving data.
-3. **Data delivery** — The Host sends tool arguments and, once available, tool results to the View. Results include both `content` (text for the model's context) and optionally `structuredContent` (data optimized for UI rendering). This separation lets servers provide rich data to the UI without bloating the model's context.
+3. **Data delivery** — The Host sends tool arguments and, once available, tool results to the View. Results include both `content` (text for the model's context) and optionally `structuredContent` (data optimized for UI rendering, passed to the model only when `content` is empty). This separation lets servers provide rich data to the UI without bloating the model's context.
 4. **Interactive phase** — The user interacts with the View. The View can call tools, send messages, or update context.
 5. **Teardown** — Before unmounting, the Host notifies the View so it can save state or release resources.
 

docs/patterns.md

@@ -47,7 +47,7 @@ A tool result has three fields for data, each with different visibility:
 | `structuredContent` | Only when `content` is empty | Yes         | Structured data the App renders (tables, charts, lists)       |
 | `_meta`             | No                           | Yes         | Opaque metadata such as IDs, timestamps, and view identifiers |
 
-Per the MCP guideline, hosts pass `structuredContent` to the model only when `content` is omitted, so populating `content` is the way to keep large render payloads out of the model's context. The App receives all three fields regardless. Keep `content` brief: the model uses it to decide what to say next, so a one-line summary is preferable to raw data.
+Per the core MCP guideline, hosts fall back to passing `structuredContent` to the model only when `content` is empty, so populating `content` is the way to keep large render payloads out of the model's context. The App receives all three fields regardless. Keep `content` brief: the model uses it to decide what to say next, so a one-line summary is preferable to raw data.
 
 > [!WARNING]
 > Do not return large payloads in tool results. Serve base64-encoded audio, images, or file contents via MCP resources (see [Serving binary blobs via resources](#serving-binary-blobs-via-resources)) or have the App fetch them over the network. Even when `structuredContent` is kept out of the model's context, large tool results still slow down transport, inflate conversation storage, and some host implementations include more of the result than the specification requires.
@@ -511,9 +511,13 @@ In fullscreen mode, remove the container's border radius so content extends to t
 
 By default, the SDK observes the document's content height and reports it to the host so the iframe grows to fit (`autoResize: true`). This is appropriate for content-driven UI such as cards, tables, and forms. It is the wrong choice for viewport-filling UI such as canvases, maps, and editors.
 
-There are three height strategies:
+| UI type                               | Strategy    | `autoResize` | Root CSS height            |
+| ------------------------------------- | ----------- | ------------ | -------------------------- |
+| Cards, tables, forms (natural height) | Auto-resize | `true`       | unset                      |
+| Fixed-size widgets                    | Fixed       | `false`      | explicit `px`              |
+| Canvases, maps, editors (fill space)  | Host-driven | `false`      | from `containerDimensions` |
 
-**Auto-resize (default).** For content with a natural height. The iframe grows to fit. Do not set `height: 100vh` or `height: 100%` on the root element; doing so creates a feedback loop where the reported height keeps increasing.
+**Auto-resize (default).** For content with a natural height. The iframe grows to fit.
 
 **Fixed height.** For UI that should remain the same size when inline. Disable auto-resize, set an explicit height, and report it to the host with {@link app!App.sendSizeChanged `sendSizeChanged`} so the iframe is allocated the correct size:
 
@@ -523,7 +527,7 @@ const app = new App(
   {},
   { autoResize: false },
 );
-await app.connect(new PostMessageTransport(window.parent, window.parent));
+await app.connect();
 app.sendSizeChanged({ width: document.body.clientWidth, height: 500 });
 ```
 
@@ -535,12 +539,28 @@ body {
 }
 ```
 
-**Host-driven height.** For UI that should fill the space the host provides (common for fullscreen-capable Apps). Disable auto-resize and read dimensions from {@link types!McpUiHostContext `hostContext.containerDimensions`}, updating on {@link app!App.onhostcontextchanged `onhostcontextchanged`}.
+**Host-driven height.** For UI that should fill the space the host provides (common for fullscreen-capable Apps). Disable auto-resize and size the root element from {@link types!McpUiHostContext `hostContext.containerDimensions`}, which may report fixed `width`/`height` or `maxWidth`/`maxHeight` bounds:
+
+```ts
+const app = new App(
+  { name: "my-app", version: "0.1.0" },
+  {},
+  { autoResize: false },
+);
+const root = document.getElementById("root")!;
+
+app.addEventListener("hostcontextchanged", (ctx) => {
+  const dims = ctx.containerDimensions;
+  if (dims && "height" in dims) root.style.height = `${dims.height}px`;
+  if (dims && "width" in dims) root.style.width = `${dims.width}px`;
+});
+await app.connect();
+```
 
 > [!WARNING]
 > Do not combine `autoResize: true` with `height: 100vh` or `100%` on the root element. The SDK reports the document height, the host grows the iframe to match, the document sees a taller viewport and grows again. This loops until the host's maximum height cap.
 
-The React `useApp` hook always creates the App with `autoResize: true`. For fixed or host-driven height, construct the `App` manually or use the `useAutoResize` hook with a specific element.
+The React `useApp` hook always creates the App with `autoResize: true` and does not currently expose an option to disable it. For fixed or host-driven height, construct the `App` manually with `{ autoResize: false }` instead of using `useApp`.
 
 ## Passing contextual information from the App to the model
 
@@ -714,7 +734,10 @@ return {
 
 ```ts
 // In the App, branch on the discriminator
-app.ontoolresult = (result) => {
+app.addEventListener("toolresult", (result) => {
+  if (result.isError || !result.structuredContent) {
+    return renderError(result);
+  }
   const data = result.structuredContent as { kind: string };
   switch (data.kind) {
     case "open-document":
@@ -724,7 +747,7 @@ app.ontoolresult = (result) => {
       renderSearchResults(data);
       break;
   }
-};
+});
 ```
 
 ## Conditionally showing UI
@@ -779,12 +802,16 @@ Use {@link app!App.openLink `app.openLink()`} instead of `window.open()` or `<a
 Both are optional host capabilities. Check {@link app!App.getHostCapabilities `getHostCapabilities`} before rendering the corresponding controls so the App degrades gracefully on hosts that do not implement them:
 
 ```ts
-if (app.getHostCapabilities()?.openLinks) {
-  await app.openLink({ url: "https://example.com/docs" });
-}
+const caps = app.getHostCapabilities();
+
+// Hide controls the host cannot honor
+docsLink.hidden = !caps?.openLinks;
+downloadButton.hidden = !caps?.downloadFile;
 
-if (app.getHostCapabilities()?.downloadFile) {
-  await app.downloadFile({
+docsLink.onclick = () => app.openLink({ url: "https://example.com/docs" });
+
+downloadButton.onclick = () =>
+  app.downloadFile({
     contents: [
       {
         type: "resource",
@@ -796,7 +823,6 @@ if (app.getHostCapabilities()?.downloadFile) {
       },
     ],
   });
-}
 ```
 
 Hosts typically show an interstitial confirmation for `openLink` so users can review the destination before navigating. Do not assume navigation is instant, and do not chain multiple `openLink` calls.

docs/troubleshooting.md

@@ -8,6 +8,9 @@ description: Diagnose common MCP App issues including blank iframes, CSP errors,
 
 ## Blank iframe
 
+> [!TIP]
+> The fastest way to diagnose any of the issues below is to load your App in the reference host, which logs all protocol traffic to the browser console. See [Test with basic-host](./testing-mcp-apps.md#test-with-basic-host).
+
 The most common causes, in the order you should check them:
 
 1. **`connect()` was never called.** The host waits for the App to send `ui/initialize` before giving the iframe a non-zero size, so an App that constructs `new App(...)` but never calls `app.connect(transport)` renders as an empty sliver. Confirm `connect()` runs on page load and that its promise resolves.
@@ -20,9 +23,9 @@ The most common causes, in the order you should check them:
 
 5. **Wrong MIME type.** The resource's `mimeType` must be `text/html;profile=mcp-app` (exported as {@link app!RESOURCE_MIME_TYPE `RESOURCE_MIME_TYPE`}). Plain `text/html` is not recognized as an App resource.
 
-## `ontoolinput` / `ontoolresult` never fires
+## `toolinput` / `toolresult` events never fire
 
-- **Handlers registered too late.** Attach `app.ontoolresult` before calling `connect()`. If the handler is attached after `connect()` resolves, the notification may have already been delivered and discarded. The React `useApp` hook handles this ordering automatically.
+- **Listeners registered too late.** Call `app.addEventListener("toolresult", …)` before calling `connect()`. If the listener is attached after `connect()` resolves, the notification may have already been delivered and discarded. The React `useApp` hook handles this ordering automatically.
 - **Tool was not called.** If the model chose a different tool, or none, there is no result to deliver. Check the host's tool-call log.
 - **SDK version mismatch.** Older SDK versions used stricter schemas for host notifications. If the App was built against a significantly older `@modelcontextprotocol/ext-apps` than the host expects, the initialize handshake can fail silently. Keep the SDK version current.