stream_weaver 0.3.0

data/examples/claude_code/tutorial/README.md

@@ -0,0 +1,102 @@
+# StreamWeaver Canvas Tutorial
+
+A conversational, freeform tutorial for learning StreamWeaver through Claude Code.
+
+## What This Is
+
+Unlike the standalone `tutorial.rb` (which teaches StreamWeaver components in a fixed order), this is a **conversational** tutorial where:
+
+- You ask questions naturally in the terminal
+- Claude explains briefly and renders examples to the canvas
+- You iterate: "make it blue", "add more fields", "try something else"
+- No fixed order—explore what interests you
+
+## Usage
+
+```bash
+cd examples/claude_code/tutorial
+claude
+# /learn
+```
+
+## How It Works
+
+1. **Welcome** - Canvas shows topics you can explore
+2. **You ask** - Type questions/requests in terminal
+3. **Claude renders** - Canvas shows both DSL code AND rendered output
+4. **You iterate** - Modify, explore more, or finish
+
+## Example Questions
+
+- "Show me how text_field works"
+- "What chart options are there?"
+- "Make a dashboard with 3 stats"
+- "Show me a login form"
+- "Add validation styling to that"
+- "Now try it with a dark theme"
+
+## Canvas Layout
+
+Each response shows:
+
+```
+┌─────────────────────────────┐
+│ Component: text_field       │
+├─────────────────────────────┤
+│ DSL Code                    │
+│ ```ruby                     │
+│ text_field :email, ...      │
+│ ```                         │
+├─────────────────────────────┤
+│ Rendered Output             │
+│ ┌─────────────────────────┐ │
+│ │ Email: [____________]   │ │
+│ └─────────────────────────┘ │
+├─────────────────────────────┤
+│ Ask follow-up or try next   │
+└─────────────────────────────┘
+```
+
+## Comparison with tutorial.rb
+
+| Feature | tutorial.rb | /learn |
+|---------|-------------|--------|
+| Mode | Standalone app | Claude Code canvas |
+| Flow | Fixed sections | Freeform conversation |
+| Learning | Self-guided | Claude-guided |
+| Generation | Pre-built | Dynamic per question |
+| Iteration | Playgrounds | "Make it X" requests |
+
+Both are useful—`tutorial.rb` for comprehensive self-study, `/learn` for quick exploration with Claude.
+
+`tutorial.rb` isn't just components anymore: it also has lessons on the four
+run modes (standalone/agentic/service/canvas-panel), `navbar`/state routing,
+the `resource` CRUD DSL, the `endpoint` HTTP escape hatch, and service-mode
+slug URLs. If a `/learn` question strays into "how do I run this thing", point
+there first.
+
+## Topics Covered
+
+**Components:**
+- Forms: text_field, radio_group, checkbox, select, button
+- Data: table, bar_chart, pie_chart, stat_display
+- Status: status_dot, progress_bar, spinner, badge, alert
+- Layout: card, hstack, vstack, columns, collapsible
+
+**Patterns:**
+- Login/signup forms
+- Dashboards with stats
+- Status pages
+- Multi-step progress
+- Data tables with charts
+
+## Files
+
+```
+tutorial/
+├── .claude/
+│   ├── commands/
+│   │   └── learn.md           # Slash command instructions
+│   └── settings.local.json    # Pre-allowed permissions
+└── README.md                  # This file
+```

data/examples/claude_code/verification_flow/.claude/commands/verify.md

