feat: connecting/connected indicator

Author: brandonkachen

cli/knowledge.md

@@ -132,3 +132,224 @@ The implementation uses:
 - `markdownToInline()`: Converts markdown AST to array of inline JSX elements
 - `renderInlineContent()`: Renders inline styling (`<strong>`, `<em>`, `<span>`)
 - Returns a fragment `<>{inlineElements}</>` that can be safely placed inside parent `<text>`
+
+## React Reconciliation Issues
+
+### The "Child not found in children at remove" Error
+
+OpenTUI's React reconciler has **critical limitations** with certain conditional rendering patterns that can cause the error:
+
+```
+Error: Child not found in children
+  at remove (/path/to/TextNode.ts:152:17)
+  at removeChild (/path/to/host-config.ts:60:12)
+```
+
+### Root Cause
+
+OpenTUI's reconciler struggles when:
+1. **Conditionally rendering elements at the same level** using `{condition && <element>}`
+2. **The parent `<text>` element switches between different child structures**
+3. Components that dynamically create/remove `<span>` elements (like ShimmerText)
+4. **Conditionally rendering text nodes** (including spaces like `{showText ? ' ' : ''}`)
+
+This happens because OpenTUI's reconciler doesn't handle React's reconciliation algorithm as smoothly as standard React DOM.
+
+### The Text Node Problem
+
+**CRITICAL INSIGHT**: The issue isn't just about conditionally rendering elements - it also affects **TEXT NODES**. Even something as simple as a conditional space can trigger the error:
+
+```tsx
+// ❌ PROBLEMATIC: Conditionally adding/removing text nodes (including spaces)
+<span>■{showText ? ' ' : ''}</span>
+
+// ✅ WORKING: Put the conditional text inside the span content itself
+<span>{showText ? '■ ' : '■'}</span>
+```
+
+In React, spaces and other text are represented as text nodes in the virtual DOM. When you write `{showText ? ' ' : ''}`, you're conditionally adding/removing a text node child, which causes OpenTUI's reconciler to fail when trying to match up children.
+
+**Key takeaway**: Always include text content (including spaces) as part of the string literal, not as separate conditional expressions.
+
+### ❌ PROBLEMATIC PATTERNS
+
+**Pattern 1: Shared parent with conditional children**
+```tsx
+// This causes reconciliation errors!
+<text wrap={false}>
+  {isConnected ? (
+    <>
+      <span>■ </span>
+      {showText && <span>connected</span>}
+    </>
+  ) : (
+    <ShimmerText text="connecting..." />
+  )}
+</text>
+```
+
+**Pattern 2: Conditionally rendering entire span elements**
+```tsx
+// Also problematic!
+<text wrap={false}>
+  <span>■ </span>
+  {showText && (
+    <span>connected</span>
+  )}
+</text>
+```
+
+**Pattern 3: Conditionally rendering text nodes (spaces, strings, etc.)**
+```tsx
+// Triggers reconciliation errors!
+<span>■{showText ? ' ' : ''}</span>
+<span>{condition ? 'text' : ''}</span>
+```
+
+### ✅ WORKING SOLUTION
+
+**Keep each conditional state in its own stable `<text>` wrapper:**
+
+```tsx
+// This works reliably!
+{isConnected ? (
+  <text wrap={false}>
+    <span>{showText ? '■ ' : '■'}</span>
+    {showText && <span>connected</span>}
+  </text>
+) : (
+  <text wrap={false}>
+    <ShimmerText text="connecting..." />
+  </text>
+)}
+```
+
+**Key principle:** Each major UI state (connected vs disconnected) should have its own `<text>` element. The `<text>` element itself should not change during state transitions within that UI state.
+
+### Why This Works
+
+- The `<text>` element for each state remains **stable**
+- Only the *children* inside each `<text>` change
+- React never tries to reconcile between the connected and disconnected `<text>` elements
+- The reconciler doesn't get confused trying to match up old and new children
+
+### Best Practices
+
+1. **Separate `<text>` elements for different UI states** - Don't try to share a single `<text>` element across major state changes
+2. **Keep element structure stable** - If you need conditional content, prefer changing text content over conditionally rendering elements
+3. **Avoid complex conditional rendering within OpenTUI components** - What works in React DOM may not work in OpenTUI
+4. **Test thoroughly** - Reconciliation errors often appear only during specific state transitions
+
+### Alternative Approach: Stable Element Structure
+
+If you must use a single `<text>` element, keep the child element structure completely stable:
+
+```tsx
+// This also works - elements are always present
+<text wrap={false}>
+  <span>{getIndicatorText()}</span>
+  <span>{getStatusText()}</span>
+</text>
+```
+
+But this approach is less flexible and harder to read than using separate `<text>` elements for each state.
+
+### Best Practice: Direct Ternary Pattern
+
+The cleanest solution is to use a direct ternary with separate `<text>` elements:
+
+```tsx
+{isConnected ? (
+  <text wrap={false}>
+    <span>{showText ? '■ ' : '■'}</span>
+    {showText && <span>connected</span>}
+  </text>
+) : (
+  <text wrap={false}>
+    <ShimmerText text="connecting..." />
+  </text>
+)}
+```
+
+**Why this is the best approach:**
+- Clear and explicit about the two states
+- Minimal abstraction - easy to understand at a glance
+- Each state's `<text>` wrapper is clearly visible
+- No need for additional helper components
+
+**Note:** Helper components like `ConditionalText` are not recommended as they add unnecessary abstraction without providing meaningful benefits. The direct ternary pattern is clearer and easier to maintain.
+
+### The "Text Must Be Created Inside of a Text Node" Error
+
+**Error message:**
+```
+Error: Text must be created inside of a text node
+  at createTextInstance (/path/to/host-config.ts:108:17)
+```
+
+**Root cause:** This error occurs when a component returns Fragment with `<span>` elements containing text, but the parent doesn't wrap it in a `<text>` element.
+
+**What triggers it:**
+```tsx
+// Component returns Fragment with spans
+const ShimmerText = ({ text }) => {
+  return (
+    <>
+      {text.split('').map(char => (
+        <span>{char}</span>  // Text nodes created here!
+      ))}
+    </>
+  )
+}
+
+// ❌ INCORRECT: Using component without <text> wrapper
+<box>
+  <ShimmerText text="hello" />
+</box>
+```
+
+**The solution:** Parent components must wrap Fragment-returning components in `<text>` elements:
+
+```tsx
+// ✅ CORRECT: Parent wraps in <text>
+<box>
+  <text wrap={false}>
+    <ShimmerText text="hello" />
+  </text>
+</box>
+```
+
+**Why components shouldn't self-wrap in `<text>`:**
+1. Creates composition issues - you can't combine multiple components in one `<text>` element
+2. Prevents flexibility in how the component is used
+3. Can cause reconciliation errors when the component updates
+4. Goes against React's composition principles
+
+**Best practice:** 
+- Child components that render styled text should return Fragments with `<span>` elements
+- Parent components are responsible for providing the `<text>` wrapper
+- This follows React's pattern of "dumb" presentational components
+
+**Component design pattern:**
+```tsx
+// Child component - returns Fragment
+export const StyledText = ({ text, color }) => {
+  return (
+    <>
+      <span fg={color}>{text}</span>
+    </>
+  )
+}
+
+// Parent component - provides <text> wrapper
+const Parent = () => {
+  return (
+    <text wrap={false}>
+      <StyledText text="hello" color="#ff0000" />
+      <StyledText text="world" color="#00ff00" />
+    </text>
+  )
+}
+```
+
+This pattern allows multiple styled components to be composed together within a single `<text>` element while avoiding the "Text must be created inside of a text node" error.