stream_weaver 0.3.0

data/docs/plans/2025-12-16-form-blocks-design.md

@@ -0,0 +1,124 @@
+# Form Blocks with Deferred Submission
+
+## Overview
+
+Add a `form` block to StreamWeaver that groups multiple form elements together, uses client-side only state until submission, and sends all values in a single HTMX POST on submit.
+
+## Problem
+
+Currently, all form widgets trigger immediate HTMX requests on change, syncing state with the server on every keystroke/selection. This causes issues when:
+1. Multiple fields need to be edited before saving
+2. Navigation state gets reset during re-renders
+3. Unnecessary server round-trips for uncommitted changes
+
+## API
+
+```ruby
+form :edit_person do
+  text_field :name, placeholder: 'Name'
+  select :status, %w[active paused archived]
+  text_area :notes, placeholder: 'Notes...', rows: 3
+
+  submit 'Save' do |form_values|
+    # form_values = { name: "...", status: "...", notes: "..." }
+    # state[:edit_person] already updated at this point
+    api.save_person(form_values)  # optional side effects
+  end
+
+  cancel 'Cancel'  # resets to original values, no server request
+end
+```
+
+## Design Decisions
+
+### State Namespace: Nested Hash
+Form values stored as `state[:edit_person][:name]` - nested hash structure matching Rails conventions (strong params, form_for).
+
+### Initial Values: From State
+Form reads initial values from `state[:form_name]`. App code is responsible for populating state before rendering (like Rails controller setting `@person = Person.find(id)`).
+
+### Submit Behavior: Auto-Update State
+On submit, state is automatically updated with form values, then the submit block runs. This keeps UI consistent - other components using `state[:edit_person][:name]` show current values.
+
+### Context Flag for Widgets
+Same DSL methods (`text_field`, `select`, etc.) work inside and outside forms. A context flag tells the adapter to render differently (no HTMX, form-scoped x-model).
+
+## Client-Side Behavior
+
+Form block wraps contents in Alpine.js scope with local state:
+
+```html
+<div x-data="{
+  _form: { name: 'Alice', status: 'active', notes: '' },
+  _original: { name: 'Alice', status: 'active', notes: '' }
+}">
+  <input type="text" x-model="_form.name" name="edit_person[name]">
+  <select x-model="_form.status" name="edit_person[status]">...</select>
+
+  <button hx-post="/form/edit_person" hx-include="[name^='edit_person']">Save</button>
+  <button type="button" @click="_form = JSON.parse(JSON.stringify(_original))">Cancel</button>
+</div>
+```
+
+### Widget Rendering Differences
+
+| Aspect | Standalone widget | Widget inside form |
+|--------|-------------------|-------------------|
+| `x-model` | `x-model="name"` (root scope) | `x-model="_form.name"` (form-local) |
+| `hx-post` | On every change (`/update`) | None |
+| `hx-trigger` | `keyup changed delay:500ms` | None |
+| `name` attr | `name="name"` | `name="form_name[field]"` (Rails nested) |
+
+### Cancel Button
+Pure Alpine - resets `_form` to `_original` snapshot, no server request.
+
+### Submit Button
+Single HTMX POST to `/form/:form_name` with all form values.
+
+## Server-Side Handling
+
+New endpoint `POST /form/:form_name`:
+
+1. Parse Rails-style nested params: `edit_person[name]` -> `{ name: "..." }`
+2. Auto-update state: `state[:edit_person] = form_values`
+3. Execute submit block if defined
+4. Re-render page with updated state
+
+## Implementation Files
+
+| File | Changes |
+|------|---------|
+| `lib/stream_weaver/components.rb` | Add `Form` component class |
+| `lib/stream_weaver/app.rb` | Add `form`, `submit`, `cancel` DSL methods; add `@form_context` flag |
+| `lib/stream_weaver/adapter/alpinejs.rb` | Add `render_form`, modify widget renderers to check form context |
+| `lib/stream_weaver/server.rb` | Add `POST /form/:form_name` endpoint |
+| `docs/for_llms.md` | Document form block usage and auto-update behavior |
+
+## Form Component Structure
+
+```ruby
+class Form < Base
+  attr_reader :name, :submit_label, :cancel_label, :submit_action
+  attr_accessor :children
+
+  def initialize(name, **options)
+    @name = name
+    @children = []
+    @submit_label = nil
+    @cancel_label = nil
+    @submit_action = nil
+  end
+
+  def execute_submit(state, form_values)
+    @submit_action&.call(form_values)
+  end
+end
+```
+
+## Documentation Notes
+
+For `docs/for_llms.md`, emphasize:
+- Form values auto-update to state on submit (state[:form_name] = form_values)
+- Submit block is for side effects (API calls), not state management
+- Cancel resets to original values without server request
+- Same DSL methods work inside/outside forms - context determines behavior