@@ -0,0 +1,171 @@
+# Account Verification Flow
+
+This slash command demonstrates a realistic multi-step workflow with forms, status pages, toasts, and page transitions.
+
+## Instructions
+
+Execute the following phases in order. Use session name `verify` throughout. Each phase waits for user interaction before proceeding.
+
+### Phase 1: Initialize
+
+Open the panel with a fresh session. The panel command will output a URL - **show this URL to the user** in case the browser doesn't open automatically:
+
+```bash
+streamweaver panel verify --fresh
+```
+
+If the browser doesn't open, tell the user: "If the panel didn't open, paste this URL in your browser: [URL from output]"
+
+### Phase 2: Sign-Up Form
+
+Push the sign-up form:
+
+```bash
+streamweaver canvas-push verify <<'RUBY'
+card do
+  header1 "Create Account"
+  md "Enter your details to get started."
+  text_field :email, placeholder: "your@email.com", label: "Email"
+  text_field :name, placeholder: "Your Name", label: "Name"
+  button "Sign Up", id: "btn_signup", style: :primary
+end
+canvas_continue message: "Creating account..."
+RUBY
+```
+
+Wait for the user to submit:
+
+```bash
+streamweaver canvas-wait verify
+```
+
+The response will be JSON with `email` and `name` values. Store these for use in subsequent pages.
+
+### Phase 3: Provisioning Status Page with Toast
+
+This phase demonstrates proper toast usage: the canvas shows a **status page** (not a form) while terminal work happens. The toast alerts the user to check the terminal for permission prompts.
+
+Push the provisioning status page (no form, no wait - just status display):
+
+```bash
+streamweaver canvas-push verify <<'RUBY'
+card do
+  header1 "Provisioning Account"
+  status_dot status: :yellow, pulse: true, label: "SETTING UP"
+  md "Creating your account infrastructure..."
+  md "**Step 1 of 3**: Initializing database"
+end
+RUBY
+```
+
+Send a toast to alert the user to check the terminal:
+
+```bash
+streamweaver canvas-toast verify "⚠️ Grant permission in terminal to continue"
+```
+
+Now run terminal commands (which may require permission). Update the status page as work progresses:
+
+```bash
+echo "Initializing database for NAME_VALUE..."
+```
+
+Update to step 2:
+
+```bash
+streamweaver canvas-push verify <<'RUBY'
+card do
+  header1 "Provisioning Account"
+  status_dot status: :yellow, pulse: true, label: "SETTING UP"
+  md "Creating your account infrastructure..."
+  md "**Step 2 of 3**: Configuring permissions"
+end
+RUBY
+```
+
+```bash
+echo "Setting up permissions..."
+```
+
+Update to step 3 complete:
+
+```bash
+streamweaver canvas-push verify <<'RUBY'
+card do
+  header1 "Provisioning Account"
+  status_dot status: :green, pulse: false, label: "COMPLETE"
+  md "Creating your account infrastructure..."
+  md "**Step 3 of 3**: Sending verification email ✓"
+end
+RUBY
+```
+
+(Replace NAME_VALUE with the actual name from Phase 2)
+
+### Phase 4: Verification Code Page
+
+Push the verification code page, substituting the user's email into the message:
+
+```bash
+streamweaver canvas-push verify <<'RUBY'
+card do
+  header1 "Verify Your Email"
+  status_dot status: :yellow, pulse: true, label: "AWAITING CODE"
+  md "We sent a 6-digit code to **EMAIL_VALUE**"
+  text_field :code, placeholder: "Enter 6-digit code", label: "Verification Code"
+  button "Verify", id: "btn_verify", style: :primary
+end
+canvas_continue message: "Verifying code..."
+RUBY
+```
+
+(Replace EMAIL_VALUE with the actual email from Phase 2)
+
+Wait for the verification:
+
+```bash
+streamweaver canvas-wait verify
+```
+
+The response will be JSON with the `code` value. After canvas-wait returns, the user sees the "Verifying code..." spinner. **Immediately push the next page** - do NOT wait again.
+
+### Phase 5: Welcome Page
+
+Push the welcome/success page immediately (this replaces the spinner). Substitute the user's name:
+
+```bash
+streamweaver canvas-push verify <<'RUBY'
+card do
+  header1 "Welcome, NAME_VALUE!"
+  badge "VERIFIED", variant: :success
+  md "Your account has been created and verified successfully."
+  md "You can now access all features."
+end
+RUBY
+```
+
+(Replace NAME_VALUE with the actual name from Phase 2)
+
+**Do NOT wait here** - this is an informational page with no form. Pause briefly to let the user see the success message, then close:
+
+```bash
+sleep 2
+```
+
+### Phase 6: Cleanup
+
+Close the panel:
+
+```bash
+streamweaver canvas-close verify
+```
+
+## Notes
+
+- All commands use the session name `verify`
+- The `--fresh` flag on panel closes any existing session first
+- If the browser doesn't auto-open, share the URL from the panel command output with the user
+- **Toast usage**: Toasts are for alerting users to check the terminal when their attention is on a status page. Don't use toasts on form pages where the user is already expected to interact with the canvas.
+- `canvas-wait` returns JSON with all form field values
+- **canvas_continue flow**: When a form uses `canvas_continue`, after `canvas-wait` returns, the user sees the spinner. You must **immediately push the next page** to replace the spinner - do NOT call `canvas-wait` again (there's nothing to wait for).
+- **Final pages**: Informational success pages (no form) should NOT use `canvas-wait`. Just display the content briefly with `sleep`, then close.

data/examples/claude_code/verification_flow/README.md

@@ -0,0 +1,126 @@
+# Account Verification Flow Example
+
+A realistic multi-step workflow demonstrating StreamWeaver's canvas capabilities: forms, status pages, toasts, and page transitions.
+
+## The Flow
+
+1. **Sign-Up Form** → User enters email and name
+2. **Provisioning Status** → Canvas shows progress while terminal work runs (toast alerts user to check terminal)
+3. **Verification Code** → User enters verification code from email
+4. **Welcome Page** → Confirms verification, displays personalized greeting
+
+## Key Concepts Demonstrated
+
+### Canvas + Terminal Interplay
+Phase 2 shows how to use canvas as a status display while Claude runs terminal commands. The toast alerts the user to check the terminal for permission prompts.
+
+### Proper Toast Usage
+Toasts are for alerting users to check the terminal when their attention is on a **status page**. Don't use toasts on form pages where the user is already interacting with the canvas.
+
+### canvas_continue
+Use `canvas_continue message: "..."` on form pages to show a spinner after submit (instead of "You can close this window").
+
+## Usage
+
+```bash
+cd examples/claude_code/verification_flow
+# In Claude Code, run:
+/verify
+```
+
+## Core Patterns
+
+### Session Naming
+
+All commands use the same session name to route to the same canvas instance:
+
+```bash
+streamweaver panel verify --fresh      # Opens canvas for session "verify"
+streamweaver canvas-push verify <<...  # Pushes content to "verify"
+streamweaver canvas-toast verify "..." # Shows toast on "verify"
+streamweaver canvas-wait verify        # Waits for input on "verify"
+streamweaver canvas-close verify       # Closes "verify"
+```
+
+### Heredoc Syntax for DSL
+
+Pass Ruby DSL to canvas-push using heredocs:
+
+```bash
+streamweaver canvas-push SESSION_NAME <<'RUBY'
+card do
+  header1 "Title"
+  text_field :email, label: "Email"
+  button "Submit", id: "btn_submit", style: :primary
+end
+RUBY
+```
+
+Use `<<'RUBY'` (quoted) to prevent shell variable expansion, or `<<RUBY` (unquoted) if you need shell substitution.
+
+### Capturing Form Values
+
+`canvas-wait` blocks until a button is clicked, then returns JSON with all field values:
+
+```bash
+$ streamweaver canvas-wait verify
+{"type":"action","button":"btn_sign_up_1","state":{"email":"user@example.com","name":"Jane Doe"}}
+```
+
+The `state` object contains all text field values keyed by their symbol names (`:email` → `"email"`).
+
+### Variable Substitution Between Pages
+
+Capture values from one page and substitute into the next:
+
+```bash
+# Page 1: Capture user input
+RESULT=$(streamweaver canvas-wait verify)
+EMAIL=$(echo $RESULT | jq -r '.state.email')
+NAME=$(echo $RESULT | jq -r '.state.name')
+
+# Page 2: Use captured values
+streamweaver canvas-push verify <<RUBY
+card do
+  header1 "Welcome, $NAME!"
+  md "We sent a code to **$EMAIL**"
+end
+RUBY
+```
+
+### URL Fallback
+
+The panel command outputs a URL in case the browser doesn't auto-open:
+
+```bash
+$ streamweaver panel verify --fresh
+Canvas 'verify' ready
+Browser opened in split pane
+
+URL (if browser didn't open): http://localhost:4570/canvas/verify
+```
+
+Share this URL with users if the browser pane doesn't appear.
+
+## Features Demonstrated
+
+| Feature | Command | Purpose |
+|---------|---------|---------|
+| Fresh start | `panel --fresh` | Open panel, close existing session first |
+| Form pages | `canvas-push` | Display forms with text fields and buttons |
+| Status pages | `canvas-push` | Display progress while work happens |
+| Notifications | `canvas-toast` | Alert user to check terminal |
+| User input | `canvas-wait` | Block until button click, capture field values |
+| Spinner feedback | `canvas_continue` | Show spinner after form submit |
+| Cleanup | `canvas-close` | Close panel and browser pane |
+
+## DSL Components Used
+
+- `card` - Container for content
+- `header1` - Page titles
+- `md` - Markdown text with dynamic substitution
+- `text_field` - Form inputs with labels and placeholders
+- `button` - Actions with primary styling
+- `status_dot` - Visual status indicator (yellow pulsing, green complete)
+- `badge` - Success/status badges
+- `canvas_continue` - Spinner feedback for multi-step flows

data/examples/components/annotated_code_demo.rb

@@ -0,0 +1,54 @@
+# Usage: streamweaver canvas-push <session> < examples/components/annotated_code_demo.rb
+# Or:    streamweaver panel annotated-code-demo && streamweaver canvas-push annotated-code-demo < examples/components/annotated_code_demo.rb
+
+header2 "AnnotatedCode — Line-Pinned Annotations"
+md "Code block with a side panel of annotation bubbles aligned to specific lines. Annotated lines get a left-border highlight."
+
+annotated_code(language: "ruby", annotations: [
+  { line: 2, note: "keyword_init: true means Annotation.new(line:, note:) works" },
+  { line: 5, note: "Memoized — built once on first access, reused on every render call" },
+  { line: 6, note: "Set membership test is O(1); Array#include? would be O(n) per line" }
+]) do
+  <<~'RUBY'
+    class AnnotatedCode < Base
+      Annotation = Struct.new(:line, :note, keyword_init: true)
+
+      def annotated_lines
+        @annotated_lines ||= Set.new(annotations.map(&:line))
+      end
+    end
+  RUBY
+end
+
+header3 "Multiple annotations close together"
+md "Annotations at adjacent lines stack without overlap — each gets its own `min-height` slot."
+
+annotated_code(language: "javascript", annotations: [
+  { line: 1, note: "Arrow function — implicit return when body is an expression" },
+  { line: 2, note: "Destructuring with default: name falls back to 'World'" },
+  { line: 3, note: "Template literal — backtick syntax, \#{} interpolation" }
+]) do
+  <<~'JS'
+    const greet = (opts) => {
+      const { name = 'World' } = opts;
+      return `Hello, ${name}!`;
+    };
+  JS
+end
+
+header3 "No language specified"
+md "Falls back to `language-none` (no Prism highlighting) — useful for plain text or pseudocode."
+
+annotated_code(annotations: [
+  { line: 1, note: "Start: O(1) stack push" },
+  { line: 3, note: "Each node visited once — O(n) total" },
+  { line: 5, note: "Stack empty → all reachable nodes visited" }
+]) do
+  <<~'TEXT'
+    push start node onto stack
+    while stack is not empty:
+      node = stack.pop
+      for each unvisited neighbor:
+        push neighbor
+  TEXT
+end

data/examples/components/callout_demo.rb

@@ -0,0 +1,33 @@
+# Usage: streamweaver canvas-push <session> < examples/components/callout_demo.rb
+# Or:    streamweaver panel callout-demo && streamweaver canvas-push callout-demo < examples/components/callout_demo.rb
+
+header2 "Callout Variants"
+md "All seven tone variants — the last two (`:decision` and `:risk`) are new."
+
+callout(variant: :info, title: "Info") do
+  text "General information. Use for context or background knowledge."
+end
+
+callout(variant: :warning, title: "Warning") do
+  text "Something needs attention but is not a blocker."
+end
+
+callout(variant: :success, title: "Success") do
+  text "An operation completed successfully."
+end
+
+callout(variant: :error, title: "Error") do
+  text "Something went wrong. Action required."
+end
+
+callout(variant: :tip, title: "Tip") do
+  text "A helpful hint or shortcut worth knowing."
+end
+
+callout(variant: :decision, title: "Decision — Guest session storage") do
+  text "Chosen approach: opaque token stored in DB. Stateless JWT was rejected because we need revocability for account merges. Hard to reverse — commit before implementing."
+end
+
+callout(variant: :risk, title: "Risk — Session expiry") do
+  text "Guest sessions must expire. Proposed TTL: 24h. Missing this causes unbounded DB growth. Verify the cleanup job runs before shipping."
+end

data/examples/components/checkbox_group_demo.rb

@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../../lib/stream_weaver'
+
+# Sample email data
+EMAILS = [
+  { id: "email_1", from: "newsletter@techcrunch.com", subject: "Your Daily Tech Digest - AI News", date: "Jan 25, 10:32am" },
+  { id: "email_2", from: "deals@retailer.com", subject: "Flash Sale: 50% Off Everything!", date: "Jan 25, 9:15am" },
+  { id: "email_3", from: "no-reply@service.com", subject: "Your monthly statement is ready", date: "Jan 25, 8:45am" },
+  { id: "email_4", from: "updates@social.com", subject: "You have 5 new notifications", date: "Jan 24, 4:30pm" },
+  { id: "email_5", from: "support@vendor.com", subject: "Your ticket has been resolved", date: "Jan 24, 2:15pm" }
+]
+
+App = app "Spam Triage" do
+  header "Spam Triage - #{EMAILS.length} emails to review"
+
+  checkbox_group :selected_emails, select_all: "Select All", select_none: "Clear Selection" do
+    EMAILS.each do |email|
+      item email[:id] do
+        div class: "email-row" do
+          text "#{email[:from]}  #{email[:date]}"
+          text email[:subject]
+        end
+      end
+    end
+  end
+
+  # Show selected count
+  selected = state[:selected_emails] || []
+  if selected.any?
+    text "#{selected.length} email(s) selected"
+
+    button "Delete Selected", style: :secondary do |s|
+      # In a real app, you'd delete the emails here
+      s[:deleted] = s[:selected_emails].dup
+      s[:selected_emails] = []
+    end
+  end
+
+  if state[:deleted]&.any?
+    text "Deleted #{state[:deleted].length} email(s): #{state[:deleted].join(', ')}"
+  end
+end
+
+App.run! if __FILE__ == $0