chore(ui): remove dead toast and clipboard code

Remove 8 unused exports from clipboard package:
- CopyToClipboardWithMessage, IsClipboardSupported
- ToastMsg, ToastType, ToastInfo, ToastSuccess, ToastWarning, ToastError

These were remnants of a toast notification feature that was never
wired up. No callers exist anywhere in the codebase.

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,79 @@
+name: Bug Report
+description: Report a bug or issue with Kit
+title: "fix: "
+labels: ["bug"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: What happened? What did you expect to happen?
+      placeholder: |
+        The BorderColor field in ToolRenderConfig is documented but never applied 
+        during tool rendering. I expected the tool block to render with my custom 
+        color, but it uses the default styling instead.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: Provide clear steps to reproduce the issue
+      placeholder: |
+        1. Create an extension with `api.RegisterToolRenderer(ext.ToolRenderConfig{...})`
+        2. Set `BorderColor: "#89b4fa"` in the config
+        3. Run a tool that uses this renderer
+        4. Observe the border color is not applied
+      render: markdown
+    validations:
+      required: true
+
+  - type: textarea
+    id: code
+    attributes:
+      label: Relevant Code / Configuration
+      description: Paste any code, configuration, or error messages
+      placeholder: |
+        ```go
+        api.RegisterToolRenderer(ext.ToolRenderConfig{
+            ToolName:    "bash",
+            DisplayName: "Shell",
+            BorderColor: "#a6e3a1",  // This is ignored!
+            Background:  "#1e1e2e",  // This is ignored!
+        })
+        ```
+      render: go
+
+  - type: input
+    id: component
+    attributes:
+      label: Affected Component
+      description: Which part of Kit is affected?
+      placeholder: e.g., extensions, ui, tool rendering, session management
+
+  - type: input
+    id: version
+    attributes:
+      label: Kit Version
+      description: What version of Kit are you running?
+      placeholder: e.g., v0.1.0, commit hash, or "main"
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Any other context, proposed fixes, or related issues
+      placeholder: |
+        The issue appears to be in `internal/ui/messages.go:RenderToolMessage()` 
+        which ignores the BorderColor and Background fields from ToolRendererData.
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Checklist
+      options:
+        - label: I've searched existing issues and this hasn't been reported yet
+          required: true
+        - label: I've tested with the latest version of Kit
+          required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Kit Documentation
+    url: https://github.com/mark3labs/kit/tree/main/www/pages
+    about: Check the documentation before filing an issue
+  - name: Extension Examples
+    url: https://github.com/mark3labs/kit/tree/main/examples/extensions
+    about: See working extension examples for reference
+  - name: Discussions
+    url: https://github.com/mark3labs/kit/discussions
+    about: For questions, ideas, or general discussion

.github/ISSUE_TEMPLATE/documentation.yml

@@ -0,0 +1,40 @@
+name: Documentation Issue
+description: Report missing, incorrect, or unclear documentation
+title: "docs: "
+labels: ["documentation"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Documentation Issue
+      description: What's wrong or missing in the documentation?
+      placeholder: |
+        The ToolRenderConfig documentation mentions BorderColor and Background fields,
+        but the code doesn't actually use them. The docs should either be updated 
+        to reflect reality, or the bug should be fixed.
+    validations:
+      required: true
+
+  - type: input
+    id: location
+    attributes:
+      label: Documentation Location
+      description: Where is the affected documentation?
+      placeholder: e.g., README.md, examples/extensions/tool-renderer-demo.go, pkg/kit docs
+
+  - type: textarea
+    id: suggestion
+    attributes:
+      label: Suggested Improvement
+      description: How should the documentation be improved?
+      placeholder: |
+        Add a note that BorderColor and Background are not yet implemented, 
+        or fix the bug and document the correct behavior.
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Checklist
+      options:
+        - label: I've checked that this documentation issue still exists in the latest version
+          required: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,64 @@
+name: Feature Request
+description: Suggest a new feature or enhancement for Kit
+title: "feat: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Feature Description
+      description: What would you like to see added or changed?
+      placeholder: |
+        I'd like to be able to customize the border color of tool result blocks 
+        dynamically based on the tool type or result status.
+    validations:
+      required: true
+
+  - type: textarea
+    id: motivation
+    attributes:
+      label: Motivation / Use Case
+      description: Why is this feature needed? What problem does it solve?
+      placeholder: |
+        When running multiple tools in sequence, it's hard to visually distinguish 
+        between file reads (blue), shell commands (green), and errors (red) 
+        without custom border colors.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed
+    attributes:
+      label: Proposed Implementation
+      description: How do you think this should work? (optional)
+      placeholder: |
+        Extend `ToolRenderConfig` to accept a function that receives the tool 
+        result and returns a color based on the content:
+        
+        ```go
+        BorderColorFunc: func(result string, isError bool) string {
+            if isError {
+                return "#f38ba8"
+            }
+            return "#89b4fa"
+        }
+        ```
+      render: go
+
+  - type: checkboxes
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      options:
+        - label: I've considered workarounds or alternative approaches
+          required: false
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Checklist
+      options:
+        - label: I've searched existing issues and this hasn't been requested yet
+          required: true
+        - label: This feature aligns with Kit's design philosophy (TUI-first, extension-based)
+          required: false

.gitignore

@@ -3,6 +3,7 @@
 .env
 .kit/*
 !.kit/extensions/
+!.kit/prompts/
 aidocs/
 *.log
 /kit

.kit/prompts/acp-smoke-test.md

@@ -0,0 +1,37 @@
+---
+description: Run ACP smoke test against opencode/kimi-k2.5 to verify JSON-RPC stdio works
+---
+
+Run the ACP smoke test to verify the Kit ACP server works correctly over JSON-RPC stdio with streaming responses.
+
+## Steps
+
+1. Build the kit binary:
+   ```bash
+   go build -o output/kit ./cmd/kit
+   ```
+
+2. Run the smoke test Python script against opencode/kimi-k2.5:
+   ```bash
+   python3 scripts/acp_smoke_test.py
+   ```
+
+3. Verify the output shows:
+   - `session/new` returns a valid `sessionId`
+   - `session/prompt` streams `agent_thought_chunk` notifications (reasoning)
+   - `session/prompt` streams `agent_message_chunk` notifications (response)
+   - Final result has `stopReason: "end_turn"`
+   - `✓ SMOKE TEST PASSED` at the end
+
+4. If the test fails, check:
+   - `output/kit` binary exists and is executable
+   - `OPENCODE_API_KEY` or `OPENCODE_ZEN_API_KEY` environment variable is set
+   - `scripts/acp_smoke_test.py` exists
+   - The model `opencode/kimi-k2.5` is available (`kit models opencode | grep kimi-k2.5`)
+
+5. For testing with a different model, edit the script or set the `MODEL` variable:
+   ```bash
+   MODEL=anthropic/claude-sonnet-4-5 python3 scripts/acp_smoke_test.py
+   ```
+
+The smoke test exercises the full ACP protocol: session lifecycle, streaming notifications, and tool-free prompt completion.

.kit/prompts/commit-push.md

@@ -0,0 +1,30 @@
+---
+description: Stage, commit, and push changes with an auto-generated conventional commit message
+---
+
+Review the current git status and diff, then stage all changes, write a concise conventional commit message, commit, and push to the current branch.
+
+## Steps
+
+1. **Check status**: `git status` — understand what has changed
+2. **Review the diff**: `git diff` (and `git diff --cached` if anything is already staged) — read the actual changes
+3. **Stage everything**: `git add -A`
+4. **Craft the commit message** following Conventional Commits:
+   - Format: `<type>(<scope>): <short summary>`
+   - Types: `feat`, `fix`, `refactor`, `chore`, `docs`, `test`, `perf`, `build`
+   - Scope: optional, the subsystem affected (e.g. `ui`, `cmd`, `config`)
+   - Summary: imperative mood, lowercase, no trailing period, ≤72 chars
+   - Body: add a blank line then bullet points for non-trivial changes
+   - Do **not** include "Generated by" or similar noise
+5. **Commit**: `git commit -m "<message>"`
+6. **Push**: `git push`
+
+## Guidelines
+
+- Read the actual diff — do not guess from filenames alone
+- Prefer one well-scoped commit; do not split unless the changes are clearly unrelated
+- Keep the subject line under 72 characters
+- Use the body to explain *what* and *why*, not *how*
+- If there is nothing to commit, say so and stop
+
+$@

.kit/prompts/feature-request.md

@@ -0,0 +1,86 @@
+---
+description: Create a feature request using the GitHub template
+---
+
+Create a feature request for the Kit repository. The user wants to request: $@
+
+## Feature Request Template
+
+This prompt uses the `feature_request` GitHub template which requires:
+
+| Field | Required | Purpose |
+|-------|----------|---------|
+| **Feature Description** | Yes | What should be added or changed |
+| **Motivation / Use Case** | Yes | Why is this needed? What problem does it solve? |
+| **Proposed Implementation** | No | How do you think this should work? |
+
+## Steps
+
+1. **Understand the request** from `$@`
+   - What capability is missing?
+   - What would the ideal behavior look like?
+
+2. **Ask clarifying questions** if needed:
+   - "What problem does this solve for you?"
+   - "How would you expect this to work?"
+   - "Are there similar features in other tools you use?"
+
+3. **Craft the title** using conventional format:
+   - `feat: <short description>`
+   - Lowercase, imperative mood, ≤72 chars
+   - Good examples:
+     - `feat: add keyboard shortcut for clearing input`
+     - `feat: support custom themes per extension`
+     - `feat: add fuzzy matching to model selector`
+   - Bad examples:
+     - `Feature request: can we have...` (too vague)
+     - `It would be nice if...` (not imperative)
+
+4. **Build the body** with the template fields:
+
+   **Feature Description:**
+   - Clear statement of what to add/change
+   - Be specific about the behavior
+   - Include UI/UX details if relevant
+
+   **Motivation / Use Case:**
+   - What problem does this solve?
+   - Current workaround (if any) and why it's insufficient
+   - Who benefits from this feature?
+
+   **Proposed Implementation** (optional but helpful):
+   - High-level approach
+   - API changes if applicable
+   - Example usage code
+
+5. **Create the issue**:
+   ```bash
+   gh issue create --template feature_request --title "feat: ..." --body "..."
+   ```
+
+6. **Confirm success**:
+   - Show the issue URL and number
+   - Mention it was created with the feature_request template
+
+## Guidelines
+
+- Focus on the *problem* first, then the solution
+- Include concrete examples of how the feature would be used
+- Consider edge cases and mention them
+- If proposing API changes, show before/after code
+- Check if similar features exist in related tools (mention them for reference)
+- Align with Kit's philosophy: TUI-first, extension-based, keyboard-driven
+
+## Example
+
+User: `/feature-request I want to be able to customize tool border colors dynamically`
+
+You:
+1. Title: `feat: dynamic border colors for tool results based on status`
+2. Body:
+   - **Feature Description**: Allow `ToolRenderConfig` to accept a function that determines border color based on tool result content or status, enabling dynamic visual feedback.
+   - **Motivation**: When running multiple tools, it's hard to distinguish file reads (blue), shell commands (green), and errors (red) without custom colors per result.
+   - **Proposed Implementation**: Add `BorderColorFunc` callback that receives `(result string, isError bool)` and returns a color string.
+
+3. Execute: `gh issue create --template feature_request --title "feat: ..." --body "..."`
+4. Confirm: Created issue #43 using feature_request template

.kit/prompts/file-issue.md

@@ -0,0 +1,100 @@
+---
+description: File a GitHub issue using the appropriate template
+---
+
+File a GitHub issue for the Kit repository. The user wants to create an issue about: $@
+
+## Issue Templates Available
+
+This repository has structured issue templates. You MUST use the appropriate template:
+
+| Type | Template | Use For |
+|------|----------|---------|
+| `bug` | `bug_report` | Something is broken, not working as expected |
+| `feat` | `feature_request` | New feature, enhancement, improvement |
+| `docs` | `documentation` | Missing, incorrect, or unclear documentation |
+
+## Steps
+
+1. **Determine the issue type** from `$@`:
+   - Bug → use `--template bug_report`
+   - Feature → use `--template feature_request`  
+   - Documentation → use `--template documentation`
+
+2. **Ask clarifying questions** if critical info is missing:
+   - For bugs: "What were you doing when this happened?" (reproduction steps)
+   - For features: "What problem does this solve?" (motivation)
+   - For docs: "Where did you look for this information?" (location)
+
+3. **Craft the title** using conventional format:
+   - `<type>: <short description>`
+   - Lowercase, imperative mood, ≤72 chars
+   - Examples:
+     - `fix: ToolRenderConfig BorderColor ignored during rendering`
+     - `feat: add keyboard shortcut for clearing input`
+     - `docs: clarify extension widget lifecycle`
+
+4. **File the issue** using the template:
+   ```bash
+   # For bugs
+   gh issue create --template bug_report --title "fix: ..." --body "..."
+   
+   # For features
+   gh issue create --template feature_request --title "feat: ..." --body "..."
+   
+   # For documentation
+   gh issue create --template documentation --title "docs: ..." --body "..."
+   ```
+
+   The template will guide the user through the required fields. You need to provide:
+   - **Bug reports**: Description, reproduction steps, expected vs actual behavior
+   - **Feature requests**: Description, motivation/use case, optional proposed implementation
+   - **Documentation**: Description, location of docs, suggested improvement
+
+5. **Confirm success** by showing:
+   - The issue URL
+   - The issue number
+   - Which template was used
+
+## Template Field Guide
+
+### Bug Report (`bug_report`)
+Required fields in the body:
+- **Bug Description** - what happened vs expected
+- **Steps to Reproduce** - numbered list to recreate the bug
+- **Relevant Code** - code snippets, configuration, error messages
+- **Component** - which part of Kit (ui, extensions, session, etc.)
+- **Version** - Kit version or commit hash
+
+### Feature Request (`feature_request`)
+Required fields in the body:
+- **Feature Description** - what to add/change
+- **Motivation / Use Case** - why this is needed
+- **Proposed Implementation** - how it could work (optional)
+
+### Documentation (`documentation`)
+Required fields in the body:
+- **Documentation Issue** - what's wrong or missing
+- **Documentation Location** - file or URL where docs exist
+- **Suggested Improvement** - how to fix the docs
+
+## Guidelines
+
+- ALWAYS use `--template <name>` instead of bare `gh issue create`
+- Include file paths and line numbers when you know them
+- Use triple backticks for code blocks
+- Keep the body factual - avoid speculation unless in "Proposed Fix" section
+- If you're unsure about technical details, say so in the issue
+- For UI bugs, describe what you see vs what you expect
+- For API bugs, include the relevant struct/function names
+
+## Example Usage
+
+User: `/file-issue The ToolRenderConfig BorderColor field is documented but never used in rendering`
+
+You: 
+1. Determine this is a **bug** (documented field doesn't work)
+2. Use `--template bug_report`
+3. Gather: reproduction steps (register renderer with BorderColor), expected (custom color), actual (default color)
+4. Create issue with title `fix: ToolRenderConfig BorderColor and Background fields are ignored`
+5. Confirm: Created issue #42 using bug_report template

.kit/prompts/new-prompt.md

@@ -0,0 +1,47 @@
+---
+description: Scaffold a new prompt template in .kit/prompts/
+---
+
+Create a new kit prompt template. The user wants a prompt that does: $@
+
+## What a prompt template is
+
+A prompt template is a `.md` file in `.kit/prompts/` (project-local) or `~/.kit/prompts/` (global).
+It becomes a `/slug` slash command in the kit input box — typed as `/filename` with optional arguments.
+
+## File format
+
+```
+---
+description: One-line description shown in autocomplete
+---
+
+Body text of the prompt. Use $@ for all user-supplied arguments,
+$1 $2 etc. for positional arguments.
+```
+
+- **Filename** → slug: `commit-push.md` becomes `/commit-push`
+- **Frontmatter**: only `description` is recognised; keep it under ~80 chars
+- **Body**: plain markdown; the full text is submitted as the user's message when the template fires
+- **Arguments**: `$@` expands to everything the user typed after the slash command name;
+  `$1`, `$2` for individual positional args; omit entirely if no arguments are needed
+
+## Steps
+
+1. **Understand the workflow** the user described in `$@` — ask a clarifying question if the intent is ambiguous
+2. **Choose a filename**: short, lowercase, hyphen-separated, descriptive (e.g. `code-review.md`)
+3. **Write the description**: one sentence, imperative, fits in autocomplete
+4. **Draft the body**:
+   - Open with a single sentence stating the goal
+   - Use `## Steps` for multi-step workflows; use plain prose for simple prompts
+   - Be specific: name commands, flags, and file paths where relevant
+   - End with `$@` on its own line if the user might want to pass context or a hint; omit if the prompt is self-contained
+5. **Write the file** to `.kit/prompts/<slug>.md`
+6. **Confirm** by showing the final file content and the slash command that activates it
+
+## Guidelines
+
+- Keep prompts action-oriented — they should tell kit *what to do*, not just *what to think about*
+- Prefer concrete steps over vague instructions
+- A prompt that does one thing well beats one that tries to cover every edge case
+- If the workflow already exists as a prompt, suggest extending it instead of duplicating

.kit/prompts/release-tagger.md

@@ -0,0 +1,70 @@
+---
+description: Semantic version tagging workflow - analyzes commits and tags releases
+---
+
+# Release Tagging Workflow
+
+Tag a new version of this Go project following semantic versioning.
+
+## Steps
+
+1. **Fetch remote tags**: `git fetch --tags origin`
+
+2. **Find latest version**: `git tag -l | sort -V | tail -5` to see recent tags
+
+3. **Analyze changes since last tag**:
+   - `git log <latest-tag>..HEAD --oneline` - list commits
+   - `git diff <latest-tag>..HEAD --stat` - see file stats
+   - `git diff <latest-tag>..HEAD --name-only` - see changed files
+
+4. **Determine version bump** (Semantic Versioning):
+   - **MAJOR (X.0.0)**: Breaking API changes, incompatible modifications
+   - **MINOR (0.X.0)**: New features, backward-compatible additions
+   - **PATCH (0.0.X)**: Bug fixes, backward-compatible fixes
+   
+   Look for indicators:
+   - `feat:` or `feature:` commits → MINOR
+   - `fix:` or `bugfix:` commits → PATCH
+   - `breaking:` or `BREAKING CHANGE:` → MAJOR
+   - Breaking API changes in `pkg/` or public interfaces → MAJOR
+   - New commands, flags, or features → MINOR
+   - Documentation-only changes → PATCH (or skip)
+
+5. **Calculate new version**: Increment appropriate segment, reset lower segments to 0
+
+6. **Draft tag message**:
+   - Summarize key changes from commits
+   - Group by type (Features, Fixes, Breaking Changes)
+   - Keep concise but informative
+
+7. **Create annotated tag**: `git tag -a vX.Y.Z -m "vX.Y.Z - <summary>\n\n<detailed list>"`
+
+8. **Push tag**: `git push origin vX.Y.Z`
+
+## Guidelines
+
+- Always fetch remote tags first to avoid conflicts
+- Use annotated tags (`-a`) with descriptive messages
+- Follow semver strictly - when in doubt, prefer conservative bump (patch over minor)
+- For Go projects, changes to `pkg/` or exported APIs warrant careful version consideration
+- If no changes since last tag, suggest skipping the release
+- Include commit summaries in the tag message body
+
+## Example Tag Message Format
+
+```
+v0.30.1 - Bug fixes for model handling and UI improvements
+
+Fixes:
+- Properly handle think tags from Qwen/DeepSeek models
+- Handle custom provider model persistence and bare model names
+
+Improvements:
+- UI style refactoring and cleanup
+```
+
+Wait for the user to confirm the version and message before executing tag commands.
+
+---
+
+$@

AGENTS.md

@@ -100,3 +100,21 @@ Positional args are the prompt. `@file` args attach file content. Key flags: `--
 - Never guess or manually search the filesystem for external projects
 - Example: `btca ask -r https://github.com/user/repo -q "How does X work?"`
 - See `.agents/skills/btca-cli/SKILL.md` for full btca usage
+
+## BTCA Configured Resources
+The following external repositories are configured in `btca.config.jsonc` for research:
+
+- bubbletea
+- lipgloss
+- bubbles
+- glamour
+- fantasy
+- catwalk
+- crush
+- pi
+- iteratr
+- yaegi
+- acp-go-sdk
+- opencode
+- herald
+- herald-md

AUTOSCROLL_FIX_SUMMARY.md

@@ -0,0 +1,80 @@
+# Autoscroll Fix - Final Summary
+
+## Root Cause
+
+The autoscroll was failing for streaming assistant messages due to a bug in how `GotoBottom()` calculated item heights.
+
+### The Problem
+
+1. **Reasoning blocks** (`StreamingMessageItem` with `role="reasoning"`) are **never cached** because they have live duration counters that update every render
+2. The `Height()` method returns `0` when `cachedRender == ""`
+3. `GotoBottom()` was calling:
+   ```go
+   itemHeight := item.Height()  // Returns 0 for reasoning
+   if itemHeight == 0 {
+       item.Render(s.width)  // Renders but doesn't cache (reasoning)
+       itemHeight = item.Height()  // Still returns 0!
+   }
+   ```
+4. This caused incorrect scroll position calculations, especially during reasoning → assistant transitions
+
+## The Solution
+
+Changed `GotoBottom()` and `AtBottom()` to calculate height **directly from the rendered string** instead of relying on the cached height:
+
+```go
+// OLD: item.Height() which checks cached render
+itemHeight := item.Height()
+if itemHeight == 0 {
+    item.Render(s.width)
+    itemHeight = item.Height()  // Still might be 0!
+}
+
+// NEW: Calculate from rendered string directly
+rendered := item.Render(s.width)
+itemHeight := strings.Count(rendered, "\n") + 1
+```
+
+This works for **all** items regardless of whether they cache their render or not.
+
+## Files Changed
+
+### `internal/ui/scrolllist.go`
+- **`GotoBottom()`**: Calculate height from rendered string (2 loops)
+- **`AtBottom()`**: Calculate height from rendered string (1 loop)
+
+### `internal/ui/model.go`
+- **`appendStreamingChunk()`**: For existing messages, call `GotoBottom()` directly (iteratr pattern)
+- **`refreshContent()`**: Simplified to only call `SetItems()` (removed redundant `GotoBottom()`)
+- **Bash streaming handler**: Removed redundant `GotoBottom()` after `refreshContent()`
+
+## Testing Results
+
+✅ **Test prompt**: "explore this repo"
+
+**Before fix**:
+- Autoscroll stopped after reasoning block completed
+- Viewport stuck showing end of reasoning ("Thought for 203ms")
+- Assistant response streamed off-screen below
+
+**After fix**:
+- Autoscroll works throughout reasoning block
+- Autoscroll continues during reasoning → assistant transition  
+- Viewport stays at bottom showing latest assistant content
+- Final position shows end of response (build commands section)
+
+## Behavior Verified
+
+1. ✅ Streaming text auto-scrolls to bottom
+2. ✅ Works across reasoning → assistant transition
+3. ✅ Manual scroll up (PgUp) disables autoscroll
+4. ✅ Scroll to bottom (Alt+End) re-enables autoscroll
+5. ✅ Accurate positioning with no offset errors
+
+## Performance Note
+
+The fix calls `Render()` on all items during `GotoBottom()` calculations. This is acceptable because:
+- `Render()` is already optimized with caching for non-reasoning items
+- `GotoBottom()` is only called during content updates (not every frame)
+- Reasoning blocks need to render anyway for live duration updates
+- This matches iteratr's approach of ensuring items are rendered before height calculations

README.md

@@ -477,7 +477,7 @@ During an interactive session, use these slash commands:
 | `/import <path>` | Import and switch to a session from a JSONL file |
 | `/share` | Upload session to GitHub Gist and get a shareable viewer URL |
 | `/tree` | Navigate the session tree |
-| `/fork` | Branch from an earlier message |
+| `/fork` | Fork to new session from an earlier message |
 | `/new` | Start a fresh session |
 
 ## Go SDK

cmd/acp.go

@@ -11,6 +11,7 @@ import (
 	"os/signal"
 	"syscall"
 
+	"github.com/charmbracelet/log"
 	acp "github.com/coder/acp-go-sdk"
 
 	"github.com/mark3labs/kit/internal/acpserver"
@@ -54,6 +55,8 @@ func runACP(cmd *cobra.Command, _ []string) error {
 		conn.SetLogger(slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{
 			Level: slog.LevelDebug,
 		})))
+		// Also set charmbracelet/log level for acpserver package logging
+		log.SetLevel(log.DebugLevel)
 	}
 
 	// Wait for either the client to disconnect or a signal.

cmd/root.go

@@ -10,8 +10,6 @@ import (
 	"strings"
 
 	tea "charm.land/bubbletea/v2"
-	"charm.land/fantasy"
-	"charm.land/lipgloss/v2"
 	"github.com/mark3labs/kit/internal/app"
 	"github.com/mark3labs/kit/internal/auth"
 	"github.com/mark3labs/kit/internal/config"
@@ -19,6 +17,7 @@ import (
 	"github.com/mark3labs/kit/internal/models"
 	"github.com/mark3labs/kit/internal/prompts"
 	"github.com/mark3labs/kit/internal/ui"
+	"github.com/mark3labs/kit/internal/ui/commands"
 	kit "github.com/mark3labs/kit/pkg/kit"
 	"github.com/spf13/cobra"
 	"github.com/spf13/viper"
@@ -38,7 +37,6 @@ var (
 	noExitFlag       bool
 	maxSteps         int
 	streamFlag       bool // Enable streaming output
-	compactMode      bool // Enable compact output mode
 	autoCompactFlag  bool // Enable auto-compaction near context limit
 
 	// Session management
@@ -219,29 +217,10 @@ func configToUiTheme(cfg config.Theme) ui.Theme {
 	}
 }
 
-// kitBanner returns the KIT ASCII art title with KITT scanner lights,
-// rendered with a KITT red gradient.
+// kitBanner returns the KIT ASCII art title with KITT scanner lights.
+// Delegates to ui.KitBanner() which owns the logo rendering.
 func kitBanner() string {
-	kittDark := lipgloss.Color("#8B0000")
-	kittBright := lipgloss.Color("#FF2200")
-	lines := []string{
-		"            ██╗  ██╗ ██╗ ████████╗",
-		"            ██║ ██╔╝ ██║ ╚══██╔══╝",
-		"            █████╔╝  ██║    ██║",
-		"            ██╔═██╗  ██║    ██║",
-		"            ██║  ██╗ ██║    ██║",
-		"            ╚═╝  ╚═╝ ╚═╝    ╚═╝",
-		" ░░░░░░▒▒▒▒▒▓▓▓▓███████████████▓▓▓▓▒▒▒▒▒░░░░░░",
-	}
-
-	var result strings.Builder
-	for i, line := range lines {
-		if i > 0 {
-			result.WriteString("\n")
-		}
-		result.WriteString(ui.ApplyGradient(line, kittDark, kittBright))
-	}
-	return result.String()
+	return ui.KitBanner()
 }
 
 func init() {
@@ -280,8 +259,6 @@ func init() {
 		IntVar(&maxSteps, "max-steps", 0, "maximum number of agent steps (0 for unlimited)")
 	rootCmd.PersistentFlags().
 		BoolVar(&streamFlag, "stream", true, "enable streaming output for faster response display")
-	rootCmd.PersistentFlags().
-		BoolVar(&compactMode, "compact", false, "enable compact output mode without fancy styling")
 	rootCmd.PersistentFlags().
 		BoolVar(&autoCompactFlag, "auto-compact", false, "auto-compact conversation when near context limit")
 	rootCmd.PersistentFlags().
@@ -325,7 +302,6 @@ func init() {
 	_ = viper.BindPFlag("debug", rootCmd.PersistentFlags().Lookup("debug"))
 	_ = viper.BindPFlag("max-steps", rootCmd.PersistentFlags().Lookup("max-steps"))
 	_ = viper.BindPFlag("stream", rootCmd.PersistentFlags().Lookup("stream"))
-	_ = viper.BindPFlag("compact", rootCmd.PersistentFlags().Lookup("compact"))
 	_ = viper.BindPFlag("auto-compact", rootCmd.PersistentFlags().Lookup("auto-compact"))
 
 	_ = viper.BindPFlag("provider-url", rootCmd.PersistentFlags().Lookup("provider-url"))
@@ -411,21 +387,21 @@ func runKit(ctx context.Context) error {
 }
 
 // extensionCommandsForUI converts extension-registered CommandDefs into the
-// ui.ExtensionCommand type used by the interactive TUI. Command names are
+// commands.ExtensionCommand type used by the interactive TUI. Command names are
 // normalised to start with "/" so they integrate with the slash-command
 // autocomplete and dispatch pipeline.
-func extensionCommandsForUI(k *kit.Kit) []ui.ExtensionCommand {
+func extensionCommandsForUI(k *kit.Kit) []commands.ExtensionCommand {
 	defs := k.Extensions().Commands()
 	if len(defs) == 0 {
 		return nil
 	}
-	cmds := make([]ui.ExtensionCommand, 0, len(defs))
+	cmds := make([]commands.ExtensionCommand, 0, len(defs))
 	for _, d := range defs {
 		name := d.Name
 		if len(name) > 0 && name[0] != '/' {
 			name = "/" + name
 		}
-		ec := ui.ExtensionCommand{
+		ec := commands.ExtensionCommand{
 			Name:        name,
 			Description: d.Description,
 			Execute: func(args string) (string, error) {
@@ -728,7 +704,7 @@ func runNormalMode(ctx context.Context) error {
 	var spinnerFunc kit.SpinnerFunc
 	if !quietFlag {
 		spinnerFunc = func(fn func() error) error {
-			tempCli, tempErr := ui.NewCLI(viper.GetBool("debug"), viper.GetBool("compact"))
+			tempCli, tempErr := ui.NewCLI(viper.GetBool("debug"))
 			if tempErr == nil {
 				return tempCli.ShowSpinner(fn)
 			}
@@ -792,7 +768,7 @@ func runNormalMode(ctx context.Context) error {
 
 	// Load existing messages from resumed/continued sessions.
 	treeSession := kitInstance.GetTreeSession()
-	var messages []fantasy.Message
+	var messages []kit.LLMMessage
 	if treeSession != nil {
 		messages = treeSession.GetLLMMessages()
 	}
@@ -1572,7 +1548,7 @@ func runNormalMode(ctx context.Context) error {
 	emitBeforeFork := beforeForkProviderForUI(kitInstance)
 	emitBeforeSessionSwitch := beforeSessionSwitchProviderForUI(kitInstance)
 	getGlobalShortcuts := globalShortcutsProviderForUI(kitInstance)
-	getExtensionCommands := func() []ui.ExtensionCommand {
+	getExtensionCommands := func() []commands.ExtensionCommand {
 		return extensionCommandsForUI(kitInstance)
 	}
 
@@ -1652,7 +1628,7 @@ func runNormalMode(ctx context.Context) error {
 //
 // When --no-exit is set, after the prompt completes the interactive BubbleTea
 // TUI is started so the user can continue the conversation.
-func runNonInteractiveModeApp(ctx context.Context, appInstance *app.App, cli *ui.CLI, prompt string, quiet, jsonOutput, noExit bool, modelName, providerName, loadingMessage string, serverNames, toolNames []string, mcpToolCount, extensionToolCount int, usageTracker *ui.UsageTracker, extCommands []ui.ExtensionCommand, promptTemplates []*prompts.PromptTemplate, contextPaths []string, skillItems []ui.SkillItem, getWidgets func(string) []ui.WidgetData, getHeader, getFooter func() *ui.WidgetData, getToolRenderer func(string) *ui.ToolRendererData, getEditorInterceptor func() *ui.EditorInterceptor, getUIVisibility func() *ui.UIVisibility, getStatusBarEntries func() []ui.StatusBarEntryData, emitBeforeFork func(string, bool, string) (bool, string), emitBeforeSessionSwitch func(string) (bool, string), getGlobalShortcuts func() map[string]func(), getExtensionCommands func() []ui.ExtensionCommand, setModel func(string) error, emitModelChange func(string, string, string), isReasoningModel bool, thinkingLevel string, setThinkingLevel func(string) error, switchSession func(string) error) error {
+func runNonInteractiveModeApp(ctx context.Context, appInstance *app.App, cli *ui.CLI, prompt string, quiet, jsonOutput, noExit bool, modelName, providerName, loadingMessage string, serverNames, toolNames []string, mcpToolCount, extensionToolCount int, usageTracker *ui.UsageTracker, extCommands []commands.ExtensionCommand, promptTemplates []*prompts.PromptTemplate, contextPaths []string, skillItems []ui.SkillItem, getWidgets func(string) []ui.WidgetData, getHeader, getFooter func() *ui.WidgetData, getToolRenderer func(string) *ui.ToolRendererData, getEditorInterceptor func() *ui.EditorInterceptor, getUIVisibility func() *ui.UIVisibility, getStatusBarEntries func() []ui.StatusBarEntryData, emitBeforeFork func(string, bool, string) (bool, string), emitBeforeSessionSwitch func(string) (bool, string), getGlobalShortcuts func() map[string]func(), getExtensionCommands func() []commands.ExtensionCommand, setModel func(string) error, emitModelChange func(string, string, string), isReasoningModel bool, thinkingLevel string, setThinkingLevel func(string) error, switchSession func(string) error) error {
 	// Expand @file references in the prompt before sending to the agent.
 	if cwd, err := os.Getwd(); err == nil {
 		prompt = ui.ProcessFileAttachments(prompt, cwd)
@@ -1793,7 +1769,7 @@ func writeJSONError(err error) {
 //  4. Calls program.Run() which blocks until the user quits (Ctrl+C or /quit).
 //
 // SetupCLI is not used for interactive mode; the TUI (AppModel) handles its own rendering.
-func runInteractiveModeBubbleTea(_ context.Context, appInstance *app.App, modelName, providerName, loadingMessage string, serverNames, toolNames []string, mcpToolCount, extensionToolCount int, usageTracker *ui.UsageTracker, extCommands []ui.ExtensionCommand, promptTemplates []*prompts.PromptTemplate, contextPaths []string, skillItems []ui.SkillItem, getWidgets func(string) []ui.WidgetData, getHeader, getFooter func() *ui.WidgetData, getToolRenderer func(string) *ui.ToolRendererData, getEditorInterceptor func() *ui.EditorInterceptor, getUIVisibility func() *ui.UIVisibility, getStatusBarEntries func() []ui.StatusBarEntryData, emitBeforeFork func(string, bool, string) (bool, string), emitBeforeSessionSwitch func(string) (bool, string), getGlobalShortcuts func() map[string]func(), getExtensionCommands func() []ui.ExtensionCommand, setModel func(string) error, emitModelChange func(string, string, string), isReasoningModel bool, thinkingLevel string, setThinkingLevel func(string) error, switchSession func(string) error, startupExtensionMessages []string) error {
+func runInteractiveModeBubbleTea(_ context.Context, appInstance *app.App, modelName, providerName, loadingMessage string, serverNames, toolNames []string, mcpToolCount, extensionToolCount int, usageTracker *ui.UsageTracker, extCommands []commands.ExtensionCommand, promptTemplates []*prompts.PromptTemplate, contextPaths []string, skillItems []ui.SkillItem, getWidgets func(string) []ui.WidgetData, getHeader, getFooter func() *ui.WidgetData, getToolRenderer func(string) *ui.ToolRendererData, getEditorInterceptor func() *ui.EditorInterceptor, getUIVisibility func() *ui.UIVisibility, getStatusBarEntries func() []ui.StatusBarEntryData, emitBeforeFork func(string, bool, string) (bool, string), emitBeforeSessionSwitch func(string) (bool, string), getGlobalShortcuts func() map[string]func(), getExtensionCommands func() []commands.ExtensionCommand, setModel func(string) error, emitModelChange func(string, string, string), isReasoningModel bool, thinkingLevel string, setThinkingLevel func(string) error, switchSession func(string) error, startupExtensionMessages []string) error {
 	// Determine terminal size; fall back gracefully.
 	termWidth, termHeight, err := term.GetSize(int(os.Stdout.Fd()))
 	if err != nil || termWidth == 0 {
@@ -1804,54 +1780,42 @@ func runInteractiveModeBubbleTea(_ context.Context, appInstance *app.App, modelN
 	cwd, _ := os.Getwd()
 
 	appModel := ui.NewAppModel(appInstance, ui.AppModelOptions{
-		CompactMode:             viper.GetBool("compact"),
-		ModelName:               modelName,
-		ProviderName:            providerName,
-		LoadingMessage:          loadingMessage,
-		Cwd:                     cwd,
-		Width:                   termWidth,
-		Height:                  termHeight,
-		ServerNames:             serverNames,
-		ToolNames:               toolNames,
-		MCPToolCount:            mcpToolCount,
-		ExtensionToolCount:      extensionToolCount,
-		UsageTracker:            usageTracker,
-		ExtensionCommands:       extCommands,
-		PromptTemplates:         promptTemplates,
-		ContextPaths:            contextPaths,
-		SkillItems:              skillItems,
-		GetWidgets:              getWidgets,
-		GetHeader:               getHeader,
-		GetFooter:               getFooter,
-		GetToolRenderer:         getToolRenderer,
-		GetEditorInterceptor:    getEditorInterceptor,
-		GetUIVisibility:         getUIVisibility,
-		GetStatusBarEntries:     getStatusBarEntries,
-		EmitBeforeFork:          emitBeforeFork,
-		EmitBeforeSessionSwitch: emitBeforeSessionSwitch,
-		GetGlobalShortcuts:      getGlobalShortcuts,
-		GetExtensionCommands:    getExtensionCommands,
-		SetModel:                setModel,
-		EmitModelChange:         emitModelChange,
-		ThinkingLevel:           thinkingLevel,
-		IsReasoningModel:        isReasoningModel,
-		SetThinkingLevel:        setThinkingLevel,
-		SwitchSession:           switchSession,
-		ShowSessionPicker:       resumeFlag,
+		ModelName:                modelName,
+		ProviderName:             providerName,
+		LoadingMessage:           loadingMessage,
+		Cwd:                      cwd,
+		Width:                    termWidth,
+		Height:                   termHeight,
+		ServerNames:              serverNames,
+		ToolNames:                toolNames,
+		MCPToolCount:             mcpToolCount,
+		ExtensionToolCount:       extensionToolCount,
+		UsageTracker:             usageTracker,
+		ExtensionCommands:        extCommands,
+		PromptTemplates:          promptTemplates,
+		ContextPaths:             contextPaths,
+		SkillItems:               skillItems,
+		StartupExtensionMessages: startupExtensionMessages,
+		GetWidgets:               getWidgets,
+		GetHeader:                getHeader,
+		GetFooter:                getFooter,
+		GetToolRenderer:          getToolRenderer,
+		GetEditorInterceptor:     getEditorInterceptor,
+		GetUIVisibility:          getUIVisibility,
+		GetStatusBarEntries:      getStatusBarEntries,
+		EmitBeforeFork:           emitBeforeFork,
+		EmitBeforeSessionSwitch:  emitBeforeSessionSwitch,
+		GetGlobalShortcuts:       getGlobalShortcuts,
+		GetExtensionCommands:     getExtensionCommands,
+		SetModel:                 setModel,
+		EmitModelChange:          emitModelChange,
+		ThinkingLevel:            thinkingLevel,
+		IsReasoningModel:         isReasoningModel,
+		SetThinkingLevel:         setThinkingLevel,
+		SwitchSession:            switchSession,
+		ShowSessionPicker:        resumeFlag,
 	})
 
-	// Print startup info to stdout before Bubble Tea takes over the screen.
-	appModel.PrintStartupInfo()
-
-	// Print any extension messages that were captured during startup.
-	if len(startupExtensionMessages) > 0 {
-		fmt.Println()
-		for _, msg := range startupExtensionMessages {
-			fmt.Println(msg)
-		}
-		fmt.Println()
-	}
-
 	program := tea.NewProgram(appModel)
 
 	// Register the program with the app layer so agent events are sent to the TUI.

cmd/setup.go

@@ -41,7 +41,6 @@ func BuildAppOptions(mcpConfig *config.Config, modelName string, serverNames, to
 		StreamingEnabled: viper.GetBool("stream"),
 		Quiet:            quietFlag,
 		Debug:            viper.GetBool("debug"),
-		CompactMode:      viper.GetBool("compact"),
 	}
 }
 
@@ -131,7 +130,6 @@ func SetupCLIForNonInteractive(k *kit.Kit) (*ui.CLI, error) {
 		Agent:          agentAdapter,
 		ModelString:    viper.GetString("model"),
 		Debug:          viper.GetBool("debug"),
-		Compact:        viper.GetBool("compact"),
 		Quiet:          quietFlag,
 		ShowDebug:      false,
 		ProviderAPIKey: viper.GetString("provider-api-key"),

go.mod

@@ -9,12 +9,14 @@ require (
 	charm.land/huh/v2 v2.0.3
 	charm.land/lipgloss/v2 v2.0.2
 	github.com/alecthomas/chroma/v2 v2.23.1
+	github.com/atotto/clipboard v0.1.4
 	github.com/aymanbagabas/go-udiff v0.4.1
 	github.com/charmbracelet/fang v1.0.0
 	github.com/charmbracelet/log v1.0.0
+	github.com/charmbracelet/openai-go v0.0.0-20260319145158-d0740cc34266
 	github.com/coder/acp-go-sdk v0.6.3
-	github.com/indaco/herald v0.10.0
-	github.com/indaco/herald-md v0.1.0
+	github.com/indaco/herald v0.11.0
+	github.com/indaco/herald-md v0.2.0
 	github.com/mark3labs/mcp-go v0.46.0
 	github.com/spf13/cobra v1.10.2
 	github.com/spf13/viper v1.21.0
@@ -30,7 +32,6 @@ require (
 	cloud.google.com/go/compute/metadata v0.9.0 // indirect
 	github.com/Azure/azure-sdk-for-go/sdk/azcore v1.21.0 // indirect
 	github.com/Azure/azure-sdk-for-go/sdk/internal v1.11.2 // indirect
-	github.com/atotto/clipboard v0.1.4 // indirect
 	github.com/aws/aws-sdk-go-v2 v1.41.5 // indirect
 	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.8 // indirect
 	github.com/aws/aws-sdk-go-v2/config v1.32.13 // indirect
@@ -52,7 +53,6 @@ require (
 	github.com/charmbracelet/colorprofile v0.4.3 // indirect
 	github.com/charmbracelet/harmonica v0.2.0 // indirect
 	github.com/charmbracelet/lipgloss v1.1.1-0.20250404203927-76690c660834 // indirect
-	github.com/charmbracelet/openai-go v0.0.0-20260319145158-d0740cc34266 // indirect
 	github.com/charmbracelet/ultraviolet v0.0.0-20260330092749-0f94982c930b // indirect
 	github.com/charmbracelet/x/cellbuf v0.0.15 // indirect
 	github.com/charmbracelet/x/exp/charmtone v0.0.0-20260330094520-2dce04b6f8a4 // indirect
@@ -115,10 +115,10 @@ require (
 	golang.org/x/net v0.52.0 // indirect
 	golang.org/x/oauth2 v0.36.0 // indirect
 	golang.org/x/time v0.15.0 // indirect
-	google.golang.org/api v0.273.0 // indirect
-	google.golang.org/genai v1.52.0 // indirect
-	google.golang.org/genproto/googleapis/rpc v0.0.0-20260319201613-d00831a3d3e7 // indirect
-	google.golang.org/grpc v1.79.3 // indirect
+	google.golang.org/api v0.273.1 // indirect
+	google.golang.org/genai v1.52.1 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20260401024825-9d38bb4040a9 // indirect
+	google.golang.org/grpc v1.80.0 // indirect
 	google.golang.org/protobuf v1.36.11 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
 )

go.sum

@@ -181,10 +181,10 @@ github.com/hexops/gotextdiff v1.0.3 h1:gitA9+qJrrTCsiCl7+kh75nPqQt1cx4ZkudSTLoUq
 github.com/hexops/gotextdiff v1.0.3/go.mod h1:pSWU5MAI3yDq+fZBTazCSJysOMbxWL1BSow5/V2vxeg=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
-github.com/indaco/herald v0.10.0 h1:XzahEKX6cr50qZQrUdA3QrQBHg8uGm5jETD0UDi21BI=
-github.com/indaco/herald v0.10.0/go.mod h1:T5g1+XLYvpjouhzAGHnAHDCKizhESkoV6+QPZ3DhgWA=
-github.com/indaco/herald-md v0.1.0 h1:zmYudYo+uamzKTBcIffJVJYrqk9xDNnVrTh+de2zciw=
-github.com/indaco/herald-md v0.1.0/go.mod h1:Z1HxPCbSn+/+TFzOM/UbsmKeEk/28NNI6JOTileKXto=
+github.com/indaco/herald v0.11.0 h1:tJZc6DAzfUYVWQsU9Lik4RcKR7TtiRfnBIu/oXjp/WA=
+github.com/indaco/herald v0.11.0/go.mod h1:T5g1+XLYvpjouhzAGHnAHDCKizhESkoV6+QPZ3DhgWA=
+github.com/indaco/herald-md v0.2.0 h1:kGFsKE+Swzf7EyTUFx7FL1d1jwiKoJRcxqYo2bhUgS0=
+github.com/indaco/herald-md v0.2.0/go.mod h1:64DKh1wSQUsWXTuIYklFzSheJKkW0+FpaqyKqwids3g=
 github.com/kaptinlin/go-i18n v0.3.0 h1:wP76dvYg04bvwTb+8NB+CmdZ2kL7lSSCQ9B/kFv7QHo=
 github.com/kaptinlin/go-i18n v0.3.0/go.mod h1:pVcu9qsW5pOIOoZFJXesRYmLos1vMQrby70JPAoWmJU=
 github.com/kaptinlin/jsonpointer v0.4.17 h1:mY9k8ciWncxbsECyaxKnR0MdmxamNdp2tLQkAKVrtSk=
@@ -307,20 +307,20 @@ golang.org/x/text v0.35.0 h1:JOVx6vVDFokkpaq1AEptVzLTpDe9KGpj5tR4/X+ybL8=
 golang.org/x/text v0.35.0/go.mod h1:khi/HExzZJ2pGnjenulevKNX1W67CUy0AsXcNubPGCA=
 golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
 golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
-gonum.org/v1/gonum v0.16.0 h1:5+ul4Swaf3ESvrOnidPp4GZbzf0mxVQpDCYUQE7OJfk=
-gonum.org/v1/gonum v0.16.0/go.mod h1:fef3am4MQ93R2HHpKnLk4/Tbh/s0+wqD5nfa6Pnwy4E=
-google.golang.org/api v0.273.0 h1:r/Bcv36Xa/te1ugaN1kdJ5LoA5Wj/cL+a4gj6FiPBjQ=
-google.golang.org/api v0.273.0/go.mod h1:JbAt7mF+XVmWu6xNP8/+CTiGH30ofmCmk9nM8d8fHew=
-google.golang.org/genai v1.52.0 h1:ekVIxWHtLUNbt+v0WWi4j3JT4yrHDEbysMcHQcaCQoI=
-google.golang.org/genai v1.52.0/go.mod h1:A3kkl0nyBjyFlNjgxIwKq70julKbIxpSxqKO5gw/gmk=
+gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4=
+gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E=
+google.golang.org/api v0.273.1 h1:L7G/TmpAMz0nKx/ciAVssVmWQiOF6+pOuXeKrWVsquY=
+google.golang.org/api v0.273.1/go.mod h1:JbAt7mF+XVmWu6xNP8/+CTiGH30ofmCmk9nM8d8fHew=
+google.golang.org/genai v1.52.1 h1:dYoljKtLDXMiBdVaClSJ/ZPwZ7j1N0lGjMhwOKOQUlk=
+google.golang.org/genai v1.52.1/go.mod h1:A3kkl0nyBjyFlNjgxIwKq70julKbIxpSxqKO5gw/gmk=
 google.golang.org/genproto v0.0.0-20260319201613-d00831a3d3e7 h1:XzmzkmB14QhVhgnawEVsOn6OFsnpyxNPRY9QV01dNB0=
 google.golang.org/genproto v0.0.0-20260319201613-d00831a3d3e7/go.mod h1:L43LFes82YgSonw6iTXTxXUX1OlULt4AQtkik4ULL/I=
 google.golang.org/genproto/googleapis/api v0.0.0-20260319201613-d00831a3d3e7 h1:41r6JMbpzBMen0R/4TZeeAmGXSJC7DftGINUodzTkPI=
 google.golang.org/genproto/googleapis/api v0.0.0-20260319201613-d00831a3d3e7/go.mod h1:EIQZ5bFCfRQDV4MhRle7+OgjNtZ6P1PiZBgAKuxXu/Y=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260319201613-d00831a3d3e7 h1:ndE4FoJqsIceKP2oYSnUZqhTdYufCYYkqwtFzfrhI7w=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260319201613-d00831a3d3e7/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
-google.golang.org/grpc v1.79.3 h1:sybAEdRIEtvcD68Gx7dmnwjZKlyfuc61Dyo9pGXXkKE=
-google.golang.org/grpc v1.79.3/go.mod h1:KmT0Kjez+0dde/v2j9vzwoAScgEPx/Bw1CYChhHLrHQ=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260401024825-9d38bb4040a9 h1:m8qni9SQFH0tJc1X0vmnpw/0t+AImlSvp30sEupozUg=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260401024825-9d38bb4040a9/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
+google.golang.org/grpc v1.80.0 h1:Xr6m2WmWZLETvUNvIUmeD5OAagMw3FiKmMlTdViWsHM=
+google.golang.org/grpc v1.80.0/go.mod h1:ho/dLnxwi3EDJA4Zghp7k2Ec1+c2jqup0bFkw07bwF4=
 google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
 google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

internal/acpserver/agent.go

@@ -7,8 +7,11 @@ package acpserver
 
 import (
 	"context"
+	"encoding/base64"
 	"encoding/json"
 	"fmt"
+	"os"
+	"strings"
 	"sync/atomic"
 
 	"github.com/charmbracelet/log"
@@ -20,6 +23,17 @@ import (
 // Version is injected at build time; fallback to "dev".
 var Version = "dev"
 
+// thinkingTagOpen and thinkingTagClose are the XML-style tags that some models
+// (Qwen, DeepSeek) wrap reasoning content in. We parse these to extract
+// reasoning/thinking content and send it as ACP thought updates.
+// Also support <think> format used by some models.
+const (
+	thinkingTagOpen    = "<thinking>"
+	thinkingTagClose   = "</thinking>"
+	shortThinkTagOpen  = "<think>"
+	shortThinkTagClose = "</think>"
+)
+
 // Agent implements the acp.Agent interface, delegating to Kit for LLM
 // execution, tool calls, and session management.
 type Agent struct {
@@ -28,6 +42,10 @@ type Agent struct {
 
 	// toolCallCounter provides unique IDs for tool calls within a turn.
 	toolCallCounter atomic.Int64
+
+	// inThinkingTag tracks whether we're currently inside a <thinking> tag
+	// when parsing streaming content from models that wrap reasoning in XML tags.
+	inThinkingTag bool
 }
 
 // NewAgent creates a new ACP agent backed by Kit.
@@ -111,13 +129,23 @@ func (a *Agent) Prompt(ctx context.Context, params acp.PromptRequest) (acp.Promp
 		)
 	}
 
-	// Extract text from prompt content blocks.
-	promptText := extractPromptText(params.Prompt)
-	if promptText == "" {
+	// Extract text and file attachments from prompt content blocks.
+	promptText, files := extractPromptContent(params.Prompt)
+	if promptText == "" && len(files) == 0 {
 		return acp.PromptResponse{}, acp.NewInvalidParams("empty prompt")
 	}
 
-	log.Debug("acp: prompt", "session", sessionID, "prompt_len", len(promptText))
+	// If we have files but no text prompt, add a default prompt
+	// This is required because the underlying LLM library needs a non-empty prompt
+	// when there are no previous messages in the conversation.
+	if promptText == "" && len(files) > 0 {
+		promptText = "Please analyze the attached file."
+	}
+
+	log.Debug("acp: prompt", "session", sessionID, "prompt_len", len(promptText), "files", len(files))
+
+	// Reset thinking tag state for this new prompt turn
+	a.inThinkingTag = false
 
 	// Create a cancellable context for this prompt turn.
 	promptCtx, cancel := context.WithCancel(ctx)
@@ -129,7 +157,13 @@ func (a *Agent) Prompt(ctx context.Context, params acp.PromptRequest) (acp.Promp
 	defer unsub()
 
 	// Run the prompt through Kit's full turn lifecycle.
-	_, err := sess.kit.PromptResult(promptCtx, promptText)
+	// Use PromptResultWithFiles when file attachments are present.
+	var err error
+	if len(files) > 0 {
+		_, err = sess.kit.PromptResultWithFiles(promptCtx, promptText, files)
+	} else {
+		_, err = sess.kit.PromptResult(promptCtx, promptText)
+	}
 	if err != nil {
 		if promptCtx.Err() != nil {
 			return acp.PromptResponse{
@@ -162,6 +196,24 @@ func (a *Agent) SetSessionMode(_ context.Context, _ acp.SetSessionModeRequest) (
 	return acp.SetSessionModeResponse{}, nil
 }
 
+// SetSessionModel changes the active model for a session.
+func (a *Agent) SetSessionModel(ctx context.Context, params acp.SetSessionModelRequest) (acp.SetSessionModelResponse, error) {
+	sessionID := string(params.SessionId)
+	sess, ok := a.registry.get(sessionID)
+	if !ok {
+		return acp.SetSessionModelResponse{}, acp.NewInvalidParams(fmt.Sprintf("session not found: %s", sessionID))
+	}
+
+	modelID := string(params.ModelId)
+	log.Debug("acp: set_session_model", "session", sessionID, "model", modelID)
+
+	if err := sess.kit.SetModel(ctx, modelID); err != nil {
+		return acp.SetSessionModelResponse{}, fmt.Errorf("set model: %w", err)
+	}
+
+	return acp.SetSessionModelResponse{}, nil
+}
+
 // ---------------------------------------------------------------------------
 // Event streaming: Kit events → ACP SessionUpdate notifications
 // ---------------------------------------------------------------------------
@@ -178,8 +230,24 @@ func (a *Agent) subscribeEvents(ctx context.Context, k *kit.Kit, sessionID acp.S
 		var update *acp.SessionUpdate
 		switch ev := e.(type) {
 		case kit.MessageUpdateEvent:
-			u := acp.UpdateAgentMessageText(ev.Chunk)
-			update = &u
+			// Handle models that wrap reasoning in <thinking> tags (Qwen, DeepSeek)
+			// Parse the chunk and separate reasoning from regular text
+			reasoning, text := a.parseThinkingTags(ev.Chunk)
+
+			// Send reasoning update if we have reasoning content
+			if reasoning != "" {
+				u := acp.UpdateAgentThoughtText(reasoning)
+				_ = a.conn.SessionUpdate(ctx, acp.SessionNotification{
+					SessionId: sessionID,
+					Update:    u,
+				})
+			}
+
+			// Send text update if we have text content
+			if text != "" {
+				u := acp.UpdateAgentMessageText(text)
+				update = &u
+			}
 
 		case kit.ReasoningDeltaEvent:
 			u := acp.UpdateAgentThoughtText(ev.Delta)
@@ -231,19 +299,271 @@ func (a *Agent) subscribeEvents(ctx context.Context, k *kit.Kit, sessionID acp.S
 // Helpers
 // ---------------------------------------------------------------------------
 
-// extractPromptText extracts the concatenated text content from ACP content
-// blocks. Non-text blocks are ignored for now.
-func extractPromptText(blocks []acp.ContentBlock) string {
-	var text string
-	for _, block := range blocks {
-		if block.Text != nil {
-			if text != "" {
-				text += "\n"
+// extractPromptContent extracts text and file attachments from ACP content blocks.
+// It converts supported content blocks (image, audio, resource) to Kit's LLMFilePart.
+func extractPromptContent(blocks []acp.ContentBlock) (string, []kit.LLMFilePart) {
+	var textParts []string
+	var files []kit.LLMFilePart
+
+	log.Debug("acp: extracting content", "blocks", len(blocks))
+
+	for i, block := range blocks {
+		switch {
+		// Text content
+		case block.Text != nil:
+			log.Debug("acp: content block", "index", i, "type", "text", "len", len(block.Text.Text))
+			textParts = append(textParts, block.Text.Text)
+
+		// Image data (base64)
+		case block.Image != nil:
+			mimeType := block.Image.MimeType
+			if mimeType == "" {
+				mimeType = "image/png" // Default fallback
 			}
-			text += block.Text.Text
+			log.Debug("acp: content block", "index", i, "type", "image", "mime", mimeType, "data_len", len(block.Image.Data))
+			if data, err := base64.StdEncoding.DecodeString(block.Image.Data); err == nil {
+				files = append(files, kit.LLMFilePart{
+					Filename:  "image.png",
+					Data:      data,
+					MediaType: mimeType,
+				})
+			} else {
+				log.Debug("acp: failed to decode image", "error", err)
+			}
+
+		// Audio data (base64)
+		case block.Audio != nil:
+			mimeType := block.Audio.MimeType
+			if mimeType == "" {
+				mimeType = "audio/wav" // Default fallback
+			}
+			log.Debug("acp: content block", "index", i, "type", "audio", "mime", mimeType)
+			if data, err := base64.StdEncoding.DecodeString(block.Audio.Data); err == nil {
+				files = append(files, kit.LLMFilePart{
+					Filename:  "audio.wav",
+					Data:      data,
+					MediaType: mimeType,
+				})
+			} else {
+				log.Debug("acp: failed to decode audio", "error", err)
+			}
+
+		// Embedded resource (text or binary file content)
+		case block.Resource != nil:
+			log.Debug("acp: content block", "index", i, "type", "resource")
+			res := block.Resource.Resource
+			// Text resource - append as text content with file reference
+			if res.TextResourceContents != nil {
+				uri := res.TextResourceContents.Uri
+				content := res.TextResourceContents.Text
+				mimeType := "text/plain"
+				if res.TextResourceContents.MimeType != nil {
+					mimeType = *res.TextResourceContents.MimeType
+				}
+				log.Debug("acp: text resource", "uri", uri, "mime", mimeType, "len", len(content))
+				// Text files are included as formatted text, NOT as FilePart
+				// FilePart is for binary files (images, audio, PDFs) only
+				textParts = append(textParts, fmt.Sprintf("[File: %s]\n```\n%s\n```", uri, content))
+			}
+			// Binary resource (base64 blob) - these become FilePart
+			if res.BlobResourceContents != nil {
+				uri := res.BlobResourceContents.Uri
+				mimeType := "application/octet-stream"
+				if res.BlobResourceContents.MimeType != nil {
+					mimeType = *res.BlobResourceContents.MimeType
+				}
+				log.Debug("acp: binary resource", "uri", uri, "mime", mimeType, "blob_len", len(res.BlobResourceContents.Blob))
+				if data, err := base64.StdEncoding.DecodeString(res.BlobResourceContents.Blob); err == nil {
+					files = append(files, kit.LLMFilePart{
+						Filename:  extractFilenameFromURI(uri),
+						Data:      data,
+						MediaType: mimeType,
+					})
+				} else {
+					log.Debug("acp: failed to decode binary resource", "error", err)
+				}
+			}
+
+		// Resource link (file reference without embedded content)
+		case block.ResourceLink != nil:
+			uri := block.ResourceLink.Uri
+			name := block.ResourceLink.Name
+			log.Debug("acp: content block", "index", i, "type", "resource_link", "uri", uri, "name", name)
+			// For resource links, we'll try to read the file from disk
+			// This requires the file URI to be accessible (file:// scheme)
+			if content, err := readResourceFromURI(uri); err == nil {
+				// Detect if it's a text file or binary file
+				mimeType := "text/plain"
+				if block.ResourceLink.MimeType != nil {
+					mimeType = *block.ResourceLink.MimeType
+				}
+				log.Debug("acp: resource link loaded", "uri", uri, "mime", mimeType, "size", len(content))
+
+				// Only create FilePart for binary files (images, audio, PDFs, etc.)
+				// Text files are included as formatted text in the message
+				if isTextMimeType(mimeType) || looksLikeText(content) {
+					textParts = append(textParts, fmt.Sprintf("[File: %s]\n```\n%s\n```", uri, string(content)))
+				} else {
+					// Binary file - create FilePart for models that support it
+					files = append(files, kit.LLMFilePart{
+						Filename:  extractFilenameFromURI(uri),
+						Data:      content,
+						MediaType: mimeType,
+					})
+				}
+			} else {
+				// If we can't read it, include as a text reference
+				log.Debug("acp: resource link failed to load", "uri", uri, "error", err)
+				textParts = append(textParts, fmt.Sprintf("[Referenced file: %s]", uri))
+			}
+
+		default:
+			log.Debug("acp: content block", "index", i, "type", "unknown/unhandled")
 		}
 	}
-	return text
+
+	// Debug log the extracted content
+	for i, f := range files {
+		log.Debug("acp: extracted file", "index", i, "filename", f.Filename, "mime", f.MediaType, "size", len(f.Data))
+	}
+
+	return strings.Join(textParts, "\n"), files
+}
+
+// parseThinkingTags parses a text chunk for <thinking> or  tags and separates
+// reasoning content from regular text. This handles models (Qwen, DeepSeek)
+// that wrap reasoning in XML-style tags instead of using proper reasoning events.
+// Returns (reasoningContent, textContent).
+func (a *Agent) parseThinkingTags(chunk string) (reasoning string, text string) {
+	// Handle empty chunk
+	if chunk == "" {
+		return "", ""
+	}
+
+	// Determine which tag format to use (long or short)
+	openTag := thinkingTagOpen
+	closeTag := thinkingTagClose
+
+	if strings.Contains(chunk, shortThinkTagOpen) || strings.Contains(chunk, shortThinkTagClose) {
+		openTag = shortThinkTagOpen
+		closeTag = shortThinkTagClose
+	} else if !strings.Contains(chunk, thinkingTagOpen) && !strings.Contains(chunk, thinkingTagClose) && !a.inThinkingTag {
+		// No tags at all and not in thinking mode - return as text
+		return "", chunk
+	}
+
+	// Check for opening tag
+	if strings.Contains(chunk, openTag) {
+		parts := strings.SplitN(chunk, openTag, 2)
+
+		// Content before the opening tag is regular text
+		if !a.inThinkingTag && parts[0] != "" {
+			text = parts[0]
+		}
+
+		a.inThinkingTag = true
+
+		// Content after the opening tag is reasoning
+		if len(parts) > 1 {
+			// Check if the same chunk contains the closing tag
+			if strings.Contains(parts[1], closeTag) {
+				innerParts := strings.SplitN(parts[1], closeTag, 2)
+				reasoning = innerParts[0]
+				a.inThinkingTag = false
+
+				// Content after closing tag is regular text
+				if len(innerParts) > 1 && innerParts[1] != "" {
+					text += innerParts[1]
+				}
+			} else if parts[1] != "" {
+				// No closing tag yet, all remaining content is reasoning
+				reasoning = parts[1]
+			}
+		}
+		return reasoning, text
+	}
+
+	// Check for closing tag
+	if strings.Contains(chunk, closeTag) {
+		parts := strings.SplitN(chunk, closeTag, 2)
+		a.inThinkingTag = false
+
+		// Content before closing tag is reasoning
+		reasoning = parts[0]
+
+		// Content after closing tag is regular text
+		if len(parts) > 1 && parts[1] != "" {
+			text = parts[1]
+		}
+		return reasoning, text
+	}
+
+	// No tags found - content goes to current mode
+	if a.inThinkingTag {
+		return chunk, ""
+	}
+	return "", chunk
+}
+
+// isTextMimeType returns true if the MIME type indicates text content.
+func isTextMimeType(mimeType string) bool {
+	return strings.HasPrefix(mimeType, "text/") ||
+		mimeType == "application/json" ||
+		mimeType == "application/xml" ||
+		mimeType == "application/javascript" ||
+		mimeType == "application/typescript" ||
+		mimeType == "application/x-sh" ||
+		mimeType == "application/x-python" ||
+		mimeType == "application/x-yaml" ||
+		mimeType == "application/x-toml"
+}
+
+// looksLikeText checks if the content appears to be text (not binary).
+// It samples the first 512 bytes and checks for null bytes or high
+// concentration of non-printable characters.
+func looksLikeText(data []byte) bool {
+	if len(data) == 0 {
+		return true
+	}
+	// Check first 512 bytes (or less if file is smaller)
+	sampleSize := min(len(data), 512)
+	sample := data[:sampleSize]
+
+	// Count non-printable characters
+	nonPrintable := 0
+	for _, b := range sample {
+		// Null byte indicates binary
+		if b == 0 {
+			return false
+		}
+		// Count control characters (except common whitespace)
+		if b < 32 && b != '\n' && b != '\r' && b != '\t' {
+			nonPrintable++
+		}
+	}
+
+	// If more than 30% non-printable, consider it binary
+	return float64(nonPrintable)/float64(sampleSize) < 0.3
+}
+
+// extractFilenameFromURI extracts a filename from a file URI or path.
+func extractFilenameFromURI(uri string) string {
+	// Handle file:// URIs
+	uri = strings.TrimPrefix(uri, "file://")
+	// Extract basename
+	if idx := strings.LastIndex(uri, "/"); idx >= 0 {
+		return uri[idx+1:]
+	}
+	return uri
+}
+
+// readResourceFromURI attempts to read file content from a file:// URI.
+func readResourceFromURI(uri string) ([]byte, error) {
+	if !strings.HasPrefix(uri, "file://") {
+		return nil, fmt.Errorf("unsupported URI scheme: %s", uri)
+	}
+	path := uri[7:] // Remove file:// prefix
+	return os.ReadFile(path)
 }
 
 // parseToolArgs attempts to parse a JSON tool args string into a map for

internal/app/app.go

@@ -20,7 +20,7 @@ import (
 // queueItem holds a prompt and optional image attachments for the execution queue.
 type queueItem struct {
 	Prompt string
-	Files  []fantasy.FilePart
+	Files  []kit.LLMFilePart
 }
 
 // App is the application-layer orchestrator. It owns the agentic loop,
@@ -82,7 +82,7 @@ type App struct {
 
 // New creates a new App with the provided options and pre-loaded messages.
 // initialMessages may be nil or empty for a fresh session.
-func New(opts Options, initialMessages []fantasy.Message) *App {
+func New(opts Options, initialMessages []kit.LLMMessage) *App {
 	rootCtx, rootCancel := context.WithCancel(context.Background())
 	return &App{
 		opts:       opts,
@@ -126,9 +126,8 @@ func (a *App) Run(prompt string) int {
 // If the app is idle the prompt executes immediately; otherwise it is queued.
 // Returns the current queue depth (0 = started immediately, >0 = queued).
 //
-// Satisfies ui.AppController (via RunWithImages which converts ImageAttachment
-// to fantasy.FilePart).
-func (a *App) RunWithFiles(prompt string, files []fantasy.FilePart) int {
+// Satisfies ui.AppController.
+func (a *App) RunWithFiles(prompt string, files []kit.LLMFilePart) int {
 	a.mu.Lock()
 
 	if a.closed {
@@ -314,12 +313,12 @@ func (a *App) SwitchTreeSession(ts *session.TreeManager) {
 //
 // Satisfies ui.AppController.
 func (a *App) AddContextMessage(text string) {
-	msg := fantasy.NewUserMessage(text)
-	a.store.Add(msg)
+	kitMsg := fantasy.NewUserMessage(text)
+	a.store.Add(kitMsg)
 
 	// Persist to tree session if active.
 	if ts := a.opts.TreeSession; ts != nil {
-		_, _ = ts.AppendLLMMessage(msg)
+		_, _ = ts.AppendLLMMessage(fantasy.NewUserMessage(text))
 	}
 }
 
@@ -357,6 +356,15 @@ func (a *App) CompactConversation(customInstructions string) error {
 			a.mu.Unlock()
 		}()
 
+		// Subscribe to SDK events for streaming compaction summary to the TUI.
+		sendFn := func(msg tea.Msg) {
+			if a.program != nil {
+				a.program.Send(msg)
+			}
+		}
+		unsub := a.subscribeSDKEvents(sendFn, nil)
+		defer unsub()
+
 		result, err := a.opts.Kit.Compact(a.rootCtx, nil, customInstructions)
 		if err != nil {
 			a.sendEvent(CompactErrorEvent{Err: err})
@@ -506,11 +514,10 @@ func (a *App) drainQueue(first queueItem) {
 		a.mu.Lock()
 		items = append(items, a.queue...)
 		a.queue = a.queue[:0] // Clear the queue
-		queueLen := len(a.queue)
 		a.mu.Unlock()
 
-		// Send queue updated event (queue is now empty)
-		a.sendEvent(QueueUpdatedEvent{Length: queueLen})
+		// Notify UI: all queued messages have been consumed into this batch.
+		a.sendEvent(QueueUpdatedEvent{Length: 0})
 
 		// Process all collected items as a single batch
 		a.runQueueBatch(items)
@@ -543,6 +550,11 @@ func (a *App) drainQueue(first queueItem) {
 		}
 		a.mu.Unlock()
 
+		if hasMore {
+			// Notify UI: these newly queued messages have been consumed into the next batch.
+			a.sendEvent(QueueUpdatedEvent{Length: 0})
+		}
+
 		if !hasMore {
 			// No more items, we're done
 			break
@@ -609,7 +621,7 @@ func (a *App) runQueueBatch(items []queueItem) {
 // executeStep runs a single agentic step by delegating to the SDK's
 // PromptResult() (or PromptResultWithFiles for multimodal), which handles
 // session persistence, hooks, extension events, and the generation loop.
-func (a *App) executeStep(ctx context.Context, prompt string, eventFn func(tea.Msg), files []fantasy.FilePart) (*kit.TurnResult, error) {
+func (a *App) executeStep(ctx context.Context, prompt string, eventFn func(tea.Msg), files []kit.LLMFilePart) (*kit.TurnResult, error) {
 	// Test hook: bypass SDK entirely.
 	if a.opts.PromptFunc != nil {
 		return a.opts.PromptFunc(ctx, prompt)

internal/app/app_test.go

@@ -7,8 +7,6 @@ import (
 	"testing"
 	"time"
 
-	"charm.land/fantasy"
-
 	kit "github.com/mark3labs/kit/pkg/kit"
 )
 
@@ -574,13 +572,13 @@ func TestUpdateUsageFromTurnResult_skipsTotalsWhenStepUsageSeen(t *testing.T) {
 
 	app.updateUsageFromTurnResult(&kit.TurnResult{
 		Response: "ok",
-		TotalUsage: &fantasy.Usage{
+		TotalUsage: &kit.LLMUsage{
 			InputTokens:         999,
 			OutputTokens:        111,
 			CacheReadTokens:     7,
 			CacheCreationTokens: 3,
 		},
-		FinalUsage: &fantasy.Usage{InputTokens: 456},
+		FinalUsage: &kit.LLMUsage{InputTokens: 456},
 	}, "prompt", true)
 
 	usage.mu.Lock()
@@ -608,13 +606,13 @@ func TestUpdateUsageFromTurnResult_recordsWhenInputTokensZero(t *testing.T) {
 	// Simulate OpenAI-compatible behavior: all prompt tokens cached, InputTokens=0
 	app.updateUsageFromTurnResult(&kit.TurnResult{
 		Response: "ok",
-		TotalUsage: &fantasy.Usage{
+		TotalUsage: &kit.LLMUsage{
 			InputTokens:         0,   // All cached - subtracted from prompt
 			OutputTokens:        150, // Actual generated tokens
 			CacheReadTokens:     500, // Cache hit
 			CacheCreationTokens: 0,
 		},
-		FinalUsage: &fantasy.Usage{InputTokens: 0, OutputTokens: 150},
+		FinalUsage: &kit.LLMUsage{InputTokens: 0, OutputTokens: 150},
 	}, "prompt", false)
 
 	usage.mu.Lock()
@@ -642,11 +640,11 @@ func TestUpdateUsageFromTurnResult_contextTokensUsesInputOnly(t *testing.T) {
 
 	app.updateUsageFromTurnResult(&kit.TurnResult{
 		Response: "ok",
-		TotalUsage: &fantasy.Usage{
+		TotalUsage: &kit.LLMUsage{
 			InputTokens:  1000,
 			OutputTokens: 200,
 		},
-		FinalUsage: &fantasy.Usage{
+		FinalUsage: &kit.LLMUsage{
 			InputTokens:  1000, // Full context including history
 			OutputTokens: 200,
 		},

internal/app/events.go

@@ -1,6 +1,6 @@
 package app
 
-import "charm.land/fantasy"
+import kit "github.com/mark3labs/kit/pkg/kit"
 
 // StreamChunkEvent is sent by the app layer when a streaming text delta arrives
 // from the LLM. Each chunk contains an incremental portion of the response.
@@ -118,8 +118,8 @@ type SpinnerEvent struct {
 // MessageCreatedEvent is sent when a new message is added to the message store.
 // This allows the TUI to stay in sync with the conversation history.
 type MessageCreatedEvent struct {
-	// Message is the fantasy message that was added to the store.
-	Message fantasy.Message
+	// Message is the message that was added to the store.
+	Message kit.LLMMessage
 }
 
 // CompactCompleteEvent is sent when a /compact operation finishes successfully.

internal/app/messages.go

@@ -3,14 +3,14 @@ package app
 import (
 	"sync"
 
-	"charm.land/fantasy"
+	kit "github.com/mark3labs/kit/pkg/kit"
 )
 
 // MessageStore is a thread-safe in-memory store for the conversation history.
 // On-disk persistence is handled by the TreeManager at the app/SDK layer.
 type MessageStore struct {
 	mu       sync.RWMutex
-	messages []fantasy.Message
+	messages []kit.LLMMessage
 }
 
 // NewMessageStore creates an empty MessageStore.
@@ -20,14 +20,14 @@ func NewMessageStore() *MessageStore {
 
 // NewMessageStoreWithMessages creates a MessageStore pre-populated with the
 // given messages. This is used when loading an existing session at startup.
-func NewMessageStoreWithMessages(msgs []fantasy.Message) *MessageStore {
-	cp := make([]fantasy.Message, len(msgs))
+func NewMessageStoreWithMessages(msgs []kit.LLMMessage) *MessageStore {
+	cp := make([]kit.LLMMessage, len(msgs))
 	copy(cp, msgs)
 	return &MessageStore{messages: cp}
 }
 
 // Add appends a single message to the store.
-func (s *MessageStore) Add(msg fantasy.Message) {
+func (s *MessageStore) Add(msg kit.LLMMessage) {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	s.messages = append(s.messages, msg)
@@ -36,22 +36,22 @@ func (s *MessageStore) Add(msg fantasy.Message) {
 // Replace replaces the entire message history with the given slice. This is
 // used after an agent step returns the full updated conversation (including
 // tool calls and results).
-func (s *MessageStore) Replace(msgs []fantasy.Message) {
+func (s *MessageStore) Replace(msgs []kit.LLMMessage) {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 
-	cp := make([]fantasy.Message, len(msgs))
+	cp := make([]kit.LLMMessage, len(msgs))
 	copy(cp, msgs)
 	s.messages = cp
 }
 
 // GetAll returns a snapshot copy of the current message slice.
 // The returned slice is safe to modify without affecting the store.
-func (s *MessageStore) GetAll() []fantasy.Message {
+func (s *MessageStore) GetAll() []kit.LLMMessage {
 	s.mu.RLock()
 	defer s.mu.RUnlock()
 
-	cp := make([]fantasy.Message, len(s.messages))
+	cp := make([]kit.LLMMessage, len(s.messages))
 	copy(cp, s.messages)
 	return cp
 }

internal/app/messages_test.go

@@ -4,16 +4,29 @@ import (
 	"testing"
 
 	"charm.land/fantasy"
+
+	kit "github.com/mark3labs/kit/pkg/kit"
 )
 
-// makeTextMsg builds a minimal fantasy.Message with a single TextPart.
-func makeTextMsg(role, text string) fantasy.Message {
-	return fantasy.Message{
-		Role:    fantasy.MessageRole(role),
+// makeTextMsg builds a minimal kit.LLMMessage using fantasy.NewUserMessage
+// or constructing with the given role.
+func makeTextMsg(role, text string) kit.LLMMessage {
+	return kit.LLMMessage{
+		Role:    kit.LLMMessageRole(role),
 		Content: []fantasy.MessagePart{fantasy.TextPart{Text: text}},
 	}
 }
 
+// textOf extracts the plain text from an LLMMessage for assertions.
+func textOf(msg kit.LLMMessage) string {
+	for _, part := range msg.Content {
+		if tp, ok := part.(fantasy.TextPart); ok {
+			return tp.Text
+		}
+	}
+	return ""
+}
+
 // --------------------------------------------------------------------------
 // NewMessageStore / NewMessageStoreWithMessages
 // --------------------------------------------------------------------------
@@ -29,7 +42,7 @@ func TestNewMessageStore_empty(t *testing.T) {
 }
 
 func TestNewMessageStoreWithMessages_preloaded(t *testing.T) {
-	msgs := []fantasy.Message{
+	msgs := []kit.LLMMessage{
 		makeTextMsg("user", "hello"),
 		makeTextMsg("assistant", "hi"),
 	}
@@ -42,7 +55,7 @@ func TestNewMessageStoreWithMessages_preloaded(t *testing.T) {
 // NewMessageStoreWithMessages must deep-copy the slice so that external
 // modifications don't affect the store.
 func TestNewMessageStoreWithMessages_isolatesInput(t *testing.T) {
-	msgs := []fantasy.Message{makeTextMsg("user", "hello")}
+	msgs := []kit.LLMMessage{makeTextMsg("user", "hello")}
 	s := NewMessageStoreWithMessages(msgs)
 
 	// Mutate the source slice.
@@ -52,9 +65,8 @@ func TestNewMessageStoreWithMessages_isolatesInput(t *testing.T) {
 	if len(got) != 1 {
 		t.Fatalf("expected 1 message, got %d", len(got))
 	}
-	tp, ok := got[0].Content[0].(fantasy.TextPart)
-	if !ok || tp.Text != "hello" {
-		t.Fatalf("store was mutated by external slice change; got %q", tp.Text)
+	if textOf(got[0]) != "hello" {
+		t.Fatalf("store was mutated by external slice change; got %q", textOf(got[0]))
 	}
 }
 
@@ -80,9 +92,8 @@ func TestAdd_preservesOrder(t *testing.T) {
 	}
 	got := s.GetAll()
 	for i, expected := range texts {
-		tp, ok := got[i].Content[0].(fantasy.TextPart)
-		if !ok || tp.Text != expected {
-			t.Fatalf("message[%d]: expected %q, got %q", i, expected, tp.Text)
+		if textOf(got[i]) != expected {
+			t.Fatalf("message[%d]: expected %q, got %q", i, expected, textOf(got[i]))
 		}
 	}
 }
@@ -95,7 +106,7 @@ func TestReplace_swapsHistory(t *testing.T) {
 	s := NewMessageStore()
 	s.Add(makeTextMsg("user", "old"))
 
-	replacement := []fantasy.Message{
+	replacement := []kit.LLMMessage{
 		makeTextMsg("user", "new1"),
 		makeTextMsg("assistant", "new2"),
 	}
@@ -105,25 +116,22 @@ func TestReplace_swapsHistory(t *testing.T) {
 		t.Fatalf("expected 2 messages after replace, got %d", s.Len())
 	}
 	got := s.GetAll()
-	tp0, _ := got[0].Content[0].(fantasy.TextPart)
-	tp1, _ := got[1].Content[0].(fantasy.TextPart)
-	if tp0.Text != "new1" || tp1.Text != "new2" {
-		t.Fatalf("unexpected messages after replace: %q %q", tp0.Text, tp1.Text)
+	if textOf(got[0]) != "new1" || textOf(got[1]) != "new2" {
+		t.Fatalf("unexpected messages after replace: %q %q", textOf(got[0]), textOf(got[1]))
 	}
 }
 
 // Replace must deep-copy the incoming slice.
 func TestReplace_isolatesInput(t *testing.T) {
 	s := NewMessageStore()
-	replacement := []fantasy.Message{makeTextMsg("user", "original")}
+	replacement := []kit.LLMMessage{makeTextMsg("user", "original")}
 	s.Replace(replacement)
 
 	replacement[0] = makeTextMsg("user", "mutated")
 
 	got := s.GetAll()
-	tp, _ := got[0].Content[0].(fantasy.TextPart)
-	if tp.Text != "original" {
-		t.Fatalf("store was mutated by external slice change after Replace; got %q", tp.Text)
+	if textOf(got[0]) != "original" {
+		t.Fatalf("store was mutated by external slice change after Replace; got %q", textOf(got[0]))
 	}
 }
 
@@ -140,9 +148,8 @@ func TestGetAll_returnsCopy(t *testing.T) {
 	got[0] = makeTextMsg("user", "mutated")
 
 	internal := s.GetAll()
-	tp, _ := internal[0].Content[0].(fantasy.TextPart)
-	if tp.Text != "hello" {
-		t.Fatalf("GetAll returned non-copy; store was mutated to %q", tp.Text)
+	if textOf(internal[0]) != "hello" {
+		t.Fatalf("GetAll returned non-copy; store was mutated to %q", textOf(internal[0]))
 	}
 }
 
@@ -179,9 +186,8 @@ func TestClear_allowsSubsequentAdds(t *testing.T) {
 		t.Fatalf("expected 1 message after Clear+Add, got %d", s.Len())
 	}
 	got := s.GetAll()
-	tp, _ := got[0].Content[0].(fantasy.TextPart)
-	if tp.Text != "after" {
-		t.Fatalf("expected %q, got %q", "after", tp.Text)
+	if textOf(got[0]) != "after" {
+		t.Fatalf("expected %q, got %q", "after", textOf(got[0]))
 	}
 }
 

internal/app/options.go

@@ -67,10 +67,6 @@ type Options struct {
 	// Debug enables verbose debug logging.
 	Debug bool
 
-	// CompactMode selects the compact renderer instead of the block renderer for
-	// message formatting.
-	CompactMode bool
-
 	// UsageTracker is an optional callback for recording token usage after each
 	// agent step. When non-nil, the app layer calls UpdateUsage (or
 	// EstimateAndUpdateUsage as a fallback) using the usage data returned by the

internal/compaction/compaction.go

@@ -428,6 +428,10 @@ type PreviousCompaction struct {
 	ModifiedFiles []string
 }
 
+// StreamCallback is called for each chunk of text during streaming compaction.
+// Return a non-nil error to cancel the stream.
+type StreamCallback func(delta string) error
+
 // Compact summarises older messages using the LLM, returning the compaction
 // result and a new message slice (summary message + preserved recent
 // messages).
@@ -442,6 +446,8 @@ type PreviousCompaction struct {
 //
 // prev carries file tracking from a previous compaction for cumulative
 // tracking. Pass nil if there is no prior compaction.
+// onChunk is an optional callback for streaming summary text. Pass nil for
+// non-streaming compaction.
 func Compact(
 	ctx context.Context,
 	model fantasy.LanguageModel,
@@ -449,6 +455,7 @@ func Compact(
 	opts CompactionOptions,
 	customInstructions string,
 	prev *PreviousCompaction,
+	onChunk StreamCallback,
 ) (*CompactionResult, []fantasy.Message, error) {
 	opts.defaults()
 
@@ -487,9 +494,9 @@ func Compact(
 	var err error
 
 	if IsSplitTurn(messages, cutPoint) {
-		summaryText, err = compactSplitTurn(ctx, model, oldMessages, messages, cutPoint, opts, customInstructions)
+		summaryText, err = compactSplitTurn(ctx, model, oldMessages, messages, cutPoint, opts, customInstructions, onChunk)
 	} else {
-		summaryText, err = compactNormal(ctx, model, oldMessages, opts, customInstructions)
+		summaryText, err = compactNormal(ctx, model, oldMessages, opts, customInstructions, onChunk)
 	}
 	if err != nil {
 		return nil, nil, err
@@ -527,15 +534,17 @@ func Compact(
 }
 
 // compactNormal generates a summary for a clean turn-boundary cut.
+// If onChunk is provided, text deltas are streamed to it.
 func compactNormal(
 	ctx context.Context,
 	model fantasy.LanguageModel,
 	oldMessages []fantasy.Message,
 	opts CompactionOptions,
 	customInstructions string,
+	onChunk StreamCallback,
 ) (string, error) {
 	conversationText := serializeMessages(oldMessages)
-	return generateSummary(ctx, model, conversationText, opts, customInstructions)
+	return generateSummary(ctx, model, conversationText, opts, customInstructions, onChunk)
 }
 
 // compactSplitTurn handles the case where the cut point lands mid-turn.
@@ -546,6 +555,7 @@ func compactNormal(
 //
 // The merged result preserves context from both the older history and the
 // beginning of the current long turn.
+// If onChunk is provided, both summaries and the separator are streamed.
 func compactSplitTurn(
 	ctx context.Context,
 	model fantasy.LanguageModel,
@@ -554,6 +564,7 @@ func compactSplitTurn(
 	cutPoint int,
 	opts CompactionOptions,
 	customInstructions string,
+	onChunk StreamCallback,
 ) (string, error) {
 	// Find where the split turn starts.
 	turnStart := findTurnStart(allMessages, cutPoint)
@@ -573,12 +584,19 @@ func compactSplitTurn(
 	// Generate history summary if there are complete turns before the split.
 	if len(historyMessages) >= 2 {
 		historySummary, err = generateSummary(ctx, model,
-			serializeMessages(historyMessages), opts, "")
+			serializeMessages(historyMessages), opts, "", onChunk)
 		if err != nil {
 			return "", fmt.Errorf("split turn history summary failed: %w", err)
 		}
 	}
 
+	// Stream the separator between history and turn prefix summaries.
+	if onChunk != nil && historySummary != "" {
+		if err := onChunk("\n\n---\n\n## Current Turn (in progress)\n\n"); err != nil {
+			return "", fmt.Errorf("streaming separator failed: %w", err)
+		}
+	}
+
 	// Generate turn prefix summary.
 	turnPrefixText := serializeMessages(turnPrefixMessages)
 	turnPrefixPrompt := "The messages above are the BEGINNING of a long turn that was split. " +
@@ -588,16 +606,10 @@ func compactSplitTurn(
 		turnPrefixPrompt += "\n\nAdditional instructions: " + customInstructions
 	}
 
-	summaryAgent := fantasy.NewAgent(model,
-		fantasy.WithSystemPrompt(defaultSystemPrompt),
-	)
-	result, err := summaryAgent.Generate(ctx, fantasy.AgentCall{
-		Prompt: turnPrefixText + "\n\n" + turnPrefixPrompt,
-	})
+	turnPrefixSummary, err := generateSummary(ctx, model, turnPrefixText, opts, turnPrefixPrompt, onChunk)
 	if err != nil {
 		return "", fmt.Errorf("split turn prefix summary failed: %w", err)
 	}
-	turnPrefixSummary := result.Response.Content.Text()
 
 	// Merge the two summaries.
 	if historySummary != "" && turnPrefixSummary != "" {
@@ -610,12 +622,14 @@ func compactSplitTurn(
 }
 
 // generateSummary calls the LLM to produce a structured summary.
+// If onChunk is provided, the summary is streamed using Agent.Stream().
 func generateSummary(
 	ctx context.Context,
 	model fantasy.LanguageModel,
 	conversationText string,
 	opts CompactionOptions,
 	customInstructions string,
+	onChunk StreamCallback,
 ) (string, error) {
 	userPrompt := opts.SummaryPrompt
 	if userPrompt == "" {
@@ -628,8 +642,31 @@ func generateSummary(
 	summaryAgent := fantasy.NewAgent(model,
 		fantasy.WithSystemPrompt(defaultSystemPrompt),
 	)
+
+	prompt := conversationText + "\n\n" + userPrompt
+
+	// Use streaming if onChunk is provided.
+	if onChunk != nil {
+		var fullText strings.Builder
+		_, err := summaryAgent.Stream(ctx, fantasy.AgentStreamCall{
+			Prompt: prompt,
+			OnTextDelta: func(_, delta string) error {
+				if delta != "" {
+					fullText.WriteString(delta)
+					return onChunk(delta)
+				}
+				return nil
+			},
+		})
+		if err != nil {
+			return "", fmt.Errorf("compaction summarisation (streaming) failed: %w", err)
+		}
+		return fullText.String(), nil
+	}
+
+	// Non-streaming path.
 	result, err := summaryAgent.Generate(ctx, fantasy.AgentCall{
-		Prompt: conversationText + "\n\n" + userPrompt,
+		Prompt: prompt,
 	})
 	if err != nil {
 		return "", fmt.Errorf("compaction summarisation failed: %w", err)

internal/compaction/compaction_test.go

@@ -243,7 +243,7 @@ func TestCompact_TooFewMessages(t *testing.T) {
 		makeTextMessageN(fantasy.MessageRoleUser, 400),
 	}
 
-	result, newMsgs, err := Compact(context.TODO(), nil, msgs, CompactionOptions{}, "", nil)
+	result, newMsgs, err := Compact(context.TODO(), nil, msgs, CompactionOptions{}, "", nil, nil)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -262,7 +262,7 @@ func TestCompact_WithinBudget(t *testing.T) {
 		makeTextMessageN(fantasy.MessageRoleAssistant, 400),
 	}
 
-	result, newMsgs, err := Compact(context.TODO(), nil, msgs, CompactionOptions{}, "", nil)
+	result, newMsgs, err := Compact(context.TODO(), nil, msgs, CompactionOptions{}, "", nil, nil)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}

internal/config/config.go

@@ -191,7 +191,6 @@ type Config struct {
 	Model          string                     `json:"model,omitempty" yaml:"model,omitempty"`
 	MaxSteps       int                        `json:"max-steps,omitempty" yaml:"max-steps,omitempty"`
 	Debug          bool                       `json:"debug,omitempty" yaml:"debug,omitempty"`
-	Compact        bool                       `json:"compact,omitempty" yaml:"compact,omitempty"`
 	SystemPrompt   string                     `json:"system-prompt,omitempty" yaml:"system-prompt,omitempty"`
 	ProviderAPIKey string                     `json:"provider-api-key,omitempty" yaml:"provider-api-key,omitempty"`
 	ProviderURL    string                     `json:"provider-url,omitempty" yaml:"provider-url,omitempty"`

internal/session/tree_manager.go

@@ -114,6 +114,187 @@ func CreateTreeSession(cwd string) (*TreeManager, error) {
 	return tm, nil
 }
 
+// ForkToNewSession creates a new session file containing the history up to and
+// including the target entry ID. This matches Pi's /fork behavior: it creates
+// a completely new session file with a parent_session reference, copying all
+// entries from the root to the target point.
+func (tm *TreeManager) ForkToNewSession(cwd string, targetID string) (*TreeManager, error) {
+	tm.mu.RLock()
+	defer tm.mu.RUnlock()
+
+	// Get the branch from root to target (root-to-leaf order).
+	branch := tm.getBranchLocked(targetID)
+	if len(branch) == 0 {
+		return nil, fmt.Errorf("target entry %q not found", targetID)
+	}
+
+	// Create a new session file.
+	newTm, err := CreateTreeSession(cwd)
+	if err != nil {
+		return nil, err
+	}
+
+	// Set the parent session reference in the header.
+	newTm.header.ParentSession = tm.filePath
+	newTm.header.ParentSessionID = tm.header.ID
+
+	// Rewrite the header with the parent reference.
+	// We need to close and recreate the file to rewrite the header.
+	if err := newTm.file.Close(); err != nil {
+		return nil, fmt.Errorf("failed to close new session file: %w", err)
+	}
+
+	// Recreate the file and write the updated header.
+	f, err := os.Create(newTm.filePath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to recreate session file: %w", err)
+	}
+	newTm.file = f
+
+	if err := newTm.writeEntry(&newTm.header); err != nil {
+		_ = f.Close()
+		return nil, fmt.Errorf("failed to write session header: %w", err)
+	}
+
+	// Copy entries from the branch to the new session.
+	// We need to remap IDs since the new session is independent.
+	idMap := make(map[string]string) // old ID -> new ID
+	var prevNewID string
+
+	for _, entry := range branch {
+		oldID := tm.EntryID(entry)
+		newID := GenerateEntryID()
+		idMap[oldID] = newID
+
+		// Create a copy of the entry with the new ID and remapped parent.
+		var newEntry any
+		switch e := entry.(type) {
+		case *MessageEntry:
+			newEntry = &MessageEntry{
+				Entry: Entry{
+					Type:      EntryTypeMessage,
+					ID:        newID,
+					ParentID:  prevNewID, // Chain sequentially in new session
+					Timestamp: e.Timestamp,
+				},
+				Role:     e.Role,
+				Parts:    e.Parts,
+				Model:    e.Model,
+				Provider: e.Provider,
+			}
+			// Copy label if present.
+			if label, ok := tm.labels[oldID]; ok {
+				newTm.labels[newID] = label
+			}
+
+		case *ModelChangeEntry:
+			newEntry = &ModelChangeEntry{
+				Entry: Entry{
+					Type:      EntryTypeModelChange,
+					ID:        newID,
+					ParentID:  prevNewID,
+					Timestamp: e.Timestamp,
+				},
+				Provider: e.Provider,
+				ModelID:  e.ModelID,
+			}
+
+		case *LabelEntry:
+			// Remap the target ID if it's in our copied branch.
+			newTargetID := e.TargetID
+			if mapped, ok := idMap[e.TargetID]; ok {
+				newTargetID = mapped
+			}
+			newEntry = &LabelEntry{
+				Entry: Entry{
+					Type:      EntryTypeLabel,
+					ID:        newID,
+					ParentID:  prevNewID,
+					Timestamp: e.Timestamp,
+				},
+				TargetID: newTargetID,
+				Label:    e.Label,
+			}
+
+		case *SessionInfoEntry:
+			newEntry = &SessionInfoEntry{
+				Entry: Entry{
+					Type:      EntryTypeSessionInfo,
+					ID:        newID,
+					ParentID:  prevNewID,
+					Timestamp: e.Timestamp,
+				},
+				Name: e.Name,
+			}
+			newTm.sessionName = e.Name
+
+		case *ExtensionDataEntry:
+			newEntry = &ExtensionDataEntry{
+				Entry: Entry{
+					Type:      EntryTypeExtensionData,
+					ID:        newID,
+					ParentID:  prevNewID,
+					Timestamp: e.Timestamp,
+				},
+				ExtType: e.ExtType,
+				Data:    e.Data,
+			}
+
+		case *BranchSummaryEntry:
+			// Remap the from ID if it's in our copied branch.
+			newFromID := e.FromID
+			if mapped, ok := idMap[e.FromID]; ok {
+				newFromID = mapped
+			}
+			newEntry = &BranchSummaryEntry{
+				Entry: Entry{
+					Type:      EntryTypeBranchSummary,
+					ID:        newID,
+					ParentID:  prevNewID,
+					Timestamp: e.Timestamp,
+				},
+				FromID:  newFromID,
+				Summary: e.Summary,
+			}
+
+		case *CompactionEntry:
+			// Remap the first kept entry ID if it's in our copied branch.
+			newFirstKeptID := e.FirstKeptEntryID
+			if mapped, ok := idMap[e.FirstKeptEntryID]; ok {
+				newFirstKeptID = mapped
+			}
+			newEntry = &CompactionEntry{
+				Entry: Entry{
+					Type:      EntryTypeCompaction,
+					ID:        newID,
+					ParentID:  prevNewID,
+					Timestamp: e.Timestamp,
+				},
+				Summary:          e.Summary,
+				FirstKeptEntryID: newFirstKeptID,
+				TokensBefore:     e.TokensBefore,
+				TokensAfter:      e.TokensAfter,
+				MessagesRemoved:  e.MessagesRemoved,
+				ReadFiles:        e.ReadFiles,
+				ModifiedFiles:    e.ModifiedFiles,
+			}
+		}
+
+		if newEntry != nil {
+			if err := newTm.appendAndPersist(newEntry); err != nil {
+				_ = f.Close()
+				return nil, fmt.Errorf("failed to copy entry: %w", err)
+			}
+			prevNewID = newID
+		}
+	}
+
+	// Set the leaf to the last entry in the new session.
+	newTm.leafID = prevNewID
+
+	return newTm, nil
+}
+
 // OpenTreeSession opens an existing JSONL session file.
 func OpenTreeSession(path string) (*TreeManager, error) {
 	data, err := os.ReadFile(path)

internal/ui/block_renderer.go

@@ -4,6 +4,8 @@ import (
 	"image/color"
 
 	"charm.land/lipgloss/v2"
+
+	"github.com/mark3labs/kit/internal/ui/style"
 )
 
 // blockRenderer handles rendering of content blocks with configurable options
@@ -175,7 +177,7 @@ func renderContentBlock(content string, containerWidth int, options ...rendering
 		borderChars = 1
 	}
 
-	theme := GetTheme()
+	theme := style.GetTheme()
 
 	// Resolve foreground color: caller override or theme default.
 	fgColor := theme.Text

internal/ui/children_test.go

@@ -6,6 +6,7 @@ import (
 
 	tea "charm.land/bubbletea/v2"
 	"github.com/mark3labs/kit/internal/app"
+	"github.com/mark3labs/kit/internal/ui/core"
 )
 
 // ==========================================================================
@@ -59,7 +60,7 @@ func TestInputComponent_SubmitEmitsSubmitMsg(t *testing.T) {
 		t.Fatal("expected a cmd from pressing enter on non-empty input")
 	}
 
-	sm, ok := msg.(submitMsg)
+	sm, ok := msg.(core.SubmitMsg)
 	if !ok {
 		t.Fatalf("expected submitMsg, got %T", msg)
 	}
@@ -83,7 +84,7 @@ func TestInputComponent_CtrlD_SubmitEmitsSubmitMsg(t *testing.T) {
 	if msg == nil {
 		t.Fatal("expected a cmd from ctrl+d on non-empty input")
 	}
-	sm, ok := msg.(submitMsg)
+	sm, ok := msg.(core.SubmitMsg)
 	if !ok {
 		t.Fatalf("expected submitMsg from ctrl+d, got %T", msg)
 	}
@@ -175,7 +176,7 @@ func TestInputComponent_ClearForwardsAsSubmitMsg(t *testing.T) {
 				t.Fatalf("%s: expected submitMsg cmd, got nil", alias)
 			}
 			msg := runCmd(cmd)
-			sm, ok := msg.(submitMsg)
+			sm, ok := msg.(core.SubmitMsg)
 			if !ok {
 				t.Fatalf("%s: expected submitMsg, got %T", alias, msg)
 			}
@@ -230,7 +231,7 @@ func TestInputComponent_ClearQueue_ForwardsAsSubmitMsg(t *testing.T) {
 				t.Fatalf("%s: expected submitMsg cmd, got nil", alias)
 			}
 			msg := runCmd(cmd)
-			sm, ok := msg.(submitMsg)
+			sm, ok := msg.(core.SubmitMsg)
 			if !ok {
 				t.Fatalf("%s: expected submitMsg, got %T", alias, msg)
 			}
@@ -258,7 +259,7 @@ func TestInputComponent_UnknownSlashCommand_ForwardsAsSubmit(t *testing.T) {
 	if msg == nil {
 		t.Fatal("expected submitMsg for unknown slash command")
 	}
-	sm, ok := msg.(submitMsg)
+	sm, ok := msg.(core.SubmitMsg)
 	if !ok {
 		t.Fatalf("expected submitMsg for unknown slash command, got %T", msg)
 	}
@@ -275,10 +276,9 @@ func TestInputComponent_UnknownSlashCommand_ForwardsAsSubmit(t *testing.T) {
 // Helpers
 // --------------------------------------------------------------------------
 
-// newTestStream creates a StreamComponent with a fixed width and model name,
-// in non-compact mode.
+// newTestStream creates a StreamComponent with a fixed width and model name.
 func newTestStream() *StreamComponent {
-	return NewStreamComponent(false, 80, "test-model")
+	return NewStreamComponent(80, "test-model")
 }
 
 // sendStreamMsg calls component.Update and returns the updated component.
@@ -699,3 +699,38 @@ func TestStreamComponent_StaleFlushTick_Discarded(t *testing.T) {
 		t.Fatalf("expected streamContent='new' after current flush, got %q", got)
 	}
 }
+
+// TestStreamComponent_ConsumeOverflow_NoHeight verifies that when height is
+// unconstrained (0), ConsumeOverflow always returns "".
+func TestStreamComponent_ConsumeOverflow_NoOp(t *testing.T) {
+	c := newTestStream()
+	// Commit some content directly.
+	c.streamContent.WriteString("line1\nline2\nline3")
+	c.phase = streamPhaseActive
+
+	// ConsumeOverflow is a no-op in alt screen mode — always returns "".
+	if got := c.ConsumeOverflow(); got != "" {
+		t.Fatalf("expected empty from no-op ConsumeOverflow, got %q", got)
+	}
+
+	// Also returns "" with a height set.
+	c.height = 2
+	if got := c.ConsumeOverflow(); got != "" {
+		t.Fatalf("expected empty from no-op ConsumeOverflow with height, got %q", got)
+	}
+}
+
+// TestStreamComponent_GetRenderedContent_ReturnsAll verifies that
+// GetRenderedContent returns all accumulated content.
+func TestStreamComponent_GetRenderedContent_ReturnsAll(t *testing.T) {
+	c := newTestStream()
+	c.renderer = nil
+	c.phase = streamPhaseActive
+
+	c.streamContent.WriteString("a\nb\nc\nd\ne")
+
+	got := c.GetRenderedContent()
+	if got != "a\nb\nc\nd\ne" {
+		t.Fatalf("expected full content, got %q", got)
+	}
+}

internal/ui/cli.go

@@ -8,36 +8,31 @@ import (
 	"charm.land/fantasy"
 	"charm.land/lipgloss/v2"
 	"golang.org/x/term"
+
+	"github.com/mark3labs/kit/internal/ui/style"
 )
 
 // CLI manages the command-line interface for KIT, providing message rendering,
-// user input handling, and display management. It supports both standard and compact
-// display modes, handles streaming responses, tracks token usage, and manages the
-// overall conversation flow between the user and AI assistants.
+// user input handling, and display management. It handles streaming responses,
+// tracks token usage, and manages the overall conversation flow between the
+// user and AI assistants.
 type CLI struct {
 	renderer     Renderer
 	usageTracker *UsageTracker
 	width        int
-	compactMode  bool
 	debug        bool
 	modelName    string
 }
 
-// NewCLI creates and initializes a new CLI instance with the specified display modes.
-// The debug parameter enables debug message rendering, while compact enables a more
-// condensed display format. Returns an initialized CLI ready for interaction or an
+// NewCLI creates and initializes a new CLI instance. The debug parameter enables
+// debug message rendering. Returns an initialized CLI ready for interaction or an
 // error if initialization fails.
-func NewCLI(debug bool, compact bool) (*CLI, error) {
+func NewCLI(debug bool) (*CLI, error) {
 	cli := &CLI{
-		compactMode: compact,
-		debug:       debug,
+		debug: debug,
 	}
 	cli.updateSize()
-	if compact {
-		cli.renderer = NewCompactRenderer(cli.width, debug)
-	} else {
-		cli.renderer = newMessageRenderer(cli.width, debug)
-	}
+	cli.renderer = newMessageRenderer(cli.width, debug)
 
 	return cli, nil
 }
@@ -132,7 +127,7 @@ func (c *CLI) DisplayInfo(message string) {
 // DisplayExtensionBlock renders a custom styled block with the given border
 // color and optional subtitle. Used by extensions via ctx.PrintBlock.
 func (c *CLI) DisplayExtensionBlock(text, borderColor, subtitle string) {
-	theme := GetTheme()
+	theme := style.GetTheme()
 
 	borderClr := theme.Info
 	if borderColor != "" {

internal/ui/clipboard/clipboard.go

@@ -0,0 +1,26 @@
+package clipboard
+
+import (
+	tea "charm.land/bubbletea/v2"
+	"github.com/atotto/clipboard"
+)
+
+// CopyToClipboard writes text to both the system clipboard and via OSC 52.
+// Returns a tea.Cmd that can be used in Bubble Tea's Update flow.
+func CopyToClipboard(text string) tea.Cmd {
+	if text == "" {
+		return nil
+	}
+
+	return tea.Sequence(
+		// Method 1: OSC 52 escape sequence (works in modern terminals)
+		tea.SetClipboard(text),
+
+		// Method 2: Native system clipboard (atotto/clipboard)
+		func() tea.Msg {
+			// Best effort - ignore errors
+			_ = clipboard.WriteAll(text)
+			return nil
+		},
+	)
+}

internal/ui/commands/commands.go

@@ -1,4 +1,4 @@
-package ui
+package commands
 
 import (
 	"slices"
@@ -7,6 +7,10 @@ import (
 	"github.com/mark3labs/kit/internal/models"
 )
 
+// ListThemesFunc is set by the ui package to provide theme name completion.
+// This breaks the circular dependency between commands and ui packages.
+var ListThemesFunc func() []string
+
 // SlashCommand represents a user-invokable slash command with its metadata.
 // Commands can have multiple aliases and are organized by category for better
 // discoverability and help display.
@@ -99,7 +103,10 @@ var SlashCommands = []SlashCommand{
 		Description: "Switch color theme (e.g. /theme catppuccin)",
 		Category:    "System",
 		Complete: func(prefix string) []string {
-			names := ListThemes()
+			if ListThemesFunc == nil {
+				return nil
+			}
+			names := ListThemesFunc()
 			if prefix == "" {
 				return names
 			}
@@ -127,7 +134,7 @@ var SlashCommands = []SlashCommand{
 	},
 	{
 		Name:        "/fork",
-		Description: "Branch from an earlier message",
+		Description: "Fork to new session from an earlier message",
 		Category:    "Navigation",
 	},
 	{

internal/ui/compact_renderer.go

@@ -1,444 +0,0 @@
-package ui
-
-import (
-	"fmt"
-	"strings"
-	"time"
-
-	"charm.land/lipgloss/v2"
-)
-
-// CompactRenderer handles rendering messages in a space-efficient compact format,
-// optimized for terminals with limited vertical space. It displays messages with
-// minimal decorations while maintaining readability and essential information.
-type CompactRenderer struct {
-	width int
-	debug bool
-
-	// getToolRenderer returns extension-provided rendering overrides for a
-	// specific tool. May be nil if no extensions are loaded. Used in
-	// RenderToolMessage to check for custom header/body formatting before
-	// falling back to builtin renderers.
-	getToolRenderer func(toolName string) *ToolRendererData
-}
-
-// NewCompactRenderer creates and initializes a new CompactRenderer with the specified
-// terminal width and debug mode setting. The width parameter determines line wrapping,
-// while debug enables additional diagnostic output in rendered messages.
-func NewCompactRenderer(width int, debug bool) *CompactRenderer {
-	return &CompactRenderer{
-		width: width,
-		debug: debug,
-	}
-}
-
-// SetWidth updates the terminal width for the renderer, affecting how content
-// is wrapped and formatted in subsequent render operations.
-func (r *CompactRenderer) SetWidth(width int) {
-	r.width = width
-}
-
-// RenderUserMessage renders a user's input message in compact format with a
-// distinctive symbol (>) and label. The content is formatted to preserve structure
-// while minimizing vertical space usage. Returns a UIMessage with formatted content
-// and metadata.
-func (r *CompactRenderer) RenderUserMessage(content string, timestamp time.Time) UIMessage {
-	theme := GetTheme()
-	symbol := lipgloss.NewStyle().Foreground(theme.Info).Render(">")
-	label := lipgloss.NewStyle().Foreground(theme.Info).Bold(true).Render("User")
-
-	// Only run markdown rendering when the message contains code spans or
-	// fenced code blocks. Plain text is rendered directly so that newlines
-	// are preserved without the extra paragraph spacing glamour adds.
-	var compactContent string
-	if strings.Contains(content, "`") {
-		mdContent := strings.ReplaceAll(content, "\n", "\n\n")
-		compactContent = r.formatUserAssistantContent(mdContent)
-		compactContent = removeBlankLines(compactContent)
-	} else {
-		compactContent = content
-	}
-
-	// Handle multi-line content
-	lines := strings.Split(compactContent, "\n")
-	var formattedLines []string
-
-	for i, line := range lines {
-		if i == 0 {
-			// First line includes symbol and label
-			formattedLines = append(formattedLines, fmt.Sprintf("%s  %s %s", symbol, label, line))
-		} else {
-			// Subsequent lines without indentation for compact mode
-			formattedLines = append(formattedLines, line)
-		}
-	}
-
-	return UIMessage{
-		Type:      UserMessage,
-		Content:   strings.Join(formattedLines, "\n"),
-		Height:    len(formattedLines),
-		Timestamp: timestamp,
-	}
-}
-
-// RenderAssistantMessage renders an AI assistant's response in compact format with
-// a distinctive symbol (<) and the model name as label. Empty content is ignored
-// and returns an empty message. Returns a UIMessage with formatted content and metadata.
-func (r *CompactRenderer) RenderAssistantMessage(content string, timestamp time.Time, modelName string) UIMessage {
-	// Ignore empty responses - don't render anything
-	compactContent := r.formatUserAssistantContent(content)
-	if compactContent == "" {
-		return UIMessage{
-			Type:      AssistantMessage,
-			Content:   "",
-			Height:    0,
-			Timestamp: timestamp,
-		}
-	}
-
-	theme := GetTheme()
-	symbol := lipgloss.NewStyle().Foreground(theme.Primary).Render("<")
-
-	// Use the full model name, fallback to "Assistant" if empty
-	if modelName == "" {
-		modelName = "Assistant"
-	}
-	label := lipgloss.NewStyle().Foreground(theme.Primary).Bold(true).Render(modelName)
-
-	// Handle multi-line content
-	lines := strings.Split(compactContent, "\n")
-	var formattedLines []string
-
-	for i, line := range lines {
-		if i == 0 {
-			// First line includes symbol and label
-			formattedLines = append(formattedLines, fmt.Sprintf("%s  %s %s", symbol, label, line))
-		} else {
-			// Subsequent lines without indentation for compact mode
-			formattedLines = append(formattedLines, line)
-		}
-	}
-
-	return UIMessage{
-		Type:      AssistantMessage,
-		Content:   strings.Join(formattedLines, "\n"),
-		Height:    len(formattedLines),
-		Timestamp: timestamp,
-	}
-}
-
-// RenderToolMessage renders a unified tool block in compact format, combining
-// the tool invocation header (icon + display name + params) with the execution
-// result body. Status is indicated by icon: checkmark for success, cross for error.
-func (r *CompactRenderer) RenderToolMessage(toolName, toolArgs, toolResult string, isError bool) UIMessage {
-	theme := GetTheme()
-
-	// Resolve extension renderer once for all overrides.
-	var extRd *ToolRendererData
-	if r.getToolRenderer != nil {
-		extRd = r.getToolRenderer(toolName)
-	}
-
-	// Status icon
-	var icon string
-	iconColor := theme.Success
-	if isError {
-		icon = "×"
-		iconColor = theme.Error
-	} else {
-		icon = "✓"
-	}
-
-	iconStr := lipgloss.NewStyle().Foreground(iconColor).Bold(true).Render(icon)
-
-	// Extension can override display name.
-	displayName := toolDisplayName(toolName)
-	if extRd != nil && extRd.DisplayName != "" {
-		displayName = extRd.DisplayName
-	}
-	nameStr := lipgloss.NewStyle().Foreground(theme.Info).Bold(true).Render(displayName)
-
-	// Format params — check extension renderer first.
-	paramBudget := max(r.width-10-len(displayName), 20)
-	var params string
-	if extRd != nil && extRd.RenderHeader != nil {
-		params = extRd.RenderHeader(toolArgs, paramBudget)
-	}
-	if params == "" {
-		params = formatToolParams(toolArgs, paramBudget)
-	}
-
-	// Build header line
-	header := iconStr + " " + nameStr
-	if params != "" {
-		header += " " + lipgloss.NewStyle().Foreground(theme.Muted).Render(params)
-	}
-
-	// Format body: check extension renderer first, then compact builtin, then default.
-	var body string
-	if extRd != nil && extRd.RenderBody != nil {
-		body = extRd.RenderBody(toolResult, isError, r.width-4)
-		// Apply markdown rendering if requested and body is non-empty.
-		if body != "" && extRd.BodyMarkdown {
-			body = strings.TrimSuffix(toMarkdown(body, r.width-4), "\n")
-		}
-	}
-	if body == "" {
-		if isError {
-			body = lipgloss.NewStyle().Foreground(theme.Error).Render(r.formatToolResult(toolResult))
-		} else {
-			// Use compact summary renderers instead of full tool body renderers.
-			body = renderToolBodyCompact(toolName, toolArgs, toolResult, r.width-4)
-			if body == "" {
-				formatted := r.formatToolResult(toolResult)
-				if formatted == "" {
-					body = lipgloss.NewStyle().Foreground(theme.Muted).Italic(true).Render("(no output)")
-				} else {
-					body = lipgloss.NewStyle().Foreground(theme.Muted).Render(formatted)
-				}
-			}
-		}
-	}
-
-	// Combine header + indented body
-	var lines []string
-	lines = append(lines, header)
-	if body != "" {
-		for line := range strings.SplitSeq(body, "\n") {
-			lines = append(lines, "  "+line)
-		}
-	}
-
-	return UIMessage{
-		Type:    ToolMessage,
-		Content: strings.Join(lines, "\n"),
-		Height:  len(lines),
-	}
-}
-
-// RenderSystemMessage renders a system notification or informational message in
-// compact format with a distinctive symbol (*) and "System" label. Content is
-// formatted to fit on a single line for minimal space usage.
-func (r *CompactRenderer) RenderSystemMessage(content string, timestamp time.Time) UIMessage {
-	theme := GetTheme()
-	symbol := lipgloss.NewStyle().Foreground(theme.Muted).Render("◇")
-	label := lipgloss.NewStyle().Foreground(theme.Muted).Bold(true).Render("System")
-
-	compactContent := r.formatCompactContent(content)
-
-	line := fmt.Sprintf("%s  %-8s %s", symbol, label, compactContent)
-
-	return UIMessage{
-		Type:      SystemMessage,
-		Content:   line,
-		Height:    1,
-		Timestamp: timestamp,
-	}
-}
-
-// RenderErrorMessage renders an error notification in compact format with a
-// distinctive error symbol (!) and styling to ensure visibility. The error
-// content is displayed in a single line with appropriate color highlighting.
-func (r *CompactRenderer) RenderErrorMessage(errorMsg string, timestamp time.Time) UIMessage {
-	theme := GetTheme()
-	symbol := lipgloss.NewStyle().Foreground(theme.Error).Render("!")
-	label := lipgloss.NewStyle().Foreground(theme.Error).Bold(true).Render("Error")
-
-	compactContent := lipgloss.NewStyle().Foreground(theme.Error).Render(r.formatCompactContent(errorMsg))
-
-	line := fmt.Sprintf("%s  %-8s %s", symbol, label, compactContent)
-
-	return UIMessage{
-		Type:      ErrorMessage,
-		Content:   line,
-		Height:    1,
-		Timestamp: timestamp,
-	}
-}
-
-// RenderDebugMessage renders diagnostic information in compact format when debug
-// mode is enabled. Messages are truncated if they exceed the available width to
-// maintain single-line display.
-func (r *CompactRenderer) RenderDebugMessage(message string, timestamp time.Time) UIMessage {
-	theme := GetTheme()
-	symbol := lipgloss.NewStyle().Foreground(theme.Tool).Render("*")
-	label := lipgloss.NewStyle().Foreground(theme.Tool).Bold(true).Render("Debug")
-
-	// Truncate message if too long
-	content := message
-	if len(content) > r.width-20 {
-		content = content[:r.width-23] + "..."
-	}
-
-	line := fmt.Sprintf("%s  %-8s %s", symbol, label, content)
-
-	return UIMessage{
-		Type:      SystemMessage,
-		Content:   line,
-		Height:    1,
-		Timestamp: timestamp,
-	}
-}
-
-// RenderDebugConfigMessage renders configuration settings in compact format for
-// debugging purposes. Config entries are displayed as key=value pairs separated
-// by commas, truncated if necessary to fit on a single line.
-func (r *CompactRenderer) RenderDebugConfigMessage(config map[string]any, timestamp time.Time) UIMessage {
-	theme := GetTheme()
-	symbol := lipgloss.NewStyle().Foreground(theme.Tool).Render("*")
-	label := lipgloss.NewStyle().Foreground(theme.Tool).Bold(true).Render("Debug")
-
-	// Format config as compact key=value pairs
-	var configPairs []string
-	for key, value := range config {
-		if value != nil {
-			configPairs = append(configPairs, fmt.Sprintf("%s=%v", key, value))
-		}
-	}
-
-	content := strings.Join(configPairs, ", ")
-	if len(content) > r.width-20 {
-		content = content[:r.width-23] + "..."
-	}
-
-	line := fmt.Sprintf("%s  %-8s %s", symbol, label, content)
-
-	return UIMessage{
-		Type:      SystemMessage,
-		Content:   line,
-		Height:    1,
-		Timestamp: timestamp,
-	}
-}
-
-// formatCompactContent formats content for compact single-line display
-func (r *CompactRenderer) formatCompactContent(content string) string {
-	if content == "" {
-		return ""
-	}
-
-	// Remove markdown formatting for compact display
-	content = strings.ReplaceAll(content, "\n", " ")
-	content = strings.ReplaceAll(content, "\t", " ")
-
-	// Collapse multiple spaces
-	for strings.Contains(content, "  ") {
-		content = strings.ReplaceAll(content, "  ", " ")
-	}
-
-	content = strings.TrimSpace(content)
-
-	// Truncate if too long (unless in debug mode)
-	maxLen := max(
-		// Reserve space for symbol and label more conservatively
-		r.width-28,
-		// Minimum width for readability
-		40)
-	if !r.debug && len(content) > maxLen {
-		content = content[:maxLen-3] + "..."
-	}
-
-	return content
-}
-
-// formatUserAssistantContent formats user and assistant content using glamour markdown rendering
-func (r *CompactRenderer) formatUserAssistantContent(content string) string {
-	if content == "" {
-		return ""
-	}
-
-	// Calculate available width more conservatively
-	// Account for: symbol (1) + spaces (2) + label (up to 20 chars) + space (1) + margin (4)
-	availableWidth := max(r.width-28,
-		// Minimum width for readability
-		40)
-
-	// Use glamour to render markdown content with proper width
-	rendered := toMarkdown(content, availableWidth)
-	return strings.TrimSuffix(rendered, "\n")
-}
-
-// wrapText wraps text to the specified width, preserving existing line breaks
-func (r *CompactRenderer) wrapText(text string, width int) string {
-	if width <= 0 {
-		return text
-	}
-
-	lines := strings.Split(text, "\n")
-	var wrappedLines []string
-
-	for _, line := range lines {
-		if len(line) <= width {
-			wrappedLines = append(wrappedLines, line)
-			continue
-		}
-
-		// Wrap long lines
-		words := strings.Fields(line)
-		if len(words) == 0 {
-			wrappedLines = append(wrappedLines, line)
-			continue
-		}
-
-		currentLine := ""
-		for _, word := range words {
-			// If adding this word would exceed the width, start a new line
-			if len(currentLine)+len(word)+1 > width && currentLine != "" {
-				wrappedLines = append(wrappedLines, currentLine)
-				currentLine = word
-			} else {
-				if currentLine == "" {
-					currentLine = word
-				} else {
-					currentLine += " " + word
-				}
-			}
-		}
-		if currentLine != "" {
-			wrappedLines = append(wrappedLines, currentLine)
-		}
-	}
-
-	return strings.Join(wrappedLines, "\n")
-}
-
-// formatToolResult formats tool results preserving formatting but limiting to 5 lines
-func (r *CompactRenderer) formatToolResult(result string) string {
-	if result == "" {
-		return ""
-	}
-
-	// Check if this is bash output with stdout/stderr tags
-	if strings.Contains(result, "<stdout>") || strings.Contains(result, "<stderr>") {
-		result = r.formatBashOutput(result)
-	}
-
-	// Calculate available width more conservatively
-	availableWidth := max(r.width-28,
-		// Minimum width for readability
-		40)
-
-	// First wrap the text to prevent long lines (tool results are usually plain text, not markdown)
-	wrappedResult := r.wrapText(result, availableWidth)
-
-	// Then limit to 5 lines
-	lines := strings.Split(wrappedResult, "\n")
-	if len(lines) > 5 {
-		lines = lines[:5]
-		// Add truncation indicator
-		if len(lines) == 5 && lines[4] != "" {
-			lines[4] = lines[4] + "..."
-		} else {
-			lines = append(lines, "...")
-		}
-	}
-
-	return strings.Join(lines, "\n")
-}
-
-// formatBashOutput formats bash command output by removing stdout/stderr tags
-// and styling appropriately. Delegates tag parsing to the shared parseBashOutput
-// helper.
-func (r *CompactRenderer) formatBashOutput(result string) string {
-	return parseBashOutput(result, GetTheme())
-}

internal/ui/core/events.go

@@ -1,4 +1,4 @@
-package ui
+package core
 
 // ImageAttachment holds a clipboard image that will be sent alongside the
 // user's text prompt to the LLM. The data is raw image bytes; MediaType is
@@ -10,9 +10,9 @@ type ImageAttachment struct {
 	MediaType string
 }
 
-// submitMsg is sent by the InputComponent when the user submits a text prompt.
+// SubmitMsg is sent by the InputComponent when the user submits a text prompt.
 // The parent model receives this and calls app.Run(Text) to start agent processing.
-type submitMsg struct {
+type SubmitMsg struct {
 	// Text is the user's input text to send to the agent.
 	Text string
 	// Images holds clipboard image attachments to send alongside the text.
@@ -20,10 +20,10 @@ type submitMsg struct {
 	Images []ImageAttachment
 }
 
-// cancelTimerExpiredMsg is sent by the tea.Tick command that starts when the user
+// CancelTimerExpiredMsg is sent by the tea.Tick command that starts when the user
 // presses ESC once during stateWorking. If this message arrives before the user
 // presses ESC a second time, the canceling state is reset to false.
-type cancelTimerExpiredMsg struct{}
+type CancelTimerExpiredMsg struct{}
 
 // --- Tree session events ---
 
@@ -42,14 +42,14 @@ type TreeNodeSelectedMsg struct {
 // TreeCancelledMsg is sent when the user cancels the tree selector (ESC).
 type TreeCancelledMsg struct{}
 
-// shellCommandMsg is sent by the InputComponent when the user submits a
+// ShellCommandMsg is sent by the InputComponent when the user submits a
 // ! or !! prefixed command. The parent model intercepts this to execute
 // the shell command directly instead of forwarding to the LLM.
 //
 // Matching pi's behavior:
 //   - !cmd  → run shell command, output INCLUDED in LLM context
 //   - !!cmd → run shell command, output EXCLUDED from LLM context
-type shellCommandMsg struct {
+type ShellCommandMsg struct {
 	// Command is the shell command to execute (prefix stripped).
 	Command string
 	// ExcludeFromContext is true for !! (output excluded from LLM context),
@@ -57,9 +57,9 @@ type shellCommandMsg struct {
 	ExcludeFromContext bool
 }
 
-// shellCommandResultMsg carries the result of a shell command execution
+// ShellCommandResultMsg carries the result of a shell command execution
 // back to the parent model for display.
-type shellCommandResultMsg struct {
+type ShellCommandResultMsg struct {
 	// Command is the original shell command that was executed.
 	Command string
 	// Output is the combined stdout/stderr output.
@@ -68,6 +68,6 @@ type shellCommandResultMsg struct {
 	ExitCode int
 	// Err is non-nil if the command failed to start or timed out.
 	Err error
-	// ExcludeFromContext mirrors the flag from shellCommandMsg.
+	// ExcludeFromContext mirrors the flag from ShellCommandMsg.
 	ExcludeFromContext bool
 }

internal/ui/exports.go

@@ -0,0 +1,62 @@
+package ui
+
+// This file re-exports types from subpackages for backward compatibility.
+// External importers can continue using ui.XXX without needing to import
+// from subpackages directly.
+
+import (
+	"github.com/mark3labs/kit/internal/ui/commands"
+	"github.com/mark3labs/kit/internal/ui/core"
+	"github.com/mark3labs/kit/internal/ui/fileutil"
+	"github.com/mark3labs/kit/internal/ui/prefs"
+	"github.com/mark3labs/kit/internal/ui/style"
+)
+
+// Re-export from core package
+type (
+	ImageAttachment       = core.ImageAttachment
+	SubmitMsg             = core.SubmitMsg
+	CancelTimerExpiredMsg = core.CancelTimerExpiredMsg
+	TreeNodeSelectedMsg   = core.TreeNodeSelectedMsg
+	TreeCancelledMsg      = core.TreeCancelledMsg
+	ShellCommandMsg       = core.ShellCommandMsg
+	ShellCommandResultMsg = core.ShellCommandResultMsg
+)
+
+// Re-export from commands package
+type (
+	SlashCommand     = commands.SlashCommand
+	ExtensionCommand = commands.ExtensionCommand
+)
+
+// Re-export functions from fileutil package
+var ProcessFileAttachments = fileutil.ProcessFileAttachments
+
+// Re-export from prefs package
+var (
+	LoadThemePreference         = prefs.LoadThemePreference
+	SaveThemePreference         = prefs.SaveThemePreference
+	LoadModelPreference         = prefs.LoadModelPreference
+	SaveModelPreference         = prefs.SaveModelPreference
+	LoadThinkingLevelPreference = prefs.LoadThinkingLevelPreference
+	SaveThinkingLevelPreference = prefs.SaveThinkingLevelPreference
+)
+
+// Re-export from style package
+type (
+	Theme               = style.Theme
+	MarkdownThemeColors = style.MarkdownThemeColors
+)
+
+var (
+	GetTheme                = style.GetTheme
+	SetTheme                = style.SetTheme
+	DefaultTheme            = style.DefaultTheme
+	ApplyTheme              = style.ApplyTheme
+	ApplyThemeWithoutSave   = style.ApplyThemeWithoutSave
+	ListThemes              = style.ListThemes
+	RegisterThemeFromConfig = style.RegisterThemeFromConfig
+	KitBanner               = style.KitBanner
+	AdaptiveColor           = style.AdaptiveColor
+	IsDarkBackground        = style.IsDarkBackground
+)

internal/ui/factory.go

@@ -25,7 +25,6 @@ type CLISetupOptions struct {
 	Agent          AgentInterface
 	ModelString    string
 	Debug          bool
-	Compact        bool
 	Quiet          bool
 	ShowDebug      bool   // Whether to show debug config
 	ProviderAPIKey string // For OAuth detection
@@ -76,7 +75,7 @@ func SetupCLI(opts *CLISetupOptions) (*CLI, error) {
 		return nil, nil // No CLI in quiet mode
 	}
 
-	cli, err := NewCLI(opts.Debug, opts.Compact)
+	cli, err := NewCLI(opts.Debug)
 	if err != nil {
 		return nil, fmt.Errorf("failed to create CLI: %v", err)
 	}

internal/ui/fileutil/processor.go

@@ -1,4 +1,4 @@
-package ui
+package fileutil
 
 import (
 	"fmt"

internal/ui/format.go

@@ -5,32 +5,34 @@ import (
 	"time"
 
 	"charm.land/lipgloss/v2"
+
+	"github.com/mark3labs/kit/internal/ui/style"
 )
 
-// Renderer is the interface satisfied by both MessageRenderer and
-// CompactRenderer. It allows model.go and cli.go to call rendering methods
-// without branching on compact mode.
+// Renderer is the interface satisfied by MessageRenderer. It allows model.go
+// and cli.go to call rendering methods uniformly.
 type Renderer interface {
 	RenderUserMessage(content string, timestamp time.Time) UIMessage
 	RenderAssistantMessage(content string, timestamp time.Time, modelName string) UIMessage
+	RenderReasoningBlock(content string, timestamp time.Time) UIMessage
 	RenderToolMessage(toolName, toolArgs, toolResult string, isError bool) UIMessage
 	RenderSystemMessage(content string, timestamp time.Time) UIMessage
 	RenderErrorMessage(errorMsg string, timestamp time.Time) UIMessage
 	RenderDebugMessage(message string, timestamp time.Time) UIMessage
 	RenderDebugConfigMessage(config map[string]any, timestamp time.Time) UIMessage
 	SetWidth(width int)
+	UpdateTheme()
 }
 
-// Compile-time checks that both renderers satisfy the Renderer interface.
+// Compile-time check that MessageRenderer satisfies the Renderer interface.
 var _ Renderer = (*MessageRenderer)(nil)
-var _ Renderer = (*CompactRenderer)(nil)
 
 // parseBashOutput parses <stdout>/<stderr> tagged output from bash tool
 // results, styling stderr with the theme's error color. Returns the
 // combined, styled output string with tags stripped.
 //
-// Shared by both MessageRenderer and CompactRenderer.
-func parseBashOutput(result string, theme Theme) string {
+// Shared by MessageRenderer.
+func parseBashOutput(result string, theme style.Theme) string {
 	var formattedResult strings.Builder
 	remaining := result
 

internal/ui/fuzzy.go

@@ -2,20 +2,22 @@ package ui
 
 import (
 	"strings"
+
+	"github.com/mark3labs/kit/internal/ui/commands"
 )
 
 // FuzzyMatch represents the result of a fuzzy string matching operation,
 // containing the matched command and its relevance score. Higher scores
 // indicate better matches.
 type FuzzyMatch struct {
-	Command *SlashCommand
+	Command *commands.SlashCommand
 	Score   int
 }
 
 // FuzzyMatchCommands performs fuzzy string matching on the provided slash commands
 // based on the query string. Returns a slice of matches sorted by relevance score
 // in descending order. An empty query returns all commands with zero scores.
-func FuzzyMatchCommands(query string, commands []SlashCommand) []FuzzyMatch {
+func FuzzyMatchCommands(query string, commands []commands.SlashCommand) []FuzzyMatch {
 	if query == "" || query == "/" {
 		// Return all commands when query is empty or just "/"
 		matches := make([]FuzzyMatch, len(commands))
@@ -57,7 +59,7 @@ func FuzzyMatchCommands(query string, commands []SlashCommand) []FuzzyMatch {
 }
 
 // fuzzyScore calculates the fuzzy match score for a command
-func fuzzyScore(query string, cmd *SlashCommand) int {
+func fuzzyScore(query string, cmd *commands.SlashCommand) int {
 	// Check exact match first
 	cmdName := strings.ToLower(strings.TrimPrefix(cmd.Name, "/"))
 	if cmdName == query {

internal/ui/input.go

@@ -10,6 +10,9 @@ import (
 	"charm.land/lipgloss/v2"
 
 	"github.com/mark3labs/kit/internal/clipboard"
+	"github.com/mark3labs/kit/internal/ui/commands"
+	"github.com/mark3labs/kit/internal/ui/core"
+	"github.com/mark3labs/kit/internal/ui/style"
 )
 
 // InputComponent is the interactive text input field for the parent AppModel.
@@ -29,7 +32,7 @@ import (
 // app.Run().
 type InputComponent struct {
 	textarea    textarea.Model
-	commands    []SlashCommand
+	commands    []commands.SlashCommand
 	showPopup   bool
 	filtered    []FuzzyMatch
 	selected    int
@@ -42,17 +45,17 @@ type InputComponent struct {
 	// Argument completion state. When the user types "/cmd " followed by
 	// a partial argument and the command has a Complete function, the popup
 	// switches to argument-completion mode showing suggestions from Complete.
-	argMode      bool           // true when showing arg completions
-	argCommand   string         // command prefix for arg mode (e.g. "/bookmark")
-	argSynthCmds []SlashCommand // backing storage for synthetic arg entries
+	argMode      bool                    // true when showing arg completions
+	argCommand   string                  // command prefix for arg mode (e.g. "/bookmark")
+	argSynthCmds []commands.SlashCommand // backing storage for synthetic arg entries
 
 	// File completion state. When the user types @ followed by a partial
 	// file path, the popup shows file/directory suggestions from the cwd.
-	fileMode        bool             // true when showing @file completions
-	filePrefix      string           // current text after @ being matched
-	fileAtStartIdx  int              // byte offset of @ in the textarea value
-	fileSuggestions []FileSuggestion // backing storage for file entries
-	fileSynthCmds   []SlashCommand   // synthetic SlashCommands wrapping file entries
+	fileMode        bool                    // true when showing @file completions
+	filePrefix      string                  // current text after @ being matched
+	fileAtStartIdx  int                     // byte offset of @ in the textarea value
+	fileSuggestions []FileSuggestion        // backing storage for file entries
+	fileSynthCmds   []commands.SlashCommand // synthetic commands.SlashCommands wrapping file entries
 
 	// cwd is the working directory used for @file path resolution and
 	// autocomplete suggestions. Set by the parent via SetCwd.
@@ -71,7 +74,7 @@ type InputComponent struct {
 
 	// pendingImages holds clipboard images attached to the next submission.
 	// Images are added via Ctrl+V and cleared on submit or Ctrl+U.
-	pendingImages []ImageAttachment
+	pendingImages []core.ImageAttachment
 
 	// history stores previously submitted prompts (most recent last).
 	// Limited to maxHistory entries; duplicates of the previous entry are
@@ -94,7 +97,7 @@ const maxHistory = 100
 
 // clipboardImageMsg is the result of an async clipboard image read.
 type clipboardImageMsg struct {
-	image *ImageAttachment
+	image *core.ImageAttachment
 	err   error
 }
 
@@ -119,7 +122,7 @@ func NewInputComponent(width int, title string, appCtrl AppController) *InputCom
 	)
 
 	// Style the textarea using theme colors.
-	theme := GetTheme()
+	theme := style.GetTheme()
 	styles := ta.Styles()
 	styles.Focused.Base = lipgloss.NewStyle()
 	styles.Focused.Placeholder = lipgloss.NewStyle().Foreground(theme.VeryMuted)
@@ -130,7 +133,7 @@ func NewInputComponent(width int, title string, appCtrl AppController) *InputCom
 
 	return &InputComponent{
 		textarea:    ta,
-		commands:    SlashCommands,
+		commands:    commands.SlashCommands,
 		width:       width,
 		popupHeight: 7,
 		title:       title,
@@ -329,7 +332,7 @@ func (s *InputComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 					s.filePrefix = prefix
 					s.fileAtStartIdx = atIdx
 					s.fileSuggestions = suggestions
-					s.fileSynthCmds = make([]SlashCommand, len(suggestions))
+					s.fileSynthCmds = make([]commands.SlashCommand, len(suggestions))
 					s.filtered = make([]FuzzyMatch, len(suggestions))
 					for i, fs := range suggestions {
 						name := fs.RelPath
@@ -337,7 +340,7 @@ func (s *InputComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 						if fs.IsDir {
 							desc = "directory"
 						}
-						s.fileSynthCmds[i] = SlashCommand{Name: name, Description: desc}
+						s.fileSynthCmds[i] = commands.SlashCommand{Name: name, Description: desc}
 						s.filtered[i] = FuzzyMatch{Command: &s.fileSynthCmds[i], Score: fs.Score}
 					}
 					s.selected = 0
@@ -396,14 +399,14 @@ func (s *InputComponent) handleSubmit(value string) tea.Cmd {
 		cmd := strings.TrimSpace(trimmed[2:])
 		if cmd != "" {
 			return func() tea.Msg {
-				return shellCommandMsg{Command: cmd, ExcludeFromContext: true}
+				return core.ShellCommandMsg{Command: cmd, ExcludeFromContext: true}
 			}
 		}
 	} else if strings.HasPrefix(trimmed, "!") {
 		cmd := strings.TrimSpace(trimmed[1:])
 		if cmd != "" {
 			return func() tea.Msg {
-				return shellCommandMsg{Command: cmd, ExcludeFromContext: false}
+				return core.ShellCommandMsg{Command: cmd, ExcludeFromContext: false}
 			}
 		}
 	}
@@ -411,9 +414,9 @@ func (s *InputComponent) handleSubmit(value string) tea.Cmd {
 	// Resolve via canonical command lookup so aliases are handled uniformly.
 	// Only /quit is handled locally — all other slash commands (including
 	// /clear and /clear-queue) are forwarded to the parent model via
-	// submitMsg so the parent can update its own state (scrollback, queue
+	// submitMsg so the parent can update its own state (ScrollList, queue
 	// counts, etc.) in one place.
-	if sc := GetCommandByName(trimmed); sc != nil {
+	if sc := commands.GetCommandByName(trimmed); sc != nil {
 		switch sc.Name {
 		case "/quit":
 			return tea.Quit
@@ -426,7 +429,7 @@ func (s *InputComponent) handleSubmit(value string) tea.Cmd {
 	images := s.pendingImages
 	s.pendingImages = nil
 	return func() tea.Msg {
-		return submitMsg{Text: trimmed, Images: images}
+		return core.SubmitMsg{Text: trimmed, Images: images}
 	}
 }
 
@@ -463,7 +466,7 @@ func (s *InputComponent) resetHistoryBrowsing() {
 func (s *InputComponent) View() tea.View {
 	containerStyle := lipgloss.NewStyle()
 
-	theme := GetTheme()
+	theme := style.GetTheme()
 
 	// PaddingLeft(3) aligns with message content: border(1) + paddingLeft(2).
 	titleStyle := lipgloss.NewStyle().
@@ -486,10 +489,8 @@ func (s *InputComponent) View() tea.View {
 	view.WriteString("\n")
 	view.WriteString(inputBoxStyle.Render(s.textarea.View()))
 
-	if s.showPopup && len(s.filtered) > 0 {
-		view.WriteString("\n")
-		view.WriteString(s.renderPopup())
-	}
+	// Popup is now rendered as a centered overlay in AppModel.View()
+	// instead of inline here to prevent bottom overflow
 
 	// Show image attachment indicator when images are pending.
 	if len(s.pendingImages) > 0 {
@@ -537,19 +538,62 @@ func (s *InputComponent) View() tea.View {
 }
 
 // renderPopup renders the autocomplete popup for slash command suggestions.
-func (s *InputComponent) renderPopup() string {
-	theme := GetTheme()
+// When rendered inline (not centered), returns the styled popup content.
+// RenderPopupCentered renders the popup as a centered overlay.
+func (s *InputComponent) RenderPopupCentered(termWidth, termHeight int) string {
+	if !s.showPopup || len(s.filtered) == 0 {
+		return ""
+	}
+
+	popupContent := s.renderPopupWithOptions(true)
+
+	// Center popup using lipgloss.Place
+	positioned := lipgloss.Place(
+		termWidth,
+		termHeight,
+		lipgloss.Center,
+		lipgloss.Center,
+		popupContent,
+	)
+
+	return positioned
+}
+
+// renderPopupWithOptions renders the popup content with optional center styling.
+func (s *InputComponent) renderPopupWithOptions(centered bool) string {
+	theme := style.GetTheme()
 	popupWidth := max(s.width-4, 20)
+
+	// Use the theme background for the popup - the full-width item backgrounds
+	// and primary-colored selection will provide sufficient contrast
+	popupBg := theme.Background
+
 	popupStyle := lipgloss.NewStyle().
 		Border(lipgloss.RoundedBorder()).
-		BorderForeground(theme.MutedBorder).
+		BorderForeground(theme.Primary).
+		Background(popupBg).
 		Padding(1, 2).
 		Width(popupWidth).
-		MarginLeft(0)
+		MarginLeft(0).
+		MarginBottom(1) // Visual depth/shadow effect
 
 	// Inner content width: popup minus border (2) and horizontal padding (4).
 	innerWidth := max(popupWidth-6, 10)
 
+	// Item background styles for high contrast
+	normalItemBg := lipgloss.NewStyle().
+		Background(popupBg).
+		Foreground(theme.Text).
+		Width(innerWidth).
+		Padding(0, 1)
+
+	selectedItemBg := lipgloss.NewStyle().
+		Background(theme.Primary).
+		Foreground(theme.Background).
+		Width(innerWidth).
+		Padding(0, 1).
+		Bold(true)
+
 	var items []string
 
 	visibleItems := min(len(s.filtered), s.popupHeight)
@@ -563,44 +607,45 @@ func (s *InputComponent) renderPopup() string {
 		match := s.filtered[i]
 		sc := match.Command
 
+		// Choose the appropriate background style
+		itemStyle := normalItemBg
+		if i == s.selected {
+			itemStyle = selectedItemBg
+		}
+
+		// Build indicator with proper coloring
 		var indicator string
 		if i == s.selected {
-			indicator = lipgloss.NewStyle().Foreground(theme.Primary).Render("> ")
+			indicator = "> "
 		} else {
 			indicator = "  "
 		}
 
-		nameStyle := lipgloss.NewStyle().Foreground(theme.Secondary).Bold(true)
-		descStyle := lipgloss.NewStyle().Foreground(theme.Muted)
-		if i == s.selected {
-			nameStyle = nameStyle.Foreground(theme.Primary)
-			descStyle = descStyle.Foreground(theme.Text)
-		}
-
+		// Build content with name and description
+		var content string
 		if s.fileMode {
-			// File mode: use full width for the path, show description
-			// (e.g. "directory") inline after a gap.
+			// File mode: use full width for the path, show description inline
 			maxNameLen := max(innerWidth-16, 8)
 			displayName := sc.Name
 			if len(displayName) > maxNameLen && maxNameLen > 3 {
 				displayName = displayName[:maxNameLen-3] + "..."
 			}
-			name := nameStyle.Render(displayName)
+
 			if sc.Description != "" && innerWidth > 30 {
-				items = append(items, indicator+name+"  "+descStyle.Render(sc.Description))
+				content = indicator + displayName + "  " + sc.Description
 			} else {
-				items = append(items, indicator+name)
+				content = indicator + displayName
 			}
 		} else {
-			// Line layout: indicator(2) + name(nameWidth-2 visual) + desc.
+			// Line layout: indicator(2) + name(nameWidth-2 visual) + desc
 			if innerWidth < 20 {
-				// Very narrow: show truncated name only, no fixed column.
+				// Very narrow: show truncated name only
 				displayName := sc.Name
 				maxName := max(innerWidth-2, 3)
 				if len(displayName) > maxName {
 					displayName = displayName[:maxName-1] + "…"
 				}
-				items = append(items, indicator+nameStyle.Render(displayName))
+				content = indicator + displayName
 			} else {
 				nameWidth := 15
 				if innerWidth < 25 {
@@ -611,33 +656,41 @@ func (s *InputComponent) renderPopup() string {
 				if len(displayName) > maxNameChars {
 					displayName = displayName[:maxNameChars-1] + "…"
 				}
-				name := nameStyle.Width(maxNameChars).Render(displayName)
 
-				// Description gets remaining space.
+				// Description gets remaining space
 				maxDescLen := max(innerWidth-nameWidth, 0)
 				desc := sc.Description
-				if maxDescLen < 4 {
-					items = append(items, indicator+name)
-				} else {
+				if maxDescLen >= 4 && desc != "" {
 					if len(desc) > maxDescLen {
 						desc = desc[:maxDescLen-3] + "..."
 					}
-					items = append(items, indicator+name+descStyle.Render(desc))
+					content = indicator + lipgloss.NewStyle().Width(maxNameChars).Render(displayName) + desc
+				} else {
+					content = indicator + displayName
 				}
 			}
 		}
+
+		items = append(items, itemStyle.Render(content))
 	}
 
+	// Add scroll indicators with background
+	scrollStyle := lipgloss.NewStyle().
+		Background(popupBg).
+		Foreground(theme.VeryMuted).
+		Width(innerWidth).
+		Padding(0, 1)
+
 	if startIdx > 0 {
-		items = append([]string{lipgloss.NewStyle().Foreground(theme.VeryMuted).Render("  ↑ more above")}, items...)
+		items = append([]string{scrollStyle.Render("  ↑ more above")}, items...)
 	}
 	if endIdx < len(s.filtered) {
-		items = append(items, lipgloss.NewStyle().Foreground(theme.VeryMuted).Render("  ↓ more below"))
+		items = append(items, scrollStyle.Render("  ↓ more below"))
 	}
 
 	content := strings.Join(items, "\n")
 
-	// Adapt footer text to available width.
+	// Adapt footer text to available width with background
 	var footerText string
 	if innerWidth >= 50 {
 		footerText = "↑↓ navigate • tab complete • ↵ select • esc dismiss"
@@ -646,7 +699,10 @@ func (s *InputComponent) renderPopup() string {
 	} else {
 		footerText = "↑↓ tab ↵ esc"
 	}
-	footer := lipgloss.NewStyle().Foreground(theme.VeryMuted).Italic(true).
+	footer := lipgloss.NewStyle().
+		Background(popupBg).
+		Foreground(theme.VeryMuted).
+		Italic(true).
 		Render(footerText)
 
 	return popupStyle.Render(content + "\n\n" + footer)
@@ -676,10 +732,10 @@ func (s *InputComponent) completeArgs(line string) []FuzzyMatch {
 
 	s.argMode = true
 	s.argCommand = cmdName
-	s.argSynthCmds = make([]SlashCommand, len(suggestions))
+	s.argSynthCmds = make([]commands.SlashCommand, len(suggestions))
 	s.filtered = make([]FuzzyMatch, len(suggestions))
 	for i, sug := range suggestions {
-		s.argSynthCmds[i] = SlashCommand{Name: sug}
+		s.argSynthCmds[i] = commands.SlashCommand{Name: sug}
 		s.filtered[i] = FuzzyMatch{Command: &s.argSynthCmds[i]}
 	}
 	return s.filtered
@@ -687,7 +743,7 @@ func (s *InputComponent) completeArgs(line string) []FuzzyMatch {
 
 // findCommandWithComplete looks up a command by name that has a non-nil
 // Complete function.
-func (s *InputComponent) findCommandWithComplete(name string) *SlashCommand {
+func (s *InputComponent) findCommandWithComplete(name string) *commands.SlashCommand {
 	for i := range s.commands {
 		if s.commands[i].Name == name && s.commands[i].Complete != nil {
 			return &s.commands[i]
@@ -705,7 +761,7 @@ func readClipboardImageCmd() tea.Cmd {
 			return clipboardImageMsg{err: err}
 		}
 		return clipboardImageMsg{
-			image: &ImageAttachment{
+			image: &core.ImageAttachment{
 				Data:      img.Data,
 				MediaType: img.MediaType,
 			},
@@ -715,7 +771,7 @@ func readClipboardImageCmd() tea.Cmd {
 
 // ClearPendingImages removes all pending image attachments and returns them.
 // Used by the parent model when consuming images for submission.
-func (s *InputComponent) ClearPendingImages() []ImageAttachment {
+func (s *InputComponent) ClearPendingImages() []core.ImageAttachment {
 	images := s.pendingImages
 	s.pendingImages = nil
 	return images

internal/ui/message_items.go

@@ -0,0 +1,381 @@
+package ui
+
+import (
+	"fmt"
+	"strings"
+	"time"
+
+	"charm.land/lipgloss/v2"
+
+	"github.com/mark3labs/kit/internal/ui/render"
+	"github.com/mark3labs/kit/internal/ui/style"
+)
+
+// --------------------------------------------------------------------------
+// MessageItem implementations for ScrollList
+// --------------------------------------------------------------------------
+
+// TextMessageItem represents a completed text message (user or assistant)
+// in the scrollback. It uses pre-rendered styled content from MessageRenderer.
+type TextMessageItem struct {
+	id          string
+	role        string // "user" or "assistant"
+	content     string // Raw content (for re-rendering if needed)
+	preRendered string // Pre-rendered styled content from MessageRenderer
+	timestamp   time.Time
+}
+
+// NewTextMessageItem creates a new text message for the scrollback.
+// The content should be pre-rendered using MessageRenderer for proper styling.
+func NewTextMessageItem(id string, role string, content string) *TextMessageItem {
+	return &TextMessageItem{
+		id:        id,
+		role:      role,
+		content:   content,
+		timestamp: time.Now(),
+	}
+}
+
+// NewStyledMessageItem creates a message item with pre-rendered styled content.
+// This is the preferred way to create messages when you have styled content from MessageRenderer.
+func NewStyledMessageItem(id string, role string, rawContent string, preRendered string) *TextMessageItem {
+	return &TextMessageItem{
+		id:          id,
+		role:        role,
+		content:     rawContent,
+		preRendered: preRendered,
+		timestamp:   time.Now(),
+	}
+}
+
+func (m *TextMessageItem) ID() string {
+	return m.id
+}
+
+func (m *TextMessageItem) Render(width int) string {
+	// If we have pre-rendered styled content, return it
+	if m.preRendered != "" {
+		return m.preRendered
+	}
+
+	// Fallback to simple formatting if no pre-rendered content
+	return m.renderContent(width)
+}
+
+func (m *TextMessageItem) Height() int {
+	rendered := m.Render(0) // Width doesn't matter since we use pre-rendered
+	if rendered == "" {
+		return 0
+	}
+	return strings.Count(rendered, "\n") + 1
+}
+
+func (m *TextMessageItem) renderContent(width int) string {
+	var parts []string
+
+	// Role indicator
+	if m.role == "user" {
+		parts = append(parts, "│ ▸ You")
+	} else {
+		parts = append(parts, "") // Assistant messages start without role
+	}
+
+	// Content with simple wrapping
+	contentWidth := max(width-4, 20)
+
+	for line := range strings.SplitSeq(m.content, "\n") {
+		if len(line) <= contentWidth {
+			parts = append(parts, "│ "+line)
+		} else {
+			// Basic wrap
+			for len(line) > contentWidth {
+				parts = append(parts, "│ "+line[:contentWidth])
+				line = line[contentWidth:]
+			}
+			if len(line) > 0 {
+				parts = append(parts, "│ "+line)
+			}
+		}
+	}
+
+	return strings.Join(parts, "\n")
+}
+
+// --------------------------------------------------------------------------
+// StreamingMessageItem - Live streaming assistant/reasoning text
+// --------------------------------------------------------------------------
+
+// StreamingMessageItem represents actively streaming assistant or reasoning text.
+// It accumulates content chunks and re-renders on each update for live display.
+type StreamingMessageItem struct {
+	id            string
+	role          string // "assistant" or "reasoning"
+	content       string // Accumulated streaming content
+	timestamp     time.Time
+	startTime     time.Time // When streaming started (for live duration counter)
+	modelName     string
+	streaming     bool          // true while actively streaming
+	finalDuration time.Duration // Frozen duration when complete
+	cachedRender  string
+	cachedWidth   int
+}
+
+// NewStreamingMessageItem creates a new streaming message item.
+func NewStreamingMessageItem(id, role string, modelName string) *StreamingMessageItem {
+	now := time.Now()
+	return &StreamingMessageItem{
+		id:        id,
+		role:      role,
+		timestamp: now,
+		startTime: now,
+		modelName: modelName,
+		streaming: true,
+	}
+}
+
+// ID returns the unique identifier.
+func (s *StreamingMessageItem) ID() string {
+	return s.id
+}
+
+// Render renders the streaming message with live content.
+func (s *StreamingMessageItem) Render(width int) string {
+	// For reasoning, never cache - we need live duration updates
+	// For assistant, cache is OK
+	if s.role != "reasoning" && s.cachedWidth == width && s.cachedRender != "" {
+		return s.cachedRender
+	}
+
+	var rendered string
+	if s.role == "reasoning" {
+		// Calculate duration in milliseconds for render.ReasoningBlock
+		var durationMs int64
+		if s.finalDuration > 0 {
+			durationMs = s.finalDuration.Milliseconds()
+		} else if !s.startTime.IsZero() {
+			durationMs = time.Since(s.startTime).Milliseconds()
+		}
+		ty := createTypography(style.GetTheme())
+		rendered = render.ReasoningBlock(s.content, durationMs, ty, style.GetTheme())
+	} else {
+		// Render as assistant message
+		rendered = render.AssistantBlock(s.content, width, style.GetTheme())
+	}
+
+	// Cache and return (but reasoning is never cached due to live duration)
+	if s.role != "reasoning" {
+		s.cachedRender = rendered
+		s.cachedWidth = width
+	}
+	return rendered
+}
+
+// Height returns the number of lines.
+func (s *StreamingMessageItem) Height() int {
+	// For reasoning blocks, cachedRender is never populated (rendering is
+	// width-independent and includes a live timer). Fall back to Render(0)
+	// so callers always get the correct height.
+	rendered := s.cachedRender
+	if rendered == "" {
+		rendered = s.Render(0)
+	}
+	if rendered == "" {
+		return 0
+	}
+	return strings.Count(rendered, "\n") + 1
+}
+
+// AppendChunk adds a content chunk and invalidates the render cache.
+func (s *StreamingMessageItem) AppendChunk(chunk string) {
+	s.content += chunk
+	s.cachedWidth = 0 // Invalidate cache
+}
+
+// MarkComplete marks the streaming message as complete and freezes the duration.
+func (s *StreamingMessageItem) MarkComplete() {
+	s.streaming = false
+	// Freeze the duration for reasoning blocks
+	if s.role == "reasoning" && !s.startTime.IsZero() {
+		s.finalDuration = time.Since(s.startTime)
+	}
+}
+
+// --------------------------------------------------------------------------
+// StreamingBashOutputItem - Live bash command output
+// --------------------------------------------------------------------------
+
+// StreamingBashOutputItem represents live bash command output.
+type StreamingBashOutputItem struct {
+	id           string
+	command      string
+	stdoutLines  []string
+	stderrLines  []string
+	maxLines     int
+	complete     bool
+	cachedRender string
+	cachedWidth  int
+}
+
+// NewStreamingBashOutputItem creates a new streaming bash output item.
+func NewStreamingBashOutputItem(id string, command string) *StreamingBashOutputItem {
+	return &StreamingBashOutputItem{
+		id:          id,
+		command:     command,
+		stdoutLines: make([]string, 0),
+		stderrLines: make([]string, 0),
+		maxLines:    100, // Cap lines to prevent memory issues
+		complete:    false,
+	}
+}
+
+func (m *StreamingBashOutputItem) ID() string {
+	return m.id
+}
+
+func (m *StreamingBashOutputItem) Render(width int) string {
+	// Return cached if width matches and complete
+	if m.complete && m.cachedWidth == width && m.cachedRender != "" {
+		return m.cachedRender
+	}
+
+	theme := style.GetTheme()
+	var parts []string
+
+	// Header with command
+	if m.command != "" {
+		headerStyle := lipgloss.NewStyle().
+			Foreground(theme.Muted).
+			Italic(true)
+		parts = append(parts, headerStyle.Render(fmt.Sprintf("▸ %s", m.command)))
+	}
+
+	const lineIndent = "  "
+	lineWidth := width - len(lineIndent)
+
+	// Stdout lines
+	if len(m.stdoutLines) > 0 {
+		outputStyle := lipgloss.NewStyle().
+			Foreground(theme.Text).
+			Background(theme.CodeBg).
+			PaddingLeft(1).
+			Width(lineWidth)
+		for _, line := range m.stdoutLines {
+			parts = append(parts, lineIndent+outputStyle.Render(line))
+		}
+	}
+
+	// Stderr lines
+	if len(m.stderrLines) > 0 {
+		stderrStyle := lipgloss.NewStyle().
+			Foreground(theme.Error).
+			Background(theme.CodeBg).
+			PaddingLeft(1).
+			Width(lineWidth)
+		for _, line := range m.stderrLines {
+			parts = append(parts, lineIndent+stderrStyle.Render(line))
+		}
+	}
+
+	result := strings.Join(parts, "\n")
+	if m.complete {
+		m.cachedRender = result
+		m.cachedWidth = width
+	}
+	return result
+}
+
+func (m *StreamingBashOutputItem) Height() int {
+	if m.cachedRender != "" {
+		return strings.Count(m.cachedRender, "\n") + 1
+	}
+	// Estimate: command header + stdout + stderr
+	return 1 + len(m.stdoutLines) + len(m.stderrLines)
+}
+
+// AppendStdout adds a stdout line to the output.
+func (m *StreamingBashOutputItem) AppendStdout(line string) {
+	m.stdoutLines = append(m.stdoutLines, line)
+	// Cap lines
+	if len(m.stdoutLines) > m.maxLines {
+		m.stdoutLines = m.stdoutLines[len(m.stdoutLines)-m.maxLines:]
+	}
+	m.cachedWidth = 0 // Invalidate cache
+}
+
+// AppendStderr adds a stderr line to the output.
+func (m *StreamingBashOutputItem) AppendStderr(line string) {
+	m.stderrLines = append(m.stderrLines, line)
+	// Cap lines
+	if len(m.stderrLines) > m.maxLines {
+		m.stderrLines = m.stderrLines[len(m.stderrLines)-m.maxLines:]
+	}
+	m.cachedWidth = 0 // Invalidate cache
+}
+
+// MarkComplete marks the bash output as complete.
+func (m *StreamingBashOutputItem) MarkComplete() {
+	m.complete = true
+}
+
+// --------------------------------------------------------------------------
+// SystemMessageItem - System messages (commands, info, errors)
+// --------------------------------------------------------------------------
+
+// SystemMessageItem represents a system message (commands, info, errors).
+type SystemMessageItem struct {
+	id           string
+	content      string
+	timestamp    time.Time
+	cachedRender string
+	cachedWidth  int
+}
+
+// NewSystemMessageItem creates a new system message for the scrollback.
+func NewSystemMessageItem(id, content string) *SystemMessageItem {
+	return &SystemMessageItem{
+		id:        id,
+		content:   content,
+		timestamp: time.Now(),
+	}
+}
+
+func (m *SystemMessageItem) ID() string {
+	return m.id
+}
+
+func (m *SystemMessageItem) Render(width int) string {
+	// Return cached render if width matches
+	if m.cachedWidth == width && m.cachedRender != "" {
+		return m.cachedRender
+	}
+
+	// Simple system message formatting
+	rendered := "│ " + strings.ReplaceAll(m.content, "\n", "\n│ ")
+
+	// Cache and return
+	m.cachedRender = rendered
+	m.cachedWidth = width
+	return rendered
+}
+
+func (m *SystemMessageItem) Height() int {
+	if m.cachedRender != "" {
+		return strings.Count(m.cachedRender, "\n") + 1
+	}
+	// Estimate
+	if m.cachedWidth > 0 {
+		return (len(m.content) / max(m.cachedWidth-10, 40)) + 3
+	}
+	return 3
+}
+
+// --------------------------------------------------------------------------
+// Helper: generateMessageID
+// --------------------------------------------------------------------------
+
+var messageCounter = 0
+
+func generateMessageID() string {
+	messageCounter++
+	return fmt.Sprintf("msg-%d-%d", time.Now().UnixNano(), messageCounter)
+}

internal/ui/messages.go

@@ -3,17 +3,16 @@ package ui
 import (
 	"encoding/json"
 	"fmt"
-	"regexp"
 	"sort"
 	"strings"
 	"time"
 
 	"charm.land/lipgloss/v2"
 	"github.com/indaco/herald"
-)
 
-// ansiEscapeRe matches ANSI escape sequences used for terminal styling.
-var ansiEscapeRe = regexp.MustCompile(`\x1b\[[0-9;]*m`)
+	"github.com/mark3labs/kit/internal/ui/render"
+	"github.com/mark3labs/kit/internal/ui/style"
+)
 
 // MessageType represents different categories of messages displayed in the UI,
 // each with distinct visual styling and formatting rules.
@@ -142,7 +141,7 @@ func newMessageRenderer(width int, debug bool) *MessageRenderer {
 	return &MessageRenderer{
 		width: width,
 		debug: debug,
-		ty:    createTypography(GetTheme()),
+		ty:    createTypography(style.GetTheme()),
 	}
 }
 
@@ -153,12 +152,7 @@ func (r *MessageRenderer) SetWidth(width int) {
 
 // RenderUserMessage renders a user's input message using herald Tip alert
 func (r *MessageRenderer) RenderUserMessage(content string, timestamp time.Time) UIMessage {
-	if strings.TrimSpace(content) == "" {
-		content = "(empty message)"
-	}
-
-	rendered := r.ty.Tip(content)
-	rendered = styleMarginBottom1.Render(rendered)
+	rendered := render.UserBlock(content, r.ty, style.GetTheme())
 
 	return UIMessage{
 		Type:      UserMessage,
@@ -170,18 +164,21 @@ func (r *MessageRenderer) RenderUserMessage(content string, timestamp time.Time)
 
 // RenderAssistantMessage renders an AI assistant's response
 func (r *MessageRenderer) RenderAssistantMessage(content string, timestamp time.Time, modelName string) UIMessage {
-	if strings.TrimSpace(content) == "" {
-		return UIMessage{
-			Type:      AssistantMessage,
-			Content:   "",
-			Height:    0,
-			Timestamp: timestamp,
-		}
-	}
+	rendered := render.AssistantBlock(content, r.width, style.GetTheme())
 
-	// Use markdown rendering with Chroma syntax highlighting
-	rendered := toMarkdown(content, r.width-4)
-	rendered = styleMarginBottom1.Render(rendered)
+	return UIMessage{
+		Type:      AssistantMessage,
+		Content:   rendered,
+		Height:    lipgloss.Height(rendered),
+		Timestamp: timestamp,
+	}
+}
+
+// RenderReasoningBlock renders a reasoning/thinking block with the same styling
+// as live streaming: muted italic text with margin. This is used when resuming
+// sessions to display saved reasoning content.
+func (r *MessageRenderer) RenderReasoningBlock(content string, timestamp time.Time) UIMessage {
+	rendered := render.ReasoningBlock(content, 0, r.ty, style.GetTheme())
 
 	return UIMessage{
 		Type:      AssistantMessage,
@@ -193,12 +190,7 @@ func (r *MessageRenderer) RenderAssistantMessage(content string, timestamp time.
 
 // RenderSystemMessage renders KIT system messages using herald Note alert
 func (r *MessageRenderer) RenderSystemMessage(content string, timestamp time.Time) UIMessage {
-	if strings.TrimSpace(content) == "" {
-		content = "No content available"
-	}
-
-	rendered := r.ty.Note(content)
-	rendered = styleMarginBottom1.Render(rendered)
+	rendered := render.SystemBlock(content, r.ty, style.GetTheme())
 
 	return UIMessage{
 		Type:      SystemMessage,
@@ -264,8 +256,7 @@ func (r *MessageRenderer) RenderDebugConfigMessage(config map[string]any, timest
 
 // RenderErrorMessage renders error notifications
 func (r *MessageRenderer) RenderErrorMessage(errorMsg string, timestamp time.Time) UIMessage {
-	rendered := r.ty.Caution(errorMsg)
-	rendered = styleMarginBottom1.Render(rendered)
+	rendered := render.ErrorBlock(errorMsg, r.ty, style.GetTheme())
 
 	return UIMessage{
 		Type:      ErrorMessage,
@@ -297,16 +288,16 @@ func (r *MessageRenderer) RenderToolMessage(toolName, toolArgs, toolResult strin
 	}
 
 	var icon string
-	iconColor := GetTheme().Success
+	iconColor := style.GetTheme().Success
 	if isError {
 		icon = "×"
-		iconColor = GetTheme().Error
+		iconColor = style.GetTheme().Error
 	} else {
 		icon = "✓"
 	}
 
 	// Style the tool name with color
-	theme := GetTheme()
+	theme := style.GetTheme()
 	nameColor := theme.Info
 	if isError {
 		nameColor = theme.Error
@@ -325,7 +316,7 @@ func (r *MessageRenderer) RenderToolMessage(toolName, toolArgs, toolResult strin
 	if extRd != nil && extRd.RenderBody != nil {
 		body = extRd.RenderBody(toolResult, isError, r.width-8)
 		if body != "" && extRd.BodyMarkdown {
-			body = strings.TrimSuffix(toMarkdown(body, r.width-8), "\n")
+			body = strings.TrimSuffix(style.ToMarkdown(body, r.width-8), "\n")
 		}
 	}
 	if body == "" {
@@ -371,7 +362,7 @@ func (r *MessageRenderer) formatToolResult(toolName, result string) string {
 	if strings.Contains(toolName, "bash") || strings.Contains(toolName, "command") ||
 		strings.Contains(toolName, "shell") {
 		if strings.Contains(result, "<stdout>") || strings.Contains(result, "<stderr>") {
-			return parseBashOutput(result, GetTheme())
+			return parseBashOutput(result, style.GetTheme())
 		}
 	}
 
@@ -379,7 +370,7 @@ func (r *MessageRenderer) formatToolResult(toolName, result string) string {
 }
 
 // createTypography creates a typography instance from theme
-func createTypography(theme Theme) *herald.Typography {
+func createTypography(theme style.Theme) *herald.Typography {
 	return herald.New(
 		herald.WithPalette(herald.ColorPalette{
 			Primary:   theme.Primary,
@@ -408,14 +399,8 @@ func createTypography(theme Theme) *herald.Typography {
 	)
 }
 
-// removeBlankLines removes lines that are visually blank from rendered output.
-func removeBlankLines(s string) string {
-	lines := strings.Split(s, "\n")
-	filtered := lines[:0]
-	for _, line := range lines {
-		if strings.TrimSpace(ansiEscapeRe.ReplaceAllString(line, "")) != "" {
-			filtered = append(filtered, line)
-		}
-	}
-	return strings.Join(filtered, "\n")
+// UpdateTheme refreshes the renderer's typography instance with colors from
+// the current theme. This is called when the user changes themes via /theme.
+func (r *MessageRenderer) UpdateTheme() {
+	r.ty = createTypography(style.GetTheme())
 }

internal/ui/model_selector.go

@@ -10,6 +10,7 @@ import (
 	"charm.land/lipgloss/v2"
 
 	"github.com/mark3labs/kit/internal/models"
+	"github.com/mark3labs/kit/internal/ui/style"
 )
 
 // ModelEntry holds display metadata for a single model in the selector.
@@ -115,12 +116,12 @@ func (ms *ModelSelectorComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 
 	case tea.KeyPressMsg:
 		switch {
-		case key.Matches(msg, key.NewBinding(key.WithKeys("up", "k"))):
+		case key.Matches(msg, key.NewBinding(key.WithKeys("up"))):
 			if ms.cursor > 0 {
 				ms.cursor--
 			}
 
-		case key.Matches(msg, key.NewBinding(key.WithKeys("down", "j"))):
+		case key.Matches(msg, key.NewBinding(key.WithKeys("down"))):
 			if ms.cursor < len(ms.filtered)-1 {
 				ms.cursor++
 			}
@@ -188,7 +189,7 @@ func (ms *ModelSelectorComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 
 // View implements tea.Model.
 func (ms *ModelSelectorComponent) View() tea.View {
-	theme := GetTheme()
+	theme := style.GetTheme()
 
 	headerStyle := lipgloss.NewStyle().
 		Bold(true).
@@ -281,7 +282,9 @@ func (ms *ModelSelectorComponent) View() tea.View {
 	footerStyle := lipgloss.NewStyle().Foreground(theme.Muted).PaddingLeft(2)
 	b.WriteString(footerStyle.Render(strings.Join(footerParts, "  ")))
 
-	return tea.NewView(b.String())
+	v := tea.NewView(b.String())
+	v.AltScreen = true
+	return v
 }
 
 // IsActive returns whether the selector is still accepting input.
@@ -393,7 +396,7 @@ func (ms *ModelSelectorComponent) fuzzyScoreModel(query string, entry ModelEntry
 }
 
 func (ms *ModelSelectorComponent) renderEntry(entry ModelEntry, isCursor bool) string {
-	theme := GetTheme()
+	theme := style.GetTheme()
 	modelStr := entry.ModelID
 	providerStr := fmt.Sprintf("[%s]", entry.Provider)
 

internal/ui/model_test.go

@@ -5,9 +5,10 @@ import (
 	"testing"
 
 	tea "charm.land/bubbletea/v2"
-	"charm.land/fantasy"
 	"github.com/mark3labs/kit/internal/app"
 	"github.com/mark3labs/kit/internal/session"
+	"github.com/mark3labs/kit/internal/ui/core"
+	kit "github.com/mark3labs/kit/pkg/kit"
 )
 
 // --------------------------------------------------------------------------
@@ -70,7 +71,7 @@ func (s *stubAppController) AddContextMessage(_ string) {
 	// no-op in tests
 }
 
-func (s *stubAppController) RunWithFiles(prompt string, _ []fantasy.FilePart) int {
+func (s *stubAppController) RunWithFiles(prompt string, _ []kit.LLMFilePart) int {
 	s.runCalls = append(s.runCalls, prompt)
 	return s.queueLen
 }
@@ -87,7 +88,6 @@ func (s *stubAppController) Steer(prompt string) int {
 // stubStreamComponent satisfies streamComponentIface without rendering anything.
 type stubStreamComponent struct {
 	resetCalled     int
-	height          int
 	lastMsg         tea.Msg
 	renderedContent string // returned by GetRenderedContent
 }
@@ -99,11 +99,11 @@ func (s *stubStreamComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 }
 func (s *stubStreamComponent) View() tea.View             { return tea.NewView("") }
 func (s *stubStreamComponent) Reset()                     { s.resetCalled++; s.renderedContent = "" }
-func (s *stubStreamComponent) SetHeight(h int)            { s.height = h }
 func (s *stubStreamComponent) GetRenderedContent() string { return s.renderedContent }
 func (s *stubStreamComponent) SpinnerView() string        { return "" }
 func (s *stubStreamComponent) SetThinkingVisible(bool)    {}
 func (s *stubStreamComponent) HasReasoning() bool         { return false }
+func (s *stubStreamComponent) UpdateTheme()               {}
 
 // stubInputComponent satisfies inputComponentIface without rendering anything.
 type stubInputComponent struct {
@@ -130,11 +130,12 @@ func newTestAppModel(ctrl AppController) (*AppModel, *stubStreamComponent, *stub
 		stream:                stream,
 		input:                 input,
 		renderer:              newMessageRenderer(80, false),
-		compactMode:           false,
 		modelName:             "test-model",
 		width:                 80,
 		height:                24,
 		streamingBashMaxLines: 50, // Initialize buffer cap like NewAppModel does
+		scrollList:            NewScrollList(80, 20),
+		messages:              []MessageItem{},
 	}
 	return m, stream, input
 }
@@ -167,7 +168,7 @@ func TestStateTransition_InputToWorking(t *testing.T) {
 		t.Fatalf("expected stateInput, got %v", m.state)
 	}
 
-	m = sendMsg(m, submitMsg{Text: "hello"})
+	m = sendMsg(m, core.SubmitMsg{Text: "hello"})
 
 	if m.state != stateWorking {
 		t.Fatalf("expected stateWorking after submitMsg, got %v", m.state)
@@ -355,7 +356,7 @@ func TestESCCancel_timerExpiry(t *testing.T) {
 	m.state = stateWorking
 	m.canceling = true
 
-	m = sendMsg(m, cancelTimerExpiredMsg{})
+	m = sendMsg(m, core.CancelTimerExpiredMsg{})
 
 	if m.canceling {
 		t.Fatal("expected canceling=false after timer expiry")
@@ -408,7 +409,7 @@ func TestQueuedMessages_storedOnQueuedSubmit(t *testing.T) {
 	m, _, _ := newTestAppModel(ctrl)
 	m.state = stateWorking
 
-	_, cmd := m.Update(submitMsg{Text: "queued prompt"})
+	_, cmd := m.Update(core.SubmitMsg{Text: "queued prompt"})
 
 	if len(m.queuedMessages) != 1 {
 		t.Fatalf("expected 1 queued message, got %d", len(m.queuedMessages))
@@ -416,7 +417,7 @@ func TestQueuedMessages_storedOnQueuedSubmit(t *testing.T) {
 	if m.queuedMessages[0] != "queued prompt" {
 		t.Fatalf("expected queued message text 'queued prompt', got %q", m.queuedMessages[0])
 	}
-	// Should NOT produce a tea.Println cmd (message is anchored, not in scrollback).
+	// Should NOT flush (message is anchored in ScrollList).
 	if cmd != nil {
 		t.Fatal("expected nil cmd for queued submit (message should not print to scrollback)")
 	}
@@ -506,19 +507,19 @@ func TestWindowResize_propagatesToStream(t *testing.T) {
 // sets the stream height after a resize.
 func TestWindowResize_distributeHeight(t *testing.T) {
 	ctrl := &stubAppController{}
-	m, stream, _ := newTestAppModel(ctrl)
+	m, _, _ := newTestAppModel(ctrl)
 
-	// With height=30, stream height = 30 - 1 (separator) - 9 (input) - 1 (statusBar) = 19
+	// With height=30, scroll height = 30 - 1 (separator) - 9 (input) - 1 (statusBar) = 19
 	m = sendMsg(m, tea.WindowSizeMsg{Width: 80, Height: 30})
 	_ = m
 
-	if stream.height != 19 {
-		t.Fatalf("expected stream height=19, got %d", stream.height)
+	if m.scrollList.height != 19 {
+		t.Fatalf("expected scroll list height=19, got %d", m.scrollList.height)
 	}
 }
 
 // --------------------------------------------------------------------------
-// tea.Println on step complete
+// Step complete behavior
 // --------------------------------------------------------------------------
 
 // TestStepComplete_preservesStreamContent verifies that StepCompleteEvent
@@ -551,65 +552,87 @@ func TestStepComplete_noStreamContent_noCmd(t *testing.T) {
 	}
 }
 
-// TestSubmitMsg_printsUserMessage verifies that submitMsg produces a tea.Println
-// cmd for the user message.
+// TestSubmitMsg_printsUserMessage verifies that submitMsg adds the user message
+// to the ScrollList messages and triggers a layout update.
 func TestSubmitMsg_printsUserMessage(t *testing.T) {
 	ctrl := &stubAppController{}
 	m, _, _ := newTestAppModel(ctrl)
 
-	_, cmd := m.Update(submitMsg{Text: "user query"})
+	m = sendMsg(m, core.SubmitMsg{Text: "user query"})
 
-	if cmd == nil {
-		t.Fatal("expected non-nil cmd (tea.Println) for user message on submitMsg")
+	// In alt screen mode, user messages are added to the in-memory ScrollList
+	// rather than printed separately. Verify the message was added.
+	found := false
+	for _, msg := range m.messages {
+		if tm, ok := msg.(*TextMessageItem); ok && tm.role == "user" && tm.content == "user query" {
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Fatal("expected user message 'user query' in ScrollList messages")
 	}
 }
 
-// TestToolCallStarted_flushesOnly verifies that ToolCallStartedEvent flushes
-// accumulated stream content but does NOT print a tool call block (the unified
-// block is printed later on ToolResultEvent).
+// TestToolCallStarted_flushesOnly verifies that ToolCallStartedEvent marks
+// any active StreamingMessageItem as complete and resets the stream.
 func TestToolCallStarted_flushesOnly(t *testing.T) {
 	ctrl := &stubAppController{}
 	m, stream, _ := newTestAppModel(ctrl)
 	m.state = stateWorking
 
-	// With no stream content, flush returns nil → cmd should be nil.
-	_, cmd := m.Update(app.ToolCallStartedEvent{
+	// With no stream content, nothing should change.
+	initialCount := len(m.messages)
+	m = sendMsg(m, app.ToolCallStartedEvent{
 		ToolName: "bash",
 		ToolArgs: `{"cmd":"ls"}`,
 	})
 
-	if cmd != nil {
-		t.Fatal("expected nil cmd on ToolCallStartedEvent with no stream content")
+	if len(m.messages) != initialCount {
+		t.Fatal("expected no new messages on ToolCallStartedEvent with no stream content")
 	}
 
-	// With stream content, flush returns tea.Println → cmd should be non-nil.
+	// Simulate a StreamingMessageItem already in messages (as if appendStreamingChunk was called)
+	// plus the stream component having rendered content.
+	streamItem := NewStreamingMessageItem("stream-1", "assistant", "test-model")
+	streamItem.AppendChunk("partial text")
+	m.messages = append(m.messages, streamItem)
 	stream.renderedContent = "partial text"
-	_, cmd = m.Update(app.ToolCallStartedEvent{
+
+	_ = sendMsg(m, app.ToolCallStartedEvent{
 		ToolName: "bash",
 		ToolArgs: `{"cmd":"ls"}`,
 	})
 
-	if cmd == nil {
-		t.Fatal("expected non-nil cmd on ToolCallStartedEvent with stream content to flush")
+	// The StreamingMessageItem should have been marked complete.
+	if streamItem.streaming {
+		t.Fatal("expected StreamingMessageItem to be marked complete after ToolCallStartedEvent")
+	}
+	// Stream should have been reset.
+	if stream.resetCalled == 0 {
+		t.Fatal("expected stream.Reset() to be called")
 	}
 }
 
-// TestToolResult_printsAndStartsSpinner verifies that ToolResultEvent produces
-// a non-nil cmd and the stream receives a SpinnerEvent.
+// TestToolResult_printsAndStartsSpinner verifies that ToolResultEvent adds
+// the tool result to the ScrollList and the stream receives a SpinnerEvent.
 func TestToolResult_printsAndStartsSpinner(t *testing.T) {
 	ctrl := &stubAppController{}
 	m, stream, _ := newTestAppModel(ctrl)
 	m.state = stateWorking
 
-	_, cmd := m.Update(app.ToolResultEvent{
+	initialCount := len(m.messages)
+
+	m = sendMsg(m, app.ToolResultEvent{
 		ToolName: "bash",
 		ToolArgs: "{}",
 		Result:   "output",
 		IsError:  false,
 	})
 
-	if cmd == nil {
-		t.Fatal("expected non-nil cmd on ToolResultEvent")
+	// Tool result should have been added to ScrollList messages.
+	if len(m.messages) <= initialCount {
+		t.Fatal("expected tool result message added to ScrollList")
 	}
 	// Stream should have received a SpinnerEvent to start spinner for next LLM call.
 	if stream.lastMsg == nil {
@@ -621,7 +644,7 @@ func TestToolResult_printsAndStartsSpinner(t *testing.T) {
 }
 
 // TestToolOutputEvent_accumulatesBashOutput verifies that ToolOutputEvent
-// accumulates stdout and stderr lines into the streaming bash output buffers.
+// accumulates stdout and stderr lines into a StreamingBashOutputItem in the ScrollList.
 func TestToolOutputEvent_accumulatesBashOutput(t *testing.T) {
 	ctrl := &stubAppController{}
 	m, _, _ := newTestAppModel(ctrl)
@@ -635,11 +658,22 @@ func TestToolOutputEvent_accumulatesBashOutput(t *testing.T) {
 		IsStderr:   false,
 	})
 
-	if len(m.streamingBashOutput) != 1 || m.streamingBashOutput[0] != "line one\n" {
-		t.Fatalf("expected streamingBashOutput=['line one\\n'], got %v", m.streamingBashOutput)
+	// Should have created a StreamingBashOutputItem in messages.
+	var bashItem *StreamingBashOutputItem
+	for _, msg := range m.messages {
+		if item, ok := msg.(*StreamingBashOutputItem); ok {
+			bashItem = item
+			break
+		}
 	}
-	if len(m.streamingBashStderr) != 0 {
-		t.Fatalf("expected empty streamingBashStderr, got %v", m.streamingBashStderr)
+	if bashItem == nil {
+		t.Fatal("expected StreamingBashOutputItem in messages after ToolOutputEvent")
+	}
+	if len(bashItem.stdoutLines) != 1 || bashItem.stdoutLines[0] != "line one\n" {
+		t.Fatalf("expected stdout=['line one\\n'], got %v", bashItem.stdoutLines)
+	}
+	if len(bashItem.stderrLines) != 0 {
+		t.Fatalf("expected empty stderr, got %v", bashItem.stderrLines)
 	}
 
 	// Send another stdout chunk.
@@ -650,8 +684,15 @@ func TestToolOutputEvent_accumulatesBashOutput(t *testing.T) {
 		IsStderr:   false,
 	})
 
-	if len(m.streamingBashOutput) != 2 {
-		t.Fatalf("expected 2 stdout lines, got %d", len(m.streamingBashOutput))
+	// Re-find the bash item (same item, updated)
+	bashItem = nil
+	for _, msg := range m.messages {
+		if item, ok := msg.(*StreamingBashOutputItem); ok {
+			bashItem = item
+		}
+	}
+	if bashItem == nil || len(bashItem.stdoutLines) != 2 {
+		t.Fatalf("expected 2 stdout lines, got %d", len(bashItem.stdoutLines))
 	}
 
 	// Send stderr chunk.
@@ -662,11 +703,17 @@ func TestToolOutputEvent_accumulatesBashOutput(t *testing.T) {
 		IsStderr:   true,
 	})
 
-	if len(m.streamingBashStderr) != 1 {
-		t.Fatalf("expected 1 stderr line, got %d", len(m.streamingBashStderr))
+	bashItem = nil
+	for _, msg := range m.messages {
+		if item, ok := msg.(*StreamingBashOutputItem); ok {
+			bashItem = item
+		}
 	}
-	if m.streamingBashStderr[0] != "error: something failed\n" {
-		t.Fatalf("expected stderr 'error: something failed\\n', got %q", m.streamingBashStderr[0])
+	if bashItem == nil || len(bashItem.stderrLines) != 1 {
+		t.Fatalf("expected 1 stderr line, got %d", len(bashItem.stderrLines))
+	}
+	if bashItem.stderrLines[0] != "error: something failed\n" {
+		t.Fatalf("expected stderr 'error: something failed\\n', got %q", bashItem.stderrLines[0])
 	}
 }
 
@@ -748,16 +795,19 @@ func TestToolCallStarted_nonBashTool_doesNotSetCommand(t *testing.T) {
 }
 
 // TestStepError_printCmd verifies that StepErrorEvent with a non-nil error
-// produces a non-nil cmd (the tea.Println call for the error message).
+// adds an error message to the ScrollList.
 func TestStepError_printCmd(t *testing.T) {
 	ctrl := &stubAppController{}
 	m, _, _ := newTestAppModel(ctrl)
 	m.state = stateWorking
 
-	_, cmd := m.Update(app.StepErrorEvent{Err: errors.New("agent failed")})
+	initialCount := len(m.messages)
 
-	if cmd == nil {
-		t.Fatal("expected non-nil cmd (tea.Println) on StepErrorEvent with error")
+	m = sendMsg(m, app.StepErrorEvent{Err: errors.New("agent failed")})
+
+	// Error should have been added to ScrollList messages.
+	if len(m.messages) <= initialCount {
+		t.Fatal("expected error message added to ScrollList on StepErrorEvent")
 	}
 }
 
@@ -827,7 +877,7 @@ func TestSubmit_duringWorking_stays(t *testing.T) {
 	m, _, _ := newTestAppModel(ctrl)
 	m.state = stateWorking
 
-	m = sendMsg(m, submitMsg{Text: "queued prompt"})
+	m = sendMsg(m, core.SubmitMsg{Text: "queued prompt"})
 
 	if m.state != stateWorking {
 		t.Fatalf("expected stateWorking to persist after submitMsg during working, got %v", m.state)

internal/ui/overlay.go

@@ -6,6 +6,8 @@ import (
 
 	tea "charm.land/bubbletea/v2"
 	"charm.land/lipgloss/v2"
+
+	"github.com/mark3labs/kit/internal/ui/style"
 )
 
 // ---------------------------------------------------------------------------
@@ -133,7 +135,7 @@ func (o *overlayDialog) handleKey(msg tea.KeyPressMsg) (*overlayResult, tea.Cmd)
 // composition. The dialog is a bordered box centered (or anchored)
 // horizontally within the terminal width.
 func (o *overlayDialog) Render() string {
-	theme := GetTheme()
+	theme := style.GetTheme()
 
 	// Calculate dialog dimensions, clamped to terminal bounds.
 	termW := max(o.width, 10)
@@ -157,7 +159,7 @@ func (o *overlayDialog) Render() string {
 	// Render body text (potentially as markdown).
 	bodyText := o.content
 	if o.markdown {
-		bodyText = toMarkdown(bodyText, innerWidth)
+		bodyText = style.ToMarkdown(bodyText, innerWidth)
 	}
 	bodyText = strings.TrimRight(bodyText, "\n")
 

internal/ui/prefs/preferences.go

@@ -1,4 +1,4 @@
-package ui
+package prefs
 
 import (
 	"os"

internal/ui/progress/ollama.go

@@ -118,22 +118,33 @@ func (m ProgressModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 // status information and help text. Displays error messages if present or
 // a completion message when the download finishes.
 func (m ProgressModel) View() tea.View {
+	var v tea.View
+	v.AltScreen = true
+	v.MouseMode = tea.MouseModeCellMotion
+	v.ReportFocus = true
+	v.KeyboardEnhancements = tea.KeyboardEnhancements{
+		ReportEventTypes: true,
+	}
+
 	if m.err != nil {
-		return tea.NewView(fmt.Sprintf("Error: %s\n", m.err.Error()))
+		v.Content = fmt.Sprintf("Error: %s\n", m.err.Error())
+		return v
 	}
 
 	if m.complete {
-		return tea.NewView(fmt.Sprintf("\n%s%s\n\n%sComplete!\n",
+		v.Content = fmt.Sprintf("\n%s%s\n\n%sComplete!\n",
 			strings.Repeat(" ", padding),
 			m.progress.View(),
-			strings.Repeat(" ", padding)))
+			strings.Repeat(" ", padding))
+		return v
 	}
 
 	pad := strings.Repeat(" ", padding)
-	return tea.NewView(fmt.Sprintf("\n%s%s\n%s%s\n\n%s",
+	v.Content = fmt.Sprintf("\n%s%s\n%s%s\n\n%s",
 		pad, m.progress.View(),
 		pad, m.status,
-		pad+helpStyle("Press 'q' or Ctrl+C to cancel")))
+		pad+helpStyle("Press 'q' or Ctrl+C to cancel"))
+	return v
 }
 
 // ProgressReader wraps an io.Reader to intercept and parse Ollama pull operation

internal/ui/prompt.go

@@ -7,6 +7,8 @@ import (
 	"charm.land/bubbles/v2/textarea"
 	tea "charm.land/bubbletea/v2"
 	"charm.land/lipgloss/v2"
+
+	"github.com/mark3labs/kit/internal/ui/style"
 )
 
 // ---------------------------------------------------------------------------
@@ -204,7 +206,7 @@ func (p *promptOverlay) updateInput(msg tea.KeyPressMsg) (*promptResult, tea.Cmd
 // AppModel layout. The prompt replaces the normal input area (below the
 // separator and above the status bar) rather than taking over the full screen.
 func (p *promptOverlay) Render() string {
-	theme := GetTheme()
+	theme := style.GetTheme()
 	var content string
 
 	switch p.mode {
@@ -224,7 +226,7 @@ func (p *promptOverlay) Render() string {
 	)
 }
 
-func (p *promptOverlay) viewSelect(theme Theme) string {
+func (p *promptOverlay) viewSelect(theme style.Theme) string {
 	var lines []string
 	lines = append(lines, lipgloss.NewStyle().Bold(true).Foreground(theme.Text).Render(p.message))
 	lines = append(lines, "")
@@ -247,7 +249,7 @@ func (p *promptOverlay) viewSelect(theme Theme) string {
 	return strings.Join(lines, "\n")
 }
 
-func (p *promptOverlay) viewConfirm(theme Theme) string {
+func (p *promptOverlay) viewConfirm(theme style.Theme) string {
 	var lines []string
 	lines = append(lines, lipgloss.NewStyle().Bold(true).Foreground(theme.Text).Render(p.message))
 	lines = append(lines, "")
@@ -272,7 +274,7 @@ func (p *promptOverlay) viewConfirm(theme Theme) string {
 	return strings.Join(lines, "\n")
 }
 
-func (p *promptOverlay) viewInput(theme Theme) string {
+func (p *promptOverlay) viewInput(theme style.Theme) string {
 	var lines []string
 	lines = append(lines, lipgloss.NewStyle().Bold(true).Foreground(theme.Text).Render(p.message))
 	lines = append(lines, "")

internal/ui/render/blocks.go

@@ -0,0 +1,126 @@
+// Package render provides pure rendering functions for message blocks.
+// These functions are stateless and can be used by both streaming and
+// historical message rendering paths, eliminating code duplication.
+package render
+
+import (
+	"fmt"
+	"strings"
+
+	"charm.land/lipgloss/v2"
+	"github.com/indaco/herald"
+
+	"github.com/mark3labs/kit/internal/ui/style"
+)
+
+// UserBlock renders a user message with herald Tip styling.
+func UserBlock(content string, ty *herald.Typography, theme style.Theme) string {
+	if strings.TrimSpace(content) == "" {
+		content = "(empty message)"
+	}
+
+	rendered := ty.Tip(content)
+	return styleMarginBottom(theme, rendered)
+}
+
+// AssistantBlock renders an assistant message with markdown styling.
+func AssistantBlock(content string, width int, theme style.Theme) string {
+	if strings.TrimSpace(content) == "" {
+		return ""
+	}
+
+	rendered := style.ToMarkdown(content, width-4)
+	return styleMarginBottom(theme, rendered)
+}
+
+// ReasoningBlock renders a reasoning/thinking block with muted italic text.
+// If duration > 0, shows "Thought for Xs" label. Otherwise shows just "Thought".
+func ReasoningBlock(content string, duration int64, ty *herald.Typography, theme style.Theme) string {
+	if strings.TrimSpace(content) == "" {
+		return ""
+	}
+
+	// Match live streaming styling: muted italic text
+	lines := strings.Split(strings.TrimRight(content, "\n"), "\n")
+	contentStr := strings.TrimLeft(strings.Join(lines, "\n"), " \t\n")
+	mutedStyle := lipgloss.NewStyle().Foreground(theme.Muted)
+	contentRendered := mutedStyle.Render(ty.Italic(contentStr))
+
+	// Build label based on duration
+	var labelText string
+	if duration > 0 {
+		var durationStr string
+		if duration < 1000 {
+			durationStr = fmt.Sprintf("%dms", duration)
+		} else {
+			durationStr = fmt.Sprintf("%.1fs", float64(duration)/1000)
+		}
+		labelText = "Thought for " + durationStr
+	} else {
+		labelText = "Thought"
+	}
+
+	label := lipgloss.NewStyle().Foreground(theme.VeryMuted).Render(labelText)
+	rendered := contentRendered + "\n" + label
+
+	return styleMarginBottom(theme, rendered)
+}
+
+// SystemBlock renders a system message with herald Note styling.
+func SystemBlock(content string, ty *herald.Typography, theme style.Theme) string {
+	if strings.TrimSpace(content) == "" {
+		content = "No content available"
+	}
+
+	rendered := ty.Note(content)
+	return styleMarginBottom(theme, rendered)
+}
+
+// ErrorBlock renders an error message with herald Caution styling.
+func ErrorBlock(errorMsg string, ty *herald.Typography, theme style.Theme) string {
+	rendered := ty.Caution(errorMsg)
+	return styleMarginBottom(theme, rendered)
+}
+
+// ToolBlock renders a tool execution result with header and body.
+func ToolBlock(displayName, params, body string, isError bool, width int, ty *herald.Typography, theme style.Theme) string {
+	var icon string
+	iconColor := theme.Success
+	if isError {
+		icon = "×"
+		iconColor = theme.Error
+	} else {
+		icon = "✓"
+	}
+
+	// Style the tool name with color
+	nameColor := theme.Info
+	if isError {
+		nameColor = theme.Error
+	}
+	styledName := lipgloss.NewStyle().Foreground(nameColor).Bold(true).Render(displayName)
+	styledIcon := lipgloss.NewStyle().Foreground(iconColor).Render(icon)
+
+	// Build the content: icon + name + params on first line, then body
+	headerLine := styledIcon + " " + styledName
+	if params != "" {
+		headerLine += " " + lipgloss.NewStyle().Foreground(theme.Muted).Render(params)
+	}
+
+	if strings.TrimSpace(body) == "" {
+		body = ty.Italic("(no output)")
+	}
+
+	// Compose: icon + name + params, then body
+	fullContent := ty.Compose(
+		headerLine,
+		"",
+		body,
+	)
+	return styleMarginBottom(theme, fullContent)
+}
+
+// styleMarginBottom applies a 1-line margin bottom using the theme.
+func styleMarginBottom(theme style.Theme, content string) string {
+	return lipgloss.NewStyle().MarginBottom(1).Render(content)
+}

internal/ui/scrolllist.go

@@ -0,0 +1,693 @@
+package ui
+
+import (
+	"strings"
+	"time"
+
+	xansi "github.com/charmbracelet/x/ansi"
+
+	"github.com/mark3labs/kit/internal/ui/selection"
+)
+
+// MessageItem is the interface all scrollback messages must implement.
+// This allows lazy rendering - messages are only rendered when visible.
+type MessageItem interface {
+	// Render returns the styled content for this message at the given width.
+	// Implementations should cache the result to avoid re-rendering.
+	Render(width int) string
+
+	// Height returns the number of lines this message occupies when rendered.
+	Height() int
+
+	// ID returns a unique identifier for this message (for tracking).
+	ID() string
+}
+
+// ScrollList manages a viewport over a list of MessageItems.
+// It handles offset-based scrolling, lazy rendering, and character-level
+// text selection (crush-style). Only visible items are rendered on each View() call.
+type ScrollList struct {
+	items      []MessageItem
+	offsetIdx  int // Index of first visible item
+	offsetLine int // Lines to skip from first visible item
+	width      int
+	height     int  // Viewport height in lines
+	autoScroll bool // Whether to auto-scroll to bottom on new content
+	itemGap    int  // Number of blank lines between items (0 = no gap)
+
+	// Character-level text selection (crush-style).
+	sel selection.State
+}
+
+// NewScrollList creates a new ScrollList with the given dimensions.
+func NewScrollList(width, height int) *ScrollList {
+	return &ScrollList{
+		items:      []MessageItem{},
+		offsetIdx:  0,
+		offsetLine: 0,
+		width:      width,
+		height:     height,
+		autoScroll: true,
+		sel:        selection.NewState(),
+	}
+}
+
+// SetItems replaces the items in the scroll list. If auto-scroll is enabled,
+// the viewport will scroll to the bottom to show the latest content.
+func (s *ScrollList) SetItems(items []MessageItem) {
+	s.items = items
+	if s.autoScroll {
+		s.GotoBottom()
+	}
+}
+
+// SetHeight updates the viewport height. Called when the terminal is resized.
+func (s *ScrollList) SetHeight(height int) {
+	s.height = height
+	s.clampOffset()
+}
+
+// SetWidth updates the viewport width. Called when the terminal is resized.
+// This may invalidate cached renders in MessageItems.
+func (s *ScrollList) SetWidth(width int) {
+	s.width = width
+	s.clampOffset()
+}
+
+// SetItemGap sets the number of blank lines between items (0 = no gap).
+func (s *ScrollList) SetItemGap(gap int) {
+	s.itemGap = gap
+}
+
+// ItemGap returns the current gap between items.
+func (s *ScrollList) ItemGap() int {
+	return s.itemGap
+}
+
+// --------------------------------------------------------------------------
+// Mouse event handling — character-level text selection (crush-style)
+// --------------------------------------------------------------------------
+
+// HandleMouseDown handles mouse button press. Detects single, double, and
+// triple clicks for character, word, and line selection respectively.
+// Returns true if the click was handled.
+func (s *ScrollList) HandleMouseDown(x, y int) bool {
+	if len(s.items) == 0 {
+		return false
+	}
+
+	itemIdx, lineIdx := s.getItemAndLineAtY(y)
+	if itemIdx < 0 {
+		return false
+	}
+
+	// Multi-click detection (crush-style).
+	now := time.Now()
+	if now.Sub(s.sel.LastClickTime) <= selection.DoubleClickThreshold &&
+		abs(x-s.sel.LastClickX) <= selection.ClickTolerance &&
+		abs(y-s.sel.LastClickY) <= selection.ClickTolerance {
+		s.sel.ClickCount++
+	} else {
+		s.sel.ClickCount = 1
+	}
+	s.sel.LastClickTime = now
+	s.sel.LastClickX = x
+	s.sel.LastClickY = y
+
+	switch s.sel.ClickCount {
+	case 1:
+		// Single click: start character-level drag selection.
+		s.sel.MouseDown = true
+		s.sel.MouseDownItemIdx = itemIdx
+		s.sel.MouseDownLineIdx = lineIdx
+		s.sel.MouseDownCol = x
+		s.sel.DragItemIdx = itemIdx
+		s.sel.DragLineIdx = lineIdx
+		s.sel.DragCol = x
+
+	case 2:
+		// Double click: select word at position.
+		s.selectWord(itemIdx, lineIdx, x)
+
+	case 3:
+		// Triple click: select entire line.
+		s.selectLine(itemIdx, lineIdx)
+		s.sel.ClickCount = 0 // Reset after triple
+	}
+
+	return true
+}
+
+// HandleMouseDrag handles mouse motion while button is held.
+// Updates the selection endpoint for character-level precision.
+// Returns true if selection was updated.
+func (s *ScrollList) HandleMouseDrag(x, y int) bool {
+	if !s.sel.MouseDown {
+		return false
+	}
+
+	if len(s.items) == 0 {
+		return false
+	}
+
+	itemIdx, lineIdx := s.getItemAndLineAtY(y)
+	if itemIdx < 0 {
+		return false
+	}
+
+	s.sel.DragItemIdx = itemIdx
+	s.sel.DragLineIdx = lineIdx
+	s.sel.DragCol = x
+
+	return true
+}
+
+// HandleMouseUp handles mouse button release.
+// Returns true if there was an active selection.
+func (s *ScrollList) HandleMouseUp() bool {
+	if !s.sel.MouseDown {
+		return false
+	}
+	s.sel.MouseDown = false
+	return s.sel.HasSelection()
+}
+
+// HasSelection returns true if there is a non-empty active selection.
+func (s *ScrollList) HasSelection() bool {
+	return s.sel.HasSelection()
+}
+
+// ClearSelection clears the current text selection.
+func (s *ScrollList) ClearSelection() {
+	s.sel.Clear()
+}
+
+// ExtractSelectedText returns the plain text content of the current selection
+// by walking through selected items and extracting text at the character level
+// using the ultraviolet cell buffer (ANSI-aware).
+func (s *ScrollList) ExtractSelectedText() string {
+	r := s.sel.GetRange()
+	if r.IsEmpty() {
+		return ""
+	}
+
+	var sb strings.Builder
+
+	for itemIdx := r.StartItemIdx; itemIdx <= r.EndItemIdx && itemIdx < len(s.items); itemIdx++ {
+		item := s.items[itemIdx]
+		content := item.Render(s.width)
+		contentLines := strings.Split(content, "\n")
+
+		for lineIdx, line := range contentLines {
+			inRange, startCol, endCol := selection.IsLineInRange(r, itemIdx, lineIdx)
+			if !inRange {
+				continue
+			}
+
+			text := selection.ExtractText(line, startCol, endCol)
+			if text != "" {
+				if sb.Len() > 0 {
+					sb.WriteString("\n")
+				}
+				sb.WriteString(text)
+			}
+		}
+	}
+
+	return sb.String()
+}
+
+// selectWord selects the word at the given position using UAX#29 word
+// segmentation and display-width-aware column calculations.
+func (s *ScrollList) selectWord(itemIdx, lineIdx, x int) {
+	if itemIdx < 0 || itemIdx >= len(s.items) {
+		return
+	}
+
+	item := s.items[itemIdx]
+	content := item.Render(s.width)
+	lines := strings.Split(content, "\n")
+	if lineIdx < 0 || lineIdx >= len(lines) {
+		return
+	}
+
+	// Strip ANSI codes for word boundary detection.
+	plainLine := xansi.Strip(lines[lineIdx])
+	startCol, endCol := selection.FindWordBoundaries(plainLine, x)
+
+	if startCol == endCol {
+		// No word at this position — set up single-click drag state.
+		s.sel.MouseDown = true
+		s.sel.MouseDownItemIdx = itemIdx
+		s.sel.MouseDownLineIdx = lineIdx
+		s.sel.MouseDownCol = x
+		s.sel.DragItemIdx = itemIdx
+		s.sel.DragLineIdx = lineIdx
+		s.sel.DragCol = x
+		return
+	}
+
+	// Set selection to the word boundaries.
+	s.sel.MouseDown = true
+	s.sel.MouseDownItemIdx = itemIdx
+	s.sel.MouseDownLineIdx = lineIdx
+	s.sel.MouseDownCol = startCol
+	s.sel.DragItemIdx = itemIdx
+	s.sel.DragLineIdx = lineIdx
+	s.sel.DragCol = endCol
+}
+
+// selectLine selects the entire line at the given position.
+func (s *ScrollList) selectLine(itemIdx, lineIdx int) {
+	if itemIdx < 0 || itemIdx >= len(s.items) {
+		return
+	}
+
+	item := s.items[itemIdx]
+	content := item.Render(s.width)
+	lines := strings.Split(content, "\n")
+	if lineIdx < 0 || lineIdx >= len(lines) {
+		return
+	}
+
+	lineWidth := xansi.StringWidth(lines[lineIdx])
+
+	s.sel.MouseDown = true
+	s.sel.MouseDownItemIdx = itemIdx
+	s.sel.MouseDownLineIdx = lineIdx
+	s.sel.MouseDownCol = 0
+	s.sel.DragItemIdx = itemIdx
+	s.sel.DragLineIdx = lineIdx
+	s.sel.DragCol = lineWidth
+}
+
+// getItemAndLineAtY converts a viewport-relative Y coordinate to item index
+// and line index within that item. Accounts for scroll offset and item gaps.
+// Returns (-1, -1) if Y is outside the viewport or beyond all items.
+//
+// IMPORTANT: Uses Render()+line counting (not Height()) to compute item height,
+// because Height() on some MessageItem implementations (e.g. StreamingMessageItem
+// for reasoning blocks) may return 0 when the render cache is empty.
+func (s *ScrollList) getItemAndLineAtY(y int) (itemIdx, lineIdx int) {
+	if y < 0 || y >= s.height || len(s.items) == 0 {
+		return -1, -1
+	}
+
+	currentY := 0
+	for idx := s.offsetIdx; idx < len(s.items); idx++ {
+		item := s.items[idx]
+		// Compute height the same way View() does: render, then count lines.
+		itemHeight := s.renderedHeight(item)
+
+		// Account for partial visibility of the first item.
+		startLine := 0
+		if idx == s.offsetIdx {
+			startLine = s.offsetLine
+			itemHeight -= s.offsetLine
+		}
+
+		if y >= currentY && y < currentY+itemHeight {
+			return idx, (y - currentY) + startLine
+		}
+
+		currentY += itemHeight
+
+		// Add gap after item (except last).
+		if s.itemGap > 0 && idx < len(s.items)-1 {
+			currentY += s.itemGap
+		}
+
+		if currentY >= s.height {
+			break
+		}
+	}
+
+	return -1, -1
+}
+
+// --------------------------------------------------------------------------
+// Scrolling
+// --------------------------------------------------------------------------
+
+// ScrollBy scrolls the viewport by the given number of lines.
+// Positive = scroll down, negative = scroll up.
+func (s *ScrollList) ScrollBy(lines int) {
+	if lines > 0 {
+		// Scroll down
+		for lines > 0 && s.offsetIdx < len(s.items) {
+			if s.offsetIdx >= len(s.items) {
+				break
+			}
+			currentItem := s.items[s.offsetIdx]
+			itemHeight := currentItem.Height()
+			remainingLines := itemHeight - s.offsetLine
+
+			if lines >= remainingLines {
+				// Move to next item
+				s.offsetIdx++
+				s.offsetLine = 0
+				lines -= remainingLines
+				// Consume gap lines between items
+				if s.itemGap > 0 && s.offsetIdx < len(s.items) {
+					if lines >= s.itemGap {
+						lines -= s.itemGap
+					} else {
+						lines = 0
+					}
+				}
+			} else {
+				// Stay on current item, skip more lines
+				s.offsetLine += lines
+				lines = 0
+			}
+		}
+	} else if lines < 0 {
+		// Scroll up
+		lines = -lines
+		for lines > 0 && (s.offsetIdx > 0 || s.offsetLine > 0) {
+			if s.offsetLine > 0 {
+				// Scroll within current item
+				if lines >= s.offsetLine {
+					lines -= s.offsetLine
+					s.offsetLine = 0
+				} else {
+					s.offsetLine -= lines
+					lines = 0
+				}
+			} else if s.offsetIdx > 0 {
+				// Consume gap lines between items
+				if s.itemGap > 0 {
+					if lines > s.itemGap {
+						lines -= s.itemGap
+					} else {
+						lines = 0
+						continue
+					}
+				}
+				// Move to previous item
+				s.offsetIdx--
+				if s.offsetIdx < len(s.items) {
+					currentItem := s.items[s.offsetIdx]
+					itemHeight := currentItem.Height()
+
+					if lines >= itemHeight {
+						lines -= itemHeight
+						s.offsetLine = 0
+					} else {
+						s.offsetLine = itemHeight - lines
+						lines = 0
+					}
+				}
+			}
+		}
+	}
+	s.clampOffset()
+}
+
+// GotoBottom scrolls to the end of the list.
+func (s *ScrollList) GotoBottom() {
+	if len(s.items) == 0 {
+		s.offsetIdx = 0
+		s.offsetLine = 0
+		return
+	}
+
+	// Calculate total height including gaps
+	totalHeight := 0
+	for i, item := range s.items {
+		rendered := item.Render(s.width)
+		itemHeight := strings.Count(rendered, "\n") + 1
+		totalHeight += itemHeight
+		if s.itemGap > 0 && i < len(s.items)-1 {
+			totalHeight += s.itemGap
+		}
+	}
+
+	// If content fits in viewport, start at top
+	if totalHeight <= s.height {
+		s.offsetIdx = 0
+		s.offsetLine = 0
+		return
+	}
+
+	// Otherwise, position viewport at bottom
+	remaining := totalHeight - s.height
+	for idx := 0; idx < len(s.items); idx++ {
+		rendered := s.items[idx].Render(s.width)
+		itemHeight := strings.Count(rendered, "\n") + 1
+		if remaining < itemHeight {
+			s.offsetIdx = idx
+			s.offsetLine = remaining
+			return
+		}
+		remaining -= itemHeight
+		if s.itemGap > 0 && idx < len(s.items)-1 {
+			remaining -= s.itemGap
+		}
+	}
+
+	// Fallback: show last item
+	s.offsetIdx = max(0, len(s.items)-1)
+	s.offsetLine = 0
+}
+
+// GotoTop scrolls to the beginning of the list.
+func (s *ScrollList) GotoTop() {
+	s.offsetIdx = 0
+	s.offsetLine = 0
+}
+
+// AtBottom returns true if the viewport is at the bottom of the list.
+func (s *ScrollList) AtBottom() bool {
+	if len(s.items) == 0 {
+		return true
+	}
+
+	visibleHeight := 0
+	for idx := s.offsetIdx; idx < len(s.items); idx++ {
+		item := s.items[idx]
+		rendered := item.Render(s.width)
+		itemHeight := strings.Count(rendered, "\n") + 1
+
+		if idx == s.offsetIdx {
+			visibleHeight += itemHeight - s.offsetLine
+		} else {
+			visibleHeight += itemHeight
+		}
+
+		if s.itemGap > 0 && idx < len(s.items)-1 {
+			visibleHeight += s.itemGap
+		}
+
+		if visibleHeight >= s.height {
+			return false
+		}
+	}
+
+	return true
+}
+
+// AtTop returns true if the viewport is at the top of the list.
+func (s *ScrollList) AtTop() bool {
+	return s.offsetIdx == 0 && s.offsetLine == 0
+}
+
+// --------------------------------------------------------------------------
+// Rendering
+// --------------------------------------------------------------------------
+
+// View renders the visible portion of the scrollback.
+// Only items that fit within the viewport height are rendered.
+// ALWAYS returns exactly s.height lines (padded with empty lines if needed)
+// to ensure the input/footer stay fixed at the bottom.
+//
+// When an active selection exists, character-level highlighting is applied
+// using ultraviolet ScreenBuffer for ANSI-aware cell manipulation.
+func (s *ScrollList) View() string {
+	if s.height <= 0 {
+		return ""
+	}
+
+	selRange := s.sel.GetRange()
+	hasSelection := !selRange.IsEmpty()
+
+	var lines []string
+	remainingHeight := s.height
+
+	if len(s.items) > 0 {
+		for idx := s.offsetIdx; idx < len(s.items) && remainingHeight > 0; idx++ {
+			item := s.items[idx]
+			content := item.Render(s.width)
+			contentLines := strings.Split(content, "\n")
+
+			startLine := 0
+			if idx == s.offsetIdx {
+				startLine = s.offsetLine
+			}
+
+			for i := startLine; i < len(contentLines) && remainingHeight > 0; i++ {
+				line := contentLines[i]
+
+				// Apply character-level selection highlighting.
+				if hasSelection {
+					inRange, startCol, endCol := selection.IsLineInRange(selRange, idx, i)
+					if inRange {
+						line = selection.HighlightLine(line, startCol, endCol)
+					}
+				}
+
+				lines = append(lines, line)
+				remainingHeight--
+			}
+
+			// Add gap lines between items.
+			if remainingHeight > 0 && idx < len(s.items)-1 && s.itemGap > 0 {
+				for g := 0; g < s.itemGap && remainingHeight > 0; g++ {
+					lines = append(lines, "")
+					remainingHeight--
+				}
+			}
+		}
+	}
+
+	// Pad with empty lines to ensure exactly s.height lines.
+	for remainingHeight > 0 {
+		lines = append(lines, "")
+		remainingHeight--
+	}
+
+	return strings.Join(lines, "\n")
+}
+
+// ScrollPercent returns the current scroll position as a percentage (0.0-1.0).
+// 0.0 = at top, 1.0 = at bottom. Useful for scroll indicators.
+func (s *ScrollList) ScrollPercent() float64 {
+	if len(s.items) == 0 {
+		return 0.0
+	}
+
+	totalHeight := 0
+	for _, item := range s.items {
+		totalHeight += item.Height()
+	}
+
+	if totalHeight <= s.height {
+		return 1.0
+	}
+
+	linesAbove := 0
+	for i := 0; i < s.offsetIdx && i < len(s.items); i++ {
+		linesAbove += s.items[i].Height()
+	}
+	linesAbove += s.offsetLine
+
+	scrollableHeight := totalHeight - s.height
+	if scrollableHeight <= 0 {
+		return 1.0
+	}
+
+	percent := float64(linesAbove) / float64(scrollableHeight)
+	if percent > 1.0 {
+		percent = 1.0
+	}
+	if percent < 0.0 {
+		percent = 0.0
+	}
+	return percent
+}
+
+// clampOffset ensures the offset values are within valid bounds after
+// resizing or scrolling operations.
+func (s *ScrollList) clampOffset() {
+	if len(s.items) == 0 {
+		s.offsetIdx = 0
+		s.offsetLine = 0
+		return
+	}
+
+	if s.offsetIdx >= len(s.items) {
+		s.offsetIdx = len(s.items) - 1
+	}
+	if s.offsetIdx < 0 {
+		s.offsetIdx = 0
+	}
+
+	if s.offsetIdx < len(s.items) {
+		rendered := s.items[s.offsetIdx].Render(s.width)
+		itemHeight := strings.Count(rendered, "\n") + 1
+		if s.offsetLine >= itemHeight {
+			s.offsetLine = max(0, itemHeight-1)
+		}
+	}
+	if s.offsetLine < 0 {
+		s.offsetLine = 0
+	}
+
+	// Prevent scrolling past the bottom
+	totalHeight := 0
+	for i, item := range s.items {
+		rendered := item.Render(s.width)
+		totalHeight += strings.Count(rendered, "\n") + 1
+		if s.itemGap > 0 && i < len(s.items)-1 {
+			totalHeight += s.itemGap
+		}
+	}
+
+	if totalHeight <= s.height {
+		s.offsetIdx = 0
+		s.offsetLine = 0
+		return
+	}
+
+	linesAbove := 0
+	for i := 0; i < s.offsetIdx; i++ {
+		rendered := s.items[i].Render(s.width)
+		linesAbove += strings.Count(rendered, "\n") + 1
+		if s.itemGap > 0 && i < len(s.items)-1 {
+			linesAbove += s.itemGap
+		}
+	}
+	linesAbove += s.offsetLine
+
+	linesFromCurrentToEnd := totalHeight - linesAbove
+	if linesFromCurrentToEnd < s.height {
+		targetLine := totalHeight - s.height
+		currentLine := 0
+
+		for idx := 0; idx < len(s.items); idx++ {
+			rendered := s.items[idx].Render(s.width)
+			itemHeight := strings.Count(rendered, "\n") + 1
+
+			if currentLine+itemHeight > targetLine {
+				s.offsetIdx = idx
+				s.offsetLine = targetLine - currentLine
+				return
+			}
+
+			currentLine += itemHeight
+			if s.itemGap > 0 && idx < len(s.items)-1 {
+				currentLine += s.itemGap
+			}
+		}
+	}
+}
+
+// renderedHeight returns the height of a message item in lines by actually
+// rendering it. This is the single source of truth for item height — it
+// matches exactly what View() produces, unlike item.Height() which may
+// return stale/zero values for uncached items (e.g. reasoning blocks).
+func (s *ScrollList) renderedHeight(item MessageItem) int {
+	rendered := item.Render(s.width)
+	if rendered == "" {
+		return 0
+	}
+	return strings.Count(rendered, "\n") + 1
+}
+
+// abs returns the absolute value of x.
+func abs(x int) int {
+	if x < 0 {
+		return -x
+	}
+	return x
+}

internal/ui/selection/selection.go

@@ -0,0 +1,324 @@
+// Package selection provides character-level text selection for terminal UIs.
+//
+// It handles converting mouse coordinates (in terminal cells) to character
+// positions within rendered ANSI-styled text, supporting multi-byte characters,
+// wide characters (CJK, emoji), and word/line selection via double/triple click.
+//
+// The approach is modeled after Charm's crush: all coordinate calculations use
+// display columns (terminal cells), not byte offsets or rune counts. The
+// ultraviolet ScreenBuffer provides the bridge between rendered ANSI strings
+// and individual character cells.
+package selection
+
+import (
+	"image"
+	"strings"
+	"time"
+
+	uv "github.com/charmbracelet/ultraviolet"
+	xansi "github.com/charmbracelet/x/ansi"
+	"github.com/clipperhouse/displaywidth"
+	"github.com/clipperhouse/uax29/v2/words"
+)
+
+// DoubleClickThreshold is the maximum time between clicks for multi-click.
+const DoubleClickThreshold = 400 * time.Millisecond
+
+// ClickTolerance is the pixel/cell tolerance for multi-click detection.
+const ClickTolerance = 2
+
+// State tracks the full state of a mouse text selection.
+type State struct {
+	// Whether a mouse button is currently held down.
+	MouseDown bool
+
+	// Position where mouse was first pressed (viewport-relative).
+	MouseDownItemIdx int
+	MouseDownLineIdx int
+	MouseDownCol     int
+
+	// Current drag position (viewport-relative).
+	DragItemIdx int
+	DragLineIdx int
+	DragCol     int
+
+	// Multi-click detection.
+	LastClickTime time.Time
+	LastClickX    int
+	LastClickY    int
+	ClickCount    int
+}
+
+// Range represents a normalized (start <= end) selection range.
+type Range struct {
+	StartItemIdx int
+	StartLine    int
+	StartCol     int
+	EndItemIdx   int
+	EndLine      int
+	EndCol       int
+}
+
+// IsEmpty returns true if the range selects nothing.
+func (r Range) IsEmpty() bool {
+	return r.StartItemIdx < 0 || r.EndItemIdx < 0 ||
+		(r.StartItemIdx == r.EndItemIdx && r.StartLine == r.EndLine && r.StartCol == r.EndCol)
+}
+
+// NewState creates a new empty selection state.
+func NewState() State {
+	return State{
+		MouseDownItemIdx: -1,
+		DragItemIdx:      -1,
+	}
+}
+
+// Clear resets all selection state.
+func (s *State) Clear() {
+	s.MouseDown = false
+	s.MouseDownItemIdx = -1
+	s.MouseDownLineIdx = 0
+	s.MouseDownCol = 0
+	s.DragItemIdx = -1
+	s.DragLineIdx = 0
+	s.DragCol = 0
+	s.LastClickTime = time.Time{}
+	s.LastClickX = 0
+	s.LastClickY = 0
+	s.ClickCount = 0
+}
+
+// HasSelection returns true if there is a non-empty active selection.
+func (s *State) HasSelection() bool {
+	return s.MouseDownItemIdx >= 0 && s.DragItemIdx >= 0 && !s.GetRange().IsEmpty()
+}
+
+// GetRange returns the normalized selection range (start <= end).
+func (s *State) GetRange() Range {
+	if s.MouseDownItemIdx < 0 || s.DragItemIdx < 0 {
+		return Range{StartItemIdx: -1, EndItemIdx: -1}
+	}
+
+	downItem := s.MouseDownItemIdx
+	downLine := s.MouseDownLineIdx
+	downCol := s.MouseDownCol
+	dragItem := s.DragItemIdx
+	dragLine := s.DragLineIdx
+	dragCol := s.DragCol
+
+	// Determine if dragging forward or backward.
+	forward := dragItem > downItem ||
+		(dragItem == downItem && dragLine > downLine) ||
+		(dragItem == downItem && dragLine == downLine && dragCol >= downCol)
+
+	if forward {
+		return Range{
+			StartItemIdx: downItem,
+			StartLine:    downLine,
+			StartCol:     downCol,
+			EndItemIdx:   dragItem,
+			EndLine:      dragLine,
+			EndCol:       dragCol,
+		}
+	}
+	return Range{
+		StartItemIdx: dragItem,
+		StartLine:    dragLine,
+		StartCol:     dragCol,
+		EndItemIdx:   downItem,
+		EndLine:      downLine,
+		EndCol:       downCol,
+	}
+}
+
+// IsLineInRange checks if a specific line within an item falls inside the
+// selection range. Returns (inRange, startCol, endCol) where startCol == -1
+// means the entire line is selected. startCol == endCol means no selection
+// on this line.
+func IsLineInRange(r Range, itemIdx, lineIdx int) (bool, int, int) {
+	if r.IsEmpty() {
+		return false, 0, 0
+	}
+
+	// Outside item range entirely.
+	if itemIdx < r.StartItemIdx || itemIdx > r.EndItemIdx {
+		return false, 0, 0
+	}
+
+	// Single-item selection.
+	if r.StartItemIdx == r.EndItemIdx {
+		if itemIdx != r.StartItemIdx {
+			return false, 0, 0
+		}
+		if lineIdx < r.StartLine || lineIdx > r.EndLine {
+			return false, 0, 0
+		}
+		if r.StartLine == r.EndLine {
+			// Single line: specific column range.
+			return true, r.StartCol, r.EndCol
+		}
+		if lineIdx == r.StartLine {
+			return true, r.StartCol, -1 // from startCol to end of line
+		}
+		if lineIdx == r.EndLine {
+			return true, 0, r.EndCol // from start of line to endCol
+		}
+		return true, -1, -1 // full line (middle of multi-line selection)
+	}
+
+	// Multi-item selection.
+	if itemIdx == r.StartItemIdx {
+		if lineIdx < r.StartLine {
+			return false, 0, 0
+		}
+		if lineIdx == r.StartLine {
+			return true, r.StartCol, -1
+		}
+		return true, -1, -1 // full line
+	}
+	if itemIdx == r.EndItemIdx {
+		if lineIdx > r.EndLine {
+			return false, 0, 0
+		}
+		if lineIdx == r.EndLine {
+			return true, 0, r.EndCol
+		}
+		return true, -1, -1 // full line
+	}
+
+	// Middle item: fully selected.
+	return true, -1, -1
+}
+
+// FindWordBoundaries finds the start and end column of the word at the given
+// column position in a plain-text line (ANSI codes already stripped).
+// Returns (startCol, endCol) where endCol is exclusive.
+// Uses UAX#29 word segmentation and display-width-aware column tracking.
+func FindWordBoundaries(line string, col int) (startCol, endCol int) {
+	if line == "" || col < 0 {
+		return 0, 0
+	}
+
+	// Segment the line into words using UAX#29.
+	lineCol := 0
+	iter := words.FromString(line)
+	for iter.Next() {
+		token := iter.Value()
+		tokenWidth := displaywidth.String(token)
+
+		graphemeStart := lineCol
+		graphemeEnd := lineCol + tokenWidth
+		lineCol += tokenWidth
+
+		// If clicked before this token, no word here.
+		if col < graphemeStart {
+			return col, col
+		}
+
+		// If clicked within this token, return its boundaries.
+		if col >= graphemeStart && col < graphemeEnd {
+			// Whitespace tokens produce empty selection.
+			if strings.TrimSpace(token) == "" {
+				return col, col
+			}
+			return graphemeStart, graphemeEnd
+		}
+	}
+
+	return col, col
+}
+
+// HighlightLine applies reverse-video highlighting to a portion of a rendered
+// line (which may contain ANSI escape codes). startCol/endCol are in display
+// columns. If startCol == -1, the entire line is highlighted. If startCol ==
+// endCol, returns the line unchanged.
+//
+// Uses ultraviolet ScreenBuffer for cell-level ANSI manipulation.
+func HighlightLine(line string, startCol, endCol int) string {
+	if line == "" {
+		return line
+	}
+
+	lineWidth := xansi.StringWidth(line)
+	if lineWidth == 0 {
+		return line
+	}
+
+	// Full-line highlight.
+	if startCol == -1 {
+		startCol = 0
+		endCol = lineWidth
+	}
+
+	if startCol >= endCol || startCol >= lineWidth {
+		return line
+	}
+	if endCol > lineWidth {
+		endCol = lineWidth
+	}
+
+	// Parse the styled line into a cell buffer.
+	area := image.Rect(0, 0, lineWidth, 1)
+	buf := uv.NewScreenBuffer(lineWidth, 1)
+	styled := uv.NewStyledString(line)
+	styled.Draw(&buf, area)
+
+	// Apply reverse attribute to cells in the selection range.
+	if buf.Height() > 0 {
+		bufLine := buf.Line(0)
+		for x := startCol; x < endCol && x < len(bufLine); x++ {
+			cell := bufLine.At(x)
+			if cell != nil {
+				cell.Style.Attrs |= uv.AttrReverse
+			}
+		}
+	}
+
+	return buf.Render()
+}
+
+// ExtractText extracts plain text from a rendered ANSI string within the given
+// column range on a single line. Uses ultraviolet to parse ANSI and extract
+// character content.
+func ExtractText(line string, startCol, endCol int) string {
+	if line == "" {
+		return ""
+	}
+
+	lineWidth := xansi.StringWidth(line)
+	if lineWidth == 0 {
+		return ""
+	}
+
+	// Full-line extraction.
+	if startCol == -1 {
+		startCol = 0
+		endCol = lineWidth
+	}
+
+	if startCol >= endCol || startCol >= lineWidth {
+		return ""
+	}
+	if endCol > lineWidth {
+		endCol = lineWidth
+	}
+
+	// Parse to cell buffer.
+	area := image.Rect(0, 0, lineWidth, 1)
+	buf := uv.NewScreenBuffer(lineWidth, 1)
+	styled := uv.NewStyledString(line)
+	styled.Draw(&buf, area)
+
+	var sb strings.Builder
+	if buf.Height() > 0 {
+		bufLine := buf.Line(0)
+		for x := startCol; x < endCol && x < len(bufLine); x++ {
+			cell := bufLine.At(x)
+			if cell != nil && cell.Content != "" {
+				sb.WriteString(cell.Content)
+			}
+		}
+	}
+
+	return sb.String()
+}

internal/ui/selection/selection_test.go

@@ -0,0 +1,400 @@
+package selection
+
+import (
+	"testing"
+	"time"
+)
+
+func TestNewState(t *testing.T) {
+	s := NewState()
+	if s.MouseDownItemIdx != -1 {
+		t.Errorf("expected MouseDownItemIdx -1, got %d", s.MouseDownItemIdx)
+	}
+	if s.DragItemIdx != -1 {
+		t.Errorf("expected DragItemIdx -1, got %d", s.DragItemIdx)
+	}
+	if s.MouseDown {
+		t.Error("expected MouseDown false")
+	}
+	if s.HasSelection() {
+		t.Error("expected no selection on new state")
+	}
+}
+
+func TestClear(t *testing.T) {
+	s := NewState()
+	s.MouseDown = true
+	s.MouseDownItemIdx = 2
+	s.DragItemIdx = 3
+	s.ClickCount = 2
+	s.Clear()
+
+	if s.MouseDown {
+		t.Error("expected MouseDown false after clear")
+	}
+	if s.MouseDownItemIdx != -1 {
+		t.Errorf("expected MouseDownItemIdx -1 after clear, got %d", s.MouseDownItemIdx)
+	}
+	if s.DragItemIdx != -1 {
+		t.Errorf("expected DragItemIdx -1 after clear, got %d", s.DragItemIdx)
+	}
+	if s.ClickCount != 0 {
+		t.Errorf("expected ClickCount 0 after clear, got %d", s.ClickCount)
+	}
+}
+
+func TestGetRange_Forward(t *testing.T) {
+	s := NewState()
+	s.MouseDownItemIdx = 0
+	s.MouseDownLineIdx = 1
+	s.MouseDownCol = 5
+	s.DragItemIdx = 0
+	s.DragLineIdx = 3
+	s.DragCol = 10
+
+	r := s.GetRange()
+	if r.StartItemIdx != 0 || r.StartLine != 1 || r.StartCol != 5 {
+		t.Errorf("unexpected start: item=%d line=%d col=%d", r.StartItemIdx, r.StartLine, r.StartCol)
+	}
+	if r.EndItemIdx != 0 || r.EndLine != 3 || r.EndCol != 10 {
+		t.Errorf("unexpected end: item=%d line=%d col=%d", r.EndItemIdx, r.EndLine, r.EndCol)
+	}
+}
+
+func TestGetRange_Backward(t *testing.T) {
+	s := NewState()
+	s.MouseDownItemIdx = 2
+	s.MouseDownLineIdx = 5
+	s.MouseDownCol = 20
+	s.DragItemIdx = 0
+	s.DragLineIdx = 1
+	s.DragCol = 3
+
+	r := s.GetRange()
+	// Should be normalized: drag position becomes start
+	if r.StartItemIdx != 0 || r.StartLine != 1 || r.StartCol != 3 {
+		t.Errorf("unexpected start: item=%d line=%d col=%d", r.StartItemIdx, r.StartLine, r.StartCol)
+	}
+	if r.EndItemIdx != 2 || r.EndLine != 5 || r.EndCol != 20 {
+		t.Errorf("unexpected end: item=%d line=%d col=%d", r.EndItemIdx, r.EndLine, r.EndCol)
+	}
+}
+
+func TestGetRange_SameLine(t *testing.T) {
+	s := NewState()
+	s.MouseDownItemIdx = 1
+	s.MouseDownLineIdx = 2
+	s.MouseDownCol = 10
+	s.DragItemIdx = 1
+	s.DragLineIdx = 2
+	s.DragCol = 20
+
+	r := s.GetRange()
+	if r.IsEmpty() {
+		t.Error("expected non-empty range")
+	}
+	if r.StartCol != 10 || r.EndCol != 20 {
+		t.Errorf("expected cols 10-20, got %d-%d", r.StartCol, r.EndCol)
+	}
+}
+
+func TestRangeIsEmpty(t *testing.T) {
+	// Same point
+	r := Range{StartItemIdx: 0, StartLine: 0, StartCol: 5, EndItemIdx: 0, EndLine: 0, EndCol: 5}
+	if !r.IsEmpty() {
+		t.Error("expected same-point range to be empty")
+	}
+
+	// Negative item idx
+	r = Range{StartItemIdx: -1, EndItemIdx: -1}
+	if !r.IsEmpty() {
+		t.Error("expected negative item idx range to be empty")
+	}
+
+	// Valid range
+	r = Range{StartItemIdx: 0, StartLine: 0, StartCol: 0, EndItemIdx: 0, EndLine: 0, EndCol: 5}
+	if r.IsEmpty() {
+		t.Error("expected valid range to not be empty")
+	}
+}
+
+func TestHasSelection(t *testing.T) {
+	s := NewState()
+	if s.HasSelection() {
+		t.Error("new state should have no selection")
+	}
+
+	// Set up a valid selection
+	s.MouseDownItemIdx = 0
+	s.MouseDownLineIdx = 0
+	s.MouseDownCol = 0
+	s.DragItemIdx = 0
+	s.DragLineIdx = 0
+	s.DragCol = 10
+	if !s.HasSelection() {
+		t.Error("expected selection to exist")
+	}
+
+	// Same point = no selection
+	s.DragCol = 0
+	if s.HasSelection() {
+		t.Error("same point should not be a selection")
+	}
+}
+
+func TestIsLineInRange_SingleItem_SingleLine(t *testing.T) {
+	r := Range{
+		StartItemIdx: 1, StartLine: 2, StartCol: 5,
+		EndItemIdx: 1, EndLine: 2, EndCol: 15,
+	}
+
+	// Exact line
+	ok, sc, ec := IsLineInRange(r, 1, 2)
+	if !ok || sc != 5 || ec != 15 {
+		t.Errorf("expected (true, 5, 15), got (%v, %d, %d)", ok, sc, ec)
+	}
+
+	// Wrong line
+	ok, _, _ = IsLineInRange(r, 1, 0)
+	if ok {
+		t.Error("line 0 should not be in range")
+	}
+
+	// Wrong item
+	ok, _, _ = IsLineInRange(r, 0, 2)
+	if ok {
+		t.Error("item 0 should not be in range")
+	}
+}
+
+func TestIsLineInRange_SingleItem_MultiLine(t *testing.T) {
+	r := Range{
+		StartItemIdx: 0, StartLine: 1, StartCol: 5,
+		EndItemIdx: 0, EndLine: 4, EndCol: 10,
+	}
+
+	// Start line
+	ok, sc, ec := IsLineInRange(r, 0, 1)
+	if !ok || sc != 5 || ec != -1 {
+		t.Errorf("start line: expected (true, 5, -1), got (%v, %d, %d)", ok, sc, ec)
+	}
+
+	// Middle line
+	ok, sc, ec = IsLineInRange(r, 0, 2)
+	if !ok || sc != -1 || ec != -1 {
+		t.Errorf("middle line: expected (true, -1, -1), got (%v, %d, %d)", ok, sc, ec)
+	}
+
+	// End line
+	ok, sc, ec = IsLineInRange(r, 0, 4)
+	if !ok || sc != 0 || ec != 10 {
+		t.Errorf("end line: expected (true, 0, 10), got (%v, %d, %d)", ok, sc, ec)
+	}
+}
+
+func TestIsLineInRange_MultiItem(t *testing.T) {
+	r := Range{
+		StartItemIdx: 0, StartLine: 3, StartCol: 5,
+		EndItemIdx: 2, EndLine: 1, EndCol: 10,
+	}
+
+	// First item, start line
+	ok, sc, ec := IsLineInRange(r, 0, 3)
+	if !ok || sc != 5 || ec != -1 {
+		t.Errorf("first item start: expected (true, 5, -1), got (%v, %d, %d)", ok, sc, ec)
+	}
+
+	// First item, line after start
+	ok, sc, ec = IsLineInRange(r, 0, 5)
+	if !ok || sc != -1 || ec != -1 {
+		t.Errorf("first item after: expected (true, -1, -1), got (%v, %d, %d)", ok, sc, ec)
+	}
+
+	// Middle item, any line
+	ok, sc, ec = IsLineInRange(r, 1, 0)
+	if !ok || sc != -1 || ec != -1 {
+		t.Errorf("middle item: expected (true, -1, -1), got (%v, %d, %d)", ok, sc, ec)
+	}
+
+	// Last item, end line
+	ok, sc, ec = IsLineInRange(r, 2, 1)
+	if !ok || sc != 0 || ec != 10 {
+		t.Errorf("last item end: expected (true, 0, 10), got (%v, %d, %d)", ok, sc, ec)
+	}
+
+	// Last item, line after end
+	ok, _, _ = IsLineInRange(r, 2, 5)
+	if ok {
+		t.Error("line after end in last item should not be in range")
+	}
+}
+
+func TestFindWordBoundaries(t *testing.T) {
+	tests := []struct {
+		name      string
+		line      string
+		col       int
+		wantStart int
+		wantEnd   int
+	}{
+		{
+			name:      "simple word",
+			line:      "hello world",
+			col:       2,
+			wantStart: 0,
+			wantEnd:   5,
+		},
+		{
+			name:      "second word",
+			line:      "hello world",
+			col:       7,
+			wantStart: 6,
+			wantEnd:   11,
+		},
+		{
+			name:      "on space",
+			line:      "hello world",
+			col:       5,
+			wantStart: 5,
+			wantEnd:   5,
+		},
+		{
+			name:      "empty line",
+			line:      "",
+			col:       0,
+			wantStart: 0,
+			wantEnd:   0,
+		},
+		{
+			name:      "negative col",
+			line:      "hello",
+			col:       -1,
+			wantStart: 0,
+			wantEnd:   0,
+		},
+		{
+			name:      "past end",
+			line:      "hello",
+			col:       10,
+			wantStart: 10,
+			wantEnd:   10,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			start, end := FindWordBoundaries(tt.line, tt.col)
+			if start != tt.wantStart || end != tt.wantEnd {
+				t.Errorf("FindWordBoundaries(%q, %d) = (%d, %d), want (%d, %d)",
+					tt.line, tt.col, start, end, tt.wantStart, tt.wantEnd)
+			}
+		})
+	}
+}
+
+func TestExtractText_PlainText(t *testing.T) {
+	line := "Hello, World!"
+	text := ExtractText(line, 0, 5)
+	if text != "Hello" {
+		t.Errorf("expected 'Hello', got %q", text)
+	}
+
+	text = ExtractText(line, 7, 12)
+	if text != "World" {
+		t.Errorf("expected 'World', got %q", text)
+	}
+}
+
+func TestExtractText_FullLine(t *testing.T) {
+	line := "Hello"
+	text := ExtractText(line, -1, -1)
+	if text != "Hello" {
+		t.Errorf("expected 'Hello', got %q", text)
+	}
+}
+
+func TestExtractText_Empty(t *testing.T) {
+	text := ExtractText("", 0, 5)
+	if text != "" {
+		t.Errorf("expected empty string, got %q", text)
+	}
+}
+
+func TestExtractText_OutOfBounds(t *testing.T) {
+	line := "Hi"
+	text := ExtractText(line, 5, 10)
+	if text != "" {
+		t.Errorf("expected empty string for out of bounds, got %q", text)
+	}
+}
+
+func TestHighlightLine_PlainText(t *testing.T) {
+	line := "Hello, World!"
+	result := HighlightLine(line, 0, 5)
+	// Should produce a non-empty result different from input (has ANSI codes)
+	if result == "" {
+		t.Error("expected non-empty result")
+	}
+	// Should still contain the text content
+	if len(result) < len(line) {
+		t.Error("result should be at least as long as input (ANSI codes add length)")
+	}
+}
+
+func TestHighlightLine_Empty(t *testing.T) {
+	result := HighlightLine("", 0, 5)
+	if result != "" {
+		t.Errorf("expected empty for empty input, got %q", result)
+	}
+}
+
+func TestHighlightLine_NoSelection(t *testing.T) {
+	line := "Hello"
+	result := HighlightLine(line, 3, 3)
+	// Same startCol and endCol = no change
+	if result != line {
+		t.Errorf("expected no change for zero-width selection, got %q", result)
+	}
+}
+
+// TestMultiClickDetection verifies the click counting logic.
+func TestMultiClickDetection(t *testing.T) {
+	s := NewState()
+	now := time.Now()
+
+	// First click
+	s.LastClickTime = now
+	s.LastClickX = 10
+	s.LastClickY = 5
+	s.ClickCount = 1
+
+	// Second click within threshold
+	later := now.Add(200 * time.Millisecond)
+	if later.Sub(s.LastClickTime) <= DoubleClickThreshold {
+		if abs(10-s.LastClickX) <= ClickTolerance && abs(5-s.LastClickY) <= ClickTolerance {
+			s.ClickCount++
+		}
+	}
+	if s.ClickCount != 2 {
+		t.Errorf("expected click count 2, got %d", s.ClickCount)
+	}
+
+	// Third click
+	s.LastClickTime = later
+	later2 := later.Add(200 * time.Millisecond)
+	if later2.Sub(s.LastClickTime) <= DoubleClickThreshold {
+		if abs(10-s.LastClickX) <= ClickTolerance && abs(5-s.LastClickY) <= ClickTolerance {
+			s.ClickCount++
+		}
+	}
+	if s.ClickCount != 3 {
+		t.Errorf("expected click count 3, got %d", s.ClickCount)
+	}
+}
+
+func abs(x int) int {
+	if x < 0 {
+		return -x
+	}
+	return x
+}

internal/ui/session_selector.go

@@ -12,6 +12,7 @@ import (
 	"charm.land/lipgloss/v2"
 
 	"github.com/mark3labs/kit/internal/session"
+	"github.com/mark3labs/kit/internal/ui/style"
 )
 
 // SessionSelectedMsg is sent when the user selects a session from the picker.
@@ -158,12 +159,12 @@ func (ss *SessionSelectorComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		}
 
 		switch {
-		case key.Matches(msg, key.NewBinding(key.WithKeys("up", "k"))):
+		case key.Matches(msg, key.NewBinding(key.WithKeys("up"))):
 			if ss.cursor > 0 {
 				ss.cursor--
 			}
 
-		case key.Matches(msg, key.NewBinding(key.WithKeys("down", "j"))):
+		case key.Matches(msg, key.NewBinding(key.WithKeys("down"))):
 			if ss.cursor < len(ss.filtered)-1 {
 				ss.cursor++
 			}
@@ -250,7 +251,7 @@ func (ss *SessionSelectorComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 
 // View implements tea.Model.
 func (ss *SessionSelectorComponent) View() tea.View {
-	theme := GetTheme()
+	theme := style.GetTheme()
 	w := ss.width
 	var b strings.Builder
 
@@ -325,7 +326,9 @@ func (ss *SessionSelectorComponent) View() tea.View {
 		}
 	}
 
-	return tea.NewView(b.String())
+	v := tea.NewView(b.String())
+	v.AltScreen = true
+	return v
 }
 
 // IsActive returns whether the selector is still accepting input.
@@ -403,7 +406,7 @@ func removeByPath(sessions []session.SessionInfo, path string) []session.Session
 // renderEntry renders a single session line with right-aligned metadata.
 // Layout: [cursor 2] [message ...variable...] [padding] [count age] [cwd?]
 func (ss *SessionSelectorComponent) renderEntry(info session.SessionInfo, isCursor, isCurrent, isDeleting bool, width int) string {
-	theme := GetTheme()
+	theme := style.GetTheme()
 
 	// ── Cursor indicator (2 chars) ───────────────────────────────
 	cursorStr := "  "

internal/ui/stream.go

@@ -9,7 +9,9 @@ import (
 	tea "charm.land/bubbletea/v2"
 	"charm.land/lipgloss/v2"
 	"github.com/indaco/herald"
+
 	"github.com/mark3labs/kit/internal/app"
+	"github.com/mark3labs/kit/internal/ui/style"
 )
 
 // thinkTagRegex matches  ...  tags that some models (Qwen, DeepSeek) wrap
@@ -31,7 +33,7 @@ func knightRiderFrames() []string {
 	const numDots = 8
 	const dot = "▪"
 
-	theme := GetTheme()
+	theme := style.GetTheme()
 
 	bright := lipgloss.NewStyle().Foreground(theme.Primary)
 	med := lipgloss.NewStyle().Foreground(theme.Muted)
@@ -131,13 +133,13 @@ const (
 // alongside streaming text until the step completes and Reset() is called.
 //
 // Tool calls, tool results, user messages, and other non-streaming content
-// are printed immediately by the parent AppModel via tea.Println(). The
-// StreamComponent only handles the live streaming text and spinner display.
+// are added to the ScrollList by the parent AppModel. The StreamComponent
+// only handles the live streaming text and spinner display.
 //
 // Lifecycle is managed entirely by the parent AppModel:
 //   - Parent calls Reset() between agent steps to clear state.
-//   - Parent emits completed responses above the BT region via tea.Println()
-//     then calls Reset(); StreamComponent never calls tea.Quit.
+//   - Content is displayed via StreamingMessageItem in the ScrollList.
+//   - StreamComponent never calls tea.Quit.
 //
 // Events handled:
 //   - app.SpinnerEvent{Show:true}  → start spinner tick loop
@@ -196,15 +198,6 @@ type StreamComponent struct {
 	// ticks from a previous step can be discarded.
 	flushGeneration uint64
 
-	// renderCache holds the last rendered output string. Reused by View()
-	// between flush ticks to avoid redundant markdown re-parsing.
-	renderCache string
-
-	// renderDirty is true when committed content has changed since the
-	// last render. Set on flush tick; cleared after render() rebuilds
-	// the cache.
-	renderDirty bool
-
 	// thinkingVisible controls whether reasoning blocks are expanded or collapsed.
 	thinkingVisible bool
 
@@ -218,7 +211,7 @@ type StreamComponent struct {
 	// from models that wrap reasoning in XML-like tags (Qwen, DeepSeek).
 	inThinkTag bool
 
-	// renderer renders streaming assistant text in either compact or standard mode.
+	// renderer renders streaming assistant text.
 	renderer Renderer
 
 	// modelName is displayed in the streaming text header.
@@ -239,17 +232,12 @@ type StreamComponent struct {
 }
 
 // NewStreamComponent creates a new StreamComponent ready to be embedded in AppModel.
-func NewStreamComponent(compactMode bool, width int, modelName string) *StreamComponent {
+func NewStreamComponent(width int, modelName string) *StreamComponent {
 	if width == 0 {
 		width = 80
 	}
 
-	var renderer Renderer
-	if compactMode {
-		renderer = NewCompactRenderer(width, false)
-	} else {
-		renderer = newMessageRenderer(width, false)
-	}
+	renderer := newMessageRenderer(width, false)
 
 	return &StreamComponent{
 		spinnerFrames: knightRiderFrames(),
@@ -269,9 +257,6 @@ func (s *StreamComponent) SetHeight(h int) {
 	}
 	if s.height != h {
 		s.height = h
-		// Invalidate cache — height clamp affects output.
-		s.renderCache = ""
-		s.renderDirty = true
 	}
 }
 
@@ -290,16 +275,20 @@ func (s *StreamComponent) Reset() {
 	s.pendingReasoning.Reset()
 	s.flushPending = false
 	s.flushGeneration++
-	s.renderCache = ""
-	s.renderDirty = false
 	s.timestamp = time.Time{}
 	s.reasoningStartTime = time.Time{}
 	s.reasoningDuration = 0
 }
 
+// ConsumeOverflow is a no-op in alt screen mode. Overflow is handled by the
+// ScrollList viewport. Retained to satisfy streamComponentIface.
+func (s *StreamComponent) ConsumeOverflow() string {
+	return ""
+}
+
 // GetRenderedContent returns the rendered assistant message from the accumulated
 // streaming text. Returns empty string if no text has been accumulated. Used by
-// the parent AppModel to flush content via tea.Println() before resetting.
+// the parent AppModel to flush stream content before resetting.
 //
 // This commits any pending chunks first so the output includes all received
 // content, not just what has been flushed by the tick.
@@ -327,19 +316,17 @@ func (s *StreamComponent) GetRenderedContent() string {
 }
 
 // commitPending moves any pending chunks to the committed content builders.
-// Called before reading content for scrollback output or on flush tick.
+// Called before reading content for output or on flush tick.
 func (s *StreamComponent) commitPending() {
 	if s.pendingStream.Len() > 0 {
 		// Strip  ...  tags that some models wrap reasoning in
 		cleanedText := thinkTagRegex.ReplaceAllString(s.pendingStream.String(), "")
 		s.streamContent.WriteString(cleanedText)
 		s.pendingStream.Reset()
-		s.renderDirty = true
 	}
 	if s.pendingReasoning.Len() > 0 {
 		s.reasoningContent.WriteString(s.pendingReasoning.String())
 		s.pendingReasoning.Reset()
-		s.renderDirty = true
 	}
 }
 
@@ -362,9 +349,6 @@ func (s *StreamComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		if s.renderer != nil {
 			s.renderer.SetWidth(s.width)
 		}
-		// Invalidate render cache — width change affects wrapping/styling.
-		s.renderCache = ""
-		s.renderDirty = true
 
 	case streamSpinnerTickMsg:
 		// Only continue the tick loop if this tick belongs to the current
@@ -504,72 +488,10 @@ func (s *StreamComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 	return s, nil
 }
 
-// View implements tea.Model. Renders the current stream region content.
+// View implements tea.Model. Returns an empty view since rendering is handled
+// by StreamingMessageItem in the ScrollList. Retained to satisfy tea.Model.
 func (s *StreamComponent) View() tea.View {
-	fullContent := s.render()
-	visibleContent := s.viewContent(fullContent)
-	return tea.NewView(visibleContent)
-}
-
-// --------------------------------------------------------------------------
-// Internal rendering
-// --------------------------------------------------------------------------
-
-// render builds the full content string for the stream region. Uses a render
-// cache to avoid redundant markdown re-parsing between flush ticks. The cache
-// is invalidated when committed content changes (flush tick), terminal width
-// changes, or height/thinking visibility changes.
-func (s *StreamComponent) render() string {
-	if s.phase == streamPhaseIdle {
-		return ""
-	}
-
-	// Return cached render if committed content hasn't changed.
-	if !s.renderDirty {
-		return s.renderCache
-	}
-
-	var sections []string
-
-	// Render reasoning/thinking block above the main text if present.
-	if reasoning := s.reasoningContent.String(); reasoning != "" {
-		sections = append(sections, s.renderReasoningBlock(reasoning))
-	}
-
-	// Render streaming text only. The spinner is rendered in the status bar
-	// by the parent so it never changes the stream region height.
-	text := s.streamContent.String()
-	if text != "" {
-		sections = append(sections, s.renderStreamingText(text))
-	}
-
-	if len(sections) == 0 {
-		s.renderCache = ""
-		s.renderDirty = false
-		return ""
-	}
-
-	content := strings.Join(sections, "\n")
-
-	// Cache FULL content without height clamping.
-	// Height clamping is applied in View() for display only.
-	s.renderCache = content
-	s.renderDirty = false
-	return content
-}
-
-// viewContent returns the visible portion of content based on height constraint.
-// This is called by View() to get the slice that fits in the terminal.
-func (s *StreamComponent) viewContent(fullContent string) string {
-	if s.height > 0 && fullContent != "" {
-		lines := strings.Split(fullContent, "\n")
-		if len(lines) > s.height {
-			// Keep only the last h lines so the most recent output is visible.
-			lines = lines[len(lines)-s.height:]
-			return strings.Join(lines, "\n")
-		}
-	}
-	return fullContent
+	return tea.NewView("")
 }
 
 // renderReasoningBlock renders the reasoning/thinking content using blockquote.
@@ -630,9 +552,6 @@ func (s *StreamComponent) renderReasoningBlock(reasoning string) string {
 func (s *StreamComponent) SetThinkingVisible(visible bool) {
 	if s.thinkingVisible != visible {
 		s.thinkingVisible = visible
-		// Invalidate cache — thinking visibility affects rendered output.
-		s.renderCache = ""
-		s.renderDirty = true
 	}
 }
 
@@ -709,3 +628,9 @@ func removeToolID(ids []string, id string) []string {
 func formatToolExecutionMessage(toolName string) string {
 	return toolName
 }
+
+// UpdateTheme refreshes the component's typography instance with colors from
+// the current theme. This is called when the user changes themes via /theme.
+func (s *StreamComponent) UpdateTheme() {
+	s.ty = createTypography(GetTheme())
+}

internal/ui/style/enhanced.go

@@ -1,4 +1,4 @@
-package ui
+package style
 
 import (
 	"fmt"
@@ -294,3 +294,28 @@ func ApplyGradient(text string, colorA, colorB color.Color) string {
 
 	return result.String()
 }
+
+// KitBanner returns the KIT ASCII art title with KITT scanner lights,
+// rendered with a KITT red gradient.
+func KitBanner() string {
+	kittDark := lipgloss.Color("#8B0000")
+	kittBright := lipgloss.Color("#FF2200")
+	lines := []string{
+		"            ██╗  ██╗ ██╗ ████████╗",
+		"            ██║ ██╔╝ ██║ ╚══██╔══╝",
+		"            █████╔╝  ██║    ██║",
+		"            ██╔═██╗  ██║    ██║",
+		"            ██║  ██╗ ██║    ██║",
+		"            ╚═╝  ╚═╝ ╚═╝    ╚═╝",
+		" ░░░░░░▒▒▒▒▒▓▓▓▓███████████████▓▓▓▓▒▒▒▒▒░░░░░░",
+	}
+
+	var result strings.Builder
+	for i, line := range lines {
+		if i > 0 {
+			result.WriteString("\n")
+		}
+		result.WriteString(ApplyGradient(line, kittDark, kittBright))
+	}
+	return result.String()
+}

internal/ui/style/styles.go

@@ -1,4 +1,4 @@
-package ui
+package style
 
 import (
 	"charm.land/lipgloss/v2"
@@ -85,10 +85,10 @@ func GetMarkdownTypography() *herald.Typography {
 	return ty
 }
 
-// toMarkdown renders markdown content using herald-md.
+// ToMarkdown renders markdown content using herald-md.
 // The width parameter is currently unused as herald handles wrapping
 // based on terminal width internally.
-func toMarkdown(content string, width int) string {
+func ToMarkdown(content string, width int) string {
 	ty := GetMarkdownTypography()
 	rendered := heraldmd.Render(ty, []byte(content))
 	return rendered

internal/ui/style/themes.go

@@ -1,4 +1,4 @@
-package ui
+package style
 
 import (
 	"encoding/json"
@@ -11,6 +11,8 @@ import (
 	"strings"
 
 	"gopkg.in/yaml.v3"
+
+	"github.com/mark3labs/kit/internal/ui/prefs"
 )
 
 // ---------------------------------------------------------------------------
@@ -410,10 +412,10 @@ func initThemeRegistry() {
 	}
 
 	// 2. User themes from ~/.config/kit/themes/
-	scanThemesDir(userThemesDir())
+	scanThemesDir(UserThemesDir())
 
 	// 3. Project-local themes from .kit/themes/
-	scanThemesDir(projectThemesDir())
+	scanThemesDir(ProjectThemesDir())
 
 	sortRegistry()
 }
@@ -461,7 +463,7 @@ func removeFromRegistry(name string) {
 }
 
 // userThemesDir returns ~/.config/kit/themes, creating it if needed.
-func userThemesDir() string {
+func UserThemesDir() string {
 	cfgDir, err := os.UserConfigDir()
 	if err != nil {
 		return ""
@@ -473,7 +475,7 @@ func userThemesDir() string {
 
 // projectThemesDir returns .kit/themes/ relative to the working directory.
 // Returns "" if the directory doesn't exist (does NOT create it).
-func projectThemesDir() string {
+func ProjectThemesDir() string {
 	dir := filepath.Join(".kit", "themes")
 	info, err := os.Stat(dir)
 	if err != nil || !info.IsDir() {
@@ -525,7 +527,7 @@ func ApplyTheme(name string) error {
 		return err
 	}
 	SetTheme(t)
-	_ = SaveThemePreference(name)
+	_ = prefs.SaveThemePreference(name)
 	return nil
 }
 

internal/ui/style/themes_test.go

@@ -1,4 +1,4 @@
-package ui
+package style
 
 import (
 	"testing"

internal/ui/tool_approval_input.go

@@ -86,6 +86,7 @@ func (t *ToolApprovalInput) View() tea.View {
 	if t.done {
 		return tea.NewView("we are done")
 	}
+
 	containerStyle := lipgloss.NewStyle()
 
 	theme := GetTheme()

internal/ui/tool_renderers.go

@@ -29,8 +29,7 @@ const (
 )
 
 // isShellTool reports if the tool name matches a shell-like tool (bash, grep, find, or
-// tools with "shell"/"command" in the name). Used by both renderToolBody and
-// renderToolBodyCompact to avoid code duplication.
+// tools with "shell"/"command" in the name). Used by renderToolBody.
 func isShellTool(toolName string) bool {
 	return toolName == "bash" || toolName == "grep" || toolName == "find" ||
 		strings.Contains(toolName, "shell") || strings.Contains(toolName, "command")
@@ -738,183 +737,6 @@ func truncateLine(s string, maxWidth int) string {
 	return xansi.Truncate(s, maxWidth, "…")
 }
 
-// ---------------------------------------------------------------------------
-// Compact tool body renderers — one-line summaries for compact mode
-// ---------------------------------------------------------------------------
-
-// renderToolBodyCompact returns a brief summary string for tool results in
-// compact display mode. Returns empty string to fall back to default.
-func renderToolBodyCompact(toolName, toolArgs, toolResult string, width int) string {
-	switch {
-	case toolName == "edit":
-		return renderEditCompact(toolArgs, toolResult)
-	case toolName == "ls":
-		return renderLsCompact(toolResult)
-	case toolName == "read":
-		return renderReadCompact(toolResult)
-	case toolName == "write":
-		return renderWriteCompact(toolArgs)
-	case isShellTool(toolName):
-		return renderBashCompact(toolResult, width)
-	case toolName == "subagent":
-		return renderSubagentCompact(toolResult)
-	}
-	return ""
-}
-
-// renderReadCompact returns a line-count summary for Read tool output.
-func renderReadCompact(toolResult string) string {
-	content := strings.TrimSpace(toolResult)
-	if content == "" {
-		return ""
-	}
-
-	lines := strings.Split(content, "\n")
-
-	// Count actual code lines (those with "N: " line-number prefix)
-	codeLines := 0
-	for _, line := range lines {
-		if idx := strings.Index(line, ": "); idx > 0 && idx <= 7 {
-			numPart := line[:idx]
-			if _, err := strconv.Atoi(strings.TrimSpace(numPart)); err == nil {
-				codeLines++
-			}
-		}
-	}
-	if codeLines == 0 {
-		return ""
-	}
-
-	theme := GetTheme()
-	summary := fmt.Sprintf("%d lines", codeLines)
-	return lipgloss.NewStyle().Foreground(theme.Muted).Italic(true).Render(summary)
-}
-
-// renderEditCompact returns a change-count summary for Edit tool output.
-func renderEditCompact(toolArgs, toolResult string) string {
-	var args map[string]any
-	if err := json.Unmarshal([]byte(toolArgs), &args); err != nil {
-		return ""
-	}
-
-	oldText, _ := args["old_text"].(string)
-	newText, _ := args["new_text"].(string)
-	if oldText == "" && newText == "" {
-		return ""
-	}
-
-	oldCount := len(strings.Split(oldText, "\n"))
-	newCount := len(strings.Split(newText, "\n"))
-
-	theme := GetTheme()
-	var summary string
-	if oldCount == newCount {
-		summary = fmt.Sprintf("%d lines modified", oldCount)
-	} else {
-		summary = fmt.Sprintf("-%d/+%d lines", oldCount, newCount)
-	}
-	return lipgloss.NewStyle().Foreground(theme.Muted).Italic(true).Render(summary)
-}
-
-// renderWriteCompact returns a line-count summary for Write tool output.
-func renderWriteCompact(toolArgs string) string {
-	var args map[string]any
-	if err := json.Unmarshal([]byte(toolArgs), &args); err != nil {
-		return ""
-	}
-
-	content, _ := args["content"].(string)
-	if content == "" {
-		return ""
-	}
-
-	count := len(strings.Split(content, "\n"))
-	theme := GetTheme()
-	summary := fmt.Sprintf("%d lines written", count)
-	return lipgloss.NewStyle().Foreground(theme.Muted).Italic(true).Render(summary)
-}
-
-// renderLsCompact returns an entry-count summary for Ls tool output.
-func renderLsCompact(toolResult string) string {
-	content := strings.TrimSpace(toolResult)
-	if content == "" {
-		return ""
-	}
-
-	entries := strings.Split(content, "\n")
-	theme := GetTheme()
-	summary := fmt.Sprintf("%d entries", len(entries))
-	return lipgloss.NewStyle().Foreground(theme.Muted).Italic(true).Render(summary)
-}
-
-// renderBashCompact returns the first few lines of bash output as a compact
-// summary. Shows up to 3 meaningful output lines.
-func renderBashCompact(toolResult string, width int) string {
-	result := strings.TrimSpace(toolResult)
-	if result == "" {
-		return ""
-	}
-
-	lines := strings.Split(result, "\n")
-
-	// Filter to meaningful output lines (skip STDERR: label, keep exit codes separate)
-	var outputLines []string
-	var exitCode string
-	inStderr := false
-	for _, line := range lines {
-		trimmed := strings.TrimSpace(line)
-		if trimmed == "STDERR:" {
-			inStderr = true
-			continue
-		}
-		if strings.HasPrefix(trimmed, "Exit code:") {
-			exitCode = trimmed
-			continue
-		}
-		if trimmed == "" {
-			continue
-		}
-		outputLines = append(outputLines, line)
-		_ = inStderr // stderr lines are included in output
-	}
-
-	if len(outputLines) == 0 {
-		if exitCode != "" {
-			theme := GetTheme()
-			return lipgloss.NewStyle().Foreground(theme.Error).Render(exitCode)
-		}
-		return ""
-	}
-
-	const maxLines = 3
-	theme := GetTheme()
-
-	display := outputLines
-	if len(display) > maxLines {
-		display = display[:maxLines]
-	}
-
-	// Truncate each line to available width (ANSI-aware)
-	lineMax := max(width-4, 20)
-	for i, line := range display {
-		display[i] = truncateLine(line, lineMax)
-	}
-
-	summary := strings.Join(display, "\n")
-	if len(outputLines) > maxLines {
-		summary += fmt.Sprintf("\n...(%d more lines)", len(outputLines)-maxLines)
-	}
-	if exitCode != "" {
-		summary += "\n" + lipgloss.NewStyle().Foreground(theme.Error).Render(exitCode)
-	}
-
-	return lipgloss.NewStyle().Foreground(theme.Muted).Render(summary)
-}
-
-// ---------------------------------------------------------------------------
-// Subagent tool renderers — show only summary, not full output
-// ---------------------------------------------------------------------------
-
 // renderSubagentBody renders a clean summary of subagent results with bash-style
 // background styling for consistency with other tools.
 func renderSubagentBody(toolResult string, width int) string {
@@ -1026,27 +848,3 @@ func extractSubagentPreviewLines(content string, maxLines, maxWidth int) []strin
 
 	return preview
 }
-
-// renderSubagentCompact returns a brief one-line summary for subagent results.
-func renderSubagentCompact(toolResult string) string {
-	result := strings.TrimSpace(toolResult)
-	if result == "" {
-		return ""
-	}
-
-	theme := GetTheme()
-
-	// Extract just the first line which contains the status
-	lines := strings.Split(result, "\n")
-	if len(lines) == 0 {
-		return ""
-	}
-
-	statusLine := lines[0]
-
-	// Make it more compact by removing redundant words
-	statusLine = strings.Replace(statusLine, "Subagent completed successfully in ", "Completed in ", 1)
-	statusLine = strings.Replace(statusLine, "Subagent failed", "Failed", 1)
-
-	return lipgloss.NewStyle().Foreground(theme.Muted).Italic(true).Render(statusLine)
-}

internal/ui/tree_selector.go

@@ -10,6 +10,7 @@ import (
 	"charm.land/lipgloss/v2"
 
 	"github.com/mark3labs/kit/internal/session"
+	"github.com/mark3labs/kit/internal/ui/core"
 )
 
 // TreeFilterMode controls which entries are visible in the tree selector.
@@ -88,6 +89,28 @@ func NewTreeSelector(tm *session.TreeManager, width, height int) *TreeSelectorCo
 	return ts
 }
 
+// NewTreeSelectorForFork creates a tree selector for the /fork command.
+// It shows only user messages (flat list) matching Pi's fork behavior.
+func NewTreeSelectorForFork(tm *session.TreeManager, width, height int) *TreeSelectorComponent {
+	ts := &TreeSelectorComponent{
+		tm:     tm,
+		filter: TreeFilterUserOnly,
+		leafID: tm.GetLeafID(),
+		width:  width,
+		height: height,
+		active: true,
+	}
+	ts.rebuildFlatList()
+	// Position cursor at the last user message before the leaf.
+	for i := len(ts.flatNodes) - 1; i >= 0; i-- {
+		if ts.isUserMessage(ts.flatNodes[i].Entry) {
+			ts.cursor = i
+			break
+		}
+	}
+	return ts
+}
+
 // Init implements tea.Model.
 func (ts *TreeSelectorComponent) Init() tea.Cmd {
 	return nil
@@ -103,12 +126,12 @@ func (ts *TreeSelectorComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 
 	case tea.KeyPressMsg:
 		switch {
-		case key.Matches(msg, key.NewBinding(key.WithKeys("up", "k"))):
+		case key.Matches(msg, key.NewBinding(key.WithKeys("up"))):
 			if ts.cursor > 0 {
 				ts.cursor--
 			}
 
-		case key.Matches(msg, key.NewBinding(key.WithKeys("down", "j"))):
+		case key.Matches(msg, key.NewBinding(key.WithKeys("down"))):
 			if ts.cursor < len(ts.flatNodes)-1 {
 				ts.cursor++
 			}
@@ -138,7 +161,7 @@ func (ts *TreeSelectorComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 				ts.selectedID = ts.flatNodes[ts.cursor].ID
 				ts.active = false
 				return ts, func() tea.Msg {
-					return TreeNodeSelectedMsg{
+					return core.TreeNodeSelectedMsg{
 						ID:       ts.selectedID,
 						Entry:    ts.flatNodes[ts.cursor].Entry,
 						IsUser:   ts.isUserMessage(ts.flatNodes[ts.cursor].Entry),
@@ -155,7 +178,7 @@ func (ts *TreeSelectorComponent) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 				ts.cancelled = true
 				ts.active = false
 				return ts, func() tea.Msg {
-					return TreeCancelledMsg{}
+					return core.TreeCancelledMsg{}
 				}
 			}
 
@@ -265,7 +288,9 @@ func (ts *TreeSelectorComponent) View() tea.View {
 	footer := fmt.Sprintf("(%d/%d) [%s]", ts.cursor+1, len(ts.flatNodes), ts.filter)
 	b.WriteString(footerStyle.Render(footer))
 
-	return tea.NewView(b.String())
+	v := tea.NewView(b.String())
+	v.AltScreen = true
+	return v
 }
 
 // IsActive returns whether the tree selector is still accepting input.

npm/package-lock.json

@@ -0,0 +1,29 @@
+{
+  "name": "@mark3labs/kit",
+  "version": "0.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@mark3labs/kit",
+      "version": "0.0.0",
+      "cpu": [
+        "x64",
+        "arm64"
+      ],
+      "hasInstallScript": true,
+      "license": "MIT",
+      "os": [
+        "darwin",
+        "linux",
+        "win32"
+      ],
+      "bin": {
+        "kit": "bin/kit"
+      },
+      "engines": {
+        "node": ">=16"
+      }
+    }
+  }
+}

pkg/kit/README.md

@@ -134,12 +134,16 @@ kit.Message, kit.MessageRole, kit.ContentPart
 kit.TextContent, kit.ReasoningContent, kit.ToolCall, kit.ToolResult, kit.Finish
 kit.RoleUser, kit.RoleAssistant, kit.RoleTool, kit.RoleSystem
 
-// LLM types (re-exported from the underlying LLM library)
-kit.LLMMessage, kit.LLMUsage, kit.LLMResponse, kit.LLMFilePart
+// LLM types — concrete Kit-owned structs, no external library dependency
+kit.LLMMessage      // {Role LLMMessageRole, Content string}
+kit.LLMMessageRole  // "user" | "assistant" | "system" | "tool"
+kit.LLMUsage        // {InputTokens, OutputTokens, TotalTokens, ...}
+kit.LLMResponse     // {Content, FinishReason, Usage}
+kit.LLMFilePart     // {Filename, Data []byte, MediaType}
 
 // Conversion helpers
-msgs := kit.ConvertToLLMMessages(&msg)   // SDK message → LLM messages
-msg := kit.ConvertFromLLMMessage(fMsg)    // LLM message → SDK message
+msgs := kit.ConvertToLLMMessages(&msg)   // SDK Message → []LLMMessage
+msg  := kit.ConvertFromLLMMessage(lMsg)  // LLMMessage  → SDK Message
 ```
 
 ## API Reference

pkg/kit/compaction.go

@@ -5,8 +5,6 @@ import (
 	"errors"
 	"fmt"
 
-	"charm.land/fantasy"
-
 	"github.com/mark3labs/kit/internal/compaction"
 )
 
@@ -155,7 +153,15 @@ func (m *Kit) compactInternal(ctx context.Context, opts *CompactionOptions, cust
 	}
 
 	model := m.agent.GetModel()
-	result, _, err := compaction.Compact(ctx, model, messages, *opts, customInstructions, prev)
+
+	// Create a streaming callback to emit chunks as events.
+	streamCallback := func(delta string) error {
+		// Emit MessageUpdateEvent to the UI for streaming display.
+		m.events.emit(MessageUpdateEvent{Chunk: delta})
+		return nil
+	}
+
+	result, _, err := compaction.Compact(ctx, model, messages, *opts, customInstructions, prev, streamCallback)
 	if err != nil {
 		return nil, err
 	}
@@ -181,7 +187,7 @@ func (m *Kit) compactInternal(ctx context.Context, opts *CompactionOptions, cust
 // applyCustomCompaction handles compaction when an extension provides a
 // custom summary. It still determines the cut point and persists a
 // CompactionEntry.
-func (m *Kit) applyCustomCompaction(summary string, messages []fantasy.Message, opts *CompactionOptions) (*CompactionResult, error) {
+func (m *Kit) applyCustomCompaction(summary string, messages []LLMMessage, opts *CompactionOptions) (*CompactionResult, error) {
 	originalTokens := compaction.EstimateMessageTokens(messages)
 
 	cutPoint := compaction.FindCutPoint(messages, opts.KeepRecentTokens)
@@ -199,9 +205,9 @@ func (m *Kit) applyCustomCompaction(summary string, messages []fantasy.Message,
 	}
 
 	// Estimate new token count.
-	summaryTokens := compaction.EstimateMessageTokens([]fantasy.Message{{
-		Role:    "system",
-		Content: []fantasy.MessagePart{fantasy.TextPart{Text: summary}},
+	summaryTokens := compaction.EstimateMessageTokens([]LLMMessage{{
+		Role:    LLMRoleSystem,
+		Content: []LLMMessagePart{LLMTextPart{Text: summary}},
 	}})
 	recentTokens := compaction.EstimateMessageTokens(messages[cutPoint:])
 	compactedTokens := summaryTokens + recentTokens
@@ -249,3 +255,5 @@ func (m *Kit) persistAndEmitCompaction(
 	})
 	return nil
 }
+
+// Conversion helpers are in llm_convert.go.

pkg/kit/extensions_bridge.go

@@ -4,7 +4,6 @@ import (
 	"strings"
 	"sync"
 
-	"charm.land/fantasy"
 	"github.com/mark3labs/kit/internal/extensions"
 )
 
@@ -248,19 +247,19 @@ func (m *Kit) bridgeExtensions(runner *extensions.Runner) {
 	if runner.HasHandlers(extensions.ContextPrepare) {
 		m.OnContextPrepare(HookPriorityNormal, func(h ContextPrepareHook) *ContextPrepareResult {
 			// Convert LLM message slice to extension ContextMessage slice.
+			// Extract plain text from each message for the extension API.
 			extMsgs := make([]extensions.ContextMessage, len(h.Messages))
 			for i, msg := range h.Messages {
-				// Extract text from content parts.
-				var text strings.Builder
+				var sb strings.Builder
 				for _, part := range msg.Content {
-					if tp, ok := part.(fantasy.TextPart); ok {
-						text.WriteString(tp.Text)
+					if tp, ok := part.(LLMTextPart); ok {
+						sb.WriteString(tp.Text)
 					}
 				}
 				extMsgs[i] = extensions.ContextMessage{
 					Index:   i,
 					Role:    string(msg.Role),
-					Content: text.String(),
+					Content: sb.String(),
 				}
 			}
 
@@ -271,27 +270,25 @@ func (m *Kit) bridgeExtensions(runner *extensions.Runner) {
 			}
 
 			// Rebuild LLM message slice from extension result.
-			rebuilt := make([]fantasy.Message, 0, len(r.Messages))
+			rebuilt := make([]LLMMessage, 0, len(r.Messages))
 			for _, cm := range r.Messages {
 				if cm.Index >= 0 && cm.Index < len(h.Messages) {
-					// Reuse original message (preserves tool calls, reasoning, etc.)
+					// Reuse original message (preserves original role and content).
 					rebuilt = append(rebuilt, h.Messages[cm.Index])
 				} else {
-					// New message injected by extension.
-					role := fantasy.MessageRoleUser
+					// New message injected by extension — construct from role + text.
+					role := LLMRoleUser
 					switch cm.Role {
 					case "assistant":
-						role = fantasy.MessageRoleAssistant
+						role = LLMRoleAssistant
 					case "system":
-						role = fantasy.MessageRoleSystem
+						role = LLMRoleSystem
 					case "tool":
-						role = fantasy.MessageRoleTool
+						role = LLMRoleTool
 					}
-					rebuilt = append(rebuilt, fantasy.Message{
-						Role: role,
-						Content: []fantasy.MessagePart{
-							fantasy.TextPart{Text: cm.Content},
-						},
+					rebuilt = append(rebuilt, LLMMessage{
+						Role:    role,
+						Content: []LLMMessagePart{LLMTextPart{Text: cm.Content}},
 					})
 				}
 			}

pkg/kit/hooks.go

@@ -83,14 +83,14 @@ type AfterTurnResult struct{}
 // messages are sent to the LLM. Hooks can filter, reorder, or inject messages.
 type ContextPrepareHook struct {
 	// Messages is the current context as LLM message objects.
-	Messages []fantasy.Message
+	Messages []LLMMessage
 }
 
 // ContextPrepareResult can replace the context window.
 type ContextPrepareResult struct {
 	// Messages replaces the entire context window. If nil, the original
 	// messages are used.
-	Messages []fantasy.Message
+	Messages []LLMMessage
 }
 
 // BeforeCompactHook is the input for hooks that fire before compaction runs.

pkg/kit/kit.go

@@ -831,6 +831,7 @@ type TurnResult struct {
 
 	// Messages is the full updated conversation after the turn, including
 	// any tool call/result messages added during the agent loop.
+	// Each message carries role and plain-text content.
 	Messages []LLMMessage
 }
 

pkg/kit/types.go

@@ -127,21 +127,74 @@ type ModelsRegistry = models.ModelsRegistry
 type SpinnerFunc = agent.SpinnerFunc
 
 // ==== LLM Types ====
+//
+// These are type aliases for the corresponding charm.land/fantasy types,
+// giving them clean LLM-prefixed names without leaking the dependency name.
+// SDK consumers can use these types without importing charm.land/fantasy directly.
 
-// LLMMessage is the underlying message type used by the LLM agent
-// library. Re-exported so SDK users can work with LLM types without a
-// direct import of the underlying LLM library.
+// LLMMessage represents a message in an LLM conversation, carrying a role
+// and a slice of typed content parts (text, tool calls, reasoning, etc.).
 type LLMMessage = fantasy.Message
 
-// LLMUsage contains token usage information from an LLM response.
+// LLMMessagePart is the interface implemented by all LLM message content parts.
+type LLMMessagePart = fantasy.MessagePart
+
+// LLMFilePart represents a file attachment (image, document, audio, etc.)
+// that can be included in a multimodal prompt via PromptResultWithFiles.
+type LLMFilePart = fantasy.FilePart
+
+// LLMUsage contains token usage information returned by the LLM provider.
 type LLMUsage = fantasy.Usage
 
-// LLMResponse is the response type returned by the LLM agent library.
+// LLMResponse represents a complete response from the LLM provider.
 type LLMResponse = fantasy.Response
 
-// LLMFilePart represents a file attachment (image, document, etc.) that can
-// be included in a prompt via PromptResultWithFiles.
-type LLMFilePart = fantasy.FilePart
+// LLMTextPart is a plain-text content part for constructing LLM messages.
+type LLMTextPart = fantasy.TextPart
+
+// LLMReasoningPart is a reasoning/chain-of-thought content part.
+type LLMReasoningPart = fantasy.ReasoningPart
+
+// LLMToolCallPart represents an LLM-initiated tool invocation within a message.
+type LLMToolCallPart = fantasy.ToolCallPart
+
+// LLMToolResultPart represents the result of a tool execution within a message.
+type LLMToolResultPart = fantasy.ToolResultPart
+
+// LLMToolResultOutputContent is the interface for tool result output content.
+type LLMToolResultOutputContent = fantasy.ToolResultOutputContent
+
+// LLMToolResultOutputContentText is a text-valued tool result output.
+type LLMToolResultOutputContentText = fantasy.ToolResultOutputContentText
+
+// LLMToolResultOutputContentError is an error-valued tool result output.
+type LLMToolResultOutputContentError = fantasy.ToolResultOutputContentError
+
+// LLMMessageRole identifies the participant role in an LLM conversation.
+type LLMMessageRole = fantasy.MessageRole
+
+// LLMFinishReason indicates why the LLM stopped generating.
+type LLMFinishReason = fantasy.FinishReason
+
+// LLM role constants mirror fantasy.MessageRole* values under clean LLM-prefixed names.
+const (
+	// LLMRoleUser identifies a user message.
+	LLMRoleUser = fantasy.MessageRoleUser
+	// LLMRoleAssistant identifies an assistant message.
+	LLMRoleAssistant = fantasy.MessageRoleAssistant
+	// LLMRoleSystem identifies a system message.
+	LLMRoleSystem = fantasy.MessageRoleSystem
+	// LLMRoleTool identifies a tool result message.
+	LLMRoleTool = fantasy.MessageRoleTool
+)
+
+// NewLLMUserMessage constructs a user-role LLMMessage with optional file
+// attachments. It is equivalent to fantasy.NewUserMessage.
+var NewLLMUserMessage = fantasy.NewUserMessage
+
+// NewLLMSystemMessage constructs a system-role LLMMessage from one or more
+// prompt strings. It is equivalent to fantasy.NewSystemMessage.
+var NewLLMSystemMessage = fantasy.NewSystemMessage
 
 // ==== Compaction Types (internal/compaction/) ====
 
@@ -177,24 +230,13 @@ func LoadSystemPrompt(pathOrContent string) (string, error) {
 
 // ==== Conversion Helpers ====
 
-// ConvertToLLMMessages converts an SDK message to the underlying LLM
-// messages used by the agent for LLM interactions.
-func ConvertToLLMMessages(msg *Message) []fantasy.Message {
+// ConvertToLLMMessages converts an SDK message to a slice of LLMMessages.
+// Each SDK message may expand to multiple LLM messages depending on its content.
+func ConvertToLLMMessages(msg *Message) []LLMMessage {
 	return msg.ToLLMMessages()
 }
 
-// ConvertFromLLMMessage converts an LLM message from the agent to an SDK
-// message format for use in the SDK API.
-func ConvertFromLLMMessage(msg fantasy.Message) Message {
+// ConvertFromLLMMessage converts an LLMMessage to an SDK message.
+func ConvertFromLLMMessage(msg LLMMessage) Message {
 	return message.FromLLMMessage(msg)
 }
-
-// Deprecated: Use ConvertToLLMMessages instead.
-func ConvertToFantasyMessages(msg *Message) []fantasy.Message {
-	return ConvertToLLMMessages(msg)
-}
-
-// Deprecated: Use ConvertFromLLMMessage instead.
-func ConvertFromFantasyMessage(msg fantasy.Message) Message {
-	return ConvertFromLLMMessage(msg)
-}

pkg/kit/types_test.go

@@ -1,6 +1,7 @@
 package kit_test
 
 import (
+	"encoding/json"
 	"testing"
 
 	kit "github.com/mark3labs/kit/pkg/kit"
@@ -59,3 +60,218 @@ func TestTypeExports(t *testing.T) {
 		t.Errorf("round-trip Content() = %q, want %q", roundTrip.Content(), "test")
 	}
 }
+
+// TestLLMRoleConstants verifies the LLM role constants have the correct values.
+func TestLLMRoleConstants(t *testing.T) {
+	if kit.LLMRoleUser != "user" {
+		t.Errorf("LLMRoleUser = %q, want %q", kit.LLMRoleUser, "user")
+	}
+	if kit.LLMRoleAssistant != "assistant" {
+		t.Errorf("LLMRoleAssistant = %q, want %q", kit.LLMRoleAssistant, "assistant")
+	}
+	if kit.LLMRoleSystem != "system" {
+		t.Errorf("LLMRoleSystem = %q, want %q", kit.LLMRoleSystem, "system")
+	}
+	if kit.LLMRoleTool != "tool" {
+		t.Errorf("LLMRoleTool = %q, want %q", kit.LLMRoleTool, "tool")
+	}
+}
+
+// TestLLMMessageAlias verifies LLMMessage is a type alias for fantasy.Message
+// and can be used interchangeably.
+func TestLLMMessageAlias(t *testing.T) {
+	// Construct an LLMMessage using alias types.
+	msg := kit.LLMMessage{
+		Role: kit.LLMRoleUser,
+		Content: []kit.LLMMessagePart{
+			kit.LLMTextPart{Text: "hello world"},
+		},
+	}
+	if msg.Role != "user" {
+		t.Errorf("LLMMessage.Role = %q, want %q", msg.Role, "user")
+	}
+	// Verify we can extract text via the part types.
+	if len(msg.Content) != 1 {
+		t.Fatalf("expected 1 content part, got %d", len(msg.Content))
+	}
+	tp, ok := msg.Content[0].(kit.LLMTextPart)
+	if !ok {
+		t.Fatal("content part is not LLMTextPart")
+	}
+	if tp.Text != "hello world" {
+		t.Errorf("LLMTextPart.Text = %q, want %q", tp.Text, "hello world")
+	}
+}
+
+// TestNewLLMUserMessage verifies the NewLLMUserMessage constructor works.
+func TestNewLLMUserMessage(t *testing.T) {
+	msg := kit.NewLLMUserMessage("hello from user")
+	if msg.Role != kit.LLMRoleUser {
+		t.Errorf("NewLLMUserMessage role = %q, want %q", msg.Role, kit.LLMRoleUser)
+	}
+	if len(msg.Content) == 0 {
+		t.Fatal("NewLLMUserMessage content is empty")
+	}
+	tp, ok := msg.Content[0].(kit.LLMTextPart)
+	if !ok {
+		t.Fatal("content[0] is not LLMTextPart")
+	}
+	if tp.Text != "hello from user" {
+		t.Errorf("NewLLMUserMessage text = %q, want %q", tp.Text, "hello from user")
+	}
+}
+
+// TestNewLLMSystemMessage verifies the NewLLMSystemMessage constructor works.
+func TestNewLLMSystemMessage(t *testing.T) {
+	msg := kit.NewLLMSystemMessage("you are helpful")
+	if msg.Role != kit.LLMRoleSystem {
+		t.Errorf("NewLLMSystemMessage role = %q, want %q", msg.Role, kit.LLMRoleSystem)
+	}
+	if len(msg.Content) == 0 {
+		t.Fatal("NewLLMSystemMessage content is empty")
+	}
+}
+
+// TestLLMUsageAlias verifies LLMUsage is a type alias for fantasy.Usage
+// and carries the correct fields.
+func TestLLMUsageAlias(t *testing.T) {
+	u := kit.LLMUsage{
+		InputTokens:         100,
+		OutputTokens:        50,
+		TotalTokens:         150,
+		ReasoningTokens:     10,
+		CacheCreationTokens: 5,
+		CacheReadTokens:     20,
+	}
+	if u.InputTokens != 100 {
+		t.Errorf("LLMUsage.InputTokens = %d, want 100", u.InputTokens)
+	}
+	if u.TotalTokens != 150 {
+		t.Errorf("LLMUsage.TotalTokens = %d, want 150", u.TotalTokens)
+	}
+
+	// Verify JSON marshaling uses snake_case (inherited from fantasy.Usage tags).
+	data, err := json.Marshal(u)
+	if err != nil {
+		t.Fatalf("LLMUsage.MarshalJSON: %v", err)
+	}
+	jsonStr := string(data)
+	if jsonStr == "" {
+		t.Error("LLMUsage JSON is empty")
+	}
+	// Check that input_tokens key is present.
+	if !containsStr(jsonStr, `"input_tokens":100`) {
+		t.Errorf("LLMUsage JSON missing input_tokens: %s", jsonStr)
+	}
+}
+
+// TestLLMFilePartAlias verifies LLMFilePart is a type alias for fantasy.FilePart.
+func TestLLMFilePartAlias(t *testing.T) {
+	fp := kit.LLMFilePart{
+		Filename:  "screenshot.png",
+		Data:      []byte{0x89, 0x50, 0x4E, 0x47},
+		MediaType: "image/png",
+	}
+	if fp.Filename != "screenshot.png" {
+		t.Errorf("LLMFilePart.Filename = %q, want %q", fp.Filename, "screenshot.png")
+	}
+	if fp.MediaType != "image/png" {
+		t.Errorf("LLMFilePart.MediaType = %q, want %q", fp.MediaType, "image/png")
+	}
+	if len(fp.Data) != 4 {
+		t.Errorf("LLMFilePart.Data len = %d, want 4", len(fp.Data))
+	}
+
+	// Verify it can be used as a file part for constructing user messages.
+	msg := kit.NewLLMUserMessage("see this image", fp)
+	if msg.Role != kit.LLMRoleUser {
+		t.Errorf("message role = %q, want user", msg.Role)
+	}
+}
+
+// TestLLMPartTypesAlias verifies all the part type aliases compile and work.
+func TestLLMPartTypesAlias(t *testing.T) {
+	// LLMTextPart
+	tp := kit.LLMTextPart{Text: "plain text"}
+	if tp.Text != "plain text" {
+		t.Errorf("LLMTextPart.Text = %q", tp.Text)
+	}
+
+	// LLMReasoningPart
+	rp := kit.LLMReasoningPart{Text: "I think therefore"}
+	if rp.Text != "I think therefore" {
+		t.Errorf("LLMReasoningPart.Text = %q", rp.Text)
+	}
+
+	// LLMToolCallPart
+	tc := kit.LLMToolCallPart{
+		ToolCallID: "call-1",
+		ToolName:   "bash",
+		Input:      `{"cmd":"echo hi"}`,
+	}
+	if tc.ToolCallID != "call-1" {
+		t.Errorf("LLMToolCallPart.ToolCallID = %q", tc.ToolCallID)
+	}
+
+	// LLMToolResultPart
+	tro := kit.LLMToolResultOutputContentText{Text: "output text"}
+	tr := kit.LLMToolResultPart{
+		ToolCallID: "call-1",
+		Output:     tro,
+	}
+	if tr.ToolCallID != "call-1" {
+		t.Errorf("LLMToolResultPart.ToolCallID = %q", tr.ToolCallID)
+	}
+}
+
+// TestConvertToLLMMessages verifies round-trip conversion preserves content.
+func TestConvertToLLMMessages(t *testing.T) {
+	msg := kit.Message{
+		Role:  kit.RoleUser,
+		Parts: []kit.ContentPart{kit.TextContent{Text: "what is 2+2?"}},
+	}
+	llmMsgs := kit.ConvertToLLMMessages(&msg)
+	if len(llmMsgs) == 0 {
+		t.Fatal("ConvertToLLMMessages returned empty slice")
+	}
+	if llmMsgs[0].Role != kit.LLMRoleUser {
+		t.Errorf("converted Role = %q, want %q", llmMsgs[0].Role, kit.LLMRoleUser)
+	}
+	// Check text is preserved in content parts.
+	found := false
+	for _, part := range llmMsgs[0].Content {
+		if tp, ok := part.(kit.LLMTextPart); ok && tp.Text == "what is 2+2?" {
+			found = true
+		}
+	}
+	if !found {
+		t.Errorf("text content not found in converted LLMMessage")
+	}
+}
+
+// TestConvertFromLLMMessage verifies LLMMessage → Message conversion.
+func TestConvertFromLLMMessage(t *testing.T) {
+	llm := kit.NewLLMUserMessage("the answer is 4")
+	llm.Role = kit.LLMRoleAssistant
+	msg := kit.ConvertFromLLMMessage(llm)
+	if msg.Role != kit.RoleAssistant {
+		t.Errorf("converted Role = %q, want %q", msg.Role, kit.RoleAssistant)
+	}
+	if msg.Content() != "the answer is 4" {
+		t.Errorf("converted Content() = %q, want %q", msg.Content(), "the answer is 4")
+	}
+}
+
+// containsStr is a tiny helper to avoid importing strings in test.
+func containsStr(s, substr string) bool {
+	return len(s) >= len(substr) && (s == substr || len(s) > 0 && indexStr(s, substr) >= 0)
+}
+
+func indexStr(s, substr string) int {
+	for i := 0; i <= len(s)-len(substr); i++ {
+		if s[i:i+len(substr)] == substr {
+			return i
+		}
+	}
+	return -1
+}

scripts/acp_smoke_test.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""
+ACP smoke test — drives `kit acp` over JSON-RPC 2.0 stdio.
+
+Protocol flow:
+  1. session/new  → get sessionId
+  2. session/set_model → set opencode/kimi-k2.5
+  3. session/prompt → "What is 2+2? Answer in one sentence."
+  4. Collect session updates until done
+"""
+
+import json
+import subprocess
+import sys
+import threading
+import time
+import os
+
+KIT_BIN = os.path.join(os.path.dirname(__file__), "..", "output", "kit")
+MODEL   = "opencode/kimi-k2.5"
+CWD     = os.path.expanduser("~")
+TIMEOUT = 60  # seconds to wait for the prompt to complete
+
+
+def rpc(method, params, req_id):
+    return json.dumps({"jsonrpc": "2.0", "id": req_id, "method": method, "params": params}) + "\n"
+
+
+def send(proc, line):
+    print(f"\n→ SEND  {line.strip()}", flush=True)
+    proc.stdin.write(line)
+    proc.stdin.flush()
+
+
+def read_responses(proc, collected, done_event):
+    """Read newline-delimited JSON from stdout until process exits."""
+    for raw in proc.stdout:
+        raw = raw.strip()
+        if not raw:
+            continue
+        try:
+            msg = json.loads(raw)
+        except json.JSONDecodeError:
+            print(f"  [non-JSON stdout]: {raw}", flush=True)
+            continue
+
+        collected.append(msg)
+
+        # Pretty-print condensed
+        if "result" in msg:
+            result = msg["result"]
+            print(f"← RESP  id={msg.get('id')}  result={json.dumps(result)[:200]}", flush=True)
+            # Prompt complete when we get a stopReason on id=3
+            if msg.get("id") == 3 and "stopReason" in result:
+                done_event.set()
+        elif "error" in msg:
+            print(f"← ERROR id={msg.get('id')}  {json.dumps(msg['error'])}", flush=True)
+            # If it's the prompt call that errored, unblock
+            if msg.get("id") == 3:
+                done_event.set()
+        elif "method" in msg:
+            # Notification / session update
+            m = msg.get("method", "")
+            p = msg.get("params", {})
+            if m in ("session/update", "session/updated"):
+                update = p.get("update", {})
+                stype = update.get("sessionUpdate") or update.get("type", "?")
+                content = update.get("content", {})
+                if stype == "agent_thought_chunk":
+                    print(f"  [thinking] {content.get('text','')}", end="", flush=True)
+                elif stype == "agent_message_chunk":
+                    print(f"  [response] {content.get('text','')}", end="", flush=True)
+                else:
+                    print(f"\n  [update/{stype}] {json.dumps(update)[:200]}", flush=True)
+            else:
+                print(f"\n← NOTIF {m}  {json.dumps(p)[:200]}", flush=True)
+
+
+def main():
+    print(f"Starting: {KIT_BIN} acp -m {MODEL}", flush=True)
+
+    proc = subprocess.Popen(
+        [KIT_BIN, "acp", "-m", MODEL],
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        bufsize=1,
+    )
+
+    collected = []
+    done_event = threading.Event()
+
+    reader = threading.Thread(target=read_responses, args=(proc, collected, done_event), daemon=True)
+    reader.start()
+
+    stderr_lines = []
+    def read_stderr():
+        for line in proc.stderr:
+            line = line.rstrip()
+            stderr_lines.append(line)
+            if line:
+                print(f"  [stderr] {line}", flush=True)
+    threading.Thread(target=read_stderr, daemon=True).start()
+
+    time.sleep(0.3)  # let the process initialise
+
+    # 1. session/new
+    send(proc, rpc("session/new", {"cwd": CWD, "mcpServers": []}, 1))
+    time.sleep(1.0)
+
+    session_id = None
+    for msg in collected:
+        if msg.get("id") == 1 and "result" in msg:
+            session_id = msg["result"].get("sessionId")
+            break
+
+    if not session_id:
+        print("\n✗ FAIL: did not get sessionId from session/new", flush=True)
+        proc.terminate()
+        sys.exit(1)
+
+    print(f"\n✓ Got sessionId: {session_id}", flush=True)
+
+    # 2. session/set_model (model already set via -m flag, but exercise the RPC)
+    send(proc, rpc("session/set_model", {"sessionId": session_id, "modelId": MODEL}, 2))
+    time.sleep(0.5)
+
+    # 3. session/prompt
+    prompt_params = {
+        "sessionId": session_id,
+        "prompt": [{"type": "text", "text": "What is 2+2? Answer in one sentence."}],
+    }
+    send(proc, rpc("session/prompt", prompt_params, 3))
+
+    # Wait for finished update or timeout
+    if not done_event.wait(timeout=TIMEOUT):
+        print(f"\n✗ FAIL: timed out after {TIMEOUT}s waiting for finished update", flush=True)
+        proc.terminate()
+        sys.exit(1)
+
+    # Check we got a successful prompt response
+    prompt_resp = next((m for m in collected if m.get("id") == 3), None)
+    if prompt_resp and "error" in prompt_resp:
+        print(f"\n✗ FAIL: prompt returned error: {prompt_resp['error']}", flush=True)
+        proc.terminate()
+        sys.exit(1)
+
+    print("\n✓ SMOKE TEST PASSED", flush=True)
+    proc.terminate()
+    proc.wait(timeout=5)
+
+
+if __name__ == "__main__":
+    main()

skills/kit-sdk/SKILL.md

@@ -120,15 +120,17 @@ result, err := host.PromptResult(ctx, "Analyze this file")
 // result.StopReason   — "stop", "length", "tool-calls", "error", etc.
 // result.SessionID    — session UUID
 // result.TotalUsage   — aggregate tokens across all steps (*kit.LLMUsage)
-// result.FinalUsage   — tokens from last API call only
+//                        LLMUsage{InputTokens, OutputTokens, TotalTokens, ...}
+// result.FinalUsage   — tokens from last API call only (*kit.LLMUsage)
 // result.Messages     — full updated conversation ([]kit.LLMMessage)
+//                        LLMMessage{Role kit.LLMMessageRole, Content string}
 ```
 
 ### Multimodal with file attachments
 
 ```go
 files := []kit.LLMFilePart{{
-    Name:      "screenshot.png",
+    Filename:  "screenshot.png",
     MediaType: "image/png",
     Data:      imageBytes,
 }}
@@ -640,15 +642,19 @@ kit.Config, kit.MCPServerConfig
 // Provider types
 kit.ProviderConfig, kit.ProviderResult, kit.ModelInfo, kit.ModelCost, kit.ModelLimit
 
-// LLM types (re-exported from the underlying LLM library)
-kit.LLMMessage, kit.LLMUsage, kit.LLMResponse, kit.LLMFilePart
+// LLM types — concrete Kit-owned structs (no external library dependency)
+kit.LLMMessage      // {Role LLMMessageRole, Content string}
+kit.LLMMessageRole  // "user" | "assistant" | "system" | "tool"
+kit.LLMUsage        // {InputTokens, OutputTokens, TotalTokens, ReasoningTokens, ...}
+kit.LLMResponse     // {Content, FinishReason, Usage}
+kit.LLMFilePart     // {Filename, Data []byte, MediaType}
 
 // Compaction types
 kit.CompactionResult, kit.CompactionOptions
 
 // Conversion helpers
-msgs := kit.ConvertToLLMMessages(&msg)   // SDK message → LLM messages
-msg := kit.ConvertFromLLMMessage(fMsg)    // LLM message → SDK message
+msgs := kit.ConvertToLLMMessages(&msg)   // SDK Message  → []LLMMessage
+msg  := kit.ConvertFromLLMMessage(lMsg)  // LLMMessage   → SDK Message
 ```
 
 ---

specs/unified-bubbletea-architecture.md

@@ -1,450 +0,0 @@
-# Unified Bubble Tea Architecture
-
-## Overview
-
-Replace the micro-program pattern (3 interactive `tea.NewProgram` calls + 1 standalone progress) with a single persistent Bubble Tea program using child model composition. Extract a thick app layer from `cmd/root.go` to own agent orchestration, message storage, and event emission. TUI becomes purely reactive.
-
-New capabilities: message queueing during streaming, double-tap ESC cancellation, stacked layout (output above, input pinned below), queue badge with clear support.
-
-## User Story
-
-As a KIT user, I want the TUI to remain responsive during agent streaming so I can queue follow-up messages, cancel in-progress work, and see a persistent input area -- instead of waiting for each response to complete before typing.
-
-As a developer, I want the TUI architecture to follow Bubble Tea's idiomatic child-model pattern so components are composable, testable, and extensible without terminal ownership conflicts.
-
-## Requirements
-
-### Architecture
-- Single `tea.NewProgram()` call for the entire interactive session
-- Parent model manages state transitions and routes messages to child components
-- Child components: `InputComponent` (slash commands + autocomplete), `StreamComponent` (streaming display + spinner), `ApprovalComponent` (tool approval)
-- Ollama `ProgressModel` remains standalone (different lifecycle, runs during provider init)
-- Non-interactive mode bypasses `tea.Program` entirely, uses same app layer without TUI
-
-### App Layer
-- New `internal/app` package owns: agent orchestration loop, in-memory message store, message queue, tool approval callback, hook execution, session persistence, usage tracking
-- App layer exposes `Run(prompt)`, `RunOnce(ctx, prompt)`, `CancelCurrentStep()`, `ClearQueue()`, `QueueLength()`, `ClearMessages()`
-- Events sent to TUI via `program.Send()` -- no pubsub infra
-- Message store: mutable `[]fantasy.Message` with wrapper IDs, emits events on change. Bridges to `session.Manager` for persistence on each step completion.
-- `ToolApprovalFunc` provided at construction via `Options`. Interactive mode: channel handshake with TUI. Non-interactive: auto-approve. Channel must be `select`-able against app context to avoid goroutine leaks on shutdown.
-- All 7 agent callbacks from `GenerateWithLoopAndStreaming` (`agent.go:144-151`) mapped to events sent via `program.Send()`. See Events section.
-- Hook executor (`hooks.Executor`) owned by app layer. Fires `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop` at same points as current `runAgenticStep`.
-
-### App Layer Options
-
-Full options mirroring current `AgenticLoopConfig` (`root.go:753-769`):
-
-```go
-type Options struct {
-    Agent            *agent.Agent
-    ToolApprovalFunc ToolApprovalFunc   // required, set at construction
-    HookExecutor     *hooks.Executor    // optional
-    SessionManager   *session.Manager   // optional, for persistence
-    MCPConfig        *config.Config     // for session continuation
-    ModelName        string
-    ServerNames      []string           // for slash commands
-    ToolNames        []string           // for slash commands
-    StreamingEnabled bool
-    Quiet            bool
-    Debug            bool
-    CompactMode      bool
-}
-```
-
-### Events
-
-Events emitted by app layer (defined in `internal/app/events.go`):
-
-| Event | Source callback | Purpose |
-|---|---|---|
-| `StreamChunkEvent` | `onStreamingResponse` | Streaming text delta |
-| `ToolCallStartedEvent` | `onToolCall` | Tool call initiated (name + args) |
-| `ToolExecutionEvent` | `onToolExecution` | Tool execution starting/stopping |
-| `ToolResultEvent` | `onToolResult` | Tool result (name, args, result, isError) |
-| `ToolCallContentEvent` | `onToolCallContent` | Tool call content display |
-| `ResponseCompleteEvent` | `onResponse` | Final response text |
-| `StepCompleteEvent` | (after generate returns) | Agent step finished, includes usage data |
-| `StepErrorEvent` | (on agent error) | Agent step failed with error |
-| `QueueUpdatedEvent` | (on queue change) | Queue length changed |
-| `ToolApprovalNeededEvent` | `onToolApproval` | Approval required, includes response channel |
-| `SpinnerEvent` | (before first chunk) | Show/hide spinner state |
-| `HookBlockedEvent` | (hook returns block) | Hook blocked the action |
-| `MessageCreatedEvent` | (on history add) | New message added to store |
-
-TUI-internal messages (defined in `internal/ui/events.go`, NOT in app layer):
-
-| Message | Purpose |
-|---|---|
-| `submitMsg` | Input component submitted text |
-| `approvalResultMsg` | Approval component returned decision |
-| `cancelTimerExpiredMsg` | 2s ESC timer expired |
-
-### TUI Behavior
-- Stacked layout: latest response output above, input textarea pinned below
-- Output area shows latest response only. Completed responses emitted above the BT-managed region via `tea.Println()` before the model resets for the next interaction. This works with BT v2 inline mode (no alt screen).
-- Input textarea keeps current sizing behavior from `SlashCommandInput`
-- Slash command autocomplete fully self-contained in input component. Component holds `*app.App` reference for executing commands that affect app state (`/clear` calls `app.ClearMessages()`, `/quit` returns `tea.Quit` to parent, `/clear-queue` calls `app.ClearQueue()`). Parent receives either a `submitMsg` (text prompt) or a `tea.Cmd` (slash command side effect).
-- Message queueing: user can submit while agent streams. Queue badge shows "N queued" near input. `/clear-queue` slash command flushes queue.
-- Double-tap ESC: first press shows "press again to cancel", second press calls `App.CancelCurrentStep()`. Timer expires after 2s, resets state.
-- Tool approval: agent blocks on `ToolApprovalFunc` callback. Callback sends `ToolApprovalNeededEvent` (containing a `chan<- bool` response channel) to program, then blocks on that channel via `select` with `ctx.Done()`. TUI transitions to approval state, user decides, parent sends result on channel. If ctx cancelled, callback returns `false, ctx.Err()`.
-- Keyboard during streaming: input textarea remains focused and editable. All keystrokes go to the input component normally. ESC is intercepted by parent for cancel flow. Enter/submit queues the message via `app.Run()`.
-- Spinner: `StreamComponent` renders a spinner animation (replacing the current standalone goroutine-based `ui.Spinner`) when the agent is processing but hasn't sent any chunks yet. First `StreamChunkEvent` transitions from spinner to streaming display. No more goroutine writing to stderr.
-
-### Compact Mode
-
-Current code uses two renderers (`MessageRenderer` and `CompactRenderer`) toggled by `cli.compactMode`. Both renderers retained. The `CompactMode` flag propagated through `App.Options` → parent model → child components. Each component checks the flag and delegates to the appropriate renderer for message formatting.
-
-### Usage Tracking
-
-`UsageTracker` moves to the app layer. Created during `App.New()` using model info from `Options`. App layer calls `UpdateUsageFromResponse()` after each step. Emits usage data in `StepCompleteEvent`. TUI renders usage via retained `UsageTracker.RenderUsageInfo()` method. Non-interactive mode reads usage from app layer directly.
-
-### Non-Interactive Mode
-- Same app layer, no TUI. `ToolApprovalFunc` auto-approves (provided at construction). Output prints directly to stdout.
-- Current `runNonInteractiveMode` refactored to use `app.RunOnce()`.
-- **Behavior change**: current non-interactive non-quiet mode creates a BT streaming display program. New behavior: `RunOnce()` accepts an optional `StreamingWriter io.Writer` for real-time output. Non-interactive passes `os.Stdout`. No BT program created.
-
-### Session Persistence
-
-`session.Manager` owned by app layer (passed via `Options.SessionManager`). App layer calls `session.Manager.AddMessages()` after each step completion and on queue drain. `--load-session` flag handled in `cmd/root.go` before app construction -- loaded messages passed to `App.New()` as initial history. `MessageStore.Clear()` also calls `session.Manager.ReplaceAllMessages()`.
-
-### Error Handling
-
-Agent errors (API failures, rate limits, MCP crashes) emitted as `StepErrorEvent`. Parent model receives the event, passes error to `StreamComponent` for inline display (matching current behavior), then transitions to `stateInput`. No automatic retry -- user can retry by submitting again.
-
-### Graceful Shutdown
-
-Shutdown sequence when user quits (Ctrl+C or `/quit`):
-
-1. Parent model returns `tea.Quit`
-2. `tea.Program.Run()` returns in `cmd/root.go`
-3. If agent goroutine running: `app.CancelCurrentStep()` called (deferred)
-4. `app.Close()` called (deferred) -- cancels app context, waits for agent goroutine to exit
-5. `mcpAgent.Close()` called (deferred, existing) -- closes MCP connections and provider
-
-`App` holds a top-level `context.Context` (created with `context.WithCancel` in `New()`). All agent goroutines use this context. `App.Close()` cancels it and calls `sync.WaitGroup.Wait()` to ensure clean exit.
-
-### Parent Model State Machine
-
-```
-stateInput ──submit──→ stateWorking ──StepComplete──→ stateInput
-                            │                              ↑
-                            ├──ToolApproval──→ stateApproval──approve/deny──┘
-                            │                              │
-                            ├──StepError────→ stateInput   │
-                            │                              │
-                            └──Cancel────────→ stateInput  │
-                                                           │
-                          (queue non-empty: auto-drain) ───┘
-```
-
-States:
-- `stateInput` -- input focused, waiting for user
-- `stateWorking` -- agent running (spinner → streaming → tool calls → streaming → ...)
-- `stateApproval` -- tool approval dialog active (sub-state of working)
-
-### Testing
-- Unit tests for each child component (send messages, assert state transitions)
-- Unit tests for parent model (state routing, child delegation, cancel flow, error handling)
-- Unit tests for app layer (message store, queue, cancel, session save ordering, ToolApprovalFunc channel + ctx cancellation)
-
-## Technical Implementation
-
-### Package Structure
-
-```
-internal/
-  app/
-    app.go              # App struct, New(), Run(), RunOnce(), CancelCurrentStep(), Close()
-    app_test.go         # App tests (queue, cancel, drain, session save)
-    messages.go         # MessageStore (in-memory, wraps []fantasy.Message, bridges session.Manager)
-    messages_test.go    # MessageStore tests
-    events.go           # All event types sent to TUI via program.Send()
-    options.go          # Options struct, ToolApprovalFunc type
-  ui/
-    model.go            # Parent tea.Model (AppModel), state machine, message routing
-    model_test.go       # Parent model tests
-    input.go            # InputComponent (refactored slash_command_input.go)
-    input_test.go       # Input tests
-    stream.go           # StreamComponent (refactored streaming_display.go + spinner)
-    stream_test.go      # Stream tests
-    approval.go         # ApprovalComponent (refactored tool_approval_input.go)
-    approval_test.go    # Approval tests
-    events.go           # TUI-internal message types (submitMsg, approvalResultMsg, cancelTimerExpiredMsg)
-    cli.go              # Retained: SetupCLI factory (creates App + AppModel), non-TUI helpers
-    messages.go         # Retained: message rendering (used by StreamComponent)
-    styles.go           # Retained
-    enhanced_styles.go  # Retained
-    compact_renderer.go # Retained
-    block_renderer.go   # Retained
-    commands.go         # Retained + /clear-queue added
-    fuzzy.go            # Retained
-    usage_tracker.go    # Retained (used by app layer)
-    debug_logger.go     # Retained (used by app layer)
-  ui/progress/
-    ollama.go           # Retained standalone (not part of refactor)
-```
-
-### Parent Model
-
-```go
-type appState int
-const (
-    stateInput    appState = iota  // Input focused, waiting for user
-    stateWorking                    // Agent running, streaming output
-    stateApproval                   // Tool approval dialog active
-)
-
-type AppModel struct {
-    state        appState
-    app          *app.App            // Thick app layer reference
-    input        InputComponent      // Child: user input + autocomplete
-    stream       StreamComponent     // Child: streaming display + spinner
-    approval     ApprovalComponent   // Child: tool approval
-    renderer     *MessageRenderer    // For tea.Println of completed responses
-    compactRdr   *CompactRenderer    // Compact mode renderer
-    compactMode  bool                // Which renderer to use
-    queueCount   int                 // Cached from QueueUpdatedEvent
-    canceling    bool                // Double-tap ESC state
-    approvalChan chan<- bool         // Response channel for current approval
-    width        int
-    height       int
-}
-```
-
-### Event Flow
-
-```
-User types → InputComponent.Update() → submit
-  ↓
-Parent receives submitMsg → calls app.Run(prompt) in tea.Cmd goroutine
-  ↓
-Parent transitions to stateWorking → StreamComponent active (spinner mode)
-  ↓
-App layer goroutine: agent processes
-  → program.Send(SpinnerEvent{Show: true})
-  → program.Send(ToolCallStartedEvent{...})
-  → program.Send(StreamChunkEvent{...})  (first chunk hides spinner)
-  → program.Send(ToolResultEvent{...})
-  → program.Send(ToolCallContentEvent{...})
-  ↓
-Parent routes events to StreamComponent.Update()
-  ↓
-Agent needs tool approval → ToolApprovalFunc called
-  → creates chan bool, sends ToolApprovalNeededEvent{ResponseChan: ch}
-  → blocks: select { case result := <-ch; case <-ctx.Done() }
-  ↓
-Parent stores channel in approvalChan, transitions to stateApproval
-  ↓
-User approves → Parent sends on approvalChan → Agent continues
-  ↓
-Agent completes → app sends StepCompleteEvent{Usage: ...}
-  ↓
-Parent: tea.Println() completed response, transitions to stateInput
-  ↓
-If queue non-empty: App auto-drains next message, stays in stateWorking
-```
-
-### Cancel Flow
-
-```
-User presses ESC during stateWorking
-  ↓
-Parent sets canceling=true, returns cancelTimerCmd (2s tea.Tick)
-  ↓
-User presses ESC again within 2s → Parent calls app.CancelCurrentStep()
-  ↓
-App cancels step context → agent goroutine exits
-  → ToolApprovalFunc unblocks via ctx.Done() if waiting
-  → StepErrorEvent or StepCompleteEvent emitted
-  ↓
-Parent transitions to stateInput
-  ↓
-cancelTimerExpiredMsg arrives (if no second ESC) → resets canceling=false
-```
-
-### cmd/root.go Changes
-
-```go
-// runNormalMode becomes:
-appInstance, err := app.New(app.Options{
-    Agent:            mcpAgent,
-    ToolApprovalFunc: toolApprovalFunc,  // set per mode, see below
-    HookExecutor:     hookExecutor,
-    SessionManager:   sessionManager,
-    MCPConfig:        mcpConfig,
-    ModelName:        modelString,
-    ServerNames:      serverNames,
-    ToolNames:        toolNames,
-    StreamingEnabled: viper.GetBool("stream"),
-    Quiet:            quietFlag,
-    Debug:            viper.GetBool("debug"),
-    CompactMode:      viper.GetBool("compact"),
-}, initialMessages)  // loaded from session if --load-session
-defer appInstance.Close()
-
-// Interactive mode:
-toolApprovalFunc = app.NewInteractiveApprovalFunc(appInstance)
-model := ui.NewAppModel(appInstance, uiOpts)
-program := tea.NewProgram(model)
-appInstance.SetProgram(program)  // Safe: app.Run() not called until Init()
-_, err := program.Run()
-
-// Non-interactive mode:
-toolApprovalFunc = app.AutoApproveFunc
-result, err := appInstance.RunOnce(ctx, prompt, os.Stdout) // stdout for streaming
-printResult(result)
-```
-
-**SetProgram timing**: Safe because `app.Run()` is only called from `tea.Cmd` functions after the program starts its event loop. `AppModel.Init()` returns no command that calls `app.Run()` -- the first `Run()` call happens when the user submits input or when `Init()` dispatches an initial prompt (non-interactive continuation via `--no-exit`).
-
-## Tasks
-
-### 1. Create app layer skeleton
-- [ ] [P0] Create `internal/app/events.go` with all event types: `StreamChunkEvent`, `ToolCallStartedEvent`, `ToolExecutionEvent`, `ToolResultEvent`, `ToolCallContentEvent`, `ResponseCompleteEvent`, `StepCompleteEvent` (with usage data), `StepErrorEvent`, `QueueUpdatedEvent`, `ToolApprovalNeededEvent` (with `ResponseChan chan<- bool`), `SpinnerEvent`, `HookBlockedEvent`, `MessageCreatedEvent`
-- [ ] [P0] Create `internal/app/options.go` with `Options` struct (all fields from App Layer Options section), `ToolApprovalFunc` type (`func(ctx context.Context, toolName, toolArgs string) (bool, error)`), `AutoApproveFunc` var, `NewInteractiveApprovalFunc` constructor
-- [ ] [P0] Create `internal/app/messages.go` with `MessageStore` wrapping `[]fantasy.Message`. Methods: `Add(fantasy.Message)`, `Replace([]fantasy.Message)`, `GetAll() []fantasy.Message`, `Clear()`. Bridges to `session.Manager` (if non-nil) on every mutation for persistence.
-- [ ] [P0] Create `internal/app/app.go` with `App` struct, `New(opts, initialMessages)`, `SetProgram(*tea.Program)`, `Run(prompt)`, `RunOnce(ctx, prompt, io.Writer)`, `CancelCurrentStep()`, `QueueLength()`, `ClearQueue()`, `ClearMessages()`, `Close()`. Internal: `context.WithCancel`, `sync.WaitGroup`, `sync.Mutex` for busy/queue state.
-
-### 2. Migrate agent orchestration into app layer
-- [ ] [P1] Move `runAgenticStep` logic from `cmd/root.go:873-1191` into `App.executeStep()`. Map all 7 agent callbacks to `program.Send()` events. Wire `ToolApprovalFunc` for `onToolApproval`. Emit `SpinnerEvent{Show:true}` before calling agent, `SpinnerEvent{Show:false}` on first stream chunk.
-- [ ] [P1] Move hook execution from `cmd/root.go:810-828,943-969,1002-1019,1186-1223` into `App.executeStep()`. Fire `UserPromptSubmit` in `Run()` before `executeStep()`. Fire `PreToolUse`/`PostToolUse`/`Stop` at same points. Emit `HookBlockedEvent` if hook blocks.
-- [ ] [P1] Move conversation history management into `MessageStore`. `App.executeStep()` calls `store.Add()` for user message before agent call, `store.Replace()` with updated history after agent returns. Store bridges to `session.Manager`.
-- [ ] [P1] Move usage tracking into app layer. Create `UsageTracker` in `App.New()` from model info. Call `UpdateUsageFromResponse()` after each step. Include usage data in `StepCompleteEvent`.
-- [ ] [P1] Implement queue drain: after step completes (success or error), if queue non-empty, dequeue next message and call `executeStep()` in same goroutine (no new goroutine spawn).
-
-### 3. Create parent TUI model
-- [ ] [P1] Create `internal/ui/model.go` with `AppModel` struct (see Parent Model section), `NewAppModel()`, `Init()`, `Update()`, `View()`. State machine routes events to children based on `appState`. Handle `tea.WindowSizeMsg` to distribute height. Store `approvalChan` for tool approval response.
-- [ ] [P1] Implement double-tap ESC cancel in parent `Update()`: intercept `tea.KeyPressMsg` for ESC during `stateWorking`. Track `canceling` bool, return `tea.Tick(2*time.Second, ...)` as timer cmd, call `app.CancelCurrentStep()` on second press within window.
-- [ ] [P1] Implement `tea.Println()` for completed responses: on `StepCompleteEvent`, render the completed response using message renderer (respecting compact mode), emit via `tea.Println()`, then reset `StreamComponent` state.
-- [ ] [P1] Implement `StepErrorEvent` handling: render error inline in stream area, transition to `stateInput`.
-- [ ] [P1] Implement graceful quit: Ctrl+C and `/quit` return `tea.Quit`. Deferred `app.Close()` in `cmd/root.go` handles cleanup.
-
-### 4. Refactor child components
-- [ ] [P1] Refactor `slash_command_input.go` → `internal/ui/input.go` as `InputComponent`. Remove `tea.Quit` on submit -- return `submitMsg` as a `tea.Cmd`. Keep autocomplete + popup self-contained. Hold `*app.App` reference for slash command execution: `/clear` → `app.ClearMessages()`, `/clear-queue` → `app.ClearQueue()`, `/quit` → return `tea.Quit` cmd. Remove `os.Exit(0)` from `/quit`.
-- [ ] [P1] Refactor `streaming_display.go` → `internal/ui/stream.go` as `StreamComponent`. Add spinner state: render KITT-style animation (from current `spinner.go`) when `SpinnerEvent{Show:true}` received, switch to streaming text on first `StreamChunkEvent`. Accept all display events (`ToolCallStartedEvent`, `ToolResultEvent`, etc.) and render via retained `MessageRenderer`/`CompactRenderer`. Remove `streamDoneMsg`/`tea.Quit` -- parent manages lifecycle. Add `Reset()` to clear state between steps.
-- [ ] [P1] Refactor `tool_approval_input.go` → `internal/ui/approval.go` as `ApprovalComponent`. Remove `tea.Quit` -- return `approvalResultMsg{approved: bool}` as a `tea.Cmd`. Parent handles sending result on `approvalChan`.
-
-### 5. Wire TUI to app layer in cmd/root.go
-- [ ] [P1] Refactor `runNormalMode()`: create `app.App` with full `Options` (all fields). Wire `ToolApprovalFunc` per mode. Load session messages before construction. Defer `appInstance.Close()`.
-- [ ] [P1] Interactive path: create `ui.NewAppModel()` + single `tea.NewProgram(model)` + `appInstance.SetProgram(program)` + `program.Run()`. Remove `SetupCLI()` flow for interactive mode.
-- [ ] [P1] Non-interactive path: call `appInstance.RunOnce(ctx, prompt, os.Stdout)`. Handle `--no-exit` by switching to interactive mode after. No `tea.Program` created. Remove old streaming display usage for non-interactive.
-- [ ] [P1] Retain `SetupCLI()` as alternative factory for non-interactive quiet mode (just prints final text, no renderers needed). Or inline the quiet-mode logic.
-
-### 6. Implement message queueing UX
-- [ ] [P2] Add queue badge rendering in parent `View()` -- show "N queued" right-aligned on separator line when `queueCount > 0`. Update count on `QueueUpdatedEvent`.
-- [ ] [P2] Register `/clear-queue` slash command in `internal/ui/commands.go`.
-- [ ] [P2] Handle `submitMsg` during `stateWorking`: parent calls `app.Run()` (which queues internally), does NOT transition state. Input component stays active and clears text.
-
-### 7. Stacked layout
-- [ ] [P2] Implement stacked `View()` in parent: stream output region (variable height) + separator line + input region (current textarea height). Use `lipgloss.JoinVertical`. Separator shows queue badge if applicable.
-- [ ] [P2] Handle `tea.WindowSizeMsg` propagation: calculate input height (fixed, from textarea), separator (1 line), remaining goes to stream. Propagate dimensions to children.
-
-### 8. Cleanup
-- [ ] [P2] Delete standalone `tea.NewProgram` calls from `cli.go` (`GetPrompt`, `StartStreamingMessage`, `GetToolApproval`). Remove `streamProgram`/`streamDone` fields.
-- [ ] [P2] Delete `runAgenticStep`, `runAgenticLoop`, `runInteractiveLoop`, `addMessagesToHistory`, `replaceMessagesHistory`, `AgenticLoopConfig` from `cmd/root.go`.
-- [ ] [P2] Delete old `spinner.go` (replaced by StreamComponent's inline spinner).
-- [ ] [P3] Trim `CLI` struct to only non-TUI helpers needed by non-interactive quiet mode. Remove `GetPrompt`, `StartStreamingMessage`, `UpdateStreamingMessage`, `GetToolApproval`, `finishStreaming`, `HandleSlashCommand`. Retain `DisplayError`, `DisplayInfo` for non-interactive error output if needed, or remove entirely if `RunOnce` handles its own output.
-
-### 9. Tests
-- [ ] [P2] Unit tests for `MessageStore`: add, replace, getAll, clear, session.Manager bridge (mock manager, verify calls)
-- [ ] [P2] Unit tests for `App`: run (single), run (queued), cancel during step, cancel during approval (verify ToolApprovalFunc unblocks via ctx), queue drain ordering, ClearQueue, Close (verify goroutine cleanup via WaitGroup)
-- [ ] [P2] Unit tests for `AppModel`: state transitions (input→working→approval→input), StepError→input, ESC cancel flow (single tap resets, double tap cancels), queue badge update, window resize, tea.Println on step complete
-- [ ] [P2] Unit tests for child components: `InputComponent` (submit emits submitMsg, slash commands execute, /quit returns tea.Quit), `StreamComponent` (spinner→streaming transition, chunk accumulation, tool call rendering, reset), `ApprovalComponent` (approve/deny emits approvalResultMsg)
-
-## UI Mockup
-
-### Processing (stateWorking, spinner)
-
-```
-  ◇◇◇◆◇◇◇ Thinking...
-
-
-───────────────────────────────────
-> █
-```
-
-### During Streaming (stateWorking)
-
-```
-  assistant (claude-sonnet-4-20250514)
-  Here is the implementation of the requested
-  feature. First, I'll create the new file...
-  █ (streaming cursor)
-
-─────────────────────────────────── 2 queued
-> write tests for that too█
-```
-
-### Tool Call in Stream (stateWorking)
-
-```
-  assistant (claude-sonnet-4-20250514)
-  Let me check the build first.
-
-  ⚙ bash: go build -o output/kit
-  ◇◇◇◆◇◇◇ Executing...
-
-─────────────────────────────────── 2 queued
-> write tests for that too█
-```
-
-### During Tool Approval (stateApproval)
-
-```
-  assistant (claude-sonnet-4-20250514)
-  I need to run a command to check the build.
-
-  ┌─ Tool Approval ──────────────────────┐
-  │ bash: go build -o output/kit          │
-  │                                      │
-  │  [Yes]   No                          │
-  └──────────────────────────────────────┘
-
-─────────────────────────────────── 2 queued
-> █
-```
-
-### Cancel in Progress (stateWorking, canceling)
-
-```
-  assistant (claude-sonnet-4-20250514)
-  Analyzing the codebase structure to find
-  relevant files...
-
-  ⚠ Press ESC again to cancel
-
-─────────────────────────────────── 1 queued
-> also check the tests█
-```
-
-### Error (stateWorking → stateInput)
-
-```
-  ✗ Error: API rate limit exceeded. Try again.
-
-───────────────────────────────────
-> █
-```
-
-## Out of Scope
-
-- Scrollable viewport / chat history browsing (latest response only for v1)
-- Ollama `ProgressModel` unification (stays standalone)
-- Persistent message storage / database (session JSON files retained as-is)
-- Multi-session support
-- Split-pane or tabbed layouts
-- Mouse interaction
-- Changing tool call display format (keep current rendering via retained renderers)
-- Prompt history persistence across sessions
-- Any visual/theme changes beyond new layout
-- Refactoring the `agent.Agent` or `fantasy` interfaces
-- Changing hook execution semantics
-
-## Open Questions
-
-- Should queue drain be immediate (next message starts as soon as current step completes) or should there be a brief pause to let the user read the response?
-- If the user cancels mid-stream and there are queued messages, should the queue also be flushed or should the next queued message execute?
-- Should the input component retain focus (cursor visible, editable) during `stateApproval`, or should focus fully transfer to the approval dialog?
-- Should `tea.Println()` of completed responses include tool call/result details, or just the final assistant text? Current behavior shows everything inline.
-- How should debug logging work during the TUI lifecycle? Currently `BufferedDebugLogger` accumulates messages shown after agent creation. In the new architecture, should debug messages be events rendered in the stream component?
-- For `--no-exit` (non-interactive then interactive): should `RunOnce` return and then `cmd/root.go` creates the TUI program for the interactive continuation, or should the TUI program be created upfront and the initial prompt dispatched via `Init()`?

test_messages.txt

@@ -0,0 +1,9 @@
+1. Hello, world!
+
+2. Testing one, two, three.
+
+3. This is a quick test message.
+
+4. Sample text for verification.
+
+5. All systems operational.

www/pages/cli/commands.md

@@ -73,7 +73,7 @@ These commands are available inside the Kit TUI during an interactive session:
 | `/usage` | Show token usage |
 | `/reset-usage` | Reset usage statistics |
 | `/tree` | Navigate session tree |
-| `/fork` | Branch from an earlier message |
+| `/fork` | Fork to new session from an earlier message |
 | `/new` | Start a new session (creates new session file) |
 | `/name [name]` | Set or show session display name |
 | `/resume` | Open session picker to switch sessions (alias: `/r`) |

www/pages/sessions.md

@@ -80,7 +80,7 @@ These slash commands are available during an interactive session:
 | `/import <path>` | Import and switch to a session from a JSONL file |
 | `/share` | Upload session to GitHub Gist and get a shareable viewer URL |
 | `/tree` | Navigate the session tree |
-| `/fork` | Branch from an earlier message |
+| `/fork` | Fork to new session from an earlier message (creates new session file) |
 | `/new` | Start a new session (creates new session file) |
 
 ## Ephemeral mode