Add lettered sub-item indentation and DEFAULT highlighting

Implement proper visual hierarchy for AskUserQuestion multi-select options:
- Indent lettered sub-items (a), b), c)) under numbered questions
- Highlight DEFAULT options with green background and black text
- Document OpenTUI TextNodeRenderable constraints and workarounds

Note: Wrapped lines return to column 0 due to OpenTUI limitations with
inline text rendering. This is documented as a known constraint.

Author: brandonkachen

cli/knowledge.md

@@ -58,7 +58,7 @@ tmux new-session -d -s test-session 'cd /path/to/codebuff && bun --cwd=cli run d
 
 ## Migration from Custom OpenTUI Fork
 
-**October 2024**: Migrated from custom `CodebuffAI/opentui#codebuff/custom` fork to official `@opentui/react@^0.1.27` and `@opentui/core@^0.1.27` packages. Updated to `^0.1.28` in February 2025.
+**October 2024**: Migrated from custom `CodebuffAI/opentui#codebuff/custom` fork to official `@opentui/react@^0.1.27` and `@opentui/core@^0.1.27` packages. Updated to `^0.1.28` in February 2025. **November 2025**: Upgraded to `0.1.41` to test if TextNodeRenderable constraints were relaxed (they weren't - still have same limitations).
 
 **Lost Features from Custom Fork:**
 
@@ -604,6 +604,98 @@ This prevents invalid children from reaching `TextNodeRenderable` while preservi
 
 **Related**: `cli/src/hooks/use-message-renderer.tsx` ensures toggle headers render within a single `<text>` block for StyledText compatibility.
 
+### Using `<text>` vs `<box>` for Container Elements
+
+**CRITICAL**: `<text>` elements have strict child requirements and cannot accept arbitrary React elements as direct children.
+
+**The Error:**
+```
+Error: TextNodeRenderable only accepts strings, TextNodeRenderable instances, or StyledText instances
+  at add (/path/to/TextNode.ts:108:15)
+```
+
+**When this occurs:**
+```tsx
+// ❌ WRONG: Passing React fragments/elements directly as children of <text>
+<text style={{ paddingLeft: 3 }}>
+  {wrapSegmentsInFragments(children, 'key-prefix')}  // Returns Fragments containing spans
+</text>
+```
+
+**Why it fails:**
+- `wrapSegmentsInFragments()` returns `KeyedFragment` elements wrapping content
+- `<text>` expects direct text-renderable children (strings, `<span>`, `<strong>`, etc.)
+- React Fragments are not TextNodeRenderable instances
+- OpenTUI's TextNode cannot process the Fragment wrapper
+
+**✅ CORRECT Solution: Use `<box>` for layout, `<text>` for content**
+
+```tsx
+// Use <box> as container with paddingLeft style
+<box style={{ paddingLeft: 3 }}>
+  <text>
+    {wrapSegmentsInFragments(children, 'key-prefix')}
+  </text>
+</box>
+```
+
+**Why this works:**
+- `<box>` accepts any React elements as children (fragments, boxes, text, etc.)
+- `<box>` supports `paddingLeft` style property for indentation
+- The inner `<text>` properly wraps the text-renderable content
+- Wrapping behavior respects the box's paddingLeft on ALL lines
+
+**Key Learnings:**
+
+1. **For indentation with paddingLeft**: Use `<box style={{ paddingLeft: N }}>`, NOT `<text style={{ paddingLeft: N }}>`
+2. **`<text>` is for text rendering**: It should contain text-renderable elements (strings, spans, etc.)
+3. **`<box>` is for layout**: It can contain any React elements and supports layout styles
+4. **Fragments as children**: Only `<box>` can handle Fragment children; `<text>` cannot
+5. **paddingLeft on wrapped text**: Use `<box>` container to ensure wrapped lines maintain indentation
+
+**Pattern for indented text blocks:**
+```tsx
+// ✅ Correct pattern for indented, wrappable text
+<box style={{ paddingLeft: 3 }}>
+  <text>
+    <span>Line one</span>
+    {'\n'}
+    <span>Line two</span>
+  </text>
+</box>
+```
+
+### Markdown Renderer Indentation Limitation
+
+**Problem:** When markdown content is rendered as inline elements (strings, `<span>`, etc.) and wrapped in `<text>` by parent components, there's no way to maintain indentation on wrapped lines.
+
+**Why we can't use `<box>` with `paddingLeft`:**
+- Markdown renderer returns text-renderable inline elements
+- Parent components wrap output in `<text>{markdownOutput}</text>`
+- `<text>` can only contain text-renderable children (strings, `<span>`, etc.)
+- `<box>` is NOT text-renderable, so returning it from markdown renderer causes:
+  ```
+  Error: TextNodeRenderable only accepts strings, TextNodeRenderable instances, or StyledText instances
+  ```
+
+**Current Solution:**
+- Use manual space prepending for lettered sub-items (e.g., `   a) Option`)
+- First line is indented correctly
+- **Known limitation:** Wrapped lines return to column 0 instead of maintaining indentation
+- This is an acceptable trade-off given OpenTUI's architecture
+
+**Example of limitation:**
+```
+   a) This is a very long option that wraps to
+the next line but doesn't stay indented
+   b) Short option
+```
+
+**Why this is acceptable:**
+- The first line indentation still provides visual hierarchy
+- Alternative approaches (returning `<box>` from renderer) violate OpenTUI's rendering constraints
+- Users can still clearly see the structure even with imperfect wrapping
+
 
 
 ## Command Menus

cli/src/utils/__tests__/markdown-renderer.test.tsx

@@ -414,7 +414,7 @@ b) Focus on email/in-app notifications first (simpler to implement)`
       // Convert to text content (recursively extracts all text including from nested spans)
       const textContent = getAllTextContent(output)
 
-      // Lettered items should be indented (3 spaces when under numbered lists)
+      // Lettered items should be indented with manual spaces (3 spaces under numbered lists)
       expect(textContent).toContain('   a) (DEFAULT) PostgreSQL')
       expect(textContent).toContain('   b) Dedicated time-series')
       expect(textContent).toContain('   c) Redis for real-time')
@@ -435,19 +435,10 @@ a) Another option
 b) One more option`
 
       const output = renderMarkdown(markdown)
