docs: fill gaps surfaced by developer feedback

Adds guidance for recurring questions and pitfalls that came up while
building Apps against the SDK:

patterns.md:
- Model vs App data visibility (content/structuredContent/_meta split)
- Controlling App height, including the autoResize + 100vh feedback loop
- Touch device support (touch-action, horizontal overflow)
- localStorage key namespacing across shared sandbox origin
- Sharing a single ui:// resource across multiple tools
- Conditionally showing UI (two-tool workaround)
- Opening external links via app.openLink
- color-scheme CSS gotcha that breaks iframe transparency

overview.md:
- Resource versioning/caching note — template and data may be from
  different code versions

New pages:
- design-guidelines.md
- troubleshooting.md

typedoc.config.mjs wired up to include the two new pages.

Author: localden

docs/design-guidelines.md

@@ -0,0 +1,61 @@
+---
+title: Design Guidelines
+group: Getting Started
+description: UX guidance for MCP Apps — what the host already provides, how to size your content, and how to stay visually consistent with the surrounding chat.
+---
+
+# Design Guidelines
+
+MCP Apps live inside a conversation. They should feel like a natural part of the chat, not a separate application wedged into it.
+
+## The host provides the chrome
+
+Hosts typically render a frame around your App that includes:
+
+- A **title bar** showing your App's name (from the tool or server metadata)
+- **Display-mode controls** (expand to fullscreen, collapse, close)
+- **Attribution** (which connector/server the App came from)
+
+**Don't duplicate these.** Your App doesn't need its own close button, title header, or "powered by" footer. Start your layout with the actual content.
+
+If you need a title _inside_ your content (e.g., "Q3 Revenue by Region" above a chart), that's fine — just don't put your App's brand name there.
+
+## Keep it focused
+
+An MCP App answers one question or supports one task. Resist the urge to build a full dashboard with tabs, sidebars, and settings panels.
+
+Good heuristics:
+
+- **Inline mode should fit in roughly one screen of scroll.** If your content is much taller than the chat viewport, consider whether it belongs in fullscreen mode — or whether you're showing too much.
+- **One primary action at most.** A "Confirm" button is fine. A toolbar with eight icons is probably too much for inline mode.
+- **Let the conversation drive navigation.** Instead of building a search box inside your App, let the user ask a follow-up question and re-invoke the tool with new arguments.
+
+## Don't replicate the host's UI
+
+Your App must not look like the surrounding chat client. Specifically, avoid:
+
+- Rendering fake chat bubbles or message threads
+- Mimicking the host's input box or send button
+- Showing fake system notifications or permission dialogs
+
+These patterns confuse users about what's real host UI versus App content, and most hosts prohibit them in their submission guidelines.
+
+## Use host styling where possible
+
+Hosts provide CSS custom properties for colors, fonts, spacing, and border radius (see [Adapting to host context](./patterns.md#adapting-to-host-context-theme-styling-fonts-and-safe-areas)). Using them makes your App feel native across light mode, dark mode, and different host themes.
+
+You can bring your own brand colors for content (chart series, status badges), but let the host's variables drive backgrounds, text, and borders. Always provide fallback values so your App still renders reasonably on hosts that don't supply every variable.
+
+## Inline vs fullscreen layout
+
+Design for **inline first** — that's where your App appears by default. Inline mode is narrow (often the width of a chat message) and height-constrained.
+
+Treat **fullscreen** as a progressive enhancement for Apps that benefit from more space (editors, maps, large datasets). Check `hostContext.availableDisplayModes` before showing a fullscreen toggle — not every host supports it.
+
+When switching modes, remember to adjust your layout: remove border radius at the edges, expand to fill the viewport, and re-read `containerDimensions` from the updated host context.
+
+## Handle the empty and loading states
+
+Your App mounts before the tool result arrives. Between `ui/initialize` and `ontoolresult`, show something — a skeleton, a spinner, or at minimum a neutral background. A blank white rectangle looks broken.
+
+Similarly, if your tool result can be empty (no search results, no items in cart), design a clear empty state rather than rendering nothing.

docs/overview.md

@@ -110,6 +110,8 @@ Resources are declared upfront, during tool registration. This design enables:
 - **Separation of concerns** — Templates (presentation) are separate from tool results (data)
 - **Review** — Hosts can inspect UI templates during connection setup
 
+**Versioning and caching.** Resource caching behavior is host-defined. A host may re-fetch your `ui://` resource each time it renders, cache it for the session, or persist it alongside the conversation. This means a user revisiting an old conversation may see either your _current_ template code running against the _original_ tool result, or a snapshot of both from when the tool first ran. Design your App to tolerate older `structuredContent` shapes — treat unknown fields gracefully and don't assume the template and the data were produced by the same code version.
+
 See the [UI Resource Format](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx#ui-resource-format) section of the specification for the full schema.
 
 ## Tool-UI Linkage

docs/patterns.md

@@ -37,6 +37,35 @@ registerAppTool(
 > [!NOTE]
 > For full examples that implement this pattern, see: [`examples/system-monitor-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/system-monitor-server) and [`examples/pdf-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/pdf-server).
 
+## What the model sees vs what the App sees
+
+A tool result has three places to put data, each with different visibility:
+
+| Field               | Seen by model | Seen by App | Use for                                                                    |
+| ------------------- | ------------- | ----------- | -------------------------------------------------------------------------- |
+| `content`           | ✅            | ✅          | Short text summary the model can reason about and text-only hosts can show |
+| `structuredContent` | ❌            | ✅          | Structured data the App renders (tables, charts, lists)                    |
+| `_meta`             | ❌            | ✅          | Opaque metadata (IDs, timestamps, view identifiers)                        |
+
+Keep `content` brief — a one-line summary is usually enough. The model uses it to decide what to say next, so avoid dumping raw data there.
+
+> [!WARNING]
+> **Don't put large payloads in tool results.** Base64-encoded audio, images, or file contents should be served via MCP resources (see [Serving binary blobs via resources](#serving-binary-blobs-via-resources)) or fetched by the App over the network, not returned inline in `structuredContent`. Even though `structuredContent` is not added to the model's context by spec, large tool results slow down transport, inflate conversation storage, and some host implementations may include more of the result than you expect.
+
+**Write `content` for the model, not the user.** The user is looking at your App, not reading the `content` text. A good `content` string tells the model what just happened so it can respond naturally without repeating what's already on screen:
+
+```ts
+return {
+  content: [
+    {
+      type: "text",
+      text: "Rendered an interactive chart of Q3 revenue by region. The user can see and interact with it directly — do not describe the chart contents in your response.",
+    },
+  ],
+  structuredContent: { regions, revenue, quarter: "Q3" },
+};
+```
+
 ## Polling for live data
 
 For real-time dashboards or monitoring views, use an app-only tool (with `visibility: ["app"]`) that the App polls at regular intervals.
@@ -402,6 +431,29 @@ function MyApp() {
 > [!NOTE]
 > For full examples that implement this pattern, see: [`examples/basic-server-vanillajs/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vanillajs) and [`examples/basic-server-react/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-react).
 
+> [!TIP]
+> **Avoid the `color-scheme` CSS property on your root element.** If your App declares `color-scheme: light dark` but the host's document doesn't, browsers insert an opaque backdrop behind the iframe to prevent cross-scheme bleed-through — which breaks transparent backgrounds. Prefer the `[data-theme]` attribute approach shown above and let the host control scheme negotiation.
+
+## Supporting touch devices
+
+Apps that handle pointer gestures (pan, drag, pinch) need to prevent those gestures from also scrolling the surrounding chat. Use [`touch-action`](https://developer.mozilla.org/en-US/docs/Web/CSS/touch-action) on interactive surfaces:
+
+```css
+/* Chart/canvas that handles its own panning */
+.chart-surface {
+  touch-action: none;
+}
+
+/* Horizontal slider that shouldn't trigger vertical page scroll */
+.slider-track {
+  touch-action: pan-y; /* allow vertical scroll, consume horizontal */
+}
+```
+
+Without this, a user dragging across your chart on mobile will also scroll the chat, and your App may never receive the `pointermove` events.
+
+Also make sure your layout doesn't overflow horizontally — set `overflow-x: hidden` on the root container if you have any fixed-width elements. Horizontal overflow on mobile causes the entire App to wobble when scrolled.
+
 ## Entering / exiting fullscreen
 
 Toggle fullscreen mode by calling {@link app!App.requestDisplayMode `requestDisplayMode`}:
@@ -453,6 +505,39 @@ In fullscreen mode, remove the container's border radius so content extends to t
 > [!NOTE]
 > For full examples that implement this pattern, see: [`examples/shadertoy-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/shadertoy-server), [`examples/pdf-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/pdf-server), and [`examples/map-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/map-server).
 
+## Controlling App height
+
+By default, the SDK observes your document's content height and reports it to the host so the iframe grows to fit (`autoResize: true`). This works well for content-driven UI like cards, tables, and forms — but it's the wrong choice for viewport-filling UI like canvases, maps, and editors.
+
+Pick one of three strategies:
+
+**1. Auto-resize (default)** — for content that has a natural height. Let the iframe grow to fit. Don't set `height: 100vh` or `height: 100%` on your root element, or you'll create a feedback loop where the reported height keeps growing.
+
+**2. Fixed height** — for UI that should always be the same size inline. Disable auto-resize and set an explicit height:
+
+```ts
+const app = new App(
+  { name: "my-app", version: "0.1.0" },
+  {},
+  { autoResize: false },
+);
+```
+
+```css
+html,
+body {
+  height: 500px;
+  margin: 0;
+}
+```
+
+**3. Host-driven height** — for UI that should fill whatever space the host gives it (common for fullscreen-capable Apps). Disable auto-resize and read the host-provided dimensions from {@link types!McpUiHostContext `hostContext.containerDimensions`}, updating on {@link app!App.onhostcontextchanged `onhostcontextchanged`}.
+
+> [!WARNING]
+> **Never 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.
+
+If you're using the React `useApp` hook, note that it 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.
+
 ## Passing contextual information from the App to the model
 
 Use {@link app!App.updateModelContext `updateModelContext`} to keep the model informed about what the user is viewing or interacting with. Structure the content with YAML frontmatter for easy parsing:
@@ -569,6 +654,11 @@ app.ontoolresult = (result) => {
 
 For state that represents user effort (e.g., saved bookmarks, annotations, custom configurations), consider persisting it server-side using [app-only tools](#tools-that-are-private-to-apps) instead. Pass the `viewUUID` to the app-only tool to scope the saved data to that view instance.
 
+> [!WARNING]
+> **Always namespace your `localStorage` keys.** Hosts typically serve all MCP Apps from the same sandbox origin, which means every App shares the same `localStorage`. Using generic keys like `"state"` or `"settings"` will collide with other Apps. The server-generated `viewUUID` pattern above avoids this, but if you use any other keys, prefix them with a string unique to your App.
+>
+> Availability of `localStorage` is also host-dependent — it may be unavailable in some sandbox configurations. Always wrap access in `try`/`catch` and degrade gracefully.
+
 > [!NOTE]
 > For full examples using `localStorage`, see: [`examples/pdf-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/pdf-server) (persists current page) and [`examples/map-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/map-server) (persists camera position).
 
@@ -601,6 +691,61 @@ app.onteardown = async () => {
 > [!NOTE]
 > For full examples that implement this pattern, see: [`examples/shadertoy-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/shadertoy-server) and [`examples/threejs-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/threejs-server).
 
+## Sharing one UI resource across multiple tools
+
+You can point several tools at the same `ui://` resource — for example, a single "document viewer" App that renders results from `open-document`, `search-documents`, and `recent-documents`.
+
+The App needs to know which tool produced its data so it can parse the payload correctly. The host may provide this via `hostContext.toolInfo`, but it's optional and not guaranteed on every host. The reliable pattern is to include a discriminator in your tool result:
+
+```ts
+// In each tool handler, tag the result with its origin
+return {
+  content: [{ type: "text", text: "Opened annual-report.pdf" }],
+  structuredContent: {
+    kind: "open-document", // discriminator
+    document: { id, title, pageCount },
+  },
+};
+```
+
+```ts
+// In the App, branch on the discriminator
+app.ontoolresult = (result) => {
+  const data = result.structuredContent as { kind: string };
+  switch (data.kind) {
+    case "open-document":
+      renderViewer(data);
+      break;
+    case "search-documents":
+      renderSearchResults(data);
+      break;
+  }
+};
+```
+
+## Conditionally showing UI
+
+The tool-to-resource binding is declared at registration time — a tool either has a `_meta.ui.resourceUri` or it doesn't. You can't decide per-call whether to render UI.
+
+If you need both behaviors, register two tools:
+
+- `query-data` — no `_meta.ui`, returns text/structured data for the model to reason about
+- `visualize-data` — has `_meta.ui`, returns the same data rendered as an interactive App
+
+Give each a clear description so the model picks the right one based on user intent ("show me" → visualize, "tell me" → query).
+
+If the decision truly must be server-side (e.g., only show UI when the result set exceeds a threshold), the current workaround is to always attach the UI resource but have the App render a minimal, collapsed placeholder when there's nothing worth showing. Keep the placeholder small so it doesn't add visual noise to the conversation.
+
+## Opening external links
+
+Use {@link app!App.openLink `app.openLink()`} instead of `window.open()` or `<a target="_blank">`. The sandbox blocks direct navigation; `openLink` asks the host to open the URL on your behalf.
+
+Hosts typically show an interstitial confirmation before navigating so users can review the destination — don't assume the navigation is instant, and don't chain multiple `openLink` calls.
+
+```ts
+await app.openLink({ url: "https://example.com/docs" });
+```
+
 ## Lowering perceived latency
 
 Use {@link app!App.ontoolinputpartial `ontoolinputpartial`} to receive streaming tool arguments as they arrive. This lets you show a loading preview before the complete input is available, such as streaming code into a `<pre>` tag before executing it, partially rendering a table as data arrives, or incrementally populating a chart.