stream_weaver 0.3.0

data/docs/ideas/2026-01-16-charm-tui-exploration.md

@@ -0,0 +1,542 @@
+# StreamWeaver for TUI: Adapting the DSL to Charm
+
+**Date:** January 16, 2026
+**Status:** Exploration / Feasibility Analysis
+
+## Executive Summary
+
+StreamWeaver's reactive DSL could be adapted to target Charm's TUI libraries (Bubbletea, Lipgloss, Bubbles) instead of web browsers. The core insight—**your Ruby block re-executes on every interaction**—translates naturally to Bubbletea's Elm Architecture. This document explores feasibility, architectural alignment, and a potential implementation path.
+
+## The Opportunity
+
+With Marco Roth's Charm Ruby gems now available, Ruby developers can build "glamorous" terminal UIs. But Charm follows the Elm Architecture pattern, requiring explicit model/update/view separation:
+
+```ruby
+# Current Charm/Bubbletea approach
+class Counter
+  include Bubbletea::Model
+
+  def initialize
+    @count = 0
+  end
+
+  def update(msg)
+    case msg
+    when Bubbletea::KeyMsg
+      @count += 1 if msg.key == "+"
+      @count -= 1 if msg.key == "-"
+    end
+    [self, nil]
+  end
+
+  def view
+    "Count: #{@count}\n\nPress + or - to change, q to quit"
+  end
+end
+
+Bubbletea::Program.new(Counter.new).run
+```
+
+StreamWeaver's approach is more declarative—state changes and UI definition live together:
+
+```ruby
+# StreamWeaver's reactive approach
+app "Counter" do
+  state[:count] ||= 0
+
+  text "Count: #{state[:count]}"
+
+  button "+" do |s|
+    s[:count] += 1
+  end
+end.run!
+```
+
+**Question: Can we bring StreamWeaver's token-efficient DSL to terminal UIs?**
+
+## Architectural Alignment Analysis
+
+### What Aligns Well
+
+| StreamWeaver Concept | Charm Equivalent | Compatibility |
+|---------------------|------------------|---------------|
+| `state[:key]` hash | Model instance variables | Direct mapping |
+| Block re-execution | `view()` method called after `update()` | Same pattern |
+| Component rendering | Lipgloss styled strings | Conceptual match |
+| Button callbacks | KeyMsg/MouseMsg handling | Needs translation layer |
+| Layout (vstack, hstack) | Lipgloss.join_vertical/horizontal | Direct equivalent |
+
+### Key Differences
+
+| Aspect | StreamWeaver (Web) | Charm (TUI) |
+|--------|-------------------|-------------|
+| Event model | HTTP requests via HTMX | Keyboard/mouse messages |
+| Rendering | HTML via Phlex | ANSI strings via Lipgloss |
+| Components | Form elements (text_field, select) | Bubbles components (TextInput, List) |
+| State persistence | Session cookies | In-memory only |
+| Interaction | Click, type, submit | Keypress, mouse click |
+
+## Proposed Architecture: CharmWeaver
+
+A new rendering backend for StreamWeaver's DSL that targets Charm instead of web browsers.
+
+### Core Abstraction
+
+```ruby
+# Same DSL, different target
+tui "Counter" do
+  state[:count] ||= 0
+
+  text "Count: #{state[:count]}"
+
+  # TUI-specific: key bindings instead of buttons
+  on_key "+" do |s|
+    s[:count] += 1
+  end
+
+  on_key "-" do |s|
+    s[:count] -= 1
+  end
+end.run!
+```
+
+### Implementation Strategy
+
+**Phase 1: Proof of Concept**
+- Create `CharmWeaver::App` that wraps Bubbletea::Model
+- Implement basic components: `text`, `header`, `vstack`, `hstack`
+- Map `state[:key]` to model instance variables
+- Block re-execution on each `view()` call
+
+```ruby
+module CharmWeaver
+  class App
+    include Bubbletea::Model
+
+    def initialize(title, &block)
+      @title = title
+      @block = block
+      @state = {}
+      @components = []
+      @key_handlers = {}
+    end
+
+    def init
+      [self, nil]
+    end
+
+    def update(msg)
+      case msg
+      when Bubbletea::KeyMsg
+        return [self, Bubbletea.quit] if msg.key == "q"
+
+        if handler = @key_handlers[msg.key]
+          handler.call(@state)
+        end
+      end
+      [self, nil]
+    end
+
+    def view
+      @components.clear
+      @key_handlers.clear
+
+      # Re-execute block (StreamWeaver's core insight)
+      instance_eval(&@block)
+
+      render_components
+    end
+
+    private
+
+    def state
+      @state
+    end
+
+    def text(content)
+      @components << { type: :text, content: content }
+    end
+
+    def on_key(key, &handler)
+      @key_handlers[key] = handler
+    end
+
+    def render_components
+      @components.map do |c|
+        case c[:type]
+        when :text
+          c[:content]
+        end
+      end.join("\n")
+    end
+  end
+end
+
+def tui(title, &block)
+  CharmWeaver::App.new(title, &block)
+end
+```
+
+**Phase 2: Component Library**
+
+Map StreamWeaver components to Charm equivalents:
+
+| StreamWeaver | CharmWeaver | Implementation |
+|--------------|-------------|----------------|
+| `text` | `text` | Lipgloss styled string |
+| `header` | `header` | Lipgloss bold/colored |
+| `text_field :name` | `text_input :name` | Bubbles::TextInput |
+| `text_area :bio` | `text_area :bio` | Bubbles::TextArea |
+| `select :choice, [...]` | `list :choice, [...]` | Bubbles::List |
+| `checkbox :agree` | `toggle :agree` | Custom toggle component |
+| `button "Click"` | `on_key "enter"` | Key binding |
+| `vstack` | `vstack` | Lipgloss.join_vertical |
+| `hstack` | `hstack` | Lipgloss.join_horizontal |
+| `card` | `box` | Lipgloss border + padding |
+| `alert` | `styled_box` | Lipgloss with color variant |
+
+**Phase 3: Focus Management**
+
+TUIs need focus handling for input components:
+
+```ruby
+tui "Form" do
+  state[:focus] ||= :name
+
+  text_input :name, focused: state[:focus] == :name
+  text_input :email, focused: state[:focus] == :email
+
+  on_key "tab" do |s|
+    s[:focus] = s[:focus] == :name ? :email : :name
+  end
+
+  on_key "enter" do |s|
+    # Submit
+  end
+end.run!
+```
+
+**Phase 4: Agentic Mode**
+
+StreamWeaver's `run_once!` maps to TUI forms:
+
+```ruby
+result = tui "Quick Input" do
+  text "Enter your name:"
+  text_input :name
+
+  on_key "enter" do |s|
+    s[:_submit] = true
+  end
+end.run_once!
+
+puts result[:name]
+```
+
+## Component Mapping Deep Dive
+
+### Text & Display
+
+```ruby
+# StreamWeaver (web)
+text "Hello, #{name}"
+md "**Bold** text"
+header "Section"
+
+# CharmWeaver (TUI)
+text "Hello, #{name}"                    # Plain text
+text "**Bold** text", style: :markdown   # Glamour rendering
+header "Section"                          # Lipgloss bold + color
+```
+
+### Input Components
+
+```ruby
+# StreamWeaver (web)
+text_field :name, placeholder: "Name"
+
+# CharmWeaver (TUI) - wraps Bubbles::TextInput
+text_input :name, placeholder: "Name"
+```
+
+The key difference: TUI inputs require focus management and cursor handling, which Bubbles handles internally.
+
+### Layout
+
+```ruby
+# StreamWeaver (web)
+columns widths: ['30%', '70%'] do
+  column { sidebar_content }
+  column { main_content }
+end
+
+# CharmWeaver (TUI) - character-based widths
+columns widths: [20, 60] do
+  column { sidebar_content }
+  column { main_content }
+end
+```
+
+### Styling
+
+```ruby
+# New: Lipgloss-based styling DSL
+tui "Styled" do
+  style :title,
+    bold: true,
+    foreground: "#FF6B6B",
+    margin_bottom: 1
+
+  text "Welcome", style: :title
+end.run!
+```
+
+## Challenges & Solutions
+
+### Challenge 1: Event Model Difference
+
+**Web:** Events trigger HTTP requests, server re-renders entire UI
+**TUI:** Events are keyboard/mouse messages, model updates locally
+
+**Solution:** CharmWeaver's `update()` method triggers block re-execution, mimicking StreamWeaver's behavior. The pattern is the same—just the transport differs.
+
+### Challenge 2: Component Complexity
+
+Bubbles components (TextInput, List) maintain internal state (cursor position, scroll offset). StreamWeaver components are stateless—state lives in the hash.
+
+**Solution:** CharmWeaver manages Bubbles component instances internally, syncing their values to `state[:key]` after each update cycle.
+
+```ruby
+class CharmWeaver::App
+  def text_input(key, **opts)
+    @bubble_components[key] ||= Bubbles::TextInput.new(**opts)
+    @components << { type: :text_input, key: key, component: @bubble_components[key] }
+  end
+
+  def update(msg)
+    # Forward messages to focused component
+    if focused = @bubble_components[@focused_key]
+      focused, cmd = focused.update(msg)
+      @state[@focused_key] = focused.value
+    end
+    [self, cmd]
+  end
+end
+```
+
+### Challenge 3: Mouse Support
+
+StreamWeaver buttons are clickable. TUI "buttons" are typically key-bound.
+
+**Solution:** Use Bubblezone for mouse region tracking:
+
+```ruby
+tui "Clickable" do
+  button "Save" do |s|
+    s[:saved] = true
+  end
+  # Renders as clickable zone + key hint: [Save] (Enter)
+end.run!
+```
+
+### Challenge 4: Forms & Submission
+
+StreamWeaver's `run_once!` returns when a form is "submitted." TUIs need explicit submission handling.
+
+**Solution:** Define submission triggers:
+
+```ruby
+result = tui "Form" do
+  text_input :name
+  text_input :email
+
+  # Explicit submit key
+  submit_on "ctrl+s"
+  # Or automatic when all fields filled
+  submit_when { state[:name] && state[:email] }
+end.run_once!
+```
+
+## API Design: Full Example
+
+```ruby
+require 'charm_weaver'
+
+tui "Task Manager",
+  theme: :dracula,        # Lipgloss color scheme
+  border: :rounded        # App border style
+do
+  header "My Tasks"
+
+  # Input with auto-focus
+  text_input :new_task, placeholder: "Add task..."
+
+  on_key "enter" do |s|
+    next if s[:new_task].to_s.empty?
+    s[:tasks] ||= []
+    s[:tasks] << { name: s[:new_task], done: false }
+    s[:new_task] = ""
+  end
+
+  divider
+
+  # List with selection
+  state[:tasks]&.each_with_index do |task, i|
+    selected = state[:selected] == i
+
+    hstack do
+      text selected ? ">" : " "
+      text task[:done] ? "[x]" : "[ ]"
+      text task[:name], style: task[:done] ? :dim : :normal
+    end
+  end
+
+  # Key bindings
+  on_key "j" do |s|
+    s[:selected] = [(s[:selected] || 0) + 1, (s[:tasks]&.size || 1) - 1].min
+  end
+
+  on_key "k" do |s|
+    s[:selected] = [(s[:selected] || 0) - 1, 0].max
+  end
+
+  on_key "space" do |s|
+    if s[:tasks] && s[:selected]
+      s[:tasks][s[:selected]][:done] ^= true
+    end
+  end
+
+  on_key "d" do |s|
+    s[:tasks]&.delete_at(s[:selected]) if s[:selected]
+  end
+
+  # Footer
+  divider
+  text "j/k: navigate | space: toggle | d: delete | q: quit", style: :help
+end.run!
+```
+
+## Token Efficiency Comparison
+
+The goal: same expressiveness, fewer tokens for LLM-driven development.
+
+**Raw Bubbletea (58 lines):**
+```ruby
+class TaskManager
+  include Bubbletea::Model
+
+  def initialize
+    @tasks = []
+    @new_task = Bubbles::TextInput.new(placeholder: "Add task...")
+    @selected = 0
+    @focused = :input
+  end
+
+  def init
+    [self, Bubbles::TextInput.focus]
+  end
+
+  def update(msg)
+    case msg
+    when Bubbletea::KeyMsg
+      case msg.key
+      when "enter"
+        unless @new_task.value.empty?
+          @tasks << { name: @new_task.value, done: false }
+          @new_task.set_value("")
+        end
+      when "j"
+        @selected = [@selected + 1, @tasks.size - 1].min
+      when "k"
+        @selected = [@selected - 1, 0].max
+      when " "
+        @tasks[@selected][:done] ^= true if @tasks[@selected]
+      when "d"
+        @tasks.delete_at(@selected)
+      when "q"
+        return [self, Bubbletea.quit]
+      else
+        @new_task, cmd = @new_task.update(msg)
+        return [self, cmd]
+      end
+    end
+    [self, nil]
+  end
+
+  def view
+    lines = ["My Tasks", "", @new_task.view, ""]
+    @tasks.each_with_index do |t, i|
+      prefix = i == @selected ? ">" : " "
+      check = t[:done] ? "[x]" : "[ ]"
+      lines << "#{prefix} #{check} #{t[:name]}"
+    end
+    lines << ""
+    lines << "j/k: navigate | space: toggle | d: delete | q: quit"
+    lines.join("\n")
+  end
+end
+
+Bubbletea::Program.new(TaskManager.new).run
+```
+
+**CharmWeaver DSL (35 lines):** ~40% fewer tokens, same functionality.
+
+## Implementation Roadmap
+
+### Phase 1: Core (Week 1-2)
+- [ ] `CharmWeaver::App` base class wrapping Bubbletea::Model
+- [ ] Basic components: `text`, `header`, `divider`, `vstack`, `hstack`
+- [ ] State hash integration
+- [ ] `on_key` handler registration
+- [ ] Block re-execution in `view()`
+
+### Phase 2: Input Components (Week 3-4)
+- [ ] `text_input` wrapping Bubbles::TextInput
+- [ ] `text_area` wrapping Bubbles::TextArea
+- [ ] Focus management system
+- [ ] Tab navigation between inputs
+
+### Phase 3: Selection Components (Week 5-6)
+- [ ] `list` wrapping Bubbles::List
+- [ ] `table` wrapping Bubbles::Table
+- [ ] Selection state synchronization
+
+### Phase 4: Styling & Polish (Week 7-8)
+- [ ] Theme support via Lipgloss
+- [ ] `style` DSL for custom styles
+- [ ] `box` component with borders
+- [ ] `alert` with color variants
+
+### Phase 5: Advanced Features (Week 9-10)
+- [ ] Mouse support via Bubblezone
+- [ ] `run_once!` agentic mode
+- [ ] Animation via Harmonica
+- [ ] Charts via NTCharts
+
+## Risks & Mitigations
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| Bubbles component state sync complexity | High | Medium | Start with simple components, add complex ones incrementally |
+| Focus management edge cases | Medium | High | Study Huh? form library implementation |
+| Performance with large state | Low | Medium | Optimize re-render diffing if needed |
+| Charm gem API changes | Medium | Medium | Pin gem versions, contribute upstream |
+
+## Success Criteria
+
+1. **Token efficiency:** CharmWeaver DSL uses 30-50% fewer tokens than raw Bubbletea for equivalent functionality
+2. **Familiar API:** StreamWeaver users can transfer knowledge directly
+3. **Full component coverage:** All common TUI patterns expressible
+4. **Production quality:** Suitable for real CLI tools, not just demos
+
+## Conclusion
+
+Adapting StreamWeaver's DSL to Charm is **highly feasible**. The reactive model (block re-execution on state change) maps directly to Bubbletea's Elm Architecture. The main work is:
+
+1. Wrapping Bubbles components to sync with `state[:key]`
+2. Implementing focus management
+3. Translating web concepts (buttons → key bindings)
+
+The payoff: Ruby developers get a token-efficient, declarative DSL for beautiful TUIs, consistent with StreamWeaver's web approach. Same mental model, different output target.
+
+**Recommendation:** Proceed with Phase 1 proof of concept to validate the component wrapping approach before committing to full implementation.

