stream_weaver 0.3.0

data/lib/stream_weaver/university/demos/counter.rb

@@ -0,0 +1,33 @@
+require 'stream_weaver'
+
+app "Counter" do
+  callout "This whole app is the file your agent just ran -- nothing hidden. Click +1 -- the whole block re-runs on the server and the count updates. When you're done playing: come back to your Claude session and say \"done\".", variant: :info
+  state[:count] ||= 0
+  header1 "Six lines of Ruby"
+  text "Count: #{state[:count]}"
+  button("+1") { |s| s[:count] += 1 }
+end.run!
+
+# ^ The mechanism above is still the whole app: a six-line block (four
+# statements wrapped by `app "Counter" do` and `end.run!`), in an eight-line
+# file. Nothing has been elided, and nothing below this line runs -- `.run!`
+# blocks. StreamWeaver University, step 2 (story: step-2-dsl-reexec). The
+# worker runs THIS file, verbatim, rather than writing its own: two real
+# worker sessions each lost a debug cycle to the "six-line app" framing, one
+# by omitting `require 'stream_weaver'` (NoMethodError: undefined method
+# 'app') and the other by omitting `.run!` (builds the app, starts no
+# server, exits silently). Both lines are above, on purpose.
+#
+#   ruby "$(streamweaver university-demo counter)"
+#
+# There is no event-handler code here and no route. The block on line 5 is
+# re-executed on every click; `state[:count]` is one higher when it runs, so
+# line 7 renders a different number. That single idea -- the block re-runs
+# -- is every other thing StreamWeaver does, wearing different clothes.
+#
+# Round-6 UAT (2026-09-03): the app used to pop up with no explanation of
+# its own, so anyone who tabbed over before the agent's narration caught up
+# saw a bare counter and nothing else. The `callout` above is the file's
+# ninth line -- deliberately not part of the six-line mechanism, and not one
+# of the two bookend lines named above either. It is the one line meant to
+# be read on screen, not walked through.

