stream_weaver 0.3.0

data/docs/visual-skills/lessons-learned/process.md

@@ -0,0 +1,145 @@
+# Lessons Learned — Visual Skills Development Process
+
+## Meta: This Document
+This captures the process of porting pi-design-deck and visual-explainer into
+StreamWeaver, with the goal of extracting a repeatable skill for
+"analyze N reference projects → design unified solution → implement via subagents."
+
+---
+
+## Phase 1: Setup & Analysis
+
+### Lesson 1: Clone reference repos locally
+**What:** Git clone both projects into the parent workspace so subagents can
+read all source files without web fetch rate limits or API constraints.
+**Why:** WebFetch hit 429 rate limits on the first attempt. Local files are instant
+and unlimited. Subagents need to read *every* file, not just READMEs.
+**Skill extraction:** Any "port from reference" workflow should start with local clones.
+
+### Lesson 2: Parallel deep-analysis with shared template
+**What:** Launch one subagent per reference project with identical analysis
+structure (Intent → Features → Architecture → UX → Gherkin → Token Cost).
+**Why:** Consistent output format enables mechanical overlap detection in the next
+phase. If agent A uses one taxonomy and agent B uses another, the diff is noise.
+**Skill extraction:** The analysis template IS the skill's core IP. Standardize it.
+
+### Lesson 3: Gherkin as the bridge format
+**What:** Have analysis agents write cucumber/Gherkin scenarios capturing all
+user-facing behavior.
+**Why:** Gherkin is:
+  - Precise enough for implementation
+  - Readable enough for design review
+  - Diff-friendly for overlap analysis
+  - Model-friendly (LLMs handle it well)
+  - Testable (can become actual integration tests)
+**Skill extraction:** Always produce Gherkin as intermediate artifact.
+
+### Lesson 4: Research the orchestration pattern BEFORE designing implementation
+**What:** Researched GSD's ralph-loop / subagent orchestration pattern up front.
+**Why:** The implementation approach (how to break work into subagent-sized chunks)
+constrains the design (how modular the architecture needs to be). Knowing we'll
+use context-sharded subagents means the design MUST be decomposable into
+independently-implementable units.
+**Key GSD insights:**
+  - **Context sharding**: Each task gets fresh 200k context, reads specs from files
+  - **Atomic tasks**: 2-3 tasks per plan, each fitting ~50% of context window
+  - **File-tracked state**: PLAN.md, STATE.md, REQUIREMENTS.md are the handoff
+  - **Immediate commits**: Each task commits independently → git bisect works
+  - **Orchestrator stays lean**: Main thread only tracks task completion, not implementation
+
+### Lesson 5: Track evolution, not just final state
+**What:** Maintain PROGRESS.md with running log, design evolution history,
+and decision rationale at every step.
+**Why:** Future LLMs advancing this work need to understand *why* decisions were made,
+not just what was decided. A design doc without history is a puzzle without context.
+**Skill extraction:** Every phase produces a dated log entry.
+
+### Lesson 6: Multi-model vetting before implementation
+**What:** User wants to vet progression/plans with other models before implementing.
+**Why:** Different models catch different things. Codex for second opinions, DHH
+reviewer for Ruby idiom quality, possibly Gemini for a third perspective.
+**Skill extraction:** Build review gates into the process.
+
+---
+
+## Phase 2: Overlap Analysis
+
+### Lesson 7: User's intuition was validated by data
+**What:** User predicted ~1/3 code overlap. Analysis yielded 37%.
+**Why this matters:** Domain experts have good intuitions. The analysis doesn't replace intuition — it validates and refines it. If the number had been 15% or 60%, the architecture would change significantly.
+**Skill extraction:** Always ask the user for their hypothesis before running analysis. It calibrates expectations and highlights surprises.
+
+### Lesson 8: Asymmetric token savings reveal architectural insight
+**What:** Design deck saves 30-45% (already uses structured JSON). Visual explainer saves 80-85% (reads 30K tokens of reference material per invocation).
+**Why this matters:** The savings aren't uniform. The biggest win comes from moving the design system FROM the prompt INTO the framework. This is an architectural argument, not just an optimization.
+**Skill extraction:** Token cost analysis should be a required section in every analysis. It reveals where the real value is.
+
+### Lesson 9: Blog material emerges from process, don't reconstruct later
+**What:** User identified 4 blog posts from the process mid-stream.
+**Why this matters:** The process IS content. Waiting until the end means losing the "in the moment" insights.
+**Skill extraction:** Add "blog-worthy observations" as a running section in the progress doc.
+
+## Phase 3: Design
+
+### Lesson 10: Parallel reviews catch different things
+**What:** DHH reviewer focused on Ruby idiom/simplicity. Codex focused on edge cases/scalability. Gemini found a race condition and proposed a better architecture for generate-more (push-to-state).
+**Why:** Each model has different strengths. DHH caught over-engineering. Codex caught missing failure modes. Gemini caught a race condition and offered a structural improvement. No single review found everything.
+**Skill extraction:** Always run at least 2 reviews from different angles. Consider: idiom/simplicity, edge cases/scaling, adversarial/what-if.
+
+### Lesson 11: "Adversarial perspective" prompt yields best insights
+**What:** Telling Gemini "I've had two favorable reviews, I need the adversarial perspective" produced the session's best architectural insight (push-to-state).
+**Why:** Favorable reviews confirm the design but don't improve it. Adversarial reviews find the improvements. Explicitly requesting adversarial framing overcomes the model's tendency to be agreeable.
+**Skill extraction:** Third review should always request adversarial/contrarian angle.
+
+### Lesson 12: Save a SESSION-CONTEXT.md before compaction
+**What:** Before context window fills, write a comprehensive recovery document listing all artifacts, key decisions, current status, and next steps.
+**Why:** Context compaction loses nuance. The recovery doc is the insurance policy. Future sessions read it first to rebuild working context.
+**Skill extraction:** Add "pre-compaction checkpoint" to the process template.
+
+## Phase 4: Implementation
+_To be filled as we progress_
+
+---
+
+## Process Anti-Patterns Observed
+_Running list of things that didn't work_
+
+1. WebFetch for GitHub READMEs — rate limited quickly. Use `gh api` + base64 decode instead.
+2. WebFetch for GitHub READMEs — rate limited quickly. Use `gh api` + base64 decode instead.
+3. **Token cost asymmetry reveals the real value proposition.** pi-design-deck saves 30-45% (already somewhat efficient with JSON), but visual-explainer saves 80-85% because it reads ~30K tokens of reference material per invocation. The design system living in framework code (0 prompt tokens) vs in the prompt is the killer advantage. This should be the lead of the blog post.
+4. **Subagent analysis cost is reasonable.** Each deep analysis used ~140-150K tokens and took 5-6 minutes. The output quality (exhaustive feature inventories, Gherkin scenarios, token cost estimates, porting recommendations) would have consumed far more main-thread context if done inline. Good tradeoff.
+5. **Analysis template should request architecture recommendations.** Both agents provided excellent "what maps directly / needs rearchitecting / can be dropped" sections. This wasn't in the original template but emerged organically. Add it to the skill template.
+
+---
+
+## Skill Template (Draft)
+When this process is complete, the repeatable skill should look like:
+
+```
+/port-from-reference <repo1> <repo2> [--target <our-project>]
+
+Phase 1: Clone & Analyze (parallel subagents)
+  → analysis/<project>.md with standardized sections + Gherkin
+
+Phase 2: Overlap Analysis (single agent)
+  → overlap.md with shared/unique feature matrix
+  → unified-specs.feature
+
+Phase 3: Design (main thread + review agents)
+  → architecture.md
+  → codex-review.md, dhh-review.md
+  → evolution.md
+
+Phase 4: Implementation Planning
+  → GSD-style task breakdown
+  → Each task: scope, input files, output files, acceptance criteria
+
+Phase 5: Implementation (ralph-loop subagents)
+  → One subagent per task, fresh context, reads specs from disk
+  → Atomic commits per task
+
+Phase 6: Verification & Documentation
+  → Run Gherkin scenarios
+  → Blog post / docs
+  → Updated lessons-learned
+```

