stream_weaver 0.3.0

data/lib/stream_weaver/skills/visual-recap/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: visual-recap
+description: Use after finishing a task (or mid-task for incremental updates) — renders a live canvas showing what changed, why, and the key design choices made during implementation
+---
+
+# Visual Recap
+
+Post-implementation canvas recap. Pushes a live visual summary of what actually changed: files touched, the most significant diffs, annotated complex code, and design choices flagged during the work — all in one persistent canvas that evolves with the task.
+
+## When to Use
+
+After any task where:
+- Multiple files changed
+- A design decision was made
+- The user wants to see what happened, not just a text summary
+- You're mid-task and want to show progress without finishing
+
+Push at task start (showing intended changes), update mid-task, finalize when done. The canvas evolves — it is not a one-shot publish.
+
+Skip for trivial one-liner edits where a text summary is faster than a canvas.
+
+## Why StreamWeaver vs Static Recap
+
+Builder.io's visual-recap and similar tools generate a static artifact at the end of a task — one snapshot, one publish, frozen. StreamWeaver's recap is **live and incremental**:
+
+- Push at the start with the intended change map
+- Update after each batch of files
+- Add diff blocks as significant changes land
+- Finalize with annotated code and design decisions
+
+The user sees real progress. Mid-task pivots are visible. The canvas reflects the actual task state, not a post-hoc reconstruction.
+
+## !! DO NOT LAUNCH STANDALONE SERVERS PER UPDATE !!
+
+**NEVER** run `ruby app.rb` or `streamweaver <file.rb>` for each recap update. Use `canvas-push` to update a single persistent window throughout the session.
+
+## Step 1 — Get the Changed Files
+
+```bash
+# After finishing: diff since the last commit
+git diff HEAD~1 --name-only
+
+# Mid-task or across a feature branch:
+git diff main..HEAD --name-only
+
+# For uncommitted changes:
+git diff --name-only
+git status --short
+```
+
+Parse the output to build a `{ path:, note: }` list. The `note:` should explain **why** the file changed, not what the file is. Write it now — don't defer to Step 3.
+
+Example mapping:
+
+```
+lib/stream_weaver/components/callout.rb  → "Added :decision and :risk tone variants"
+spec/components/callout_spec.rb          → "Cover new tone variants, edge cases for missing title"
+lib/stream_weaver/display_dsl.rb         → "Expose callout shorthand with default variant: :info"
+```
+
+## Step 2 — Start the Canvas
+
+```bash
+streamweaver panel recap
+```
+
+This opens a persistent canvas named `recap` in an iTerm2 split pane (or browser tab elsewhere). The URL is printed to stdout — tell the user where to look.
+
+## Step 3 — Push the Implementation Map
+
+```bash
+streamweaver canvas-push recap <<'RUBY'
+  header1 "Recap: <task name>"
+
+  implementation_map(files: [
+    { path: "lib/stream_weaver/components/callout.rb",
+      note: "Added :decision and :risk tone variants with icon and border color" },
+    { path: "spec/components/callout_spec.rb",
+      note: "Cover new tone variants and missing-title edge case" },
+    { path: "lib/stream_weaver/display_dsl.rb",
+      note: "Expose callout shorthand: default variant :info, no block required" }
+  ])
+RUBY
+```
+
+`note:` is the rationale — **why this file changed**, not just what it contains. One sentence.
+
+## Step 4 — Push Diffs for the 2-3 Most Significant Changes
+
+Pick the files where the change is non-obvious from the file name. Push a `diff` block per file:
+
+```bash
+streamweaver canvas-push recap <<'RUBY'
+  header2 "Key Changes"
+
+  diff(language: "ruby") do
+    before do
+      <<~CODE
+        def callout(variant: :info, title: nil, &block)
+          @components << Components::Callout.new(variant: variant, title: title, &block)
+        end
+      CODE
+    end
+    after do
+      <<~CODE
+        def callout(variant: :info, title: nil, **options, &block)
+          with_container(Components::Callout.new(variant: variant, title: title, **options), &block)
+        end
+      CODE
+    end
+  end
+RUBY
+```
+
+Limit to 2-3 diffs. If more files changed significantly, pick the ones that tell the story of the task. The `before`/`after` content should be the actual code — copy from the diff, don't paraphrase.
+
+## Step 5 — Annotated Code for the Most Complex Change (Optional)
+
+If one file has a non-obvious implementation worth explaining:
+
+```bash
+streamweaver canvas-push recap <<'RUBY'
+  header2 "Implementation Detail"
+
+  annotated_code(
+    language: "ruby",
+    annotations: [
+      { line: 3,  label: "Delegates to with_container",
+        note: "Allows callout to hold nested DSL components — text, md, badge, etc." },
+      { line: 7,  label: "Variant maps to CSS class",
+        note: "sw-callout-decision, sw-callout-risk, sw-callout-info — defined in callout.css" },
+      { line: 12, label: "Title is optional",
+        note: "Renders as a <strong> header when present; omitted entirely if nil" }
+    ]
+  ) do
+    <<~CODE
+      def callout(variant: :info, title: nil, **options, &block)
+        with_container(
+          Components::Callout.new(variant: variant, title: title, **options),
+          &block
+        )
+      end
+
+      class Callout
+        VARIANT_CLASSES = { info: "sw-callout-info", decision: "sw-callout-decision",
+                            risk: "sw-callout-risk", tip: "sw-callout-tip" }
+        # ...
+        def render_title
+          strong { @title } if @title
+        end
+      end
+    CODE
+  end
+RUBY
+```
+
+Skip this step if the implementation is straightforward.
+
+## Step 6 — Flag Design Choices
+
+Push a `callout(:decision)` for each meaningful design decision made during the task:
+
+```bash
+streamweaver canvas-push recap <<'RUBY'
+  header2 "Design Choices"
+
+  callout(variant: :decision, title: "with_container instead of direct push") do
+    text "Callout now accepts nested DSL calls (text, md, badge). Using with_container lets the"
+    text "component collect children from the block the same way card and columns do."
+    text "Alternative: parse the block as a string. Rejected — loses type safety and child ordering."
+  end
+
+  callout(variant: :decision, title: ":info as the default variant") do
+    text "Matches the most common use case (informational callouts). Callers who want :risk or"
+    text ":decision must opt in — no accidental risk styling on plain callouts."
+  end
+RUBY
+```
+
+One `callout(:decision)` per meaningful choice. If you made a risky call, use `callout(:risk)` instead.
+
+## Incremental Updates (Mid-Task)
+
+You do not have to wait until a task is done. Update the recap as you go:
+
+```bash
+# After the first batch of files:
+streamweaver canvas-push recap <<'RUBY'
+  header1 "Recap: Add Callout Tones — In Progress"
+
+  implementation_map(files: [
+    { path: "lib/stream_weaver/components/callout.rb",  note: "[done] Tone variants added" },
+    { path: "spec/components/callout_spec.rb",          note: "[wip]" },
+    { path: "lib/stream_weaver/display_dsl.rb",         note: "[pending]" }
+  ])
+RUBY
+```
+
+Use `[done]`, `[wip]`, and `[pending]` prefixes in the `note:` field to show live status.
+
+## Combining Steps in One Push
+
+For small tasks, push everything in a single canvas update:
+
+```bash
+streamweaver canvas-push recap <<'RUBY'
+  header1 "Recap: Add Callout Tones"
+
+  implementation_map(files: [
+    { path: "lib/stream_weaver/components/callout.rb",
+      note: "Added :decision and :risk tone variants with icon and border color" },
+    { path: "spec/components/callout_spec.rb",
+      note: "Cover new tone variants and missing-title edge case" }
+  ])
+
+  diff(language: "ruby") do
+    before { "def callout(variant: :info, &block)\n  ..." }
+    after  { "def callout(variant: :info, **options, &block)\n  with_container(...)\nend" }
+  end
+
+  callout(variant: :decision, title: "with_container for nested DSL") do
+    text "Allows callout to contain text, md, badge — matches card/columns pattern."
+  end
+RUBY
+```
+
+## DSL Reference
+
+| Method | Purpose |
+|---|---|
+| `implementation_map(files: [...])` | File-to-rationale map; `note:` is the why |
+| `diff(language:) { before { } after { } }` | Side-by-side code diff |
+| `annotated_code(language:, annotations: [...]) { }` | Code with line-pinned notes |
+| `callout(variant: :decision, title: "...") { }` | Design choice flag |
+| `callout(variant: :risk, title: "...") { }` | Risk or caveat flag |
+
+## Known Gotchas
+
+- DSL method is `diff`, not `diff_block` — `diff_block` does not exist
+- `annotated_code` line numbers are 1-indexed; they match the code block you supply, not the original file
+- `callout` block must use `text` or `md` — nesting `diff` or `implementation_map` inside a callout throws
+- `spacer` and `divider` don't exist — use `div(style: "height:Npx")` for spacing
+- StreamWeaver auto-selects a port — capture the URL from stdout, don't hardcode 4567
+- If `undefined method` errors appear, the bridge is stale: `streamweaver canvas-stop && streamweaver panel recap`