data/docs/plans/2025-12-30-examples-browser-design.md

@@ -0,0 +1,152 @@
+# Examples Browser Design
+
+## Overview
+
+An interactive Examples Browser app that showcases StreamWeaver examples, built with StreamWeaver itself. Features directory navigation, syntax-highlighted code display, and ability to run examples.
+
+## Goals
+
+1. **Phase 1 (MVP):** Browse and run examples with read-only code display
+2. **Phase 2:** Edit code and run modified versions
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Examples Browser                      │
+├──────────────┬──────────────────────────────────────────┤
+│   Sidebar    │              Main Area                    │
+│              │  ┌────────────────────────────────────┐  │
+│  📁 basic/   │  │  Code Panel (CodeMirror 5)         │  │
+│    hello_wo  │  │  ┌──────────────────────────────┐  │  │
+│    todo_lis  │  │  │ require 'stream_weaver'      │  │  │
+│  📁 agentic/ │  │  │                              │  │  │
+│    ...       │  │  │ app "Hello" do               │  │  │
+│              │  │  │   text_field :name           │  │  │
+│              │  │  └──────────────────────────────┘  │  │
+│              │  │  [▶ Run]  [✓ Check Syntax]         │  │
+│              │  └────────────────────────────────────┘  │
+└──────────────┴──────────────────────────────────────────┘
+```
+
+## State Structure
+
+```ruby
+state[:selected_dir]      # Currently expanded directory
+state[:selected_file]     # Full path to selected file
+state[:code_content]      # File content (or edited content in phase 2)
+state[:error_message]     # Syntax error from ruby -c
+state[:error_modal_open]  # Show/hide error modal
+state[:running_pid]       # Track spawned process for cleanup
+```
+
+## New Component: `code_editor`
+
+Added to core StreamWeaver for reusability.
+
+### Usage
+
+```ruby
+# Read-only (phase 1)
+code_editor :code_content, language: :ruby, readonly: true, height: "500px"
+
+# Editable (phase 2)
+code_editor :code_content, language: :ruby, readonly: false
+```
+
+### Implementation Details
+
+- Renders `<div>` with `hx-preserve="true"` to survive HTMX swaps
+- Contains hidden `<textarea>` bound to state key
+- Emits initialization JS for CodeMirror instance
+- Single instance pattern: `window.cmEditor` persists across navigation
+
+### CDN Dependencies (CodeMirror 5)
+
+```ruby
+stylesheets: [
+  "https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.65.16/codemirror.min.css"
+]
+scripts: [
+  "https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.65.16/codemirror.min.js",
+  "https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.65.16/mode/ruby/ruby.min.js"
+]
+```
+
+### HTMX Integration Strategy
+
+**Challenge:** CodeMirror creates complex DOM that HTMX can orphan/duplicate.
+
+**Solution:**
+1. Use `hx-preserve="true"` on editor container
+2. Update content via JS: `window.cmEditor.setValue(newContent)`
+3. Initialize once on DOMContentLoaded, not on HTMX swaps
+
+## Interactions
+
+### Run Flow
+
+1. User clicks "Run"
+2. System runs `ruby -c` on content for syntax check
+3. If error: Parse message, show error modal
+4. If OK: Write temp file to `/tmp/sw_example_*.rb`
+5. Spawn process: `ruby /tmp/sw_example_*.rb`
+6. Track PID for cleanup
+7. Show success toast
+
+### Error Modal
+
+```
+┌─────────────────────────────────────┐
+│  ❌ Syntax Error                    │
+├─────────────────────────────────────┤
+│  Line 5: syntax error, unexpected   │
+│  end-of-input, expecting `end'      │
+│                          [Close]    │
+└─────────────────────────────────────┘
+```
+
+### Cleanup
+
+`at_exit` hook kills spawned PIDs (matches tutorial.rb pattern).
+
+## File Structure
+
+```
+lib/stream_weaver/
+├── components.rb          # Add CodeEditor class
+├── adapter/
+│   └── alpinejs.rb        # Add render_code_editor method
+└── views.rb               # Add CodeMirror CSS
+
+examples/
+└── advanced/
+    └── examples_browser.rb
+```
+
+## Implementation Plan
+
+### Phase 1: Core Component + MVP Browser
+
+1. Add `CodeEditor` component to `components.rb`
+2. Add `render_code_editor` to AlpineJS adapter
+3. Add CodeMirror initialization JS
+4. Build `examples_browser.rb`:
+   - Directory discovery
+   - Sidebar navigation
+   - Code display (read-only)
+   - Run button with syntax check
+   - Error modal
+
+### Phase 2: Editing Support
+
+1. Enable `readonly: false` mode
+2. Sync edited content back to state
+3. Track "modified" state
+4. "Run Modified" writes temp file
+5. "Reset" button restores original
+
+## Inspiration
+
+- [Glimmer meta_example.rb](https://github.com/AndyObtiva/glimmer-dsl-libui/blob/master/examples/meta_example.rb) - Example discovery, categorization, launch pattern
+- StreamWeaver tutorial.rb - Process spawning, PID tracking, temp file approach

data/docs/plans/2026-01-02-charts-design.md

@@ -0,0 +1,288 @@
+# StreamWeaver Charts Design
+
+**Date**: 2026-01-02
+**Status**: Approved
+**Context**: Spin-off from cultiv-os/cultiv-ai daily-brief timing instrumentation work
+
+## Overview
+
+Add chart visualization components to StreamWeaver, following Streamlit's data-first philosophy while maintaining StreamWeaver's minimal-dependency ethos.
+
+### Goals
+
+1. Composable chart primitives (not a pre-built dashboard)
+2. External data pattern (charts read files, don't bloat session)
+3. Chart.js via CDN, lazy-loaded only when charts are used
+4. Path toward Streamlit-like API as Ruby DataFrame ecosystem matures
+
+## Components
+
+| Component | Purpose | Primary Use |
+|-----------|---------|-------------|
+| `bar_chart` | Horizontal/vertical bars | Phase breakdown, comparisons |
+| `line_chart` | Trend lines | Time series, progress |
+| `stacked_bar_chart` | Segmented bars | Distribution across runs |
+| `sparkline` | Minimal line (no axes) | Compact trends |
+| `hbar_chart` | Horizontal bar shorthand | Quick horizontal bars |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  StreamWeaver App                                       │
+│  ┌─────────────────────────────────────────────────┐   │
+│  │  bar_chart file: "timing.yaml", path: "..."     │   │
+│  └─────────────────────────────────────────────────┘   │
+│                         │                               │
+│                         ▼                               │
+│  ┌─────────────────────────────────────────────────┐   │
+│  │  Components::BarChart                            │   │
+│  │  - Loads data (file or inline)                  │   │
+│  │  - Normalizes to labels/values                  │   │
+│  └─────────────────────────────────────────────────┘   │
+│                         │                               │
+│                         ▼                               │
+│  ┌─────────────────────────────────────────────────┐   │
+│  │  AlpineJS Adapter                                │   │
+│  │  - Renders <canvas> with Chart.js config        │   │
+│  │  - Lazy-loads Chart.js CDN on first chart       │   │
+│  └─────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────┘
+```
+
+## API Design
+
+### Data Input Options (Priority Order)
+
+```ruby
+# 1. File with dot-path (recommended for external data)
+bar_chart file: "~/metrics/timing.yaml", path: "entries.-1.phases"
+
+# 2. File with block transform (complex extraction)
+bar_chart file: "timing.yaml" do |data|
+  data[:entries].last[:phases]
+end
+
+# 3. Inline hash (quick/simple)
+bar_chart data: { calendar: 45, news: 120, tasks: 30 }
+
+# 4. Explicit labels/values (full control)
+bar_chart labels: %w[Calendar News Tasks],
+          values: [45, 120, 30]
+
+# 5. State-bound (when data is already in state)
+bar_chart data: :timing_phases  # reads state[:timing_phases]
+```
+
+### Common Options (All Chart Types)
+
+```ruby
+bar_chart data: timing,
+          title: "Phase Breakdown",        # Optional header
+          height: "300px",                 # CSS height (default: 250px)
+          horizontal: true,                # Bar direction (default: false)
+          colors: ["#c45b28", "#4a90d9"],  # Custom palette
+          show_legend: false,              # Hide legend (default: auto)
+          show_values: true                # Display values on bars
+```
+
+### Chart-Specific Options
+
+```ruby
+# Line chart
+line_chart data: trends,
+           fill: true,          # Area fill under line
+           smooth: true,        # Curved vs straight lines
+           points: false        # Hide data points
+
+# Stacked bar
+stacked_bar_chart data: runs,
+                  stack: true,      # true (stacked) or false (grouped)
+                  normalize: false  # Percentage mode (100% bars)
+```
+
+### DSL Methods
+
+```ruby
+app "Dashboard" do
+  bar_chart data: { a: 1, b: 2 }      # Vertical bars
+  hbar_chart data: { a: 1, b: 2 }     # Horizontal bars (shorthand)
+  line_chart data: [1, 2, 3, 4]       # Simple array = sequential x
+  sparkline data: [1, 2, 3, 4]        # Minimal line (no axes/labels)
+  stacked_bar_chart data: complex_data
+end
+```
+
+## Implementation Details
+
+### Chart.js Integration (Lazy Loading)
+
+```ruby
+# In views.rb - only include when charts are present
+def chart_js_assets
+  return unless @app.has_charts?
+
+  script(src: "https://cdn.jsdelivr.net/npm/chart.js@4.4.1/dist/chart.umd.min.js",
+         defer: true)
+end
+```
+
+### Component Class Pattern
+
+```ruby
+class BarChart < Base
+  attr_reader :labels, :values, :options
+
+  def initialize(data: nil, file: nil, path: nil, labels: nil, values: nil, **options, &block)
+    @data = data
+    @file = file
+    @path = path
+    @labels = labels
+    @values = values
+    @transform_block = block
+    @options = options
+  end
+
+  def resolve_data(state)
+    if @file
+      raw = load_file(@file)
+      raw = @transform_block ? @transform_block.call(raw) : extract_path(raw, @path)
+      normalize_hash(raw)
+    elsif @data.is_a?(Symbol)
+      normalize_hash(state[@data])
+    elsif @data.is_a?(Hash)
+      normalize_hash(@data)
+    else
+      { labels: @labels, values: @values }
+    end
+  end
+
+  def render(view, state)
+    view.adapter.render_bar_chart(view, self, state)
+  end
+end
+```
+
+### File Loading & Path Extraction
+
+```ruby
+# Supports YAML, JSON, expanding ~
+def load_file(path)
+  expanded = File.expand_path(path)
+  case File.extname(expanded)
+  when '.yaml', '.yml' then YAML.safe_load_file(expanded, symbolize_names: true)
+  when '.json' then JSON.parse(File.read(expanded), symbolize_keys: true)
+  else raise "Unsupported file type: #{path}"
+  end
+end
+
+# Dot-path extraction: "entries.-1.phases"
+def extract_path(data, path)
+  return data unless path
+  path.split('.').reduce(data) do |obj, key|
+    case key
+    when /^-?\d+$/ then obj[key.to_i]  # Array index
+    else obj[key.to_sym] rescue obj[key]  # Hash key
+    end
+  end
+end
+```
+
+## Example: Timing Dashboard
+
+```ruby
+# examples/charts/timing_dashboard.rb
+require 'stream_weaver'
+
+TIMING_FILE = File.expand_path("~/cultiv-os/metrics/brief-timing.yaml")
+
+app "Daily Brief Timing", layout: :wide do
+  header2 "Performance Dashboard"
+
+  # Latest run breakdown
+  card do
+    header3 "Latest Run"
+    hbar_chart file: TIMING_FILE,
+               path: "entries.-1.phases",
+               title: "Phase Breakdown (seconds)",
+               show_values: true,
+               colors: ["#c45b28"]
+  end
+
+  columns widths: ['50%', '50%'] do
+    column do
+      card do
+        header3 "Total Duration Trend"
+        line_chart file: TIMING_FILE do |data|
+          data[:entries].last(14).map { |e| e[:wall_clock_seconds] }
+        end
+      end
+    end
+
+    column do
+      card do
+        header3 "News-Wait Over Time"
+        sparkline file: TIMING_FILE do |data|
+          data[:entries].last(14).map { |e| e[:phases][:"news-wait"] }
+        end
+      end
+    end
+  end
+
+  # Historical comparison
+  card do
+    header3 "Last 7 Runs by Phase"
+    stacked_bar_chart file: TIMING_FILE do |data|
+      data[:entries].last(7).map do |entry|
+        { label: entry[:date], **entry[:phases] }
+      end
+    end
+  end
+end.run!
+```
+
+## Implementation Plan
+
+| Phase | What | Why First |
+|-------|------|-----------|
+| **1** | `BarChart` component + adapter | Most useful, validates pattern |
+| **2** | Chart.js CDN lazy-loading in views.rb | Required for any chart |
+| **3** | File loading + dot-path extraction | Core data pattern |
+| **4** | `LineChart` + `sparkline` | Second most useful |
+| **5** | `StackedBarChart` | More complex data shape |
+| **6** | Example dashboard | Proves composition works |
+| **7** | Tests | Ensure stability |
+
+## Files to Create/Modify
+
+| File | Action |
+|------|--------|
+| `lib/stream_weaver/components.rb` | Add BarChart, LineChart, StackedBarChart classes |
+| `lib/stream_weaver/adapter/alpinejs.rb` | Add render methods for each chart type |
+| `lib/stream_weaver/views.rb` | Add conditional Chart.js CDN include |
+| `lib/stream_weaver/app.rb` | Add DSL methods |
+| `examples/charts/timing_dashboard.rb` | New example |
+| `spec/components/charts_spec.rb` | New test file |
+
+## Design Decisions
+
+### Why Chart.js via CDN?
+- Zero build step (fits StreamWeaver's philosophy)
+- Apps without charts pay no cost
+- Well-documented, handles edge cases (scaling, tooltips, animation)
+
+### Why file-based data loading?
+- Session storage has limits (~4KB cookies, memory for server-side)
+- Timing data already lives in external YAML
+- Pattern: session for UI state, external for data
+
+### Why explicit API first?
+- Ruby hashes lack Pandas-style metadata
+- Can evolve toward Streamlit-like inference later
+- Optional DataFrame support (ruby-polars, Rover) when gems present
+
+## Future Considerations
+
+- **DataFrame support**: Detect ruby-polars/Rover, enable richer data inference
+- **Auto-refresh**: `refresh: 30` option to re-read files periodically
+- **Dashboard creator UI**: Visual tool for composing charts (ultrathink later)