stream_weaver 0.3.0

data/examples/lazy_fragments_demo.rb

@@ -0,0 +1,151 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Manual-verification harness for LAZY fragments
+# (`fragment ..., defer: true, lazy: true`) -- Turbo's `loading="lazy"`.
+#
+# A lazy fragment is a deferred fragment whose fetch waits until the element is
+# VISIBLE, whatever made it visible: scrolling to it, or a CSS rule flipping an
+# ancestor from display:none to display:block. It fetches exactly once. There is
+# no JavaScript in this file -- the trigger is `hx-trigger="intersect once"`,
+# backed by the browser's own IntersectionObserver.
+#
+#   SW_NO_OPEN=1 STREAMWEAVER_PORT=4641 ruby examples/lazy_fragments_demo.rb
+#
+# Then, with devtools' Network tab open and filtered to `update`:
+#
+#   1. On load, ZERO fetches fire. Every panel below is either off-screen or
+#      CSS-hidden.
+#   2. Hover the card in section 1 and HOLD -> exactly one fetch, and the card
+#      fills in. Move away and hover again -> no second fetch.
+#   3. Scroll to section 2 -> one fetch when the panel enters the viewport.
+#   4. Keep scrolling through section 3 -> one fetch per page, in order, each
+#      page's tail carrying the next page's placeholder. Each fetch re-runs its
+#      ancestors' blocks, so page N takes N * SW_LAZY_DELAY -- the pages getting
+#      progressively slower is the nesting cost, not a stall.
+#   5. Click "Re-render the page" -> every panel returns to its placeholder and
+#      re-arms, but still waits for visibility rather than refetching at once.
+#
+# SW_LAZY_DELAY overrides the per-fragment sleep (default 1.0s), so the
+# placeholder is on screen long enough to see.
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "stream_weaver"
+
+DELAY = (ENV["SW_LAZY_DELAY"] || "1.0").to_f
+PAGES = 4
+
+def slow_work(label)
+  sleep DELAY
+  "#{label} rendered by the server at #{Time.now.strftime('%H:%M:%S.%L')}"
+end
+
+# The Russian doll: each page's content ends with the NEXT page's lazy
+# placeholder, so the pages materialize one at a time as the reader scrolls and
+# the app never has to know how many there are up front.
+#
+# NOTE: page 1 is deliberately lazy here TOO, so this demo's "zero fetches on
+# load" check holds — that exercises the primitive, not the Turbo parity shape.
+# For a real feed, render the current page's rows in the shell and lazy-wrap
+# only the NEXT page — see the streamweaver-way skill's infinite-scroll recipe.
+def scroll_page(number)
+  fragment :"page_#{number}", lazy: true, placeholder: -> { spinner(size: :sm, label: "Loading page #{number}…") } do
+    text slow_work("Page #{number}")
+    div(class: "lazy-demo-filler") { text "(page #{number} content, scroll on)" }
+    scroll_page(number + 1) if number < PAGES
+  end
+end
+
+app "Lazy Fragments" do
+  use_stylesheet <<~CSS
+    /* Section 1 -- the zero-JS hover card. CSS alone flips the popup from
+       display:none to display:block; that is what fires the fetch. */
+    .lazy-demo-hover-host { position: relative; display: inline-block; }
+    .lazy-demo-hover-label {
+      border-bottom: 2px dotted var(--sw-accent, #0d9488);
+      cursor: help;
+      font-weight: 600;
+    }
+    .lazy-demo-hover-card {
+      display: none;
+      position: absolute;
+      top: 1.6rem;
+      left: 0;
+      z-index: 20;
+      min-width: 22rem;
+      padding: 0.75rem 1rem;
+      background: var(--sw-surface, #ffffff);
+      color: var(--sw-text, #111111);
+      border: 1px solid var(--sw-border, #e0e0e0);
+      border-radius: 6px;
+      box-shadow: 0 8px 24px rgba(0, 0, 0, 0.18);
+    }
+    .lazy-demo-hover-host:hover .lazy-demo-hover-card { display: block; }
+
+    /* Pushes the later sections below the fold so scrolling is what reveals
+       them. */
+    .lazy-demo-spacer {
+      height: 90vh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      color: var(--sw-text-dim, #444444);
+      border: 1px dashed var(--sw-border, #e0e0e0);
+      border-radius: 6px;
+      margin: 1.5rem 0;
+    }
+    .lazy-demo-filler {
+      height: 55vh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      color: var(--sw-text-dim, #444444);
+      background: var(--sw-surface-elevated, #f3f3f3);
+      border-radius: 6px;
+      margin: 0.75rem 0;
+    }
+  CSS
+
+  header1 "Lazy fragments"
+  md "Every panel on this page sleeps #{DELAY}s inside its block. **None of them " \
+     "has fetched yet.** A lazy fragment holds its fetch until the element is " \
+     "visible. Open devtools' Network tab, filter to `update`, and watch the " \
+     "count stay at zero until you hover or scroll."
+  text "Shell rendered at #{Time.now.strftime('%H:%M:%S.%L')}"
+
+  header3 "1. Hover card: CSS-hidden, so it never fetches until it is shown"
+  md "The popup below is `display: none` until `:hover` flips it. No JavaScript " \
+     "is involved on either side: CSS makes it visible, the IntersectionObserver " \
+     "notices, htmx fetches once."
+  div(class: "lazy-demo-hover-host") do
+    div(class: "lazy-demo-hover-label") { text "Hover me for the account summary" }
+    div(class: "lazy-demo-hover-card") do
+      fragment :hovercard, lazy: true, placeholder: "Fetching summary…" do
+        text slow_work("Hover card")
+        text "Hover away and back: this does not fetch again."
+      end
+    end
+  end
+
+  header3 "2. Below the fold: fetches when scrolled into the viewport"
+  div(class: "lazy-demo-spacer") { text "↓ keep scrolling ↓" }
+  fragment :below_fold, lazy: true, placeholder: -> { spinner(size: :sm, label: "Waiting to be seen…") } do
+    text slow_work("Below-the-fold panel")
+  end
+
+  header3 "3. Infinite scroll: #{PAGES} pages of Russian dolls"
+  md "Each page's block ends by declaring the next page as its own lazy " \
+     "fragment, so page N+1 does not exist in the DOM until page N has landed " \
+     "and been scrolled past. This is the whole of the pagination logic."
+  scroll_page(1)
+
+  header3 "4. Full re-render: re-arms, but stays lazy"
+  md "This button swaps the whole app container. Every panel above returns to " \
+     "its placeholder and re-arms; the ones still off-screen or hidden wait " \
+     "rather than fetching immediately, which is what makes this different from " \
+     "a plain `defer: true`."
+  button "Re-render the page" do |s|
+    s[:renders] = s[:renders].to_i + 1
+  end
+  text "Full re-renders so far: #{state[:renders].to_i}"
+end.run!

data/examples/my_todos/README.md

@@ -0,0 +1,29 @@
+# My Todos — Turbo Frames parity proof
+
+A StreamWeaver mirror of the learnhotwire.com course's Rails "My Todos" app
+(`github.com/learnhotwire/rails`), building all four Turbo Frames chapter features under one
+rule: **zero custom JavaScript in app code**. No script tags, no inline JS, no hand-written
+Alpine — DSL verbs and CSS only.
+
+This started as a discovery spike (two of the four features didn't work yet); it's now the
+parity proof — all four work end to end on the primitives the spike's findings motivated
+(deferred/lazy fragments, strict-ids keying).
+
+```bash
+SW_NO_OPEN=1 STREAMWEAVER_PORT=4599 ruby examples/my_todos/my_todos.rb
+```
+
+| Route | Feature | How |
+|---|---|---|
+| `/` | Inline editing | Per-row `fragment` + title-only `form_for`, keyed by record id |
+| `/search` | Search | `text_field` auto-submit, in two arrangements (field outside vs. inside the results fragment) — both filter correctly; see the app for the remaining cost trade-off |
+| `/hover-cards` | Hover cards | `fragment(..., lazy: true)` keyed by todo, inside the CSS `:hover` reveal — fetches once, only when hovered |
+| `/infinite-scroll` | Infinite scroll | Russian-doll nested `fragment(..., lazy: true)` — each page declares the next as its own lazy fragment; scrolling triggers the fetch |
+
+Boot with `SW_HOVERCARD_DELAY=1.5` to feel the difference: the shell renders in well under a
+second, and each card pays its 1.5s only once, only if hovered (the equivalent of the chapter's
+`sleep 1.5`).
+
+**Full write-up**: [`docs/research/streamweaver-way-spike-findings.md`](../../docs/research/streamweaver-way-spike-findings.md)
+— per feature, the Rails mechanism with its key elements, the StreamWeaver equivalent, and the
+resolution history (what was missing, what shipped to close it).

data/examples/my_todos/my_todos.rb

@@ -0,0 +1,312 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# My Todos -- StreamWeaver parity PROOF against the learnhotwire.com course's
+# Rails app (github.com/learnhotwire/rails), Turbo Frames chapter.
+#
+# Rule: ZERO custom JavaScript in app code. No script tags, no inline JS, no
+# hand-written Alpine. Only DSL verbs and CSS. All four chapter features --
+# inline editing, search, hover cards, infinite scroll -- work end to end
+# under that rule, on the primitives shipped by this epic (strict-ids keying,
+# deferred/lazy fragments). This app started as a spike (SDRD: build to
+# discover); docs/research/streamweaver-way-spike-findings.md is the full
+# history, now with every recorded stumble resolved or re-filed.
+#
+#   SW_NO_OPEN=1 ruby examples/my_todos/my_todos.rb
+#
+# Findings doc: docs/research/streamweaver-way-spike-findings.md
+
+require_relative '../../lib/stream_weaver'
+require_relative 'store'
+
+# The chapter's hover card is "three lines of CSS, no JavaScript": the frame is
+# display:none until :hover flips it to display:block, and Turbo's
+# loading="lazy" IntersectionObserver fires the fetch at exactly that moment.
+# StreamWeaver gets both halves -- the CSS reveal, plus `fragment(...,
+# lazy: true)`'s own visibility-triggered fetch. See feature 3 below.
+HOVERCARD_CSS = <<~CSS
+  .hovercard { position: relative; display: inline-block; cursor: help; }
+  .hovercard .hovercard-panel {
+    display: none; position: absolute; top: 1.6em; left: 0; z-index: 50;
+    min-width: 15rem;
+  }
+  .hovercard:hover .hovercard-panel { display: block; }
+  .todo-row { padding: 0.15rem 0; }
+  .spike-gap { border-left: 3px solid #d97706; padding-left: 0.75rem; }
+CSS
+
+# Only `:title` -- the StreamWeaver equivalent of the course's narrow
+# `Projects::NamesController` with `params.expect(project: [:name])`. `form_for`
+# coerces exactly the fields listed here and nothing else, so a submit through
+# this form cannot reach `:completed` (app.rb#form_for_coerce). That is the
+# "edit safe" half of the chapter's demo, enforced by construction rather than
+# by remembering to pass the right `url:`.
+TITLE_ONLY = [StreamWeaver::Field.new(:title, :string, {})].freeze
+
+FEATURE_PATHS = {
+  inline_edit: '/',
+  search: '/search',
+  hover_cards: '/hover-cards',
+  infinite_scroll: '/infinite-scroll'
+}.freeze
+
+# routing.md Pitfall 1: every parser branch merges on top of this so a
+# feature-local key set by an earlier request cannot leak into a later view.
+VIEW_RESET = { editing_id: nil }.freeze
+
+# The Russian doll, in Turbo's actual shape: the page the reader is ON renders
+# inline in whatever response we are already writing, and only the NEXT page is
+# wrapped in a lazy fragment. Rails does exactly this -- a frame around the
+# current page's rows, plus a separate `loading: :lazy` frame for `@pagy.next`.
+# Page N+1 does not exist in the DOM -- and never fetches -- until page N has
+# been scrolled past. That recursion is the whole of the pagination logic: no
+# scroll handler, no page counter in state (llms.txt "Recipe: infinite scroll,
+# as nested fragments").
+#
+# Do NOT wrap page `number` itself in the lazy fragment. A deferred block is
+# skipped on the shell render, so that shape serves HTML with zero rows in it;
+# it only LOOKS right because page 1's placeholder lands in the initial viewport
+# and the observer fires immediately.
+def scroll_todos_page(number)
+  TodoStore.page(number).each { |t| text "#{t[:completed] ? '☑' : '☐'}  #{t[:title]}" }
+
+  # The guard is the chapter's `@pagy.next` check: without it Rails renders a
+  # frame with a blank id and the chain dead-ends in "Content missing".
+  nxt = number + 1
+  return if TodoStore.page(nxt).empty?
+
+  fragment(:"todos_page_#{nxt}", lazy: true, placeholder: 'Loading…') do
+    scroll_todos_page(nxt)
+  end
+end
+
+app 'My Todos', layout: :wide do
+  use_stylesheet HOVERCARD_CSS
+
+  route_with(
+    parser: lambda do |path|
+      base = path.to_s.split('?').first
+      feature = FEATURE_PATHS.key(base.empty? ? '/' : base)
+      feature ? VIEW_RESET.merge(feature: feature) : nil
+    end,
+    builder: lambda do |current_state|
+      base = FEATURE_PATHS[current_state[:feature]&.to_sym] || '/'
+      # Search is a GET filter, so the query belongs in the URL -- the same
+      # reason the chapter uses `method: :get` for its search form.
+      query = current_state[:query].to_s
+      if current_state[:feature]&.to_sym == :search && !query.strip.empty?
+        "#{base}?query=#{CGI.escape(query)}"
+      else
+        base
+      end
+    end
+  )
+
+  state[:feature] ||= :inline_edit
+
+  navbar do
+    nav_item 'Inline editing',  href: '/',                active: state[:feature] == :inline_edit
+    nav_item 'Search',          href: '/search',          active: state[:feature] == :search
+    nav_item 'Hover cards',     href: '/hover-cards',     active: state[:feature] == :hover_cards
+    nav_item 'Infinite scroll', href: '/infinite-scroll', active: state[:feature] == :infinite_scroll
+  end
+
+  fragment(:flash) { flash_messages }
+
+  case state[:feature].to_sym
+  # ==========================================================================
+  # 1. Inline editing
+  #
+  # Rails: two `turbo_frame_tag @project, :edit_name` frames -- one wrapping the
+  # display <h1>, one wrapping the edit form -- that swap by matching dom_id.
+  # StreamWeaver: one `fragment` per row, keyed by record id, whose body
+  # branches on `state[:editing_id]`. Every interactive element rendered inside
+  # a fragment is auto-scoped to it (adapter/alpinejs.rb#htmx_attrs), so the
+  # Edit button and the form submit both swap just this row.
+  # ==========================================================================
+  when :inline_edit
+    header1 'My Todos'
+    md 'Click **Edit** on a row: the row becomes a title-only form in place. ' \
+       'The completed checkbox is rendered *outside* the form -- watch that it ' \
+       'survives the save.'
+
+    TodoStore.all.first(6).each do |todo|
+      fragment("todo-#{todo[:id]}") do
+        div class: 'todo-row' do
+          if state[:editing_id].to_s == todo[:id]
+            text "#{todo[:completed] ? '☑' : '☐'}  (editing)"
+            form_for(
+              store: TodoStore,
+              fields: TITLE_ONLY,
+              name: :"todo_#{todo[:id]}_form",
+              record: todo,
+              on_success: ->(_id) { state[:editing_id] = nil }
+            ) { submit_label 'Save' }
+            button('Cancel', style: :secondary, key: "cancel-#{todo[:id]}") do |s|
+              s[:editing_id] = nil
+            end
+          else
+            hstack spacing: :sm do
+              text "#{todo[:completed] ? '☑' : '☐'}  #{todo[:title]}"
+              button('Edit', style: :secondary, key: "edit-#{todo[:id]}") do |s|
+                s[:editing_id] = todo[:id]
+              end
+            end
+          end
+        end
+      end
+    end
+
+  # ==========================================================================
+  # 2. Search
+  #
+  # Rails: the form sits OUTSIDE the results frame and names it with
+  # `data: {turbo_frame: :todos}`; a Stimulus `autosubmit` controller turns
+  # keystrokes into `requestSubmit()`.
+  # StreamWeaver: `text_field` auto-submits on input with no controller at all.
+  # Both arrangements below now filter correctly -- the fragment-scoped param
+  # merge bug the spike found is fixed (InteractionRunner merges posted state
+  # before every scoped rebuild; see spec/live_input_fragment_wiring_spec.rb
+  # and spec/deferred_fragments_spec.rb's regression coverage). What's left is
+  # a genuine trade-off, not a break: shown in both arrangements below.
+  # ==========================================================================
+  when :search
+    header1 'Search'
+    alert(variant: :success) do
+      text 'WORKS -- submit-as-you-type is free in both arrangements below, ' \
+           'with no custom JavaScript.'
+      text 'A is the Rails layout (field outside the results): swaps the whole ' \
+           'app body, so it costs more bytes but the field never re-renders ' \
+           'itself. B moves the field inside the fragment for a scoped morph ' \
+           '-- fewer bytes, and focus/caret survive the morph -- at the cost ' \
+           'of the field re-rendering itself on every keystroke.'
+    end
+
+    header3 'A. Rails arrangement -- field outside the results region'
+    text_field :query, placeholder: 'Filter todos…', label: 'Search (outside)'
+    fragment(:search_results_outside) do
+      results = TodoStore.search(state[:query])
+      text "#{results.length} of #{TodoStore.all.length} todos"
+      results.first(8).each { |t| text "• #{t[:title]}" }
+    end
+
+    div(style: 'height:24px') { }
+
+    header3 'B. StreamWeaver arrangement -- field inside the results fragment'
+    fragment(:search_results_inside) do
+      text_field :query_inside, placeholder: 'Filter todos…', label: 'Search (inside)'
+      results = TodoStore.search(state[:query_inside])
+      text "#{results.length} of #{TodoStore.all.length} todos"
+      results.first(8).each { |t| text "• #{t[:title]}" }
+    end
+
+    div class: 'spike-gap' do
+      header3 'The remaining trade-off'
+      md 'Both arrangements filter correctly now. What StreamWeaver still ' \
+         'lacks is a `data-turbo-frame` equivalent: `text_field` never passes ' \
+         '`sw_updates:` to `htmx_attrs`, so an input can only target its own ' \
+         'enclosing fragment (B) or `#app-container` (A) -- it cannot name a ' \
+         'sibling fragment from outside it. `text_field :query, updates: ' \
+         ':results` is accepted and silently ignored (a real gap, tracked, ' \
+         'not fixed by this story). Until that lands, A pays the whole-body ' \
+         'swap and B pays the self-re-render -- pick per feature which cost ' \
+         'you\'d rather carry.'
+    end
+
+  # ==========================================================================
+  # 3. Hover cards
+  #
+  # Rails: `turbo_frame_tag todo.user, :hovercard, src: ..., loading: :lazy`
+  # inside a `div.hovercard`. CSS reveals it; `loading=lazy` means the fetch
+  # only happens because the reveal made it visible.
+  # StreamWeaver: `fragment(..., lazy: true)` is the same two-part interlock --
+  # CSS does the revealing, `hx-trigger="intersect once"` does the fetching,
+  # and it never fires while the card is `display: none`.
+  # ==========================================================================
+  when :hover_cards
+    header1 'Hover cards'
+    alert(variant: :success) do
+      text 'WORKS -- CSS reveals the card, and revealing it is what fires the ' \
+           'fetch. Nothing has fetched until the pointer arrives.'
+      text 'Boot with SW_HOVERCARD_DELAY=1.5 and hover a name: the shell above ' \
+           'already rendered; only the hovered card pays the 1.5s, once.'
+    end
+
+    TodoStore.all.first(6).each do |todo|
+      user = UserStore.find(todo[:user_id])
+      div class: 'todo-row' do
+        hstack spacing: :sm do
+          text "#{todo[:completed] ? '☑' : '☐'}  #{todo[:title]} —"
+          # Keyed by the todo, not the user: the chapter (38:52) demos two todos
+          # sharing an assignee emitting the same frame id twice. The fragment
+          # name below carries that same rule -- key by what is unique per
+          # position on the page (the todo), not by what the content is about
+          # (the user) -- per llms.txt "Interactive IDs and keying".
+          div class: 'hovercard' do
+            text user[:name]
+            div class: 'hovercard-panel' do
+              fragment(:"hovercard_#{todo[:id]}", lazy: true, placeholder: 'Loading…') do
+                UserStore.delay
+                card do
+                  header3 user[:name]
+                  text user[:role]
+                  text "#{TodoStore.all.count { |t| t[:user_id] == user[:id] }} todos"
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+
+    div class: 'spike-gap' do
+      header3 'How it works now'
+      md 'Each card is its own `fragment(:"hovercard_#{todo[:id]}", lazy: ' \
+         'true)`. The CSS wrapper hides it (`display: none`), so the fragment' \
+         '\'s IntersectionObserver never fires -- no request goes out. Hovering ' \
+         'flips the CSS to `display: block`, which is what makes the fragment ' \
+         'visible, which is what fires the fetch. It fetches exactly once: ' \
+         'hover away and back, and the content that already landed stays put, ' \
+         'no second request. Six cards, zero eager cost.'
+    end
+
+  # ==========================================================================
+  # 4. Infinite scroll
+  #
+  # Rails: nested "Russian doll" frames -- each response renders the CURRENT
+  # page's rows inline and appends page N+1's placeholder frame, already
+  # `loading: :lazy`, so scrolling to the bottom fetches the next page and
+  # nothing is ever removed from the DOM.
+  # StreamWeaver: the same shape, with `fragment(..., lazy: true)` around the
+  # NEXT page only -- see `scroll_todos_page` above. No button, no scroll
+  # listener, no page counter in state: scrolling to page N's bottom is what
+  # makes page N+1's fragment visible, which is what fetches it.
+  # ==========================================================================
+  when :infinite_scroll
+    header1 'Infinite scroll'
+    alert(variant: :success) do
+      text 'WORKS -- scroll-to-load-more, nested "Russian doll" fragments, ' \
+           'each fetch sends exactly its own page.'
+    end
+
+    scroll_todos_page(1)
+
+    div class: 'spike-gap' do
+      header3 'How it works now'
+      md 'The page you are ON renders inline; only the NEXT page is wrapped in ' \
+         '`fragment(:"todos_page_N+1", lazy: true)`. So this shell already ' \
+         'carries page 1\'s ten rows plus exactly one placeholder — view source ' \
+         'and the rows are really there, which is the same progressive-' \
+         'enhancement guarantee Rails gives you. Page N+1 is not in the DOM -- ' \
+         'and has not fetched -- until scrolling reveals its placeholder. Each ' \
+         'response carries only that page\'s rows (`TodoStore.page(n)`), not ' \
+         'everything loaded so far: a constant per-page payload where the old ' \
+         'click-driven version grew with every click. Wrapping page N itself in ' \
+         'the lazy fragment is the tempting shape and it is wrong -- the block ' \
+         'is skipped on the shell render, so the served HTML has no rows at ' \
+         'all, and it only looks right because page 1\'s placeholder starts in ' \
+         'the viewport. See findings doc, feature 4 resolution for the measured ' \
+         'byte counts.'
+    end
+  end
+end.run!

data/examples/my_todos/store.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+# In-memory stores for the My Todos parity spike.
+#
+# Mirrors the learnhotwire.com course app's `Todo` / `User` models closely
+# enough to exercise the same four Turbo Frames chapter features:
+# `Todo.search(query)` (including the blank guard the chapter demos as a live
+# bug), a `user_id` assignee for hover cards, and enough rows to paginate.
+
+module UserStore
+  USERS = {
+    'u1' => { id: 'u1', name: 'Ada Lovelace',  role: 'Engineering', joined: '2024-03-11' },
+    'u2' => { id: 'u2', name: 'Alan Turing',   role: 'Research',    joined: '2023-11-02' },
+    'u3' => { id: 'u3', name: 'Grace Hopper',  role: 'Platform',    joined: '2025-01-20' }
+  }.freeze
+
+  def self.all = USERS.values
+  def self.find(id) = USERS[id]
+
+  # Deliberately slow, to make "was this fetched lazily or eagerly?" observable
+  # the way the chapter's `sleep 1.5` does in the Rails app. Off by default so
+  # the spike app stays usable; set SW_HOVERCARD_DELAY=1.5 to feel the cost of
+  # rendering every card eagerly.
+  def self.delay
+    seconds = ENV['SW_HOVERCARD_DELAY'].to_f
+    sleep(seconds) if seconds.positive?
+  end
+end
+
+module TodoStore
+  PER_PAGE = 10
+
+  TITLES = [
+    'Buy milk', 'Ship the parity spike', 'Review the fragment docs',
+    'Book the offsite', 'Refactor the store protocol', 'Write release notes',
+    'Answer the support thread', 'Update the changelog', 'Prune stale branches',
+    'Draft the design memo', 'Pair on the routing bug', 'Buy coffee beans'
+  ].freeze
+
+  @todos = 60.times.map do |i|
+    {
+      id: (i + 1).to_s,
+      title: "#{TITLES[i % TITLES.length]} ##{i + 1}",
+      completed: (i % 5).zero?,
+      user_id: "u#{(i % 3) + 1}"
+    }
+  end
+
+  class << self
+    def all = @todos
+    def find(id) = @todos.find { |t| t[:id] == id.to_s }
+
+    def create(attrs)
+      id = ((@todos.map { |t| t[:id].to_i }.max || 0) + 1).to_s
+      @todos << { id: id, completed: false, user_id: 'u1', **attrs }
+      id
+    end
+
+    def update(id, attrs)
+      todo = find(id) or return false
+      todo.merge!(attrs)
+      true
+    end
+
+    def destroy(id)
+      @todos.reject! { |t| t[:id] == id.to_s }
+      true
+    end
+
+    # Mirrors the course's `Todo.search`, blank guard included. The chapter
+    # demos the missing-guard version as a live bug: clear the box and the
+    # whole list vanishes because the LIKE runs against nil.
+    def search(query)
+      return all if query.to_s.strip.empty?
+      needle = query.to_s.downcase
+      all.select { |t| t[:title].downcase.include?(needle) }
+    end
+
+    # A single page's slice -- the Russian-doll infinite-scroll recipe fetches
+    # one page per request, not everything-so-far. See
+    # docs/research/streamweaver-way-spike-findings.md, feature 4 resolution.
+    # An empty return is the recursion's own termination signal -- see
+    # scroll_todos_page in my_todos.rb.
+    def page(number) = all.drop(([number.to_i, 1].max - 1) * PER_PAGE).first(PER_PAGE)
+  end
+end

data/examples/opal/reactive_demo.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+# Demo: ReactiveState — watch, on_start, and computed/derived state
+# Build: bundle exec streamweaver opal-build examples/opal/reactive_demo.rb --output dist/reactive_demo
+# Open: open dist/reactive_demo/index.html
+
+app "Reactive Demo" do
+  # ── S8: Loan Calculator (derived state, no useMemo needed) ──────────
+  card do
+    header2 "Loan Calculator"
+    text_field :principal, label: "Loan Amount ($)", type: :number
+    text_field :rate,      label: "Annual Rate (%)", type: :number
+    text_field :term,      label: "Term (months)",   type: :number
+
+    p       = state[:principal].to_f
+    r       = state[:rate].to_f / 100.0 / 12.0
+    n       = state[:term].to_f
+    payment = (r > 0 && n > 0) ? (p * r * (1 + r)**n) / ((1 + r)**n - 1) : 0.0
+
+    card do
+      header3 "Monthly Payment"
+      text "$#{"%.2f" % payment}"
+    end
+  end
+
+  div(style: "height: 32px")
+
+  # ── S5: Watch — filter list reacts to search ──────────────────────
+  card do
+    header2 "Search Filter (watch)"
+    watch(:search_query) do |query|
+      all = %w[Apple Banana Blueberry Cherry Cranberry Date Elderberry Fig Grape]
+      state[:filtered] = query.to_s.empty? ? all : all.select { |f| f.downcase.include?(query.downcase) }
+    end
+
+    text_field :search_query, placeholder: "Type to filter fruit..."
+
+    div do
+      (state[:filtered] || %w[Apple Banana Blueberry Cherry Cranberry Date Elderberry Fig Grape]).each do |fruit|
+        text fruit
+      end
+    end
+  end
+
+  div(style: "height: 32px")
+
+  # ── S6: on_start — runs once after first render ───────────────────
+  card do
+    header2 "on_start Demo"
+    md "**on_start** fires exactly once after the first render — like `useEffect(fn, [])` in React. Watch for the 'Loading...' state to briefly appear, then swap to real data after 800ms."
+    state[:items] = state[:items] || []
+    on_start do
+      after(0.8) { state[:items] = ["Loaded Item A", "Loaded Item B", "Loaded Item C"] }
+    end
+
+    if state[:items].empty?
+      text "Loading..."
+    else
+      badge "Loaded via on_start", color: :green
+      state[:items].each { |item| text item }
+    end
+  end
+end

data/examples/opal/scenarios/s1_counter.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+# S1: Counter with Derived Display
+# React equivalent: useState + useMemo
+# StreamWeaver: inline computation, zero annotation
+
+app "S1 — Counter with Derived Display" do
+  button("Increment") { state[:count] = state[:count].to_i + 1 }
+  button("Reset") { state[:count] = 0 }
+
+  card do
+    text "Count: #{state[:count].to_i}"
+    text "Is even: #{state[:count].to_i.even?}"
+    text "Double: #{state[:count].to_i * 2}"
+  end
+end

data/examples/opal/scenarios/s2_search_filter.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+# S2: Search-Filtered List
+# React equivalent: useMemo with [search] dependency array
+# StreamWeaver: inline computation — the filter IS the render
+
+app "S2 — Search-Filtered List" do
+  text_field :search, placeholder: "Filter fruits..."
+
+  fruits = %w[Apple Apricot Avocado Banana Blueberry Cherry Cranberry Date Elderberry Fig Grape Kiwi]
+  query  = state[:search].to_s.downcase
+  items  = query.empty? ? fruits : fruits.select { |f| f.downcase.include?(query) }
+
+  text "#{items.size} of #{fruits.size} shown"
+  div do
+    items.each { |fruit| text fruit }
+  end
+end