stream_weaver 0.3.0

data/docs/streamweaver-for-ai-agents.md

@@ -0,0 +1,401 @@
+# StreamWeaver for AI Agents
+
+A guide to building visual UI for AI agent workflows with minimal token overhead.
+
+## The Problem
+
+AI agents need visual UI, but the options are frustrating:
+
+**Terminal output** is hard to parse. Complex choices become walls of text. Multi-step workflows turn into scrolling nightmares. Users lose context.
+
+**HTML/React** is verbose. A simple form is 50+ lines. AI generation is slow and expensive. Token costs matter—slower, more expensive, less context available for the actual problem.
+
+**What agents actually need:**
+- Quick visual feedback for complex choices
+- Forms that don't require parsing natural language
+- Progress indicators and status displays
+- Charts and data visualization
+- All without burning context on boilerplate
+
+## The Solution: Concise DSL
+
+StreamWeaver is a Ruby DSL that renders to HTML. Many components, clear syntax, fast to build real apps.
+
+### Token Comparison
+
+A form with 3 fields and a button:
+
+**StreamWeaver DSL** (~45 tokens):
+```ruby
+card do
+  header1 "Sign Up"
+  text_field :email, placeholder: "you@example.com", label: "Email"
+  text_field :name, placeholder: "Your Name", label: "Name"
+  text_field :company, label: "Company"
+  button "Submit", id: "btn_submit", style: :primary
+end
+```
+
+**HTML** (~200+ tokens):
+```html
+<div class="card">
+  <h1>Sign Up</h1>
+  <div class="form-group">
+    <label for="email">Email</label>
+    <input type="text" id="email" name="email" placeholder="you@example.com" class="form-control">
+  </div>
+  <div class="form-group">
+    <label for="name">Name</label>
+    <input type="text" id="name" name="name" placeholder="Your Name" class="form-control">
+  </div>
+  <div class="form-group">
+    <label for="company">Company</label>
+    <input type="text" id="company" name="company" class="form-control">
+  </div>
+  <button type="submit" class="btn btn-primary">Submit</button>
+</div>
+```
+
+**React** (~300+ tokens):
+```jsx
+function SignUpForm() {
+  const [email, setEmail] = useState('');
+  const [name, setName] = useState('');
+  const [company, setCompany] = useState('');
+
+  return (
+    <div className="card">
+      <h1>Sign Up</h1>
+      <div className="form-group">
+        <label htmlFor="email">Email</label>
+        <input
+          type="text"
+          id="email"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          placeholder="you@example.com"
+        />
+      </div>
+      {/* ... more fields ... */}
+      <button type="submit" className="btn btn-primary">Submit</button>
+    </div>
+  );
+}
+```
+
+That's **5-7x fewer tokens** for the same UI. For AI generation, this means:
+- Faster responses
+- Lower cost
+- More context available for actual work
+
+### Component Variety
+
+StreamWeaver includes components for common agent needs:
+
+| Category | Components |
+|----------|------------|
+| Layout | `card`, `columns`, `hstack`, `vstack`, `collapsible` |
+| Text | `header1`-`header4`, `text`, `md` (markdown) |
+| Forms | `text_field`, `radio_group`, `checkbox`, `select`, `button` |
+| Data | `table`, `bar_chart`, `pie_chart`, `stat_display` |
+| Status | `status_dot`, `progress_bar`, `spinner`, `badge`, `alert` |
+| Media | `image`, `video`, `audio` |
+
+### CRITICAL: Never Put Markdown Inside `text`
+
+`text` is a literal renderer — markdown syntax appears as raw characters on screen.
+
+```ruby
+# WRONG — renders as: **Select the article PDF:**  (asterisks visible to user)
+text "**Select the article PDF:**"
+
+# CORRECT — use md for markdown formatting
+md "**Select the article PDF:**"
+
+# BETTER — use semantic headers for labels and section titles
+header3 "Select the article PDF:"
+header4 "What do you want to know?"
+```
+
+Use `text` only for plain prose. Use `md` when you need inline markdown (bold, italic, links, code). Use `header1`–`header6` for structural headings and form-section labels.
+
+## The Modes Gamut
+
+StreamWeaver supports multiple modes, from full standalone apps to persistent canvas sessions with Claude Code.
+
+| Mode | Use Case | Process Model | Example |
+|------|----------|---------------|---------|
+| **Standalone** | Full applications | `streamweaver app.rb` | Rivet, tutorial.rb, theme_tweaker |
+| **Agentic** (`run_once!`) | Mid-task UI from scripts | Generate → wait → parse JSON | Quick prompts, confirmations |
+| **Service** | Multi-app hosting | Long-running server, reuse apps | Dashboard with multiple widgets |
+| **Canvas/Panel** | Claude Code companion | Persistent session, push/wait | codebreaker, verification_flow |
+
+### Standalone Mode
+
+Full applications that run independently.
+
+```bash
+streamweaver my_app.rb
+```
+
+Good for:
+- Reusable tools and utilities
+- Self-documenting tutorials
+- Applications that run outside agent workflows
+
+Example: `examples/advanced/tutorial.rb` teaches StreamWeaver using StreamWeaver itself.
+
+### Agentic Mode (`run_once!`)
+
+Quick UI mid-script. Generate DSL, render, wait for input, parse JSON response.
+
+```ruby
+require 'stream_weaver'
+
+result = StreamWeaver.run_once! do
+  card do
+    header1 "Quick Question"
+    radio_group :choice, ["Option A", "Option B", "Option C"]
+    button "Continue", id: "btn_continue", style: :primary
+  end
+end
+
+puts "User chose: #{result['choice']}"
+```
+
+Good for:
+- Confirmation dialogs
+- Quick selections
+- Mid-workflow decisions
+
+### Service Mode
+
+Long-running server that hosts multiple apps. Avoids startup overhead when switching between apps.
+
+```bash
+streamweaver service start
+streamweaver service add my_app.rb
+streamweaver service status
+```
+
+Good for:
+- Dashboard with multiple widgets
+- Frequently-used utilities
+- Development workflows
+
+### Canvas/Panel Mode
+
+Persistent session with Claude Code. The agent opens a panel, pushes updates, waits for input, and continues the conversation.
+
+```bash
+# Open a panel (browser in iTerm split pane)
+streamweaver panel my_session
+
+# Push DSL content (via stdin)
+streamweaver canvas-push my_session <<'DSL'
+card do
+  header1 "Working..."
+  spinner label: "Processing files..."
+end
+DSL
+
+# Wait for user interaction (returns JSON)
+streamweaver canvas-wait my_session
+
+# Show toast notification
+streamweaver canvas-toast my_session "Check terminal for input"
+
+# Close when done
+streamweaver canvas-close my_session
+```
+
+Good for:
+- Multi-phase Claude Code workflows
+- Real-time status updates
+- Interactive analysis tools
+
+## Remote & Mobile Access
+
+StreamWeaver apps aren't limited to localhost. With Tailscale or LAN access, the same app you build for local use becomes a mobile dashboard:
+
+```bash
+# Access from your phone via Tailscale
+STREAMWEAVER_HOST=0.0.0.0 STREAMWEAVER_PORT=4580 ruby dashboard.rb
+# → http://your-machine:4580 from any Tailscale device
+```
+
+Or in code:
+```ruby
+app "Ops Dashboard", theme: :dark do
+  # ... status displays, charts, priority items
+end.run!(host: '0.0.0.0', port: 4580)
+```
+
+This opens up use cases like:
+- **Mobile monitoring** — check build status, deployment health from your phone
+- **Team dashboards** — share a StreamWeaver app across Tailscale for team visibility
+- **Remote agentic UI** — trigger agent workflows from a tablet while away from your desk
+
+The fixed port ensures bookmarks and home screen shortcuts stay stable across restarts.
+
+## When to Use What
+
+```
+                                    ┌─────────────────────┐
+                                    │  What are you       │
+                                    │  building?          │
+                                    └──────────┬──────────┘
+                                               │
+                    ┌──────────────────────────┼──────────────────────────┐
+                    │                          │                          │
+                    ▼                          ▼                          ▼
+           ┌────────────────┐        ┌────────────────┐        ┌────────────────┐
+           │  Reusable app  │        │  Quick UI in   │        │  Claude Code   │
+           │  or tool?      │        │  a script?     │        │  integration?  │
+           └───────┬────────┘        └───────┬────────┘        └───────┬────────┘
+                   │                         │                         │
+                   ▼                         ▼                         │
+           ┌────────────────┐        ┌────────────────┐                │
+           │  STANDALONE    │        │  AGENTIC       │                │
+           │  streamweaver  │        │  run_once!     │                │
+           │  app.rb        │        │                │                │
+           └────────────────┘        └────────────────┘                │
+                                                                       │
+                                               ┌───────────────────────┴───────────────────────┐
+                                               │                                               │
+                                               ▼                                               ▼
+                                      ┌────────────────┐                              ┌────────────────┐
+                                      │  Single        │                              │  Multi-app     │
+                                      │  workflow?     │                              │  dashboard?    │
+                                      └───────┬────────┘                              └───────┬────────┘
+                                              │                                               │
+                                              ▼                                               ▼
+                                      ┌────────────────┐                              ┌────────────────┐
+                                      │  CANVAS/PANEL  │                              │  SERVICE       │
+                                      │  slash command │                              │  multi-app     │
+                                      │  + heredocs    │                              │  hosting       │
+                                      └────────────────┘                              └────────────────┘
+```
+
+## Canvas/Panel Patterns
+
+The canvas/panel mode is the most common for Claude Code integration. Key patterns:
+
+### Pattern A: Progress While Working
+
+Show a spinner while Claude does actual work:
+
+```bash
+# Push spinner (with canvas_continue)
+streamweaver canvas-push session <<'DSL'
+canvas_continue message: "Analyzing..."
+card do
+  header1 "Working"
+  spinner label: "Processing files..."
+end
+DSL
+
+# DO THE ACTUAL WORK (Glob, Grep, Read, etc.)
+# ...
+
+# Push results (NO canvas_continue)
+streamweaver canvas-push session <<'DSL'
+card do
+  header1 "Results"
+  table headers: ["File", "Lines"], rows: [["main.rb", "150"]]
+  button "Continue", id: "btn_continue", style: :primary
+end
+DSL
+
+# Wait for user
+streamweaver canvas-wait session
+```
+
+### Pattern B: Form Interaction
+
+Show a form and wait for user input:
+
+```bash
+# Push form (NO canvas_continue)
+streamweaver canvas-push session <<'DSL'
+card do
+  header1 "Choose Options"
+  radio_group :choice, ["Option A", "Option B"]
+  button "Submit", id: "btn_submit", style: :primary
+end
+DSL
+
+# Wait for user
+streamweaver canvas-wait session
+```
+
+**Critical:** Never combine `canvas_continue` with `canvas-wait`. That's contradictory:
+- `canvas_continue` says "I'm working, here's a spinner"
+- `canvas-wait` says "I'm done, waiting for you"
+
+### Toast for Terminal Prompts
+
+When Claude needs permission for tools, toast alerts the user:
+
+```bash
+streamweaver canvas-toast session "Check terminal for authorization" --variant warning
+```
+
+## Real Examples
+
+### codebreaker
+
+Spy-themed code analysis tool. Demonstrates:
+- Multi-phase workflow (briefing → reconnaissance → report → deep analysis)
+- Component variety (charts, tables, status dots, progress bars)
+- Dynamic DSL generation based on analysis results
+- `canvas_continue` for progress, `canvas-wait` for interaction
+
+### verification_flow
+
+Realistic 2FA-style account verification. Demonstrates:
+- Form collection across multiple steps
+- Status page updates during provisioning
+- Toast usage for terminal prompts
+- Clean phase transitions
+
+### tutorial (Claude Code)
+
+Conversational canvas tutorial. Demonstrates:
+- Freeform exploration (no fixed order)
+- Dynamic DSL generation based on questions
+- Code + rendered output in same view
+- Iterative refinement ("make it blue")
+
+## Creating Your Own
+
+1. Create directory with `.claude/commands/yourcommand.md`
+2. Write instructions with canvas-push heredocs and canvas-wait
+3. Add `.claude/settings.local.json` for permissions:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(streamweaver panel:*)",
+      "Bash(streamweaver canvas-push:*)",
+      "Bash(streamweaver canvas-wait:*)",
+      "Bash(streamweaver canvas-toast:*)",
+      "Bash(streamweaver canvas-close:*)"
+    ]
+  }
+}
+```
+
+4. Run with `/yourcommand` in Claude Code
+
+## Summary
+
+StreamWeaver makes AI agent UI practical:
+
+- **Concise DSL**: 5-7x fewer tokens than HTML/React
+- **Rich components**: Forms, charts, tables, status indicators
+- **Multiple modes**: Standalone apps to Claude Code canvases
+- **Simple patterns**: Push DSL, wait for JSON, repeat
+
+Build what you need to show, not the infrastructure to show it.

data/docs/streamweaver-frontend-vision.md

@@ -0,0 +1,123 @@
+# StreamWeaver Frontend Vision
+
+## The Thesis
+
+A **Hotwire-equivalent frontend stack for Ruby/Rails developers**, built on lighter infrastructure than Hotwire and with no build step:
+
+```
+Ruby DSL  +  htmx  +  Alpine.js  +  Idiomorph
+```
+
+Same capabilities as Turbo + Stimulus, but cheaper to load, easier to read for Rails developers, and aligned with the way StreamWeaver already ships UI: a Ruby DSL renders complete server-side pages, the browser swaps regions intelligently, and nobody runs `npm install`.
+
+The goal is to make StreamWeaver the obvious choice when a Ruby developer wants to build a browser UI without leaving Ruby — and to make those apps **look and feel like well-built Rails apps** so anyone with Rails muscle memory can read them.
+
+## Why Not Hotwire Directly
+
+Hotwire is excellent. The reasons we're not adopting it wholesale:
+
+- **Asset pipeline assumptions.** Turbo and Stimulus expect a Rails-flavored build pipeline (importmaps, esbuild, propshaft). StreamWeaver apps are a single Ruby file plus a CDN script tag — bringing in Hotwire's tooling violates that promise.
+- **Bundle size.** Turbo (~30kb) + Stimulus (~10kb) is fine in absolute terms but heavier than htmx (~10kb) + Alpine (~15kb) + Idiomorph (~5kb).
+- **Tied to a worldview.** Stimulus controllers are JavaScript classes registered to DOM elements. Alpine declarations live inline in the markup, closer to the data they affect. For Ruby developers used to ERB partials with embedded behavior, Alpine is a smaller mental jump.
+- **Token efficiency.** Alpine inline declarations and htmx attributes are token-cheap when an LLM is generating views — relevant given how much of StreamWeaver gets written by Claude.
+
+We are not anti-Hotwire. We are choosing the same shape with lighter materials.
+
+## What We Keep From Hotwire
+
+- **Server renders complete pages.** No virtual DOM in the browser, no client-side router, no JSON-and-render-on-client pattern. The server is the source of truth for what the page looks like.
+- **Diff-based morph for navigation.** Idiomorph is literally the same algorithm Turbo 8 uses; we adopt it directly. State preservation across navigation comes from the morph algorithm, not from explicit per-region swap configuration.
+- **Bookmarkable resource URLs.** Every meaningful view has its own URL. Users can share links, back-button works, refresh works.
+- **Forms POST to controllers, return updated views.** No client-side form state machines. The server says what the page should look like after a submission.
+
+## What We Use Instead
+
+| Hotwire | StreamWeaver convention | Why |
+|---|---|---|
+| Turbo Drive | htmx `hx-boost` | Lighter, no build step, same UX |
+| Turbo Frames | htmx `hx-target`/`hx-swap` | More explicit, less opinionated, fits htmx idioms |
+| Turbo Streams | htmx out-of-band swaps + Alpine | OOB covers the partial-update case; Alpine covers the live-update case |
+| Stimulus controllers | Alpine `x-data` declarations | Closer to the markup, no separate JS file per component |
+| Idiomorph (extracted from Turbo) | Idiomorph (used directly) | Same library |
+
+## Rails-isms We Are Adopting
+
+This is the part of the vision still being filled in. Confirmed directions:
+
+### Resource URLs
+Every meaningful view gets a Rails-style resource URL. No positional indexes that depend on local server state.
+
+```
+/docs/:name                        # show
+/docs                              # index
+/history/:session                  # session's history
+/history/:session/:timestamp       # specific snapshot
+```
+
+Filed as bd `stream_weaver-9ei`.
+
+### Routes-as-conventions
+Sidebar navigation, Prev/Next links, all link emission produces these resource URLs. No hand-rolled query-string indexes.
+
+### Layouts and Partials (in progress)
+Templates compose from a layout + content + nav region structure. Partials would be a future addition once the layout convention stabilizes.
+
+### Forms (open question)
+Rails form helpers (`form_with`, `form_for`, `f.text_field`) translate naturally to a StreamWeaver DSL. The user has signaled interest in stealing the patterns:
+
+```ruby
+form_with(url: "/docs", method: :post) do |f|
+  f.text_field :name
+  f.submit "Save"
+end
+```
+
+This is **not yet implemented**. It is on the roadmap. The current DSL has `text_field :name, placeholder: "..."` which is closer to Rails' `text_field_tag`. Migrating to a `form_with`-style block is plausible.
+
+### Scaffolding (long-term)
+A `streamweaver new <name>` generator that scaffolds a resource (model + canvas templates + URLs) following these conventions. This is well downstream — the conventions need to stabilize first.
+
+## Naming
+
+The combined frontend stack ("htmx + Alpine + Idiomorph + StreamWeaver DSL with resource URL conventions") deserves a name so it can be referred to as a unit. Working title: **streamwire** (StreamWeaver + Hotwire-shape). Open to alternatives. The naming matters because once a thing is named, conventions can be enforced ("this should follow streamwire patterns") instead of restated each time.
+
+## State Conventions
+
+Where each kind of state lives:
+
+| State type | Lives in | Examples |
+|---|---|---|
+| What is being viewed | URL | which doc, which session, which tab |
+| Persistent data | Server (file/DB) | saved docs, user preferences |
+| Ephemeral UI state | Client (Alpine) | dialog open/closed, dropdown expanded |
+| In-progress input | Client (Alpine) | text being typed before submit |
+| Bookmarkable filters | URL query string | search query, sort order |
+
+The principle: **state is in the URL when sharing/bookmarking the URL should restore it.** Otherwise it's client-only.
+
+## What Solves What
+
+The recurring bug pattern Forrest has hit ("my apps reload the whole page and lose state") is solved structurally by Idiomorph. Once the bridge_server and reader templates use morph as the default swap strategy, future features inherit state preservation without thinking about it. No new feature can accidentally regress to "click → full reload → lose accordion state" because that path stops existing in the layouts.
+
+## Path Forward
+
+1. **Adopt Idiomorph in StreamWeaver layouts** (bd `stream_weaver-2ds`, P2). Replaces hand-rolled OOB swaps and JS active-class fixups with one extension.
+2. **Adopt resource URLs in canvas-read** (bd `stream_weaver-9ei`, P2). Establishes the URL convention.
+3. **Document everything in `llms.txt` (linked as `docs/for_llms.md`)** so LLMs build new apps correctly without rediscovering the patterns. This is the most important deliverable — Forrest reports significant churn from unclear conventions.
+4. **Migrate existing examples** to the conventions once the patterns are documented. Existing apps under `examples/` become reference material.
+5. **(Later)** Forms — translate Rails form helpers to the DSL.
+6. **(Later)** Scaffolding generator.
+
+## Open Questions
+
+- Naming: streamwire? streamweave? something else?
+- Forms: how much Rails form helper API to mirror exactly?
+- Multi-page apps: routing conventions for apps with several resources
+- Asset handling: how a single-file Ruby app declares its own CSS/JS without a build step
+- Testing: convention for testing StreamWeaver views (currently spec-by-rendered-HTML — fine for now)
+
+These get answered as the conventions get exercised by real apps.
+
+---
+
+*This document captures the strategic direction. For the practical "how to build a StreamWeaver app correctly" guide, see `llms.txt` (linked as `docs/for_llms.md`).*

data/docs/streamweaver_canvas/glimmer_initial_final_layer.rb

@@ -0,0 +1,77 @@
+# streamweaver-doc: v1
+header1 "Glimmer: Inspired By, Not Dependent On"
+
+  div(style: "height:8px")
+
+  columns widths: ["50%", "50%"] do
+    column do
+      card do
+        header3 "Why we skip the Glimmer gem"
+        badge "Too heavy for Opal", color: :red
+        div(style: "height:8px")
+        md "Glimmer depends on **facets** — a massive Ruby utility library. Compiled to Opal, facets alone balloons the JS bundle."
+        div(style: "height:8px")
+        md "Also: the `<=>` / `<=` binding syntax is confusing — it reuses comparison operators for a completely different meaning."
+        div(style: "height:8px")
+        md "We take the **ideas**, not the code."
+      end
+    end
+    column do
+      card do
+        header3 "What we take from Glimmer"
+        badge "Conceptual only", color: :green
+        div(style: "height:8px")
+        md "**Observer pattern** — the right model for reactive state"
+        md "**Direct DOM** (no virtual DOM) — proven to be sufficient"
+        md "**Observable model enhancement** — state auto-notifies observers when keys change"
+        div(style: "height:8px")
+        md "We implement this in ~70 lines of pure Ruby/Opal. No dependencies."
+      end
+    end
+  end
+
+  div(style: "height:24px")
+  header2 "ReactiveState: ~70 Lines, Zero Deps"
+  div(style: "height:8px")
+
+  card do
+    header3 "Design"
+    columns widths: ["50%", "50%"] do
+      column do
+        md "**ReactiveState** is a Ruby hash wrapper:"
+        md "- `[]` tracks which block regions read which keys during render"
+        md "- `[]=` notifies observers when a key changes"
+        md "- Observers are DOM updater lambdas registered at render time"
+        div(style: "height:8px")
+        md "Explicit watch for edge cases:"
+        md "- `watch(:search) { |val| ... }` — readable, obvious"
+        md "- No operator overloading confusion"
+      end
+      column do
+        md "**Invisible to the user — no API change:**"
+        md "Phase 1: plain hash, whole block re-runs"
+        md "Phase 2: ReactiveState proxy, only affected DOM nodes update"
+        div(style: "height:8px")
+        md "Same DSL code works in both phases. Upgrade is internal to the adapter."
+        div(style: "height:8px")
+        badge "Zero learning curve for app authors", color: :green
+      end
+    end
+  end
+
+  div(style: "height:24px")
+  header2 "Final Layer Map"
+  div(style: "height:8px")
+
+  table(
+    headers: ["Layer", "What it is", "Phase"],
+    rows: [
+      ["User DSL", "Unchanged StreamWeaver DSL — same app/card/text_field/button", "Now"],
+      ["Adapter::Opal", "Renders DSL to HTML string, wires event listeners, holds state", "1"],
+      ["OpalBuilder", "opal-build command → dist/index.html + dist/app.js", "1"],
+      ["morphdom.js", "Client-side DOM patching after block re-execution", "1"],
+      ["ReactiveState", "~70-line Observable hash: auto-tracks reads, notifies on write", "2"],
+      ["History API wrapper", "route DSL via pushState/popstate — same calls as Sinatra routes", "2"],
+      ["Supabase client", "Thin Ruby/Opal wrapper — sync state to Supabase on demand", "3 (MMA app)"]
+    ]
+  )

data/docs/streamweaver_canvas/save_example.rb

@@ -0,0 +1,9 @@
+# streamweaver-doc: v1
+header1 "🎯 Save as doc button — fresh bridge"
+md "Hard-refresh this page (cmd-shift-R or ctrl-shift-R) — old bridge had stale code."
+md ""
+md "**Button is at the bottom-right corner.** If you don't see it:"
+md "1. Try hard-refresh"
+md "2. Check that this URL is `http://localhost:4700/canvas/canvas-arch`"
+md "3. Open dev tools (cmd-opt-I) → Console — any JS errors?"
+md "4. Inspect element on the page → look for `<button class=\"sw-save-doc-btn\">`"