# React State & Hydration Analysis — MCP App Lifecycle
## Executive Summary
**The interactive state destruction is caused by a cascading chain of three interconnected bugs:**
1. Every tool call result replaces the entire UITree → full component tree teardown
2. Element keys from the server may not be stable across calls → React unmounts everything
3. All interactive components store state locally (`useState`) instead of in the shared context that was built specifically to survive re-renders
---
## Bug #1: `ontoolresult` → `setUITree()` Nuclear Replacement
### The Code (App.tsx:80-86)
```tsx
app.ontoolresult = async (result) => {
const tree = extractUITree(result);
if (tree) {
setUITree(tree); // ← REPLACES the entire tree object
setToolInput(null);
}
};
```
### What Happens
Every tool result that contains a UITree — even from a button click, search query, or tab switch — causes `setUITree(brandNewTreeObject)`. This triggers:
1. `App.tsx` re-renders with new `uiTree` state
2. `<UITreeRenderer tree={uiTree} />` receives a **new object reference**
3. `ElementRenderer` receives a **new `elements` map** (new reference, even if data is identical)
4. React walks the entire tree and reconciles
**The critical question:** does it unmount/remount or just re-render?
That depends entirely on **Bug #2** (keys).
---
## Bug #2: `key: element.key` — Keys Control Component Identity
### The Code (UITreeRenderer.tsx:37-40)
```tsx
// Each component gets its key from the JSON tree
return React.createElement(Component, { key: element.key, ...element.props }, childElements);
// Children also keyed from the tree
const childElements = element.children?.map((childKey) =>
React.createElement(ElementRenderer, {
key: childKey, // ← from JSON
elementKey: childKey, // ← from JSON
elements,
}),
);
```
### The Problem
React uses `key` to determine component identity. When keys change between renders:
- **Same key** → React re-renders the existing component (state preserved)
- **Different key** → React unmounts old, mounts new (STATE DESTROYED)
If the MCP server generates keys like `contact-list-abc123` on call #1 and `contact-list-def456` on call #2, React sees them as **completely different components** and tears down the entire subtree.
**Even if keys are stable**, the `elements` object reference changes every time, forcing re-renders down the entire tree. Not a state-loss issue by itself, but causes performance problems and can trigger effects/callbacks unnecessarily.
---
## Bug #3: Dual `uiTree` State — App.tsx vs MCPAppContext
### The Code
```tsx
// App.tsx — has its own uiTree state
const [uiTree, setUITree] = useState<UITree | null>(null);
// MCPAppContext.tsx — ALSO has its own uiTree state
const [uiTree, setUITree] = useState<UITree | null>(null);
```
### The Problem
There are **two completely independent `uiTree` states**:
- `App.tsx` manages the actual rendering tree (used by `<UITreeRenderer tree={uiTree} />`)
- `MCPAppContext` has its own `uiTree` + `setUITree` exposed via context, but **nobody calls the context's `setUITree`**
The context's `uiTree` is **always null**. The context was designed to provide shared state (`formState`, `setFormValue`, `callTool`), but the tree management is disconnected.
---
## Bug #4: Interactive Components Use Local State That Gets Destroyed
### FormGroup (forms reset)
```tsx
// FormGroup.tsx — all form values in LOCAL useState
const [values, setValues] = useState<Record<string, string>>(() => {
const init: Record<string, string> = {};
for (const f of fields) { init[f.key] = ""; }
return init;
});
```
**Chain:** User types → submits → `execute(submitTool, values)` → server returns new tree → `ontoolresult` → `setUITree(newTree)` → FormGroup unmounts → remounts → `values` resets to `{}`
### KanbanBoard (drag-and-drop fails)
```tsx
// KanbanBoard.tsx — drag state + columns in LOCAL state
const [columns, setColumns] = useState<KanbanColumn[]>(initialColumns);
const [dropTargetStage, setDropTargetStage] = useState<string | null>(null);
const [draggingCardId, setDraggingCardId] = useState<string | null>(null);
const dragRef = useRef<DragState | null>(null);
```
**Chain:** User drags card → optimistic update → `callTool(moveTool, ...)` → server returns new tree → `ontoolresult` → `setUITree(newTree)` → KanbanBoard unmounts → remounts → drag state gone, optimistic move reverted, columns reset to server data
The KanbanBoard even has a mitigation attempt that fails:
```tsx
// This ref-based sync ONLY works if React re-renders without unmounting
const prevColumnsRef = useRef(initialColumns);
if (prevColumnsRef.current !== initialColumns) {
prevColumnsRef.current = initialColumns;
setColumns(initialColumns); // ← This runs, but after unmount/remount it's moot
}
```
### SearchBar (search clears)
```tsx
// SearchBar.tsx — query in LOCAL state
const [value, setValue] = useState("");
```
**Chain:** User types query → debounced `callTool(searchTool, ...)` → server returns new tree → SearchBar unmounts → remounts → search input clears
### ActionButton (stops working)
```tsx
// ActionButton.tsx — loading state in LOCAL state
const [loading, setLoading] = useState(false);
```
**Chain:** User clicks → `setLoading(true)` → `callTool(...)` → server returns new tree → ActionButton unmounts → remounts → `loading` stuck at initial `false`, but the async `callTool` still has a stale closure reference. The `finally { setLoading(false) }` calls `setLoading` on an unmounted component.
### TabGroup (tab selection lost)
```tsx
const [localActive, setLocalActive] = useState<string>(
controlledActiveTab || tabs[0]?.value || "",
);
```
**Chain:** User clicks tab → `setLocalActive(value)` → `callTool(switchTool, ...)` → new tree → TabGroup remounts → `localActive` resets to first tab
### ContactPicker (search results disappear)
```tsx
const [query, setQuery] = useState("");
const [results, setResults] = useState<Contact[]>([]);
const [isOpen, setIsOpen] = useState(false);
const [selected, setSelected] = useState<Contact | null>(null);
```
### InvoiceBuilder (entire form wiped)
```tsx
const [selectedContact, setSelectedContact] = useState<SelectedContact | null>(null);
const [lineItems, setLineItems] = useState<InvoiceLineItem[]>(...);
const [taxRate, setTaxRate] = useState(8.5);
```
---
## Bug #5: Hydration Path Mismatch
### The Code (App.tsx:60-66)
```tsx
useEffect(() => {
const preInjected = getPreInjectedTree();
if (preInjected && !uiTree) {
setUITree(preInjected);
}
}, []);
```
### The Problem
Not a React hydration mismatch (we use `createRoot`, not `hydrateRoot`), but a **data transition issue**:
1. App mounts → `uiTree = null` → shows "Connecting..."
2. `useEffect` fires → finds `window.__MCP_APP_DATA__` → `setUITree(preInjectedTree)`
3. Tree renders with pre-injected keys
4. `ontoolresult` fires with server-generated tree → `setUITree(serverTree)`
5. If keys differ between pre-injected and server tree → **full unmount/remount**
The pre-injected path and the dynamic path produce trees with potentially different key schemas, causing a jarring full teardown on the first real tool result.
---
## Bug #6: MCPAppProvider Context Is Stable (NOT a bug)
`MCPAppProvider` wrapping does **not** cause context loss. It's rendered consistently in all branches of the conditional render in App.tsx. The provider identity is stable.
However, the provider creates a **new `value` object on every render**:
```tsx
const value: MCPAppContextValue = {
uiTree, setUITree, formState, setFormValue, resetFormState, callTool, isLoading, app,
};
return <MCPAppContext.Provider value={value}>{children}</MCPAppContext.Provider>;
```
This causes every `useMCPApp()` consumer to re-render on every provider render, but it doesn't cause state loss — just unnecessary renders.
---
## The Kill Chain (Full Interaction Flow)
```
User clicks ActionButton("View Contact", toolName="get_contact", toolArgs={id: "123"})
│
├─ ActionButton.handleClick()
│ ├─ setLoading(true)
│ └─ callTool("get_contact", {id: "123"})
│ └─ app.callServerTool({name: "get_contact", arguments: {id: "123"}})
│
├─ MCP Server processes tool call, returns CallToolResult with NEW UITree
│
├─ app.ontoolresult fires
│ ├─ extractUITree(result) → newTree (new keys, new elements, new object)
│ └─ setUITree(newTree) ← App.tsx state update
│
├─ App.tsx re-renders
│ └─ <UITreeRenderer tree={newTree} />
│ └─ ElementRenderer receives new elements map
│ └─ For each element: React.createElement(Component, {key: NEW_KEY, ...})
│ └─ React sees different key → UNMOUNT old component, MOUNT new one
│
├─ ALL components unmount:
│ ├─ FormGroup: values={} (reset)
│ ├─ KanbanBoard: columns=initial, dragState=null (reset)
│ ├─ SearchBar: value="" (reset)
│ ├─ TabGroup: localActive=first tab (reset)
│ ├─ ContactPicker: query="", results=[], selected=null (reset)
│ └─ InvoiceBuilder: lineItems=[default], contact=null (reset)
│
└─ Meanwhile, ActionButton's finally{} block calls setLoading(false)
on an UNMOUNTED component → React warning + no-op
```
---
## Fixes
### Fix 1: Deterministic Stable Keys (Server-Side)
The MCP server must generate **deterministic, position-stable keys** for UITree elements. Keys should be based on component type + semantic identity, not random IDs.
```typescript
// BAD: keys change every call
{ key: `card-${crypto.randomUUID()}`, type: "Card", ... }
// GOOD: keys are stable across calls
{ key: "contact-detail-card", type: "Card", ... }
{ key: "pipeline-kanban", type: "KanbanBoard", ... }
```
### Fix 2: Tree Diffing / Partial Updates Instead of Full Replace
Don't replace the entire tree on every tool result. Diff the new tree against the old one and only update changed branches:
```tsx
// App.tsx — instead of wholesale replace:
app.ontoolresult = async (result) => {
const newTree = extractUITree(result);
if (newTree) {
setUITree(prev => {
if (!prev) return newTree;
// Merge: keep unchanged elements, update changed ones
return mergeUITrees(prev, newTree);
});
}
};
function mergeUITrees(oldTree: UITree, newTree: UITree): UITree {
const mergedElements: Record<string, UIElement> = {};
for (const [key, newEl] of Object.entries(newTree.elements)) {
const oldEl = oldTree.elements[key];
// Keep old reference if data is identical (prevents re-render)
if (oldEl && JSON.stringify(oldEl) === JSON.stringify(newEl)) {
mergedElements[key] = oldEl;
} else {
mergedElements[key] = newEl;
}
}
return { root: newTree.root, elements: mergedElements };
}
```
### Fix 3: Separate Data Results from UI Results
Not every tool call should trigger a tree replacement. ActionButton clicks that return data (not a new view) should be handled by the component, not by `ontoolresult`:
```tsx
// ActionButton.tsx — handle result locally, don't let ontoolresult replace tree
const handleClick = useCallback(async () => {
if (!toolName || loading || disabled) return;
setLoading(true);
try {
const result = await callTool(toolName, toolArgs || {});
// Result handled locally — only navigate if result contains a NEW view
if (result && hasNavigationIntent(result)) {
// Let ontoolresult handle it
}
// Otherwise, toast/notification with result, don't replace tree
} finally {
setLoading(false);
}
}, [toolName, toolArgs, loading, disabled, callTool]);
```
### Fix 4: Move Interactive State to Context
Use the existing `formState` in MCPAppContext instead of local `useState`:
```tsx
// FormGroup.tsx — use shared form state that survives remounts
const { formState, setFormValue } = useMCPApp();
// Instead of local useState, derive from context
const getValue = (key: string) => formState[`form:${formId}:${key}`] ?? "";
const setValue = (key: string, val: string) => setFormValue(`form:${formId}:${key}`, val);
```
### Fix 5: Fix the Dual uiTree State
Either:
- **Option A:** Remove `uiTree` from MCPAppContext entirely (it's unused)
- **Option B:** Have App.tsx use the context's uiTree and remove its local state
```tsx
// Option B: App.tsx uses context state
export function App() {
const [hostContext, setHostContext] = useState<McpUiHostContext | undefined>();
// Remove local uiTree state — let context own it
// In MCPAppProvider, connect ontoolresult to context's setUITree
}
```
### Fix 6: Memoize Context Value
Prevent unnecessary re-renders of all context consumers:
```tsx
// MCPAppContext.tsx
const value = useMemo<MCPAppContextValue>(() => ({
uiTree, setUITree, formState, setFormValue, resetFormState, callTool, isLoading, app,
}), [uiTree, formState, callTool, isLoading, app]);
```
### Fix 7: Add React.memo to Leaf Components
Prevent re-renders when props haven't actually changed:
```tsx
export const MetricCard = React.memo<MetricCardProps>(({ label, value, trend, ... }) => {
// ...
});
export const StatusBadge = React.memo<StatusBadgeProps>(({ label, variant }) => {
// ...
});
```
---
## Priority Order
| # | Fix | Impact | Effort |
|---|-----|--------|--------|
| 1 | Stable keys (server-side) | 🔴 Critical — fixes unmount/remount | Medium |
| 2 | Tree diffing/merge | 🔴 Critical — prevents unnecessary teardown | Medium |
| 3 | Separate data vs UI results | 🟡 High — stops button clicks from nuking the view | Low |
| 4 | Context-based interactive state | 🟡 High — state survives even if components remount | Medium |
| 5 | Fix dual uiTree state | 🟢 Medium — removes confusion, single source of truth | Low |
| 6 | Memoize context value | 🟢 Medium — performance improvement | Low |
| 7 | React.memo leaf components | 🟢 Low — performance polish | Low |
