stream_weaver 0.3.0

data/docs/tutorials/the-streamweaver-way.md

@@ -0,0 +1,882 @@
+<!-- GENERATED FILE -- do not edit directly. -->
+<!-- Source outline: examples/tutorials/tutorial_content.rb -->
+<!-- Regenerate:     ruby examples/tutorials/render_markdown.rb -->
+
+# Build My Todos: the StreamWeaver Way
+
+*StreamWeaver · Tutorial* · Zero custom JavaScript · Four features, one file · Rebuilt from examples/my_todos
+
+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.
+
+## Contents
+
+- [01. Why this tutorial exists](#why)
+- [02. The six laws, and why they're laws](#laws)
+- [03. Start with the store](#store)
+- [04. Feature 1 — Inline editing](#inline-editing)
+- [05. Feature 2 — Scoped live search](#search)
+- [06. Interlude — the three fragment timings](#timings)
+- [07. Feature 3 — Lazy hover cards](#hover-cards)
+- [08. Feature 4 — Russian-doll infinite scroll](#infinite-scroll)
+- [09. What you built](#scoreboard)
+- [10. Where to go next](#next)
+
+<a id="why"></a>
+
+## 01. Why this tutorial exists
+
+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.
+
+### 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.
+
+> [!IMPORTANT]
+> **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.
+
+### 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.
+
+**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.
+
+<a id="laws"></a>
+
+## 02. The six laws, and why they're laws
+
+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.
+
+| # | 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. |
+
+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.
+
+<a id="store"></a>
+
+## 03. Start with the store
+
+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.
+
+```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
+```
+
+> [!NOTE]
+> **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.
+
+<a id="inline-editing"></a>
+
+## 04. Feature 1 — Inline editing
+
+### 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.
+
+```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!
+```
+
+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.
+
+### The law it obeys
+
+**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.
+
+### The gotcha it avoids
+
+> [!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.
+
+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.
+
+### The number
+
+| 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 |
+
+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`.
+
+<a id="search"></a>
+
+## 05. Feature 2 — Scoped live search
+
+### 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:
+
+```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
+```
+
+Then the view. Put the field **inside** the results fragment:
+
+```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!
+```
+
+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.
+
+### The law it obeys
+
+**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.
+
+### The gotcha it avoids
+
+> [!CAUTION]
+> **`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.
+
+That constraint is what makes the field's placement a trade-off rather
+than a preference:
+
+| 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 |
+
+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.
+
+<a id="timings"></a>
+
+## 06. Interlude — the three fragment timings
+
+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.
+
+| 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 |
+
+`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:
+
+| Request | Time |
+|---|---|
+| Initial `GET` (was 1.5s before deferring) | 0.018s |
+| The fragment's own fetch, afterward | 1.508s |
+
+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`.
+
+> [!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.
+>
+> **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.
+>
+> **Each fetch re-runs its ancestors' blocks.** Nest for staging, not to split one expensive block into cheaper pieces.
+
+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).
+
+<a id="hover-cards"></a>
+
+## 07. Feature 3 — Lazy hover cards
+
+### 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.
+
+```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!
+```
+
+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`.
+
+### The law it obeys
+
+**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]}`.
+
+### The gotcha it avoids
+
+> [!CAUTION]
+> **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.
+
+> [!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.
+
+### The number
+
+| 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 |
+
+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`.
+
+<a id="infinite-scroll"></a>
+
+## 08. Feature 4 — Russian-doll infinite scroll
+
+### 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:
+
+```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
+```
+
+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:
+
+```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!
+```
+
+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.
+
+### The gotcha it avoids
+
+> [!CAUTION]
+> **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.
+>
+> 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.
+
+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.
+
+> [!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.
+
+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.
+
+### The number
+
+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:
+
+| 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 |
+
+With nested lazy fragments, each fetch carries only its own page:
+
+| 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 |
+
+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`.
+
+<a id="scoreboard"></a>
+
+## 09. What you built
+
+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:
+
+| 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 |
+
+### 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.
+
+```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!
+```
+
+> [!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.
+
+### 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.
+
+```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
+```
+
+### 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.**
+
+### The anti-pattern list
+
+Each of these has bitten someone, which is why it is written down:
+
+| 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 |
+
+<a id="next"></a>
+
+## 10. Where to go next
+
+**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`.
+
+| 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 |
+
+**Read the why.** These exist for when you are extending a primitive
+rather than using one:
+
+| 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 |
+
+> [!NOTE]
+> **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.