data/examples/README.md

@@ -0,0 +1,96 @@
+# StreamWeaver Examples
+
+## Directory Structure
+
+### [basic/](basic/)
+Simple getting-started examples. Hello world, forms, basic layouts.
+
+### [components/](components/)
+Individual component showcases. Each file demonstrates a specific component's options and styling.
+
+### [layout/](layout/)
+Layout patterns: columns, grids, cards, collapsibles.
+
+### [styling/](styling/)
+Theme and styling examples: dark mode, custom CSS, color schemes.
+
+### [charts/](charts/)
+Chart components: bar charts, pie charts, stat displays.
+
+### [advanced/](advanced/)
+Complex patterns: multi-step wizards, dashboards, tables with sorting.
+
+### [agentic/](agentic/)
+Interactive workflows with user input and state management.
+
+### [claude_code/](claude_code/)
+**Claude Code slash command integrations**. Interactive canvas workflows powered by Claude Code. See [claude_code/README.md](claude_code/README.md).
+
+## Live Streaming Examples
+
+### timer_showcase.rb
+Dev Machine Monitor — live CPU, Memory, and Disk metrics updated every few seconds. Demonstrates `every` timers, `add_class`/`remove_class` for spotlight effects, and `prepend` for an alert feed.
+
+```bash
+bundle exec ruby examples/timer_showcase.rb
+```
+
+### timer_health_checker.rb
+Endpoint Health Checker — pings GitHub, RubyGems, and Httpbin every 5 seconds, showing response times, SLA badges, and ring effects on degraded endpoints.
+
+```bash
+bundle exec ruby examples/timer_health_checker.rb
+```
+
+## Standalone Scripts
+
+### panel_demo.sh
+Multi-step workflow demonstrating StreamWeaver's visual capabilities:
+- Syntax-highlighted code diffs
+- Animated progress indicators
+- Interactive charts and tables
+
+```bash
+./examples/panel_demo.sh
+```
+
+### git_health.sh
+Git repository health analyzer with dynamic canvas dashboard:
+- Real git data analysis
+- File structure visualization
+- Contributor stats
+
+```bash
+./examples/git_health.sh [path-to-repo]
+```
+
+### dashboard_components.rb
+Component showcase for operations dashboards.
+
+### operations_dashboard_demo.rb
+Full operations dashboard example with dark theme.
+
+## Running Examples
+
+### Ruby Files
+```bash
+streamweaver examples/basic/hello_world.rb
+```
+
+### Shell Scripts
+```bash
+./examples/panel_demo.sh
+```
+
+### Claude Code Slash Commands
+```bash
+cd examples/claude_code/codebreaker
+claude
+# /infiltrate
+```
+
+## Documentation
+
+- [Canvas Panel Workflow](../docs/canvas-panel-workflow.md) - Two-way IPC for Claude Code
+- [Components Reference](../docs/components_reference.md) - All DSL components
+- [How StreamWeaver Works](../docs/architecture/how_streamweaver_works.md) - Architecture overview