-      const nodes = flattenNodes(output)
 
-      const textContent = nodes
-        .map((node) => {
-          if (typeof node === 'string') return node
-          if (React.isValidElement(node)) {
-            return flattenChildren(node.props.children).join('')
-          }
-          return ''
-        })
-        .join('')
+      const textContent = getAllTextContent(output)
 
-      // All lettered items should have 3 spaces of indentation (under numbered lists)
+      // All lettered items should be indented with manual spaces (3 spaces)
       expect(textContent).toContain('   a) First option')
       expect(textContent).toContain('   b) Second option')
       expect(textContent).toContain('   c) Third option')
@@ -461,19 +452,10 @@ b) Second standalone option
 c) Third standalone option`
 
       const output = renderMarkdown(markdown)
-      const nodes = flattenNodes(output)
 
-      const textContent = nodes
-        .map((node) => {
-          if (typeof node === 'string') return node
-          if (React.isValidElement(node)) {
-            return flattenChildren(node.props.children).join('')
-          }
-          return ''
-        })
-        .join('')
+      const textContent = getAllTextContent(output)
 
-      // Should still be indented even without numbered parents
+      // Should be indented with manual spaces (6 spaces at root level)
       expect(textContent).toContain('      a) First standalone')
       expect(textContent).toContain('      b) Second standalone')
       expect(textContent).toContain('      c) Third standalone')
@@ -490,7 +472,7 @@ c) Advanced configuration`
       // Convert to text content (recursively extracts all text including from nested spans)
       const textContent = getAllTextContent(output)
 
-      // Should preserve DEFAULT markers and apply indentation (3 spaces under list)
+      // Should preserve DEFAULT markers with indentation (3 spaces)
       expect(textContent).toContain('   a) (DEFAULT) Standard')
       expect(textContent).toContain('   b) Custom')
       expect(textContent).toContain('   c) Advanced')
@@ -503,19 +485,11 @@ b) Short option
 c) Another very detailed option explaining all the trade-offs and considerations you should think about`
 
       const output = renderMarkdown(markdown)
-      const nodes = flattenNodes(output)
 
-      const textContent = nodes
-        .map((node) => {
-          if (typeof node === 'string') return node
-          if (React.isValidElement(node)) {
-            return flattenChildren(node.props.children).join('')
-          }
-          return ''
-        })
-        .join('')
+      const textContent = getAllTextContent(output)
 
-      // Long text should still be indented (3 spaces under list)
+      // Long text should be indented (3 spaces)
+      // Note: Wrapped lines will go to column 0 (OpenTUI limitation)
       expect(textContent).toContain('   a) This is a very long option')
       expect(textContent).toContain('   b) Short option')
       expect(textContent).toContain('   c) Another very detailed')
@@ -531,19 +505,10 @@ e) Option E
 f) Option F`
 
       const output = renderMarkdown(markdown)
-      const nodes = flattenNodes(output)
 
-      const textContent = nodes
-        .map((node) => {
-          if (typeof node === 'string') return node
-          if (React.isValidElement(node)) {
-            return flattenChildren(node.props.children).join('')
-          }
-          return ''
-        })
-        .join('')
+      const textContent = getAllTextContent(output)
 
-      // All lettered items a-f should be indented (3 spaces under list)
+      // All lettered items a-f should be indented (3 spaces)
       expect(textContent).toContain('   a) Option A')
       expect(textContent).toContain('   b) Option B')
       expect(textContent).toContain('   c) Option C')
