stream_weaver 0.3.0

data/docs/plans/2026-01-10-canvas-ipc-design.md

@@ -0,0 +1,247 @@
+# Canvas IPC Design
+
+Two-way interaction between Claude Code and StreamWeaver UI, inspired by [claude-canvas](https://github.com/BEARLY-HODLING/claude-canvas).
+
+## Goal
+
+A single browser window that Claude Code can:
+- Push UI content to (forms, displays, etc.)
+- Receive user interactions from (button clicks, form submissions)
+- All in real-time via IPC, not HTTP polling
+
+```
+┌─────────────────────┐     ┌──────────────────────┐
+│   Claude Code       │◄───►│   Single UI Window   │
+│   (Terminal)        │     │   (Browser)          │
+└─────────────────────┘     └──────────────────────┘
+        │                            │
+        └── Unix Socket ─────────────┘
+            + WebSocket
+```
+
+## Architecture
+
+```
+┌─────────────┐                  ┌─────────────────────────────────┐                  ┌─────────────┐
+│ Claude Code │◄─Unix Socket────►│        Canvas Bridge            │◄───WebSocket────►│   Browser   │
+│             │                  │                                 │                  │             │
+│ streamweaver│  ~/.streamweaver │  - Sinatra + WebSocket          │  ws://...:4568   │ StreamWeaver│
+│ canvas ...  │  /canvas.sock    │  - Session management           │                  │     UI      │
+└─────────────┘                  │  - DSL → HTML rendering         │                  └─────────────┘
+                                 │  - Event routing                │
+                                 └─────────────────────────────────┘
+```
+
+### Why This Architecture
+
+- Browser can't use Unix sockets directly
+- Unix socket for Claude ↔ Bridge (fast, local IPC)
+- WebSocket for Bridge ↔ Browser (real-time, bidirectional)
+- Bridge process auto-starts on first use, reuses thereafter (like existing Service)
+
+## Process Lifecycle
+
+**Files:**
+```
+~/.streamweaver/
+├── server.pid          # Existing HTTP service
+├── canvas.pid          # Canvas bridge process
+├── canvas.sock         # Unix socket for IPC
+└── server.log
+```
+
+**First invocation:**
+1. Check if `canvas.pid` exists and process is alive
+2. If not running → spawn bridge, write PID, create socket
+3. Connect to socket, send "create session" message
+4. Bridge opens browser to `http://localhost:4568/canvas/<name>`
+5. Returns socket connection to Claude Code
+
+**Subsequent invocations:** Reuse existing bridge, create new sessions as needed.
+
+## IPC Protocol
+
+Line-delimited JSON over Unix socket.
+
+### Claude Code → Bridge
+
+| Message | Purpose | Example |
+|---------|---------|---------|
+| `create` | Create session | `{"type":"create","name":"survey"}` |
+| `push` | Push UI content | `{"type":"push","name":"survey","dsl":"header1 'Pick One'"}` |
+| `close` | Close session | `{"type":"close","name":"survey"}` |
+| `get_state` | Get current state | `{"type":"get_state","name":"survey"}` |
+
+### Bridge → Claude Code
+
+| Message | Purpose | Example |
+|---------|---------|---------|
+| `ready` | Session created | `{"type":"ready","name":"survey","url":"http://..."}` |
+| `event` | User interaction | `{"type":"event","name":"survey","event":"submit","data":{...}}` |
+| `state` | Response to get_state | `{"type":"state","name":"survey","data":{...}}` |
+| `closed` | Session closed | `{"type":"closed","name":"survey"}` |
+
+### Event Types
+
+- `submit` - User clicked submit button
+- `action` - User clicked a named button
+- `change` - Field value changed (optional)
+- `cancel` - User cancelled/closed
+
+## Adapter Mode
+
+Modify `Adapter::AlpineJS` to support WebSocket mode:
+
+| Mode | Component Output | Backend |
+|------|-----------------|---------|
+| `http` (current) | HTMX `hx-post`, `hx-target` | Sinatra routes |
+| `websocket` (canvas) | Alpine `@click` → WebSocket | Bridge process |
+
+**Button example in WebSocket mode:**
+```ruby
+def button_attributes(button)
+  if mode == :websocket
+    { '@click' => "sendEvent('action', {button: '#{button.id}', state: formState()})" }
+  else
+    { 'hx-post' => "#{url_prefix}/action/#{button.id}", ... }
+  end
+end
+```
+
+## CLI Interface
+
+### Low-level (on-the-fly)
+
+```bash
+# Create/connect to session
+streamweaver canvas <name>
+
+# Push DSL (from stdin)
+streamweaver canvas-push <name> <<'RUBY'
+  header1 "Pick an option"
+  radio_group :choice, ["A", "B", "C"]
+  button "Submit"
+RUBY
+
+# Wait for event (blocks)
+streamweaver canvas-wait <name>
+# => {"event":"submit","data":{"choice":"B"}}
+
+# Close session
+streamweaver canvas-close <name>
+
+# Management
+streamweaver canvas-list
+streamweaver canvas-stop
+```
+
+### High-level helpers
+
+```bash
+# One-liners for common patterns
+streamweaver pick "Pick approach" "Refactor" "Adapter" "Patch"
+# => {"choice":"Adapter"}
+
+streamweaver confirm "Delete 47 files?"
+# => {"confirmed":true}
+
+streamweaver form "Quick Survey" \
+  --text "name:Your name" \
+  --radio "priority:Low,Medium,High"
+# => {"name":"Alice","priority":"High"}
+```
+
+## Ruby API
+
+### High-level helpers
+
+```ruby
+require 'stream_weaver/canvas'
+
+choice = StreamWeaver::Canvas.pick("Pick approach", ["Refactor", "Adapter", "Patch"])
+# => "Adapter"
+
+confirmed = StreamWeaver::Canvas.confirm("Delete 47 files?")
+# => true
+
+data = StreamWeaver::Canvas.form("Quick Survey") do
+  text_field :name, placeholder: "Your name"
+  radio_group :priority, ["Low", "Medium", "High"]
+end
+# => { name: "Alice", priority: "High" }
+```
+
+### Low-level session API
+
+```ruby
+session = StreamWeaver::Canvas.session("wizard")
+
+session.push do
+  header1 "Step 1"
+  text_field :email
+  button "Next"
+end
+
+result = session.wait  # => { event: "submit", data: { email: "..." } }
+
+session.push do
+  header1 "Step 2"
+  # ... based on result
+end
+
+session.close
+```
+
+### Project-specific reusable canvases
+
+```ruby
+module MyProject::Canvases
+  def self.code_review_picker(files)
+    StreamWeaver::Canvas.form("Select files to review") do
+      checkbox_group :files, select_all: "All" do
+        files.each { |f| item f, f }
+      end
+      radio_group :depth, ["Quick scan", "Detailed review"]
+    end
+  end
+end
+```
+
+## Implementation Structure
+
+### New files
+
+```
+lib/stream_weaver/
+├── canvas/
+│   ├── bridge.rb          # Bridge process (Unix socket + WebSocket)
+│   ├── session.rb         # Session management
+│   ├── helpers.rb         # High-level helpers (pick, confirm, form)
+│   └── protocol.rb        # Message types and serialization
+├── adapter/
+│   └── alpinejs.rb        # MODIFY: Add websocket mode
+└── cli.rb                 # MODIFY: Add canvas commands
+```
+
+### Dependencies
+
+```ruby
+gem 'faye-websocket'       # WebSocket support
+gem 'eventmachine'         # Required by faye-websocket
+```
+
+### Implementation phases
+
+| Phase | What | Why |
+|-------|------|-----|
+| 1 | Protocol + Bridge skeleton | Core IPC working |
+| 2 | CLI commands (canvas, push, wait) | Can test manually |
+| 3 | WebSocket adapter mode | Browser ↔ Bridge communication |
+| 4 | Session management | Multi-session support |
+| 5 | High-level helpers | Ergonomic API |
+| 6 | Terminal pane spawning (optional) | iTerm2/tmux split panes |
+
+## References
+
+- [claude-canvas](https://github.com/BEARLY-HODLING/claude-canvas) - Inspiration for IPC pattern
+- Existing StreamWeaver live sessions (HTTP polling approach)

data/docs/plans/2026-01-19-cabinet-control-components.md

@@ -0,0 +1,176 @@
+# Dashboard Components Plan
+
+**Date:** 2026-01-19
+**Status:** PHASE 2 COMPLETE
+**Goal:** Add dashboard-style components and styling to StreamWeaver for operations dashboards
+
+## Missing Components
+
+### Priority 1: Core Components
+
+| Component | Purpose | Props |
+|-----------|---------|-------|
+| `StatusDot` | Colored indicator dots with optional glow | `status:` (red/yellow/green/gray), `pulse:` (bool), `size:` (sm/md/lg) |
+| `Badge` | Small count/label badges | `text:`, `variant:` (default/danger/warning/success), `size:` |
+| `StatDisplay` | Large number + small label | `value:`, `label:`, `color:` |
+| `TypeTag` | Colored type pills | `type:`, `text:` (RESEARCH, TASK, ESCALATION, etc.) |
+
+### Priority 2: Layout Components
+
+| Component | Purpose | Props |
+|-----------|---------|-------|
+| `AppShell` | Two-column layout with sidebar | `sidebar_width:`, `&block` for main + sidebar |
+| `Sidebar` | Fixed sidebar container | `position:` (left/right), `width:` |
+
+### Priority 3: Interactive Components
+
+| Component | Purpose | Props |
+|-----------|---------|-------|
+| `ExpandableCard` | Card that expands on click | `expanded:`, `on_toggle:`, `&block` |
+| `ActivityItem` | Time + title + summary + type badge | `time:`, `title:`, `summary:`, `type:` |
+| `PriorityItem` | Item with priority-colored left border | `priority:` (critical/urgent/high/normal), `title:`, `description:` |
+
+### Priority 4: Animation Components
+
+| Component | Purpose | Props |
+|-----------|---------|-------|
+| `PulseIndicator` | Animated pulsing dot for live status | `color:`, `label:` |
+
+## Missing CSS/Styling
+
+### Dark Theme Variables
+```css
+:root[data-theme="dark"] {
+  --sw-bg-deep: #0a0e14;
+  --sw-bg-surface: #131820;
+  --sw-bg-elevated: #1a2029;
+  --sw-bg-hover: #242d3a;
+  --sw-border: #2a3544;
+  --sw-text-primary: #e6edf3;
+  --sw-text-secondary: #8b949e;
+  --sw-text-muted: #565d66;
+  --sw-accent-blue: #58a6ff;
+  --sw-accent-purple: #a371f7;
+  --sw-status-red: #f85149;
+  --sw-status-yellow: #d29922;
+  --sw-status-green: #3fb950;
+}
+```
+
+### Effects
+- Glow effects for status indicators (`box-shadow` with color alpha)
+- Gradient text for summary numbers
+- Hover lift for cards (`transform: translateY(-2px)`)
+- Hover slide for items (`transform: translateX(4px)`)
+- Grid background overlay pattern
+
+### Fonts
+- JetBrains Mono for stats/timestamps (monospace)
+- Outfit for UI text (already have Source Sans 3)
+
+## Implementation Order
+
+1. **StatusDot** - Most fundamental, used everywhere
+2. **Badge** - Simple, high reuse
+3. **StatDisplay** - Used in cards
+4. **TypeTag** - Used in activity items
+5. **Dark theme CSS** - Enable the aesthetic
+6. **PulseIndicator** - Header status
+7. **AppShell/Sidebar** - Layout structure
+8. **ExpandableCard** - Interactive cards
+9. **ActivityItem** - Compound component
+10. **PriorityItem** - Escalation items
+
+## Files to Modify
+
+- `lib/stream_weaver/components.rb` - Add new component classes
+- `lib/stream_weaver/views.rb` - Add dark theme CSS variables
+- `lib/stream_weaver/css.rb` - Add animation/glow CSS
+- `lib/stream_weaver/adapter/alpinejs.rb` - Add render methods
+
+## Testing
+
+Each component should be testable via:
+```bash
+./exe/streamweaver push test --dsl 'status_dot status: :red, pulse: true'
+```
+
+## Success Criteria
+
+Can build a operations dashboard-like dashboard using only StreamWeaver DSL:
+```ruby
+app_shell sidebar_width: 320 do
+  main do
+    header do
+      pulse_indicator color: :green, label: "System Active"
+    end
+    grid cols: 2 do
+      card do
+        status_dot status: :red
+        stat_display value: 5, label: "ACTIVITIES"
+      end
+    end
+  end
+  sidebar do
+    badge text: "5", variant: :danger
+    priority_item priority: :critical, title: "Needs attention"
+  end
+end
+```
+
+---
+
+## Phase 1 Implementation (COMPLETE)
+
+### Components Implemented
+
+| Component | File | DSL Method |
+|-----------|------|------------|
+| `StatusDot` | components.rb:19-42 | `status_dot status: :green, pulse: true` |
+| `Badge` | components.rb:44-66 | `badge "5", variant: :danger` |
+| `StatDisplay` | components.rb:68-91 | `stat_display value: 42, label: "TASKS"` |
+| `TypeTag` | components.rb:93-118 | `type_tag :research` |
+| `PulseIndicator` | components.rb:120-138 | `pulse_indicator color: :green, label: "Active"` |
+| `PriorityItem` | components.rb:140-170 | `priority_item priority: :critical, title: "..."` |
+| `ActivityItem` | components.rb:172-192 | `activity_item time: "15:00", title: "..."` |
+
+### CSS Added
+- Dashboard component styles (StatusDot, Badge, StatDisplay, TypeTag, PulseIndicator, PriorityItem, ActivityItem)
+- Dark theme (`sw-theme-dark`) with full color palette
+- Glow effects for status indicators
+- Pulse animation keyframes
+- Hover effects (lift, slide)
+
+### Theme Registration
+- Added `:dark` to `BUILT_IN_THEMES` in app.rb
+
+### Example App
+- `examples/dashboard_components.rb` - Demonstrates all new components
+
+## Phase 2 Implementation (COMPLETE)
+
+### Components Implemented
+
+| Component | File | DSL Method |
+|-----------|------|------------|
+| `AppShell` | components.rb | `app_shell sidebar_width: "320px" do ... end` |
+| `Sidebar` | components.rb | `sidebar header: "Title" do ... end` |
+| `MainContent` | components.rb | `main do ... end` |
+| `ExpandableCard` | components.rb | `expandable_card key: :x, title: "..." do ... end` |
+
+### CSS Added
+- App shell grid layout with sidebar
+- Sidebar with sticky positioning
+- Expandable card with hover/transition effects
+- Alpine.js transitions for expand/collapse
+- Responsive breakpoint (stacks on mobile)
+- Dark theme overrides for layout components
+
+### Example App
+- `examples/cabinet_control_demo.rb` - Full operations dashboard-style dashboard
+
+## Phase 3 (Future)
+
+- Grid background overlay pattern
+- Gradient text for large numbers
+- Grid/List view toggle

data/docs/plans/2026-01-26-gem-release-and-panel.md

@@ -0,0 +1,140 @@
+# StreamWeaver Gem Release & Panel Feature Plan
+
+## Context
+
+Preparing StreamWeaver for initial gem release to RubyGems, and implementing iTerm2 panel feature for Claude Code integration.
+
+## What's Done
+
+### 1. Documentation Updates ✅
+- **CHANGELOG.md** - Updated with all features since 0.1.0:
+  - Canvas Mode (IPC for external apps)
+  - Templates (wizard, choices, confirm, info, table, code, diff)
+  - Dashboard Components
+  - Table enhancements
+  - Dark theme
+  - default: option for text inputs
+
+- **README.md** - Completely rewritten:
+  - "Express intention, get interface" tagline
+  - Joy of Ruby philosophy section
+  - Four modes table (Standalone, Agentic, Canvas, Service)
+  - `ruby app.rb` vs `streamweaver app.rb` distinction
+  - Token efficiency emphasis (5-10x fewer tokens)
+  - iTerm2 built-in browser tip
+  - Condensed components reference
+
+### 2. Panel Feature (Partially Done)
+**Commits pushed:**
+- `062a295` - feat: Add panel command for iTerm2 split + canvas workflow
+
+**Files created/modified:**
+- `lib/stream_weaver/iterm.rb` - NEW - iTerm2 AppleScript integration
+- `lib/stream_weaver/cli.rb` - Added `panel` and `install-skill` commands
+- `lib/stream_weaver/canvas/bridge_server.rb` - Enhanced waiting screen
+- `lib/stream_weaver.rb` - Added require for iterm.rb
+
+**What works:**
+- `streamweaver panel [name]` - Creates canvas, splits iTerm2 pane
+- `streamweaver install-skill [--global]` - Installs Claude Code skill
+- AppleScript escaping fixed (using Open3.capture2 with stdin)
+- Split returns `:external` (uses system browser since iTerm2 browser profile not set up)
+
+**Known issues to investigate:**
+- "✓ Submitted - You can close this window" message appears on canvas submit
+- User reported this is wrong for live canvas mode
+- Need to verify if this was existing behavior or regression
+
+## What's Left
+
+### 1. Test Panel Feature
+```bash
+# Test the panel command
+./exe/streamweaver panel test-session
+
+# Should:
+# - Split iTerm2 vertically
+# - Create canvas session
+# - Open browser (external or in iTerm2 if browser profile exists)
+
+# Push content
+./exe/streamweaver canvas-push test-session <<'RUBY'
+header1 "Test"
+button "Click me"
+RUBY
+
+# Clean up
+./exe/streamweaver canvas-close test-session
+```
+
+### 2. Investigate Submit Message
+- Check if "close this window" message on submit was existing behavior
+- Canvas/live mode may need different submit handling than agentic mode
+- Don't change without understanding full context
+
+### 3. Gem Release Prep
+- Version bump: 0.1.0 → 0.2.0 (in `lib/stream_weaver/version.rb`)
+- Clean up old files:
+  - `IMPLEMENTATION_SUMMARY_v0.1.0.md` - move to docs/archive?
+  - `blog_post_streamweaver_vs_react.md` - remove from gem?
+- Build and test gem locally: `gem build stream_weaver.gemspec`
+- Push to RubyGems: `gem push stream_weaver-0.2.0.gem`
+
+### 4. iTerm2 Browser Profile (Optional Enhancement)
+For true embedded browser in iTerm2 split pane:
+1. User needs to set up browser profile in iTerm2 Preferences
+2. Could add `streamweaver setup-iterm` command to guide this
+3. See: https://iterm2.com/documentation-web.html
+
+## Key Files
+
+```
+lib/stream_weaver/
+├── iterm.rb              # iTerm2 AppleScript (NEW)
+├── cli.rb                # panel, install-skill commands
+├── canvas/
+│   └── bridge_server.rb  # Enhanced waiting screen
+└── version.rb            # Bump to 0.2.0
+
+docs/
+├── canvas-roadmap.md     # Canvas documentation
+├── templates.md          # Templates documentation
+└── SERVICE_MODE.md       # Service mode docs
+```
+
+## Commands Reference
+
+```bash
+# Panel workflow
+streamweaver panel [name]           # Split iTerm2, open canvas
+streamweaver canvas-push <name>     # Push DSL content
+streamweaver canvas-wait <name>     # Wait for user interaction
+streamweaver canvas-close <name>    # Close session
+
+# Skill installation
+streamweaver install-skill          # Project scope (.claude/skills/)
+streamweaver install-skill --global # Global scope (~/.claude/skills/)
+
+# Gem build
+gem build stream_weaver.gemspec
+gem push stream_weaver-0.2.0.gem
+```
+
+## Resume Prompt
+
+To continue this work, use this prompt:
+
+---
+
+Continue StreamWeaver gem release preparation.
+
+Current state:
+- README and CHANGELOG updated and committed
+- Panel feature implemented but needs testing
+- Need to: test panel, investigate submit message behavior, bump version, release gem
+
+Read the plan at `docs/plans/2026-01-26-gem-release-and-panel.md` for full context.
+
+Start by testing the panel command to verify the iTerm2 split works correctly.
+
+---