data/examples/advanced/all_components.rb

@@ -0,0 +1,177 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../../lib/stream_weaver'
+
+# Demo of all StreamWeaver components
+App = app "Component Showcase" do
+  header "StreamWeaver Component Showcase"
+
+  # --- Text Components ---
+  header3 "Text (Literal)"
+  text "Plain text renders literally - **asterisks** stay as asterisks"
+
+  header3 "Markdown (Parsed)"
+  md "**Bold**, *italic*, `code`, and [links](https://example.com) are parsed"
+
+  header3 "Headers"
+  text "header (h2 default), header1-header6 for explicit levels"
+
+  # --- Form Components ---
+  header3 "Text Field"
+  text_field :username, placeholder: "Enter username"
+
+  header3 "Text Area"
+  text_area :bio, placeholder: "Enter bio", rows: 3
+
+  header3 "Checkbox"
+  checkbox :enabled, "Enable feature"
+
+  header3 "Select Dropdown (with default)"
+  select :color, ["Red", "Green", "Blue", "Yellow"], default: "Green"
+
+  header3 "Radio Group"
+  radio_group :size, ["Small", "Medium", "Large"]
+
+  header3 "Checkbox Group (Multi-Select)"
+  checkbox_group :selected_items, select_all: "Select All", select_none: "Clear" do
+    item "item_1" do
+      text "First item"
+    end
+    item "item_2" do
+      text "Second item"
+    end
+    item "item_3" do
+      text "Third item"
+    end
+  end
+
+  # --- Layout Components ---
+  header3 "Div Container"
+  div class: "todo-item" do
+    text "This is inside a div container"
+    text "Multiple components can be nested"
+  end
+
+  header3 "Card"
+  card do
+    text "Cards provide styled containers"
+    text "Great for grouping related content"
+  end
+
+  header3 "Columns (Monica-style sidebar layout)"
+  columns widths: ['30%', '70%'] do
+    column class: "sidebar-facts" do
+      div class: "sidebar-section" do
+        header4 "Work"
+        text "Software Engineer at Acme Corp"
+      end
+
+      div class: "sidebar-section" do
+        header4 "Location"
+        text "San Francisco, CA"
+      end
+
+      div class: "sidebar-section" do
+        header4 "Contact"
+        text "email@example.com"
+        text "(555) 123-4567"
+      end
+
+      div class: "sidebar-section" do
+        header4 "Significant Other"
+        text "Jane Doe"
+      end
+    end
+
+    column do
+      collapsible "Background", expanded: true do
+        md "This person has been working in tech for **10 years** and specializes in Ruby development."
+      end
+
+      collapsible "Key Facts" do
+        md "- Met at RubyConf 2023\n- Interested in open source\n- Coffee enthusiast"
+      end
+    end
+  end
+
+  header3 "Equal-width Columns"
+  columns do
+    column do
+      card do
+        text "Column 1"
+        text "Equal width flex"
+      end
+    end
+    column do
+      card do
+        text "Column 2"
+        text "Also equal width"
+      end
+    end
+    column do
+      card do
+        text "Column 3"
+        text "Three columns!"
+      end
+    end
+  end
+
+  # --- Interactive Components ---
+  header3 "Buttons"
+  button "Primary Action" do |state|
+    state[:clicked] ||= 0
+    state[:clicked] += 1
+  end
+
+  button "Secondary Action", style: :secondary do |state|
+    state[:secondary_clicked] = true
+  end
+
+  if state[:clicked] && state[:clicked] > 0
+    md "Primary button clicked **#{state[:clicked]}** times"
+  end
+
+  if state[:secondary_clicked]
+    text "Secondary button was clicked!"
+  end
+
+  # --- Status & Selection Components ---
+  header3 "Status Badge"
+  text "Visual match indicators with reasoning:"
+  div class: "status-badges-demo" do
+    status_badge :strong, "Perfect match for your preferences"
+    status_badge :maybe, "Good fit, but has some dark themes"
+    status_badge :skip, "Not recommended - wrong genre"
+  end
+
+  header3 "Tag Buttons (Single Select)"
+  text "Default style:"
+  tag_buttons :category, ["Fiction", "Non-fiction", "Mystery", "Sci-Fi"]
+
+  text "Destructive style (for elimination):"
+  tag_buttons :eliminate_reason, ["Too dark", "Wrong genre", "Bad reviews", "Not interested"], style: :destructive
+
+  text "Selected category: #{state[:category] || '(none)'}"
+  text "Elimination reason: #{state[:eliminate_reason] || '(none)'}"
+
+  header3 "External Link Button"
+  text "Opens URL in new tab (no form submit):"
+  external_link_button "Visit Example.com", url: "https://example.com"
+
+  text "Opens URL AND submits form (for agentic mode):"
+  external_link_button "Submit & Open Google", url: "https://google.com", submit: true
+
+  # --- Current State ---
+  header3 "Current State"
+  text "Username: #{state[:username] || '(none)'}"
+  text "Bio: #{state[:bio] || '(none)'}"
+  text "Enabled: #{state[:enabled] ? 'Yes' : 'No'}"
+  text "Color: #{state[:color] || '(none)'}"
+  text "Size: #{state[:size] || '(none)'}"
+  text "Selected items: #{(state[:selected_items] || []).join(', ').then { |s| s.empty? ? '(none)' : s }}"
+  text "Category: #{state[:category] || '(none)'}"
+  text "Elimination reason: #{state[:eliminate_reason] || '(none)'}"
+end
+
+App.run! if __FILE__ == $0