data/docs/ideas/2026-08-27-static-doc-shelf-export.md

@@ -0,0 +1,153 @@
+# Static Doc Shelf — free multi-doc export for canvas docs
+
+**Status:** captured, not scheduled. Brainstormed 2026-08-27; no implementation.
+**Trigger to pick this up:** when a doc corpus needs to reach a reader who
+should not have to run StreamWeaver, use GitHub, or hold an account.
+
+## The gap, in one line
+
+`streamweaver export` gives you one self-contained HTML file. `canvas-read`
+gives you a browsable *shelf* of many docs — but only as a local Sinatra app.
+**There is no static shelf.** That is the whole missing piece.
+
+## Why this is small
+
+Both halves already exist and are reused verbatim:
+
+- `StreamWeaver::Export::HtmlExporter.from_dsl_file(path, theme:, layout:)` —
+  per-doc rendering, already handles `.rb`, mermaid, images, CDN collection.
+- `StreamWeaver::Canvas::Reader::FileList.build(args, ...)` — input resolution,
+  already globs `.rb` and `.org`, already does multi-root discovery.
+- `StreamWeaver::Org::Reader` — `.org` → DSL, already parses `#+TITLE:`
+  (`lib/stream_weaver/org/reader.rb:62`).
+
+No new rendering engine. No Opal component-parity dependency.
+
+## Framing decisions (settled during the brainstorm)
+
+| Question | Decision |
+|---|---|
+| What is the durable asset? | The extraction pipeline, the doc format, and the curated corpus. **Not** the delivery. |
+| So how much delivery do we build? | As little as possible. Delivery is plumbing; over-building it means building the thing that is not the moat. |
+| What do recipients do? | **Read only.** Published shelf. No accounts, no writes, no server. Tracking stays on the author's side. |
+| Build strategy | Approach A (a real `shelf` command), shipped C-first (walk + export + index usable before search exists). |
+
+### Approaches considered and rejected
+
+- **One Opal app that is the shelf.** Single bundle, instant nav, snappy — but
+  every doc in the corpus must first clear Opal component parity (tables,
+  mermaid, images), and `stream_weaver-5n9w` shows doc output there still has
+  rough edges. Rejected: it gates a content corpus on framework work.
+- **Bash loop + hand-written index.** `for f in docs/*.rb; do streamweaver
+  export "$f"; done` plus a small index generator. Genuinely available today
+  and worth doing if the need is urgent and one-off. Differs from the real
+  thing by exactly two features: search and shared nav.
+
+## Design § 1 — Doc identity and the manifest
+
+This is the part that is expensive to change later, and the reason to design it
+now rather than improvise it under time pressure.
+
+**Stable, content-derived slugs — never ordinal.** The reader addresses docs by
+position (`?file=0`); `FileList` carries `files`, `history_roots`, and `labels`
+but no slug or id. A link to "the third doc in the directory" breaks the moment
+a doc is added. Precedence for the shelf:
+
+1. explicit `#+SLUG:` in the org file
+2. slugified `#+TITLE:`
+3. filename basename
+
+Output is `dist/<slug>.html`, stable across rebuilds and reordering.
+
+**`dist/shelf.json` — one manifest, three consumers.** An array of
+`{slug, title, source, headings[], tags[], links_out[], links_in[]}`:
+
+1. feeds client-side search (no separate `search.json`)
+2. is what an **agent** reads to find what is in the corpus without crawling HTML
+3. is the substrate a future wiki computes related-content over
+
+The builder walks every file anyway, so this is close to free.
+
+**Tags from org.** Teach `Org::Reader` to read `#+FILETAGS:` into the manifest —
+a few lines, and it means docs can be categorized in the authoring format
+starting immediately, so a later wiki inherits real data instead of an empty
+corpus.
+
+### Wiki-readiness (deliberate seam)
+
+An org-based Karpathy-style wiki over the doc corpus is anticipated but **out of
+scope here** — no related-content rendering, no category pages, no graph view.
+What this design *does* commit to, so the wiki is cheap when it arrives:
+
+- `[[slug]]` resolves to `<a href="slug.html">` when the slug is in the
+  manifest; stays literal text when it is not. ~10 lines.
+- Forward links **and backlinks** are recorded in `shelf.json`.
+
+The payoff is timing: links can be written into org docs from day one, so the
+corpus arrives at the wiki already connected rather than needing a linking pass
+over the whole shelf. Related: a desire to extend UKF to support org mode.
+
+## Design § 2 — The build pipeline
+
+**Command:** `streamweaver shelf <paths...> [-o dist/] [--title "..."] [--offline]`
+
+Same argument shape as `canvas-read`, using **the same `FileList.build`** — so
+whatever `canvas-read` shows, `shelf` builds, and the two cannot drift into
+disagreeing about what is in the corpus.
+
+**Three passes, because links force it:**
+
+1. **Metadata** — walk every file, extract `{slug, title, tags, source}`. No
+   rendering. Exists because `[[slug]]` cannot resolve until all slugs are known.
+2. **Render** — per doc, `HtmlExporter.from_dsl_file(path, theme: :default,
+   layout: :fluid)` (identical defaults to `streamweaver export`, so a shelf
+   page and a single-file export of the same doc are byte-comparable), then
+   resolve `[[slug]]` and record edges.
+3. **Write** — `dist/<slug>.html`, `dist/index.html`, `dist/shelf.json` with
+   backlinks now that all edges are known.
+
+**Units:**
+
+| Unit | Job | Knows nothing about |
+|---|---|---|
+| `Shelf::Manifest` | slug/title/tag extraction, doc list | HTML |
+| `Shelf::LinkResolver` | `[[slug]]` → anchor, emits edges | files, rendering |
+| `Shelf::IndexPage` | builds the index | the filesystem |
+| `Shelf::Builder` | orchestrates passes, writes output | how any of the above work |
+
+**The index page is itself a StreamWeaver DSL doc**, rendered through the same
+`HtmlExporter`. No second templating system, no second styling path — the index
+inherits the theme and is authored in the DSL.
+
+**Where a shelf differs from N single files** (decided, not open):
+
+- **Images copy to `dist/assets/` with paths rewritten, not base64.**
+  `--inline-images` suits one emailed file; across a 50-doc shelf it duplicates
+  every shared image into every referencing page. The flag stays for the
+  single-file path.
+- **Mermaid is written once to `dist/assets/` and shared.** `--offline`
+  currently inlines the whole library per document — fine once, absurd fifty
+  times. One copy, every page points at it, still works with no network.
+
+## Slices
+
+1. **Walk + per-doc export + generated index.** Usable immediately; no search.
+2. **`shelf.json` + client-side search + shared nav strip.**
+3. **`[[slug]]` resolution + backlinks.** (Can fold into 1 if links are wanted
+   from the very first corpus.)
+
+## Open questions deferred to build time
+
+- **Hosting/privacy.** GitHub Pages is free only for public repos; a corpus
+  intended for a named set of students is not obviously public. Alternatives
+  worth pricing then: Netlify or Cloudflare Pages (both serve from a private
+  repo on free tiers).
+- Whether readers want search at all, categorization by category/position, or
+  links back to source-video timestamps. Unknown until a real reader uses it —
+  do not guess, ship slice 1 and watch.
+
+## Related
+
+- `docs/opal-jamstack.md` — the static Opal path and its Phase 1 scope limits
+- `stream_weaver-5n9w` — opal-build standalone HTML `sidebar_toc` scroll-spy gap
+- `stream_weaver-mdc` — canvas docs epic (discovery, export, cleanup, fidelity)