data/lib/stream_weaver/streamer.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module StreamWeaver
+  # Thread-safe SSE connection manager with Turbo Stream-like actions.
+  # Manages browser SSE connections and broadcasts targeted DOM updates.
+  #
+  # @example Internal usage (from app stream block)
+  #   streamer.replace("#metric-rps", "<div>3500</div>")
+  #
+  # @example External usage (via POST /stream/push)
+  #   curl -X POST localhost:4567/stream/push -d 'target=#metric-rps&html=<div>3500</div>'
+  class Streamer
+    include Pushable
+
+    ACTIONS = %i[replace append prepend remove add_class remove_class].freeze
+
+    def initialize
+      @connections = []
+      @mutex = Mutex.new
+      @shutting_down = false
+    end
+
+    def shutdown!
+      @shutting_down = true
+    end
+
+    def shutting_down?
+      @shutting_down
+    end
+
+    def add_connection(conn)
+      @mutex.synchronize { @connections << conn }
+    end
+
+    def remove_connection(conn)
+      @mutex.synchronize { @connections.delete(conn) }
+    end
+
+    def connection_count
+      @mutex.synchronize { @connections.size }
+    end
+
+    private
+
+    def push_update(action:, target:, html: nil, value: nil)
+      payload = { action: action, target: target }
+      payload[:html] = html if html
+      payload[:value] = value if value
+      data = payload.to_json
+      @mutex.synchronize do
+        dead = []
+        @connections.each do |conn|
+          conn << "data: #{data}\n\n"
+        rescue IOError, Errno::EPIPE, Errno::ECONNRESET, Puma::ConnectionError
+          dead << conn
+        end
+        @connections -= dead
+      end
+    end
+  end
+end

