Cli scroll ux improvements

cli/knowledge.md

@@ -360,6 +360,55 @@ The cleanest solution is to use a direct ternary with separate `<text>` elements
 
 **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.
 
+### Combining ShimmerText with Other Inline Elements
+
+**Problem**: When you need to display multiple inline elements alongside a dynamically updating component like `ShimmerText` (e.g., showing elapsed time + shimmer text), using `<box>` causes reconciliation errors.
+
+**Why `<box>` fails:**
+
+```tsx
+// ❌ PROBLEMATIC: ShimmerText in a <box> with other elements causes reconciliation errors
+<box style={{ gap: 1 }}>
+  <text fg={theme.secondary}>{elapsedSeconds}s</text>
+  <text wrap={false}>
+    <ShimmerText text="working..." />
+  </text>
+</box>
+```
+
+The issue occurs because:
+1. ShimmerText constantly updates its internal state (pulse animation)
+2. Each update re-renders with different `<span>` structures
+3. OpenTUI's reconciler struggles to match up the changing children inside the `<box>`
+4. Results in "Component of type 'span' must be created inside of a text node" error
+
+**✅ Solution: Use a Fragment with inline spans**
+
+Instead of using `<box>`, return a Fragment containing all inline elements:
+
+```tsx
+// Component returns Fragment with inline elements
+if (elapsedSeconds > 0) {
+  return (
+    <>
+      <span fg={theme.secondary}>{elapsedSeconds}s </span>
+      <ShimmerText text="working..." />
+    </>
+  )
+}
+
+// Parent wraps in <text>
+<text style={{ wrapMode: 'none' }}>{statusIndicatorNode}</text>
+```
+
+**Key principles:**
+- Avoid wrapping dynamically updating components (like ShimmerText) in `<box>` elements
+- Use Fragments to group inline elements that will be wrapped in `<text>` by the parent
+- Include spacing as part of the text content (e.g., `"{elapsedSeconds}s "` with trailing space)
+- Let the parent component provide the `<text>` wrapper for proper rendering
+
+This pattern works because all elements remain inline within a single stable `<text>` container, avoiding the reconciliation issues that occur when ShimmerText updates inside a `<box>`.
+
 ### The "Text Must Be Created Inside of a Text Node" Error
 
 **Error message:**