stream_weaver 0.3.0

data/examples/tutorials/tutorial_content.rb

@@ -0,0 +1,1082 @@
+# frozen_string_literal: true
+
+# THE SHARED OUTLINE for "Build My Todos: the StreamWeaver Way".
+#
+# This file is the single source of truth for the tutorial's content. It is
+# rendered TWICE, and neither rendering owns the words:
+#
+#   examples/tutorials/streamweaver_way_tutorial.rb  -> :doc-theme StreamWeaver app
+#   docs/tutorials/the-streamweaver-way.md           -> markdown twin (GitHub, llms.txt)
+#
+# The markdown twin is generated by `bin/render_tutorial_markdown` and checked
+# in so GitHub readers get it without running anything.
+# `spec/tutorial_twins_spec.rb` fails if the checked-in file drifts from a fresh
+# render, so the two can't silently diverge.
+#
+# Block vocabulary (deliberately tiny -- both renderers must support all of it):
+#
+#   [:md,      "markdown prose"]
+#   [:code,    "ruby", "source"]
+#   [:callout, :variant, "Title", "markdown body"]
+#   [:table,   ["Header", ...], [["cell", ...], ...]]
+
+module TutorialContent
+  EYEBROW = "StreamWeaver · Tutorial"
+  TITLE = "Build My Todos: the StreamWeaver Way"
+  PILLS = [
+    { text: "Zero custom JavaScript", variant: :good },
+    "Four features, one file",
+    "Rebuilt from examples/my_todos"
+  ].freeze
+
+  LEAD = <<~'MD'
+    A guided rebuild of the four Turbo Frames features from the
+    [learnhotwire.com](https://learnhotwire.com) course, in StreamWeaver, with
+    no script tag, no inline JavaScript, and no hand-written Alpine anywhere in
+    app code. You will write about 120 lines of Ruby and get inline editing,
+    submit-as-you-type search, lazy hover cards, and Russian-doll infinite
+    scroll.
+
+    The `streamweaver-way` skill tells you **what** the conventions are. This
+    tutorial tells you **why** each one exists, in the order you'd hit them if
+    you built the app yourself. Every step names the law it obeys, the gotcha it
+    avoids, and — where one was actually measured — the number that makes the
+    case.
+  MD
+
+  TWIN_NOTE = <<~'MD'
+    **These two documents are twins.** This tutorial exists as a StreamWeaver
+    doc-app (`examples/tutorials/streamweaver_way_tutorial.rb`) and as markdown
+    (`docs/tutorials/the-streamweaver-way.md`). Both are rendered from one
+    outline, `examples/tutorials/tutorial_content.rb`, and a spec fails if the
+    checked-in markdown drifts from it. Edit the outline, never a twin.
+  MD
+
+  SECTIONS = [
+    # ========================================================================
+    {
+      id: "why",
+      number: "01",
+      title: "Why this tutorial exists",
+      blocks: [
+        [:md, <<~'MD'],
+          Most frontend libraries ask nothing of your backend. That is a design
+          goal for them and a tax on you: htmx will happily swap any HTML you
+          send it, but it has no opinion about what your fragment ids should be,
+          so you invent a convention, then you invent the JavaScript that
+          upholds it. Hotwire's insight was that a framework which owns *both*
+          sides of the wire can just decide — `dom_id` on the server, matching
+          `turbo_frame_tag` in the view, and the swap needs no glue code because
+          both halves already agree.
+
+          StreamWeaver owns both sides too. The DSL that renders the page also
+          mints the interactive ids, signs the endpoints, and emits the `hx-*`
+          attributes. So the conventions in this tutorial are not style advice
+          you could reasonably ignore — they are the framework. Follow them and
+          you write no JavaScript. Fight them and you write a lot.
+        MD
+
+        [:md, <<~'MD'],
+          ### What you'll build
+
+          The learnhotwire.com course's Turbo Frames chapter builds four
+          features against a Rails app. We rebuild all four:
+
+          1. **Inline editing** — click Edit and the row becomes a form in place
+          2. **Scoped live search** — results filter as you type, no controller
+          3. **Lazy hover cards** — six cards that cost nothing until hovered
+          4. **Russian-doll infinite scroll** — pages load as you reach them
+
+          One file. One in-memory store. The finished app is
+          `examples/my_todos/` in this repo, which is where every code sample
+          below comes from — these are extracts, not illustrations.
+        MD
+
+        [:callout, :decision, "The rule that makes this interesting",
+         "**Zero custom JavaScript in app code.** No `<script>` tags, no inline " \
+         "`onclick`, no hand-written Alpine, no raw `hx-*` attributes, no " \
+         "reaching into `lib/stream_weaver/adapter/*`. Only DSL verbs and CSS. " \
+         "If a feature needs JavaScript, that is a finding about the framework, " \
+         "not a licence to write some. All four features below clear the bar."],
+
+        [:md, <<~'MD'],
+          ### How to read this
+
+          Each feature section has the same four beats, in this order:
+
+          **Why** — the problem the feature has, stated before any code.
+          **Build it** — the code, with the Rails mechanism it mirrors.
+          **The law it obeys** — which of the six laws is doing the work.
+          **The gotcha it avoids** — what breaks if you write the tempting shape.
+
+          Where a number was measured on the real app, it is quoted with its
+          source. Nothing here is estimated.
+        MD
+
+        [:md, TWIN_NOTE]
+      ]
+    },
+
+    # ========================================================================
+    {
+      id: "laws",
+      number: "02",
+      title: "The six laws, and why they're laws",
+      blocks: [
+        [:md, <<~'MD'],
+          Read these once now. They will not mean much yet — that is fine, each
+          one gets earned by a feature below. Come back after section 08 and
+          they will read as obvious.
+        MD
+
+        [:table,
+         ["#", "Law", "What it costs you to ignore"],
+         [
+           ["1", "Key by what is unique per *position* on the page, not by what the content is *about*.",
+            "Two rows sharing an assignee collide silently — hovering the second shows the first one's data."],
+           ["2", "Deferred over hand-rolled timers.",
+            "A 1.5s region holds the whole shell hostage, or you write a polling loop and a loading flag."],
+           ["3", "Lazy means visible.",
+            "Sixty hover cards fetch on page load for a reader who hovers none of them."],
+           ["4", "Dev loud, prod self-heals.",
+            "Either your users see \"Content missing\", or you see nothing and debug blind."],
+           ["5", "State your intent in DSL verbs. Zero custom JavaScript is the default, not an aspiration.",
+            "You hand-roll the glue the framework already emits, and it drifts out of sync with the server."],
+           ["6", "Run every feature through three design filters: is it findable and digestible; is it zero-friction with a real perk; is the *default* path the correct path.",
+            "You ship something that demos well and changes nothing."]
+         ]],
+
+        [:md, <<~'MD'],
+          Law 1 is the one that bites hardest, so it is worth a sentence more.
+          StreamWeaver derives an id for every interactive element from its label
+          plus its block source location, with `-dup-N` auto-disambiguation on
+          repeats — so you rarely pass anything. But a derived id is
+          *position*-stable, not *content*-stable: insert or delete an earlier
+          row and every later suffix shifts. That is fine for a static form and
+          fatal for a list you filter, sort, or delete from. Reach for `key:`
+          exactly when identity must outlive reordering.
+
+          Law 6's third filter is the *why* under the other five: **the default
+          path must be the correct path.** Design for the developer you have, not
+          the one who remembers to pass the right option. Law 1's auto-keying is
+          that filter in code — because the default already disambiguates, the
+          silent-wrong-callback bug can't happen to someone who never read law 1.
+          Every law below is really this one, applied to a different primitive.
+        MD
+      ]
+    },
+
+    # ========================================================================
+    {
+      id: "store",
+      number: "03",
+      title: "Start with the store",
+      blocks: [
+        [:md, <<~'MD'],
+          Before any feature, the data. A **store** in StreamWeaver is any object
+          that answers five methods: `all`, `find(id)`, `create(attrs)`,
+          `update(id, attrs)`, and `destroy(id)`. There is no base class to
+          inherit and no schema to declare. A plain module over an Array is
+          enough to build all four features — which is the point: the framework
+          asks for a protocol, not a dependency.
+
+          Two extra methods show up later (`search` in section 05, `page` in
+          section 08); each is introduced by the feature that needs it, so you
+          can see exactly what the feature costs.
+        MD
+
+        [:code, "ruby", <<~'RUBY'],
+          require 'stream_weaver'
+
+          module UserStore
+            USERS = {
+              'u1' => { id: 'u1', name: 'Ada Lovelace', role: 'Engineering' },
+              'u2' => { id: 'u2', name: 'Alan Turing',  role: 'Research' },
+              'u3' => { id: 'u3', name: 'Grace Hopper', role: 'Platform' }
+            }.freeze
+
+            def self.find(id) = USERS[id]
+
+            # Deliberately slow, opt-in, so "was this fetched lazily or eagerly?"
+            # is observable. The course's Rails app uses a literal `sleep 1.5`
+            # here for the same reason. Section 07 turns it on.
+            def self.delay
+              seconds = ENV['SW_HOVERCARD_DELAY'].to_f
+              sleep(seconds) if seconds.positive?
+            end
+          end
+
+          module TodoStore
+            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
+
+            # Sixty rows: enough to paginate, enough that eager hover cards hurt.
+            @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
+            end
+          end
+        RUBY
+
+        [:callout, :info, "Inside this repo",
+         "The samples say `require 'stream_weaver'`, which is what a reader with " \
+         "the gem installed writes. Working inside the StreamWeaver checkout " \
+         "instead? Use `require_relative '../../lib/stream_weaver'` — that is what " \
+         "`examples/my_todos/my_todos.rb` does."]
+      ]
+    },
+
+    # ========================================================================
+    {
+      id: "inline-editing",
+      number: "04",
+      title: "Feature 1 — Inline editing",
+      blocks: [
+        [:md, <<~'MD'],
+          ### Why
+
+          Clicking Edit on a row should turn *that row* into a form, leave the
+          other 59 rows alone, and — this is the part that is easy to get wrong —
+          make it structurally impossible for the edit form to modify a field it
+          doesn't display. The course demos this as "edit safe": the form shows
+          only the title, so submitting it must not be able to flip the
+          completed checkbox, even for someone who crafts the request by hand.
+
+          Rails does this with two `turbo_frame_tag` frames sharing a `dom_id`,
+          plus a deliberately narrow controller
+          (`params.expect(project: [:name])`). Two mechanisms, held in agreement
+          by you remembering to keep them in agreement.
+
+          ### Build it
+
+          StreamWeaver needs one mechanism for the swap and gets the safety for
+          free. `fragment(name) { ... }` marks a region that interactions
+          *inside it* swap on their own, rather than swapping the whole app
+          container. Everything interactive rendered inside a fragment is
+          auto-scoped to it — so the Edit button and the form's submit both
+          swap just this row, without either of them naming the row.
+        MD
+
+        [:code, "ruby", <<~'RUBY'],
+          # Declare ONLY the editable field. `form_for` coerces exactly the fields
+          # listed here and nothing else, so a submit through this form cannot
+          # reach :completed. That is the "edit safe" guarantee, enforced by
+          # construction rather than by remembering to narrow a controller.
+          TITLE_ONLY = [StreamWeaver::Field.new(:title, :string, {})].freeze
+
+          app 'My Todos' do
+            TodoStore.all.first(6).each do |todo|
+              fragment("todo-#{todo[:id]}") 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.run!
+        RUBY
+
+        [:md, <<~'MD'],
+          Read the shape rather than the lines. There is one fragment per row,
+          named by record id. Inside it, a branch on `state[:editing_id]`: either
+          the display row with an Edit button, or the form with a Cancel button.
+          Clicking Edit sets `editing_id` and re-renders — but only this
+          fragment, because the button was rendered inside it. There is no
+          "which frame should this target?" decision to get wrong, because the
+          answer is always "the one you're inside".
+
+          `form_for` is the record-bound form primitive: it seeds fields from the
+          record, infers create-vs-update from record identity, coerces and
+          validates on submit, calls `store.update`, flashes, and redirects.
+          `on_success:` is where the row goes back to display mode.
+        MD
+
+        [:md, "### The law it obeys"],
+
+        [:md, <<~'MD'],
+          **Law 1 — key by position.** Look at the two buttons: both carry
+          `key:`. That is not decoration. Without it, their ids are derived from
+          label plus source location, which for six identical Edit buttons in one
+          loop means `edit`, `edit-dup-1`, `edit-dup-2`, and so on — stable only
+          as long as the list is. Delete row 2 and every later suffix shifts by
+          one, so the callback fires for the wrong todo. `key: "edit-#{todo[:id]}"`
+          ties the id to the record, and the record survives deletion of its
+          neighbours.
+
+          **Law 5 — state your intent in DSL verbs.** There is no JavaScript here
+          and there is also no `hx-target`. The scoping is a consequence of where
+          the code sits, which is the omakase bargain: give up the ability to
+          target an arbitrary frame, get correctness by default.
+        MD
+
+        [:md, "### The gotcha it avoids"],
+
+        [:callout, :warning, "Per-row buttons must carry `key:`",
+         "This is the single most common way to ship a silently-wrong list. The " \
+         "symptom is not an error — it's clicking Edit on row 3 and watching row " \
+         "2 open. If you want the framework to shout instead of guess, turn on " \
+         "`strict_ids` (section 09), which promotes a derived-id collision from a " \
+         "warning to a hard failure in development and test."],
+
+        [:md, <<~'MD'],
+          Two smaller ones, both real, both cosmetic-or-worse:
+
+          - **`on_success:` is required** for a standalone `form_for`. Inside a
+            `resource` block there is a post-submit transition to fall back to;
+            standalone there isn't, so you must say what happens next.
+          - **The flash noun is derived by stripping `_form` from `name:`**, so
+            `:todo_1_form` flashes "Todo_1 updated." Cosmetic, known, unfixed.
+            Mentioned here so you don't go looking for the bug you introduced.
+        MD
+
+        [:md, "### The number"],
+
+        [:table,
+         ["Interaction", "Bytes on the wire"],
+         [
+           ["Click Edit (row becomes a form)", "1,327"],
+           ["Submit the form (title renamed, `☑` preserved)", "806"],
+           ["Full page load of the same view, for comparison", "108,792"]
+         ]],
+
+        [:md, <<~'MD'],
+          Two orders of magnitude, and the reason is entirely structural: the
+          response is one row, because the interaction happened inside one row's
+          fragment. Source: `docs/research/streamweaver-way-spike-findings.md`.
+        MD
+      ]
+    },
+
+    # ========================================================================
+    {
+      id: "search",
+      number: "05",
+      title: "Feature 2 — Scoped live search",
+      blocks: [
+        [:md, <<~'MD'],
+          ### Why
+
+          Filter-as-you-type is the feature everyone reaches for JavaScript to
+          build: an input listener, a debounce, a fetch, a DOM update, and a
+          loading state. In the course's Rails app it is a form outside the
+          results frame, named with `data: {turbo_frame: :todos}`, plus a
+          Stimulus `autosubmit` controller that turns keystrokes into
+          `requestSubmit()`.
+
+          ### Build it
+
+          `text_field` auto-submits on input. There is no controller, no
+          debounce code, and no wiring — that behaviour is the verb. The only
+          decision left is **where the field lives**, and unlike most of this
+          tutorial, that one is a genuine trade-off rather than a right answer.
+
+          First, the store gains one method:
+        MD
+
+        [:code, "ruby", <<~'RUBY'],
+          # The blank guard is load-bearing -- see the gotcha below.
+          def TodoStore.search(query)
+            return all if query.to_s.strip.empty?
+            needle = query.to_s.downcase
+            all.select { |t| t[:title].downcase.include?(needle) }
+          end
+        RUBY
+
+        [:md, "Then the view. Put the field **inside** the results fragment:"],
+
+        [:code, "ruby", <<~'RUBY'],
+          app 'Search' do
+            fragment(:search_results) do
+              text_field :query, placeholder: 'Filter todos…', label: 'Search'
+              results = TodoStore.search(state[:query])
+              text "#{results.length} of #{TodoStore.all.length} todos"
+              results.first(8).each { |t| text "• #{t[:title]}" }
+            end
+          end.run!
+        RUBY
+
+        [:md, <<~'MD'],
+          Five lines, and it filters as you type. The field is inside the
+          fragment, so its auto-submit is scoped to the fragment, so the response
+          is just the results region — and because StreamWeaver morphs rather
+          than replaces, focus and caret position survive the swap.
+        MD
+
+        [:md, "### The law it obeys"],
+
+        [:md, <<~'MD'],
+          **Law 5 — zero custom JavaScript is the default.** The Rails version
+          needs a Stimulus controller because a plain form doesn't submit on
+          input; the StreamWeaver version needs nothing because `text_field`
+          already does. When you find yourself about to write JavaScript in a
+          StreamWeaver app, the odds strongly favour a verb you haven't met yet.
+        MD
+
+        [:md, "### The gotcha it avoids"],
+
+        [:callout, :error, "`text_field :query, updates: :results` is accepted and ignored",
+         "This is the natural transliteration of Rails' `data: {turbo_frame: " \
+         ":todos}` and it looks completely right. It is silently a no-op: " \
+         "`updates:` is read only by `button` and `clickable`. There is no " \
+         "`data-turbo-frame` equivalent for inputs yet, so **an input can target " \
+         "only its own enclosing fragment or `#app-container`** — it cannot name " \
+         "a sibling fragment from outside it. A field placed outside the results " \
+         "fragment still filters correctly; it just swaps the entire app body on " \
+         "every keystroke."],
+
+        [:md, <<~'MD'],
+          That constraint is what makes the field's placement a trade-off rather
+          than a preference:
+        MD
+
+        [:table,
+         ["Arrangement", "Swap target", "Response size", "Cost"],
+         [
+           ["A — field outside the results fragment (the Rails shape)", "`#app-container`",
+            "2,123 bytes", "Whole app body every keystroke; field never re-renders itself"],
+           ["B — field inside the results fragment (shown above)", "`#sw-frag-search-results`",
+            "800 bytes", "Field re-renders itself every keystroke; focus and caret survive"]
+         ]],
+
+        [:md, <<~'MD'],
+          Prefer B unless you specifically need the input never to re-render.
+          Source for both measurements:
+          `docs/research/streamweaver-way-spike-findings.md`.
+
+          Two more, quickly:
+
+          - **Guard the blank query in the store.** Without `return all if
+            query.to_s.strip.empty?`, clearing the box makes the whole list
+            vanish. The course demos exactly this as a live bug, because in Rails
+            the `LIKE` runs against `nil`.
+          - **Search is a GET filter**, so if you want a result set to be
+            shareable, put the query in the URL with `route_with`. The finished
+            `examples/my_todos/` app does this.
+        MD
+      ]
+    },
+
+    # ========================================================================
+    {
+      id: "timings",
+      number: "06",
+      title: "Interlude — the three fragment timings",
+      blocks: [
+        [:md, <<~'MD'],
+          You have now used `fragment` twice, both times in its plain form: the
+          block runs during the page render, inline, like any other DSL call.
+          That is one of three timings, and the other two are what make features
+          3 and 4 possible.
+        MD
+
+        [:table,
+         ["Form", "When the block runs", "Use for"],
+         [
+           ["`fragment(:n) { }`", "Inline, with the page", "Scoping a swap to one region"],
+           ["`fragment(:n, defer: true) { }`", "Right after page load", "Slow regions, off the critical path"],
+           ["`fragment(:n, lazy: true) { }`", "The first time it is *visible*", "Hover cards, infinite scroll, tab panels"]
+         ]],
+
+        [:md, <<~'MD'],
+          `defer: true` is **Law 2 — deferred over hand-rolled timers.** A slow
+          region ships a placeholder with the page and fetches its own content
+          immediately afterward, over the same signed endpoint every in-fragment
+          interaction already uses. No new route, no new authorization path, and
+          nothing for you to write. Measured on a page with one `sleep 1.5`
+          fragment:
+        MD
+
+        [:table,
+         ["Request", "Time"],
+         [
+           ["Initial `GET` (was 1.5s before deferring)", "0.018s"],
+           ["The fragment's own fetch, afterward", "1.508s"]
+         ]],
+
+        [:md, <<~'MD'],
+          The work didn't get cheaper — it got moved off the path the reader is
+          waiting on. Source: `CHANGELOG.md`, deferred fragments entry.
+
+          `lazy: true` is **Law 3 — lazy means visible**, and it implies
+          `defer: true`, so you only ever write one option. It holds the fetch
+          until the fragment is actually visible: scrolled into the viewport, or
+          CSS flipping an ancestor out of `display: none`. Two guarantees follow,
+          and both are load-bearing for what comes next.
+
+          **A hidden fragment never fetches while it stays hidden.** That is what
+          makes a hover card cost literally nothing on page load.
+
+          **It fetches exactly once.** The content lands in the DOM and stays, so
+          hiding and re-showing the region doesn't refetch it.
+
+          Under the hood the placeholder carries `hx-trigger="intersect once"`.
+          htmx's other visibility trigger, `revealed`, reads
+          `getBoundingClientRect()` and therefore counts a `display: none`
+          element as revealed — which would fetch every hidden fragment on load
+          and destroy the first guarantee. That choice is documented in
+          `docs/research/2026-08-22-lazy-fragments-trigger-decision.md`.
+        MD
+
+        [:callout, :warning, "Three rules for every deferred or lazy fragment",
+         "**The block is skipped on the shell render**, so anything it *registers* " \
+         "— actions, timers — isn't registered until the fetch lands. Keep " \
+         "registration outside deferred blocks.\n\n" \
+         "**A named-action button (`button 'X', action: :foo`) inside one does " \
+         "not fire.** Its token is minted outside the session's action manifest. " \
+         "Use a block button (`button('X') { |s| ... }`), which dispatches by id " \
+         "and is unaffected.\n\n" \
+         "**Each fetch re-runs its ancestors' blocks.** Nest for staging, not to " \
+         "split one expensive block into cheaper pieces."],
+
+        [:md, <<~'MD'],
+          One practical note that costs people an afternoon: **give the
+          placeholder height.** The observer watches the placeholder wrapper, and
+          a zero-area element never intersects anything, so a lazy fragment with
+          an empty placeholder simply never fires. `placeholder:` takes nothing
+          (a small spinner), a String (rendered as text), or a Proc (run as DSL).
+        MD
+      ]
+    },
+
+    # ========================================================================
+    {
+      id: "hover-cards",
+      number: "07",
+      title: "Feature 3 — Lazy hover cards",
+      blocks: [
+        [:md, <<~'MD'],
+          ### Why
+
+          Each todo has an assignee. Hovering the assignee's name should reveal a
+          card with their details — details expensive enough to fetch that you
+          would not want to fetch sixty of them for a reader who hovers none.
+
+          This is the feature that most clearly separates "it works" from "it is
+          right". A version that renders every card eagerly and hides them with
+          CSS *looks* identical. The difference is only visible in the network
+          tab, and in how long the page took to arrive.
+
+          ### Build it
+
+          Three lines of CSS and one option. The two halves interlock: CSS does
+          the revealing, and revealing is what does the fetching.
+        MD
+
+        [:code, "ruby", <<~'RUBY'],
+          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; }
+          CSS
+
+          app 'Hover cards' do
+            use_stylesheet HOVERCARD_CSS
+
+            TodoStore.all.first(6).each do |todo|
+              user = UserStore.find(todo[:user_id])
+              hstack spacing: :sm do
+                text "#{todo[:completed] ? '☑' : '☐'}  #{todo[:title]} —"
+                div class: 'hovercard' do
+                  text user[:name]
+                  div class: 'hovercard-panel' do
+                    # Keyed by the TODO, not the user. See the gotcha below.
+                    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.run!
+        RUBY
+
+        [:md, <<~'MD'],
+          Boot it with `SW_HOVERCARD_DELAY=1.5 ruby my_todos.rb` and hover a
+          name. The page was already there; the card you hovered pays 1.5
+          seconds, once, and the five you didn't hover pay nothing at all — ever,
+          if you never hover them.
+
+          To check laziness yourself, count the fragments that have *not* fetched
+          yet, in the browser console:
+          `document.querySelectorAll('.sw-fragment-lazy').length`.
+        MD
+
+        [:md, "### The law it obeys"],
+
+        [:md, <<~'MD'],
+          **Law 3 — lazy means visible**, in its purest form. Nothing on this
+          page fetches anything until the pointer arrives, and the mechanism that
+          hides the card is the same mechanism that gates the fetch. You did not
+          write a hover handler, because there is nothing for a hover handler to
+          do: the CSS already reacted, and the observer already noticed.
+
+          **Law 1 — key by position** is here too, and it is the reason the
+          fragment is named `hovercard_#{todo[:id]}` and not `hovercard_#{user[:id]}`.
+        MD
+
+        [:md, "### The gotcha it avoids"],
+
+        [:callout, :error, "Key by the todo, not the user",
+         "Sixty todos share three assignees. Key the fragment by the user and " \
+         "twenty todos emit the same fragment name — hovering the second one " \
+         "shows the first one's card, with no error anywhere. The rule states " \
+         "itself once you've been bitten: key by what is unique per *position* on " \
+         "the page (the todo), never by what the row happens to *display* (the " \
+         "assignee). The course demos this exact collision in Rails, which is how " \
+         "we knew to look for it."],
+
+        [:callout, :warning, "`display: none`, never `visibility: hidden` or `opacity: 0`",
+         "This one is subtle enough to survive review. `visibility: hidden` and " \
+         "`opacity: 0` both leave the element laid out and intersecting, so the " \
+         "IntersectionObserver counts it as visible and **every card fetches " \
+         "eagerly on page load** — the exact cost you added `lazy: true` to " \
+         "avoid. The page looks right. It just does all the work anyway."],
+
+        [:md, "### The number"],
+
+        [:table,
+         ["Page load with `SW_HOVERCARD_DELAY=1.5`", "Time"],
+         [
+           ["Eager — every card rendered in the list request (6 × 1.5s)", "9.151s"],
+           ["Lazy — shell only, cards not yet fetched", "0.085s"]
+         ]],
+
+        [:md, <<~'MD'],
+          On six rows that is an ugly page. On the full sixty it is ninety
+          seconds of work to render a page nobody may hover at all. Source:
+          `docs/research/streamweaver-way-spike-findings.md`.
+        MD
+      ]
+    },
+
+    # ========================================================================
+    {
+      id: "infinite-scroll",
+      number: "08",
+      title: "Feature 4 — Russian-doll infinite scroll",
+      blocks: [
+        [:md, <<~'MD'],
+          ### Why
+
+          Sixty rows, ten at a time, loading as the reader reaches them — with no
+          scroll handler, no page counter in state, and no "Load more" button.
+
+          Nesting lazy fragments gets you this for free, but only in one
+          particular shape, and the wrong shape is the more tempting one. This
+          section is the reason the tutorial is worth reading rather than
+          skimming.
+
+          ### Build it
+
+          The store gains one method, and it returns **one page's slice** — never
+          everything-so-far:
+        MD
+
+        [:code, "ruby", <<~'RUBY'],
+          module TodoStore
+            PER_PAGE = 10
+            def self.page(number)
+              all.drop(([number.to_i, 1].max - 1) * PER_PAGE).first(PER_PAGE)
+            end
+          end
+        RUBY
+
+        [:md, <<~'MD'],
+          Now the recursion. Read this one slowly — the whole feature is four
+          lines of logic, and which lines are inside the lazy fragment is the
+          entire design:
+        MD
+
+        [:code, "ruby", <<~'RUBY'],
+          def scroll_todos_page(number)
+            # THIS page renders NOW, inline, in whatever response we are already
+            # writing. It is not deferred and it is not lazy.
+            TodoStore.page(number).each do |t|
+              text "#{t[:completed] ? '☑' : '☐'}  #{t[:title]}"
+            end
+
+            # Only the NEXT page is lazy. The guard is load-bearing: without it
+            # the chain dead-ends in an empty fragment that fetches nothing.
+            nxt = number + 1
+            return if TodoStore.page(nxt).empty?
+
+            fragment(:"todos_page_#{nxt}", lazy: true, placeholder: 'Loading…') do
+              scroll_todos_page(nxt)   # the recursion lives INSIDE the lazy fragment
+            end
+          end
+
+          app('Infinite scroll') { scroll_todos_page(1) }.run!
+        RUBY
+
+        [:md, <<~'MD'],
+          Trace one scroll. The shell response contains page 1's ten rows, really
+          there in the HTML, plus exactly one placeholder for page 2. Page 2 does
+          not exist in the DOM. Scroll to the bottom of page 1 and the placeholder
+          enters the viewport, which is what fires its fetch. That fetch runs
+          `scroll_todos_page(2)`, which writes page 2's ten rows and one
+          placeholder for page 3. And so on, until `TodoStore.page(nxt)` comes
+          back empty and the chain simply stops.
+
+          That recursion is the whole of the pagination logic. There is no state
+          to keep, because "which page am I on" is answered by which fragment is
+          currently executing.
+        MD
+
+        [:md, "### The gotcha it avoids"],
+
+        [:callout, :error, "Do not wrap page N itself in the lazy fragment",
+         "The tempting shape is `fragment(:\"page_\#{number}\", lazy: true) { rows; " \
+         "recurse }`, called with `1` — one uniform function, each page wrapped " \
+         "the same way. It is wrong, and it is wrong in a way that passes a " \
+         "casual test.\n\n" \
+         "A deferred block **is skipped on the shell render**. So the served HTML " \
+         "contains no rows at all — just a placeholder. It looks like it works " \
+         "only because page 1's placeholder sits in the initial viewport, and a " \
+         "lazy fragment that is already visible fetches immediately. In a browser " \
+         "you see rows appear and conclude it's fine. `curl` the same URL and you " \
+         "get an empty shell."],
+
+        [:md, <<~'MD'],
+          This is not hypothetical. It is the bug a clean-room agent hit while
+          rebuilding these features from the conventions alone: the app rendered
+          correctly in the browser, every feature demonstrably worked, and the
+          served HTML had zero rows in it. Nothing in the running app said so.
+          The failure only surfaced when someone read the response instead of the
+          screen.
+
+          Rendering the current page inline and lazying only the next one is also
+          exactly what Turbo does — a frame around the current page's rows, plus a
+          separate `loading: :lazy` frame for the next page. It is what keeps the
+          shell honest for a crawler, for a reader with JavaScript disabled, and
+          for anyone who ever reads the served HTML. The pretty version fails all
+          three silently.
+        MD
+
+        [:callout, :tip, "How to check your own version",
+         "`curl -s http://127.0.0.1:PORT/infinite-scroll | grep -c 'Buy milk'` — if " \
+         "that returns 0 while the browser shows rows, you wrote the tempting " \
+         "shape. The screen is not the artifact; the response is."],
+
+        [:md, <<~'MD'],
+          Two smaller ones:
+
+          - **Return one page's slice, not everything-so-far.** Each response
+            should be a constant size. If your payloads grow per page, you are
+            re-sending rows the reader already has.
+          - **Nested fragment ids are `parent--child`.** Page 2's fragment is
+            declared beside page 1's rows, so it is `sw-frag-todos-page-2`; page
+            3's is declared inside page 2's block, giving
+            `sw-frag-todos-page-2--todos-page-3`. Useful when you are reading the
+            DOM to work out what fetched what.
+          - **Inside a tab, the lazy fragment goes *inside* a `tab` block**, never
+            beside one at the top level of a `tabs` block — a non-tab child there
+            shifts every panel index. Route tabs (`tabs :view, url: true`) render
+            inactive panels as `display: none`, so a lazy fragment in one
+            correctly waits until that tab is opened.
+        MD
+
+        [:md, "### The number"],
+
+        [:md, <<~'MD'],
+          This is the clearest measurement in the whole tutorial, because it
+          changes the *shape* of the cost rather than its size. Before nested
+          fragments existed, "Load more" re-rendered and re-sent every row loaded
+          so far:
+        MD
+
+        [:table,
+         ["Old: click-driven, O(n) per click", "Payload", "Rows in payload"],
+         [
+           ["Click 1", "1,248 bytes", "20"],
+           ["Click 2", "1,603 bytes", "30"],
+           ["Click 3", "1,957 bytes", "40"]
+         ]],
+
+        [:md, "With nested lazy fragments, each fetch carries only its own page:"],
+
+        [:table,
+         ["New: Russian-doll, O(1) per page", "Payload"],
+         [
+           ["Page 2", "809 bytes"],
+           ["Page 3", "877 bytes"],
+           ["Page 4", "934 bytes"],
+           ["Page 5", "993 bytes"],
+           ["Page 6", "1,060 bytes"],
+           ["Page 7 (terminal — chain ends)", "371 bytes"]
+         ]],
+
+        [:md, <<~'MD'],
+          The remaining growth is not rows. It is the nested id string getting
+          longer — `todos-page-2--todos-page-3--todos-page-4` and so on — which
+          is a few bytes per level, not a page of content. O(n) per click and
+          O(n²) over a session became O(1) per page. Source:
+          `docs/research/streamweaver-way-spike-findings.md`.
+        MD
+      ]
+    },
+
+    # ========================================================================
+    {
+      id: "scoreboard",
+      number: "09",
+      title: "What you built",
+      blocks: [
+        [:md, <<~'MD'],
+          Four features from a Turbo Frames course, rebuilt with no script tag,
+          no inline JavaScript, and no hand-written Alpine. Here is the whole
+          thing on one line each:
+        MD
+
+        [:table,
+         ["Feature", "The verb that did the work", "The law", "The measured win"],
+         [
+           ["Inline editing", "`fragment` per row + `form_for` + `key:`", "1, 5", "806-byte save vs 108,792-byte page"],
+           ["Scoped live search", "`text_field` inside a `fragment`", "5", "800 bytes scoped vs 2,123 whole-body"],
+           ["Lazy hover cards", "`fragment(..., lazy: true)` + 3 lines of CSS", "1, 3", "0.085s shell vs 9.151s eager"],
+           ["Infinite scroll", "nested `fragment(..., lazy: true)`", "2, 3", "O(1) per page vs O(n) per click"]
+         ]],
+
+        [:md, <<~'MD'],
+          ### Assembling the four into one app
+
+          Each section above showed its feature as its own `app` block, so you
+          could run it in isolation while building it. Putting all four in one
+          file needs one more thing: a way to say which feature the reader is
+          looking at. That is `route_with` plus a `case`, and it is the last new
+          verb in the tutorial.
+
+          `route_with` takes a **parser** (URL path in, state out) and a
+          **builder** (state in, URL path out). Between them the browser's
+          address bar and `state[:feature]` stay in agreement, so every feature
+          is a real, bookmarkable URL rather than a tab index.
+        MD
+
+        [:code, "ruby", <<~'RUBY'],
+          FEATURE_PATHS = {
+            inline_edit: '/', search: '/search',
+            hover_cards: '/hover-cards', infinite_scroll: '/infinite-scroll'
+          }.freeze
+
+          # routing.md Pitfall 1: `route_with` MERGES GET state rather than
+          # replacing it, so every parser branch merges on top of this. Without
+          # it, an `editing_id` set on the inline-edit page leaks into the search
+          # page and quietly opens a form there.
+          VIEW_RESET = { editing_id: nil }.freeze
+
+          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.
+                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
+            when :inline_edit     then inline_edit_view    # section 04's body
+            when :search          then search_view         # section 05's body
+            when :hover_cards     then hover_cards_view    # section 07's body
+            when :infinite_scroll then scroll_todos_page(1) # section 08's recursion
+            end
+          end.run!
+        RUBY
+
+        [:callout, :warning, "An incomplete route table fails silently, on both sides",
+         "`route_with` merges GET state rather than replacing it, and a `case` " \
+         "with a missing `when` renders nothing rather than raising. Add a feature " \
+         "and forget its `FEATURE_PATHS` entry and you get a blank page with a 200 " \
+         "status. `docs/routing.md`'s Common Pitfalls section is worth reading " \
+         "before any app with more than a couple of routes — this is Pitfall 1 and " \
+         "it has cost real time."],
+
+        [:md, <<~'MD'],
+          ### Turn on `strict_ids` before you ship
+
+          Everything in section 04 about keying is enforceable. `strict_ids`
+          promotes a derived-id collision from a warning to a hard failure — it
+          raises in development and test, and degrades to a warning in production,
+          because a live page shouldn't return a 500 over an id the framework
+          already disambiguated for it.
+        MD
+
+        [:code, "ruby", <<~'RUBY'],
+          StreamWeaver::App.new('My App', strict_ids: true) { ... }   # per app
+          StreamWeaver.strict_ids = true                              # global
+          SW_STRICT_IDS=1 ruby my_todos.rb                            # env, e.g. in CI
+        RUBY
+
+        [:md, <<~'MD'],
+          ### When something is wired wrong
+
+          **Law 4 — dev loud, prod self-heals.** A stale action token gets a 409
+          plus a full-container re-render that is byte-for-byte identical in
+          production: the user never sees an error, the page just heals. In
+          development only, the same response prepends a dismissible
+          `.sw-dev-fallback` overlay naming the stale target and the likely cause.
+
+          This is a deliberate inversion of Hotwire's "Content missing", which
+          shows the failure to the user and tells the developer nothing useful.
+          Keep the debugging signal; don't charge the reader for it. **If you see
+          that overlay, your wiring is wrong — don't style it away.**
+        MD
+
+        [:md, <<~'MD'],
+          ### The anti-pattern list
+
+          Each of these has bitten someone, which is why it is written down:
+        MD
+
+        [:table,
+         ["Don't", "Do"],
+         [
+           ["`defer { ... }`", "`fragment(:name, defer: true)` — the bare verb raises and names the real one"],
+           ["`every(...)` to refresh a slow region", "`fragment(..., defer: true)` (Law 2)"],
+           ["A named-action button inside a deferred/lazy fragment", "A block button — `button('X') { |s| ... }`"],
+           ["`key: i` (positional index)", "`key: record.id` — index is the identity reordering destroys"],
+           ["`text \"**bold**\"`", "`md \"**bold**\"` — `text` does not render markdown"],
+           ["`spacer` / `divider`", "They don't exist. `div(style: 'height:24px')`"],
+           ["`<button onclick=\"location.href=...\">`", "`link_to` / `nav_item` with a real `href`"],
+           ["Assuming port 4567", "Read the URL StreamWeaver prints — it finds a free port"]
+         ]]
+      ]
+    },
+
+    # ========================================================================
+    {
+      id: "next",
+      number: "10",
+      title: "Where to go next",
+      blocks: [
+        [:md, <<~'MD'],
+          **Run the finished app.** `examples/my_todos/` is all four features in
+          one file, annotated with the Rails mechanism each mirrors:
+
+          ```
+          SW_NO_OPEN=1 ruby examples/my_todos/my_todos.rb
+          SW_HOVERCARD_DELAY=1.5 SW_NO_OPEN=1 ruby examples/my_todos/my_todos.rb
+          ```
+
+          The second one is worth the extra keystrokes. Feeling a card take 1.5
+          seconds *only when you hover it* is the moment Law 3 stops being a
+          sentence.
+
+          **Get the conventions on tap.** The `streamweaver-way` skill is the
+          prescriptive twin of this tutorial: the same six laws and the same four
+          recipes, written for an agent that needs the answer rather than the
+          reasoning. Install it with `streamweaver setup`.
+        MD
+
+        [:table,
+         ["Where to look", "For"],
+         [
+           ["`llms.txt` (aliased `docs/for_llms.md`)", "The full DSL reference — every verb, every option"],
+           ["`docs/resource-dsl.md`", "`resource` + `form_for`, complete reference"],
+           ["`docs/routing.md`", "**Read Common Pitfalls** before any app with more than a couple of routes"],
+           ["`docs/crud-patterns.md`", "Create/edit/delete modals, URL-addressable edit pages, store adapters"],
+           ["`docs/components_reference.md`", "Every component's API"]
+         ]],
+
+        [:md, <<~'MD'],
+          **Read the why.** These exist for when you are extending a primitive
+          rather than using one:
+        MD
+
+        [:table,
+         ["Document", "What it answers"],
+         [
+           ["`docs/research/streamweaver-way-spike-findings.md`", "What broke building these four features, and how each break was closed — the source of every gotcha above"],
+           ["`docs/research/2026-08-22-lazy-fragments-trigger-decision.md`", "Why `intersect once` and not `revealed`"],
+           ["`docs/research/2026-08-22-learnhotwire-syllabus-coverage.md`", "Hotwire feature-by-feature coverage: what exists, what's next"],
+           ["`docs/streamweaver-frontend-vision.md`", "The strategic thesis — why owning both sides of the wire is the whole bet"]
+         ]],
+
+        [:callout, :info, "One closing thought",
+         "Every feature in this tutorial got shorter than its Rails equivalent, " \
+         "and none of them got shorter by being cleverer. They got shorter because " \
+         "the framework already knew something — which fragment you're inside, " \
+         "which record a row is for, whether a region is visible — that the other " \
+         "arrangement makes you say out loud. That is what an omakase layer buys, " \
+         "and it is the only thing it buys. Everything else in this document is a " \
+         "consequence."]
+      ]
+    }
+  ].freeze
+
+  # The TOC both renderers use.
+  def self.toc = SECTIONS.map { |s| { id: s[:id], label: s[:title] } }
+end