data/lib/stream_weaver/templates/choices.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+require_relative '../cli'
+
+module StreamWeaver
+  module Templates
+    # Simple choice selector template
+    # Shows options as buttons, returns the selected value
+    #
+    # Usage:
+    #   streamweaver template choices SESSION '{"title":"Pick a color","options":["Red","Green","Blue"]}'
+    #   # Returns: {"choice":"Green"}
+    #
+    #   # With descriptions:
+    #   streamweaver template choices SESSION '{
+    #     "title":"Database",
+    #     "description":"Which database to use?",
+    #     "options":[
+    #       {"label":"PostgreSQL","description":"Best for complex queries"},
+    #       {"label":"SQLite","description":"Simple, file-based"},
+    #       {"label":"MySQL","description":"Popular, widely supported"}
+    #     ]
+    #   }'
+    #
+    class Choices
+      def initialize(session:, config:, port: nil)
+        @session = session
+        @config = config
+        @port = port || detect_port
+        @title = config['title'] || 'Choose an option'
+        @description = config['description']
+        @options = config['options'] || []
+        @run_id = Time.now.to_i.to_s(36)
+      end
+
+      def run
+        clear_submissions
+        push_choices
+        data = wait_for_submission
+
+        # Extract choice from button id (btn_LABEL_1 format)
+        button_id = data['_button'] || ''
+        # Button id is like "btn_postgresql_1" - extract the label part
+        choice_key = button_id.sub(/^btn_/, '').sub(/_\d+$/, '')
+
+        # Find matching option
+        selected = find_option_by_key(choice_key)
+
+        { 'choice' => selected }
+      end
+
+      private
+
+      def detect_port
+        pid_file = File.expand_path('~/.streamweaver/service.pid')
+        return 4576 unless File.exist?(pid_file)
+        data = JSON.parse(File.read(pid_file))
+        data['port'] || 4576
+      rescue
+        4576
+      end
+
+      def find_option_by_key(key)
+        @options.each do |opt|
+          if opt.is_a?(Hash)
+            label = opt['label']
+            # Normalize: downcase, replace spaces with underscores
+            normalized = label.downcase.gsub(/\s+/, '_').gsub(/[^a-z0-9_]/, '')
+            return label if normalized == key
+          else
+            normalized = opt.to_s.downcase.gsub(/\s+/, '_').gsub(/[^a-z0-9_]/, '')
+            return opt if normalized == key
+          end
+        end
+        key # fallback
+      end
+
+      def push_choices
+        dsl = build_dsl
+        html = StreamWeaver::CLI.render_dsl_to_html(dsl, session_name: @session)
+
+        uri = URI("http://localhost:#{@port}/live/#{URI.encode_www_form_component(@session)}/push")
+        request = Net::HTTP::Post.new(uri)
+        request.set_form_data('content' => html, 'target' => '#main', 'action' => 'replace')
+
+        Net::HTTP.start(uri.hostname, uri.port) { |http| http.request(request) }
+      end
+
+      def build_dsl
+        lines = []
+        lines << "header2 \"#{@title}\""
+        lines << "text \"#{@description}\"" if @description
+        lines << "card do"
+
+        @options.each do |opt|
+          if opt.is_a?(Hash)
+            label = opt['label']
+            desc = opt['description']
+            lines << "  button \"#{label}\""
+            lines << "  text \"#{desc}\", style: :muted" if desc
+            lines << "  text \"\""
+          else
+            lines << "  button \"#{opt}\""
+          end
+        end
+
+        lines << "end"
+        lines.join("\n")
+      end
+
+      def clear_submissions
+        uri = URI("http://localhost:#{@port}/live/#{URI.encode_www_form_component(@session)}/submissions")
+        loop do
+          response = Net::HTTP.get_response(uri)
+          break unless response.is_a?(Net::HTTPSuccess)
+          data = JSON.parse(response.body)
+          break if (data['submissions'] || []).empty?
+        end
+      rescue
+        # ignore
+      end
+
+      def wait_for_submission(timeout: 300)
+        start_time = Time.now
+        uri = URI("http://localhost:#{@port}/live/#{URI.encode_www_form_component(@session)}/submissions")
+
+        loop do
+          raise "Timeout" if Time.now - start_time > timeout
+
+          response = Net::HTTP.get_response(uri)
+          if response.is_a?(Net::HTTPSuccess)
+            data = JSON.parse(response.body)
+            submissions = data['submissions'] || []
+            return submissions.first['data'] if submissions.any?
+          end
+
+          sleep 0.3
+        end
+      end
+
+      def self.run(session:, config:, port: nil)
+        new(session: session, config: config, port: port).run
+      end
+    end
+  end
+end

