init

CLAUDE.md

@@ -0,0 +1,68 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Clojure TUI framework inspired by Bubbletea (Go), using the Elm Architecture with Hiccup for views. Two runtimes: full async (`tui.core` with core.async) and simple sync (`tui.simple` for Babashka).
+
+## Commands
+
+```bash
+# Run tests
+bb test
+
+# List available examples
+bb examples
+
+# Run examples (with Babashka - simple sync runtime)
+bb counter
+bb timer
+bb list
+bb spinner
+bb views
+bb http
+
+# Run examples with full Clojure (async support)
+clojure -A:dev -M -m examples.counter
+```
+
+## Architecture
+
+```
+View (hiccup) → Render (ANSI string) → Terminal (raw mode I/O)
+     ↑                                        |
+     |                                        v
+   Model  ←──────── Update ←─────────── Input (key parsing)
+```
+
+### Core Modules
+
+- **tui.core** - Full async runtime with core.async. Manages the event loop, executes commands (quit, tick, batch, seq), handles input via goroutines.
+- **tui.simple** - Sync runtime for Babashka. Same API but no async commands.
+- **tui.render** - Converts hiccup (`[:col [:text "hi"]]`) to ANSI strings. Handles `:text`, `:row`, `:col`, `:box`, `:space` elements.
+- **tui.terminal** - Platform abstraction: raw mode via `stty`, reads from `/dev/tty`, renders by printing ANSI.
+- **tui.input** - Parses raw bytes into key messages (`[:key {:char \a}]`, `[:key :up]`, `[:key {:ctrl true :char \c}]`).
+- **tui.ansi** - ANSI escape codes, colors, box-drawing characters, string utilities.
+
+### Elm Architecture Flow
+
+1. App provides `:init` (model), `:update` (fn [model msg] -> [new-model cmd]), `:view` (fn [model] -> hiccup)
+2. Runtime renders initial view
+3. Input loop reads keys, puts messages on channel
+4. Update function processes messages, may return commands
+5. Commands execute async (ticks, batches), put results back on channel
+6. Loop until `[:quit]` command
+
+### Command Types
+
+- `tui/quit` - Exit
+- `(tui/tick ms)` - Send `:tick` after delay
+- `(tui/batch cmd1 cmd2)` - Parallel execution
+- `(tui/sequentially cmd1 cmd2)` - Sequential execution
+- `(fn [] msg)` - Custom async returning a message
+
+## Testing Philosophy
+
+- **E2E tests**: Small number of integration tests to verify the full stack works (terminal init → input → update → render → cleanup)
+- **Unit tests**: Cover all engine behavior for rendering (hiccup→ANSI), input handling (byte sequences→key messages), and model/command interactions