@@ -592,24 +557,15 @@ b) Final option
 Conclusion text at the end.`
 
       const output = renderMarkdown(markdown)
-      const nodes = flattenNodes(output)
 
-      const textContent = nodes
-        .map((node) => {
-          if (typeof node === 'string') return node
-          if (React.isValidElement(node)) {
-            return flattenChildren(node.props.children).join('')
-          }
-          return ''
-        })
-        .join('')
+      const textContent = getAllTextContent(output)
 
-      // Context and conclusion should not be indented
+      // Context and conclusion should be present
       expect(textContent).toContain('Here\'s some context')
       expect(textContent).toContain('And some text in between')
       expect(textContent).toContain('Conclusion text at the end')
 
-      // Lettered items should be indented (3 spaces under list)
+      // Lettered items should be indented (3 spaces)
       expect(textContent).toContain('   a) Option one')
       expect(textContent).toContain('   b) Option two')
       expect(textContent).toContain('   a) Another option')
@@ -620,49 +576,45 @@ Conclusion text at the end.`
       const markdown = `This is a sentence that mentions a) something in the middle.`
 
       const output = renderMarkdown(markdown)
-      const nodes = flattenNodes(output)
 
-      const textContent = nodes
-        .map((node) => {
-          if (typeof node === 'string') return node
-          if (React.isValidElement(node)) {
-            return flattenChildren(node.props.children).join('')
-          }
-          return ''
-        })
-        .join('')
+      const textContent = getAllTextContent(output)
 
-      // Should not add indentation for a) in the middle of a sentence
-      expect(textContent).not.toContain('      a) something')
+      // Should contain the text normally (no special handling for a) mid-sentence)
       expect(textContent).toContain('a) something in the middle')
+
+      // Should NOT have indentation spaces added
+      expect(textContent).not.toContain('      a) something')
     })
 
-    test('makes DEFAULT options bold', () => {
+    test('highlights DEFAULT options with green background and black text', () => {
       const markdown = `1. Choose your option:
 a) (DEFAULT) Standard configuration
 b) Custom configuration
 c) Advanced configuration`
 
       const output = renderMarkdown(markdown)
 
-      // Find all span elements with BOLD attribute (recursively)
-      const boldSpans = findAllElements(
+      // Find all span elements with green background
+      const defaultSpans = findAllElements(
         output,
-        (el) => el.type === 'span' && el.props.attributes === TextAttributes.BOLD
+        (el) => el.type === 'span' && el.props.bg === '#86efac'
       )
 
-      // Should have at least one bold span
-      expect(boldSpans.length).toBeGreaterThan(0)
+      // Should have at least one DEFAULT span
+      expect(defaultSpans.length).toBeGreaterThan(0)
 
-      // Check that bold span contains DEFAULT text
-      const boldTexts = boldSpans.map((span) =>
+      // Check that it has black text
+      expect(defaultSpans[0].props.fg).toBe('#000000')
+
+      // Check that highlighted span contains DEFAULT text
+      const highlightedTexts = defaultSpans.map((span) =>
         flattenChildren(span.props.children).join('')
       )
-      const hasDEFAULT = boldTexts.some((text) => text.includes('(DEFAULT)'))
+      const hasDEFAULT = highlightedTexts.some((text) => text.includes('(DEFAULT)'))
       expect(hasDEFAULT).toBe(true)
     })
 
-    test('bolds multiple DEFAULT options', () => {
+    test('highlights multiple DEFAULT options', () => {
       const markdown = `1. First question:
 a) (DEFAULT) Option A
 b) Option B
@@ -672,24 +624,46 @@ b) Non-default option`
 
       const output = renderMarkdown(markdown)
 
-      // Find all span elements with BOLD attribute (recursively)
-      const boldSpans = findAllElements(
+      // Find all span elements with green background
+      const defaultSpans = findAllElements(
         output,
-        (el) => el.type === 'span' && el.props.attributes === TextAttributes.BOLD
+        (el) => el.type === 'span' && el.props.bg === '#86efac'
       )
 
-      // Should have at least 2 bold spans
-      expect(boldSpans.length).toBeGreaterThanOrEqual(2)
+      // Should have at least 2 DEFAULT spans
+      expect(defaultSpans.length).toBeGreaterThanOrEqual(2)
+
+      // All should have black text
+      defaultSpans.forEach((span) => {
+        expect(span.props.fg).toBe('#000000')
+      })
 
-      // Both bold spans should contain DEFAULT text
-      const boldTexts = boldSpans.map((span) =>
+      // Both should contain DEFAULT text
+      const highlightedTexts = defaultSpans.map((span) =>
         flattenChildren(span.props.children).join('')
       )
-      const defaultCount = boldTexts.filter((text) =>
+      const defaultCount = highlightedTexts.filter((text) =>
         text.includes('(DEFAULT)')
       ).length
 
       expect(defaultCount).toBeGreaterThanOrEqual(2)
     })
+
+    test('indents lettered items with manual spaces', () => {
+      const markdown = `1. Question?
+a) (DEFAULT) Very long option text
+b) Short option`
+
+      const output = renderMarkdown(markdown)
+
+      const textContent = getAllTextContent(output)
+
+      // Should have manual indentation spaces (3 spaces under list)
+      expect(textContent).toContain('   a) (DEFAULT) Very long')
+      expect(textContent).toContain('   b) Short option')
+
+      // Note: Wrapped lines will return to column 0 due to OpenTUI constraints
+      // This is a known limitation documented in knowledge.md
+    })
   })
 })