data/lib/stream_weaver/templates/code.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+require_relative '../cli'
+
+module StreamWeaver
+  module Templates
+    # Code display template
+    # Shows code with optional filename and actions
+    #
+    # Usage:
+    #   streamweaver template code SESSION '{
+    #     "title": "Generated Code",
+    #     "filename": "app.rb",
+    #     "language": "ruby",
+    #     "code": "def hello\n  puts \"Hello\"\nend",
+    #     "actions": ["Copy", "Apply", "Cancel"]
+    #   }'
+    #   # Returns: {"action": "Apply"}
+    #
+    class Code
+      def initialize(session:, config:, port: nil)
+        @session = session
+        @config = config
+        @port = port || detect_port
+        @title = config['title']
+        @filename = config['filename']
+        @language = config['language'] || 'text'
+        @code = config['code'] || ''
+        @actions = config['actions'] || ['OK']
+        @line_numbers = config['line_numbers'] != false
+      end
+
+      def run
+        clear_submissions
+        push_code
+        data = wait_for_submission
+
+        button_id = data['_button'] || ''
+        action = extract_action(button_id)
+        { 'action' => action }
+      end
+
+      private
+
+      def detect_port
+        pid_file = File.expand_path('~/.streamweaver/service.pid')
+        return 4576 unless File.exist?(pid_file)
+        data = JSON.parse(File.read(pid_file))
+        data['port'] || 4576
+      rescue
+        4576
+      end
+
+      def extract_action(button_id)
+        key = button_id.sub(/^btn_/, '').sub(/_\d+$/, '')
+        @actions.each do |action|
+          normalized = action.to_s.downcase.gsub(/\s+/, '_').gsub(/[^a-z0-9_]/, '')
+          return action if normalized == key
+        end
+        key
+      end
+
+      def push_code
+        # Build HTML directly for better code formatting
+        html = build_html
+
+        uri = URI("http://localhost:#{@port}/live/#{URI.encode_www_form_component(@session)}/push")
+        request = Net::HTTP::Post.new(uri)
+        request.set_form_data('content' => html, 'target' => '#main', 'action' => 'replace')
+
+        Net::HTTP.start(uri.hostname, uri.port) { |http| http.request(request) }
+      end
+
+      def build_html
+        escaped_code = escape_html(@code)
+
+        # Add line numbers if enabled
+        if @line_numbers
+          lines = escaped_code.split("\n")
+          numbered_lines = lines.each_with_index.map do |line, i|
+            line_num = (i + 1).to_s.rjust(3)
+            "<span style='color: #666; user-select: none;'>#{line_num}</span>  #{line}"
+          end
+          escaped_code = numbered_lines.join("\n")
+        end
+
+        buttons_html = @actions.map.with_index do |action, i|
+          variant_class = i == 0 ? 'sw-btn-primary' : 'sw-btn-secondary'
+          btn_id = "btn_#{action.downcase.gsub(/\s+/, '_').gsub(/[^a-z0-9_]/, '')}_#{i + 1}"
+          %(<button id="#{btn_id}" class="sw-btn #{variant_class}"
+            hx-post="/live/#{@session}/action/#{btn_id}"
+            hx-include="[x-model]"
+            hx-target="#main"
+            hx-swap="innerHTML">#{escape_html(action)}</button>)
+        end.join("\n          ")
+
+        <<~HTML
+          <div id="main" x-data="{}">
+            #{@title ? "<h2 style='margin-bottom: 1rem;'>#{escape_html(@title)}</h2>" : ''}
+            <div class="sw-card" style="padding: 0; overflow: hidden;">
+              #{@filename ? "<div style='padding: 0.5rem 1rem; background: var(--sw-color-bg); border-bottom: 1px solid var(--sw-color-border); font-size: 0.875rem; color: var(--sw-color-text-muted);'>#{escape_html(@filename)}</div>" : ''}
+              <pre style="margin: 0; padding: 1rem; background: #1e1e1e; color: #d4d4d4; overflow-x: auto; font-family: 'SF Mono', Consolas, monospace; font-size: 0.875rem; line-height: 1.5;"><code>#{escaped_code}</code></pre>
+            </div>
+            <div style="margin-top: 1rem; display: flex; gap: 0.5rem;">
+              #{buttons_html}
+            </div>
+          </div>
+        HTML
+      end
+
+      def escape_html(text)
+        text.to_s
+          .gsub('&', '&amp;')
+          .gsub('<', '&lt;')
+          .gsub('>', '&gt;')
+          .gsub('"', '&quot;')
+      end
+
+      def clear_submissions
+        uri = URI("http://localhost:#{@port}/live/#{URI.encode_www_form_component(@session)}/submissions")
+        loop do
+          response = Net::HTTP.get_response(uri)
+          break unless response.is_a?(Net::HTTPSuccess)
+          data = JSON.parse(response.body)
+          break if (data['submissions'] || []).empty?
+        end
+      rescue
+        # ignore
+      end
+
+      def wait_for_submission(timeout: 300)
+        start_time = Time.now
+        uri = URI("http://localhost:#{@port}/live/#{URI.encode_www_form_component(@session)}/submissions")
+
+        loop do
+          raise "Timeout" if Time.now - start_time > timeout
+
+          response = Net::HTTP.get_response(uri)
+          if response.is_a?(Net::HTTPSuccess)
+            data = JSON.parse(response.body)
+            submissions = data['submissions'] || []
+            return submissions.first['data'] if submissions.any?
+          end
+
+          sleep 0.3
+        end
+      end
+
+      def self.run(session:, config:, port: nil)
+        new(session: session, config: config, port: port).run
+      end
+    end
+  end
+end