data/lib/stream_weaver/university/demos/dashboard.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+# StreamWeaver University -- step 1's dashboard demo (story:
+# step-1-canvas-push).
+#
+# Three things a terminal cannot draw, in one push: a 2x2 grid of KPI tiles,
+# a Chart.js bar chart, and a mermaid sequence diagram of the very
+# canvas-push that put them there. Then the same layout again with different
+# numbers, so the pane mutates in place while the worker narrates.
+#
+#   streamweaver panel dashboard                      # open the pane first
+#   ruby "$(streamweaver university-demo dashboard)" dashboard      # week 1
+#   ruby "$(streamweaver university-demo dashboard)" dashboard 2    # mutate
+#   ruby "$(streamweaver university-demo dashboard)" dashboard 3    # mutate
+#
+# ARGV: SESSION_NAME (default "dashboard"), SNAPSHOT (1-3, default 1).
+#
+# Why a push script rather than three DSL files piped through
+# `canvas-push`: the DSL is rendered inside the bridge process, so a file
+# cannot read the caller's environment, and three near-identical DSL files
+# would be three places for the layout to drift. One parameterized script,
+# three snapshots of the same layout.
+#
+# Design constraints baked in:
+#
+# - Pane width. This renders in a ~750-800px split pane
+#   (features/university-getting-started.context.md, "Pane-width rule"), so
+#   the tiles are two rows of two rather than one row of four -- `.sw-columns`
+#   only stacks below 640px, and four tiles across 750px is unreadable.
+# - `chart type:` explicitly, never the `bar_chart` shorthand: the shorthand
+#   family renders through Alpine `x-init`, and disc-094 kills it on export.
+#   The explicit form is what commit 51beb6c fixed for bridge poll swaps.
+
+require 'stream_weaver/canvas/client'
+
+module StreamWeaver
+  module University
+    module Demos
+      module Dashboard
+        # Each snapshot is one frame of the same dashboard. Same tile
+        # labels, same chart series, different numbers -- so a re-push reads
+        # as "the data moved", not "a different page".
+        SNAPSHOTS = [
+          {
+            caption: 'Sprint 14 · Monday standup',
+            tiles: [
+              { value: 128, label: 'PUSHES', color: :default },
+              { value: 12, label: 'SESSIONS', color: :blue },
+              { value: 3, label: 'BLOCKED', color: :red },
+              { value: 41, label: 'DOCS SAVED', color: :purple }
+            ],
+            bars: [18, 24, 31, 22, 33]
+          },
+          {
+            caption: 'Sprint 14 · Wednesday standup',
+            tiles: [
+              { value: 164, label: 'PUSHES', color: :default },
+              { value: 15, label: 'SESSIONS', color: :blue },
+              { value: 1, label: 'BLOCKED', color: :red },
+              { value: 52, label: 'DOCS SAVED', color: :purple }
+            ],
+            bars: [18, 24, 31, 29, 47]
+          },
+          {
+            caption: 'Sprint 14 · Friday standup',
+            tiles: [
+              { value: 203, label: 'PUSHES', color: :default },
+              { value: 19, label: 'SESSIONS', color: :blue },
+              { value: 0, label: 'BLOCKED', color: :red },
+              { value: 68, label: 'DOCS SAVED', color: :purple }
+            ],
+            bars: [18, 24, 31, 29, 61]
+          }
+        ].freeze
+
+        DAYS = %w[Mon Tue Wed Thu Fri].freeze
+
+        # One flat DSL body for the given snapshot. Flat and
+        # one-statement-per-component on purpose (same rule the growing-doc
+        # script follows) so the text stays legible when a curious user
+        # reads the file this course just ran.
+        def self.dsl(index = 0)
+          snap = SNAPSHOTS[index]
+          top, bottom = snap[:tiles].each_slice(2).to_a
+
+          <<~RUBY
+            header1 "Canvas activity"
+
+            text #{snap[:caption].inspect}
+
+            columns 2 do
+              column { stat_display value: #{top[0][:value]}, label: #{top[0][:label].inspect}, color: :#{top[0][:color]}, size: :lg }
+              column { stat_display value: #{top[1][:value]}, label: #{top[1][:label].inspect}, color: :#{top[1][:color]}, size: :lg }
+            end
+
+            columns 2 do
+              column { stat_display value: #{bottom[0][:value]}, label: #{bottom[0][:label].inspect}, color: :#{bottom[0][:color]}, size: :lg }
+              column { stat_display value: #{bottom[1][:value]}, label: #{bottom[1][:label].inspect}, color: :#{bottom[1][:color]}, size: :lg }
+            end
+
+            chart type: :bar, data: {
+              labels: #{DAYS.inspect},
+              datasets: [
+                { label: "Pushes", data: #{snap[:bars].inspect}, backgroundColor: "#6366f1" }
+              ]
+            }, height: 240
+
+            md "**How this got here.** Not a screenshot, not a file your agent opened in a browser -- one command, and the pane you are looking at redrew itself:"
+
+            mermaid <<~DIAGRAM
+              sequenceDiagram
+                participant A as Your agent
+                participant C as streamweaver CLI
+                participant B as canvas bridge
+                participant P as this pane
+                A->>C: ruby dashboard.rb dashboard #{index + 1}
+                C->>B: push(session, DSL)
+                B->>B: render DSL -> HTML
+                B-->>P: poll swap, in place
+                P-->>A: no reload, no flicker
+            DIAGRAM
+          RUBY
+        end
+
+        def self.run!(session_name: ARGV[0] || 'dashboard',
+                      snapshot: Integer(ARGV[1] || 1))
+          index = snapshot.clamp(1, SNAPSHOTS.length) - 1
+
+          ::StreamWeaver::Canvas::Client.ensure_bridge_running
+          ::StreamWeaver::Canvas::Client.send_message(
+            ::StreamWeaver::Canvas::Protocol::Messages.create(session_name, layout: :fluid)
+          )
+          ::StreamWeaver::Canvas::Client.send_message(
+            ::StreamWeaver::Canvas::Protocol::Messages.push(session_name, dsl(index), source_dir: nil)
+          )
+          puts "Pushed snapshot #{index + 1} of #{SNAPSHOTS.length} (#{SNAPSHOTS[index][:caption]}) to canvas session '#{session_name}'."
+        rescue ::StreamWeaver::Canvas::Client::NotRunningError,
+               ::StreamWeaver::Canvas::Client::ConnectionError => e
+          warn "dashboard: could not reach the canvas bridge (#{e.message}) -- " \
+               "run `streamweaver panel #{session_name}` first"
+        end
+      end
+    end
+  end
+end
+
+StreamWeaver::University::Demos::Dashboard.run! if $PROGRAM_NAME == __FILE__

data/lib/stream_weaver/university/demos/decision_form.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+# StreamWeaver University -- step 3's decision form (story:
+# step-3-form-modes).
+#
+# ONE artifact, two surfaces. The same question -- a mermaid diagram of two
+# candidate architectures, a comparison table, a radio_group and a rationale
+# text_field -- is rendered either as a standalone blocking app or as a
+# canvas push. Nothing is duplicated between the two modes; that identity is
+# the lesson, and the worker is told to say so out loud.
+#
+# Mode 1, the founding loop (step 3's opening move):
+#
+#   ruby "$(streamweaver university-demo decision-form)"
+#
+# `run_once!` finds a free port, OPENS the browser itself, and BLOCKS. The
+# user answers in the page that just appeared; the process prints the
+# submitted state as JSON and exits. The user never opens a page and never
+# has to tell the agent "done" -- round-5 UAT found both of those to be
+# homework the course was silently assigning.
+#
+# Mode 2, the same form on the canvas:
+#
+#   streamweaver panel decision
+#   ruby "$(streamweaver university-demo decision-form)" canvas decision
+#   streamweaver canvas-wait decision
+#
+# Input components are radio_group / text_field only. disc-098 and disc-105:
+# checkbox_group and multi chip_group harvest the wrong values back through
+# canvas-wait.
+
+require 'stream_weaver'
+require 'stream_weaver/canvas/client'
+
+module StreamWeaver
+  module University
+    module Demos
+      module DecisionForm
+        # The question and its evidence. Everything a terminal prompt cannot
+        # carry: a rendered diagram of both designs, and a table putting them
+        # side by side on three axes.
+        CONTEXT = <<~RUBY
+          header1 "Which way should the canvas bridge hold sessions?"
+
+          md "This is a real decision, not a demo prompt -- and it is the kind an agent normally has to ask you in prose, one option per paragraph, hoping you can hold both designs in your head at once."
+
+          mermaid <<~DIAGRAM
+            graph TB
+              subgraph A["A · One shared bridge"]
+                A1["streamweaver CLI"] --> A2["single bridge process"]
+                A2 --> A3["session: dashboard"]
+                A2 --> A4["session: decision"]
+                A2 --> A5["session: doc-demo"]
+              end
+              subgraph B["B · A process per session"]
+                B1["streamweaver CLI"] --> B2["bridge: dashboard"]
+                B1 --> B3["bridge: decision"]
+                B1 --> B4["bridge: doc-demo"]
+              end
+          DIAGRAM
+
+          table [
+            { axis: "Memory", shared: "One process, one Puma", per_session: "N processes, N Pumas" },
+            { axis: "Blast radius", shared: "A crash takes every pane", per_session: "A crash takes one pane" },
+            { axis: "Cross-session reads", shared: "Free -- same object graph", per_session: "Needs IPC or a store" }
+          ]
+        RUBY
+
+        # The inputs. Shared verbatim by both surfaces -- change a label here
+        # and both the standalone app and the canvas form change with it.
+        FORM = <<~RUBY
+          radio_group :architecture, [
+            "A -- one shared bridge, all sessions inside it",
+            "B -- one bridge process per session"
+          ]
+
+          md "**Why?** One line. Your agent reads this back to you verbatim and reacts to it."
+
+          text_field :rationale, placeholder: "Because..."
+        RUBY
+
+        # The canvas surface says out loud what is happening to the worker's
+        # terminal, because on the canvas there is nothing else to tell you.
+        # The standalone surface does not need it: `run_once!` prints
+        # "Waiting for form submission" in the very terminal that is stuck.
+        BLOCKING_CALLOUT = <<~RUBY
+          callout(variant: :warning, title: "Your agent is frozen right now") do
+            md "This is a **blocking** form. The worker terminal is sitting inside `streamweaver canvas-wait decision` and will not print another line until you press Submit. Look over at it -- nothing is moving."
+          end
+        RUBY
+
+        SUBMIT = <<~RUBY
+          button "Submit decision"
+        RUBY
+
+        # Standalone gets no explicit button: agentic mode (`run_once!`)
+        # renders its own submit control and uses it to unblock.
+        def self.standalone_dsl
+          "#{CONTEXT}\n#{FORM}"
+        end
+
+        def self.canvas_dsl
+          "#{BLOCKING_CALLOUT}\n#{CONTEXT}\n#{FORM}\n#{SUBMIT}"
+        end
+
+        # Mode 1. Blocks; opens the browser; prints the submitted state as
+        # JSON on stdout when the user submits.
+        def self.standalone!
+          dsl = standalone_dsl
+          ::StreamWeaver.app("A real decision") { instance_eval(dsl) }.run_once!
+        end
+
+        # Mode 2. Pushes the same question into a canvas session, for
+        # `streamweaver canvas-wait <session>` to block on.
+        def self.push!(session_name)
+          ::StreamWeaver::Canvas::Client.ensure_bridge_running
+          ::StreamWeaver::Canvas::Client.send_message(
+            ::StreamWeaver::Canvas::Protocol::Messages.create(session_name, layout: :fluid)
+          )
+          ::StreamWeaver::Canvas::Client.send_message(
+            ::StreamWeaver::Canvas::Protocol::Messages.push(session_name, canvas_dsl, source_dir: nil)
+          )
+          puts "Pushed the same decision form to canvas session '#{session_name}'. " \
+               "Block on it with: streamweaver canvas-wait #{session_name}"
+        rescue ::StreamWeaver::Canvas::Client::NotRunningError,
+               ::StreamWeaver::Canvas::Client::ConnectionError => e
+          warn "decision_form: could not reach the canvas bridge (#{e.message}) -- " \
+               "run `streamweaver panel #{session_name}` first"
+        end
+
+        def self.run!(argv = ARGV)
+          if argv.first == 'canvas'
+            push!(argv[1] || 'decision')
+          else
+            standalone!
+          end
+        end
+      end
+    end
+  end
+end
+
+StreamWeaver::University::Demos::DecisionForm.run! if $PROGRAM_NAME == __FILE__

data/lib/stream_weaver/university/demos.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module StreamWeaver
+  module University
+    # The canned artifacts every Getting Started step demonstrates.
+    #
+    # Round-5 UAT (2026-09-03) took ~5 minutes to reach first paint because
+    # each worker session *composed* its demo live, and one of them went
+    # looking for the source repo to do it. Both are now designed out: every
+    # demo ships inside the gem as a finished, runnable file, so the worker's
+    # job is to RUN it and NARRATE it -- never to invent it, and never to
+    # need a checkout.
+    #
+    # `streamweaver university-demo <name>` prints the absolute path of one
+    # of these inside the installed gem, which is what the course prompts
+    # interpolate:
+    #
+    #   ruby "$(streamweaver university-demo dashboard)" dashboard
+    #
+    # Names are normalized (`decision-form` and `decision_form` are the same
+    # demo) so a prompt, a spec and a human can each spell it the way that
+    # reads best where they are.
+    module Demos
+      ROOT = File.expand_path('demos', __dir__)
+
+      # name => path, relative to this file's directory. `doc` deliberately
+      # points at the growing-doc script that already shipped for step 4
+      # rather than a second copy of it -- one artifact, one place it can
+      # rot.
+      PATHS = {
+        'dashboard' => File.join(ROOT, 'dashboard.rb'),
+        'counter' => File.join(ROOT, 'counter.rb'),
+        'decision-form' => File.join(ROOT, 'decision_form.rb'),
+        'doc' => File.expand_path('scripts/growing_doc.rb', __dir__)
+      }.freeze
+
+      NAMES = PATHS.keys.freeze
+
+      # `decision_form`, `decision-form` and `DECISION FORM` all resolve.
+      def self.normalize(name)
+        name.to_s.strip.downcase.tr('_ ', '--')
+      end
+
+      # @return [String, nil] absolute path, or nil for an unknown name
+      def self.path(name)
+        PATHS[normalize(name)]
+      end
+    end
+  end
+end