stream_weaver 0.3.0

data/llms.txt

@@ -0,0 +1,1269 @@
+# StreamWeaver - LLM Quick Reference
+
+StreamWeaver is a Ruby DSL for building reactive web UIs with minimal code. Think "Streamlit for Ruby".
+
+## CRITICAL: Auto-Port and Auto-Browser
+
+**StreamWeaver automatically:**
+1. **Finds a free port** - Does NOT use a fixed port. Scans from 4567 upward.
+2. **Opens the browser** - You do NOT need to open it manually.
+3. **Prints the URL to stdout** - Read terminal output to get the actual port.
+
+**NEVER assume port 4567.** The actual port is printed to stdout:
+```
+╔═══════════════════════════════════════════════════════════════╗
+║              StreamWeaver App Running                          ║
+╚═══════════════════════════════════════════════════════════════╝
+
+  🌐  http://localhost:4572    ← READ THIS, don't assume 4567!
+  📱  My App
+
+  Press Ctrl+C to stop
+```
+
+**For AI agents:** Parse the terminal output after `ruby app.rb` to find the actual URL.
+
+**Finding the port an agent is already driving (do this, not a second boot):** Run the app as a
+background task, then read its own stdout for the `http://127.0.0.1:<port>` line the startup
+banner prints — that line IS the port, there is nothing to discover beyond reading it. **NEVER
+boot a second instance of the same app to "find" a port** — StreamWeaver's own port-scan means a
+second launch just finds the NEXT free port and starts a duplicate, orphaned server; it never
+tells you what the first one is running on. If the banner didn't reach your captured output
+(e.g. you weren't backgrounding the process yet), find the live port with
+`lsof -i :4567-4620 -sTCP:LISTEN` against the ALREADY-running process rather than sleeping on
+the log or launching another one.
+
+## THE KEY INSIGHT
+
+**Your Ruby DSL block RE-EXECUTES on every user interaction.**
+
+- User types in a field → entire block runs again with updated `state[:field]`
+- User clicks a button → callback runs, then entire block runs again
+- This creates reactive UI without you writing any event handling code
+
+```ruby
+app "Counter" do
+  # This ENTIRE block runs on EVERY interaction
+  state[:count] ||= 0
+
+  text "Count: #{state[:count]}"
+
+  button "+" do |s|
+    s[:count] += 1   # Modifies state, triggers re-run
+  end
+end.run!
+```
+
+## The StreamWeaver Way
+
+StreamWeaver is an omakase layer, not a widget kit — backend and frontend were designed as one system, so these conventions are the framework, not style advice. Follow them and you write no JavaScript. Six laws, each linked to the section that details it:
+
+1. **Key by what is unique per position on the page, not by what the content is about.** Auto-derived ids are position-stable, not content-stable — reach for `key: record_id` when identity must outlive reordering, filtering, or deletion. → [Interactive IDs and keying](#interactive-ids-and-keying)
+2. **Deferred over hand-rolled timers.** A slow region gets `fragment(..., defer: true)`, never an `every()` poll. → [Deferred Fragments](#deferred-fragments-fragment--defer-true)
+3. **Lazy means visible.** Hidden content costs nothing until CSS or scroll reveals it, and it fetches exactly once. → [Lazy Fragments](#lazy-fragments-fragment--lazy-true)
+4. **Dev loud, prod self-heals.** The deliberate inversion of Hotwire's "content missing": keep the debugging signal, don't charge the user for it. → [Dev Loud, Prod Self-Heal](#dev-loud-prod-self-heal-stale-action-fallback)
+5. **State your intent in DSL verbs.** Zero custom JavaScript is the default, not an aspiration — no script tags, no raw `hx-*` from app code, no adapter internals. → [Repo Conventions](#repo-conventions-anti-patterns-that-cause-churn)
+6. **Trilaws as design filters.** Matt (findable/digestible), Forrest (zero friction + real perks), Gloria (the default path must be the correct path). Law 1's auto-keying is Gloria's Law in code: the default already disambiguates, so the silent-wrong-callback bug cannot happen.
+
+The `streamweaver-way` skill ([Agent Skills](#agent-skills-install-these-before-hand-rolling-the-above)) teaches these with the four benchmark recipes — inline editing, scoped live search, lazy hover cards, Russian-doll infinite scroll. `examples/my_todos/` runs all four in one app with zero custom JavaScript.
+
+**Tutorial — `docs/tutorials/the-streamweaver-way.md`.** "Build My Todos: the StreamWeaver Way" rebuilds those same four features step by step, why-first: each step names the law it obeys, the gotcha it avoids, and the measured number where one exists (deferring a 1.5s region: 0.018s shell vs 1.508s fragment fetch; hover cards: 0.085s shell vs 9.151s eager; search: 800-byte scoped morph vs 2,123-byte whole-body swap; infinite scroll: O(1) per page vs O(n) per click). The skill *prescribes*; the tutorial *narrates* — read the tutorial when you want the reasoning, the skill when you want the answer. Runs as a `:doc`-theme app too: `SW_NO_OPEN=1 ruby examples/tutorials/streamweaver_way_tutorial.rb`.
+
+## Minimal Example
+
+```ruby
+require 'stream_weaver'
+
+app "Hello" do
+  text_field :name, placeholder: "Your name"
+
+  if state[:name].to_s.strip != ""
+    text "Hello, #{state[:name]}!"
+  end
+end.run!
+```
+
+Run: `ruby hello.rb` → browser opens automatically.
+
+## State
+
+State is a hash. Access with `state[:key]`. Components auto-bind to keys.
+
+```ruby
+text_field :email           # state[:email] = user input
+checkbox :agree, "I agree"  # state[:agree] = true/false
+select :color, ["Red", "Blue"]  # state[:color] = selected value
+
+# Read state anywhere
+if state[:agree]
+  text "You agreed!"
+end
+```
+
+## Essential Components
+
+### Input
+```ruby
+text_field :name, placeholder: "Name"
+text_area :bio, rows: 5
+text_area :paste, transient: true           # excluded from session cookie (for large paste areas)
+checkbox :key, "Label"                      # state[:key] = true/false
+select :role, ["Admin", "User"], default: "User"
+radio_group :choice, ["A", "B", "C"]
+date_field :due_on, label: "Due date"       # native <input type=date>; state[:due_on] = "YYYY-MM-DD" (ISO 8601)
+```
+
+### IMPORTANT: Form Input Auto-Submit Behavior
+
+**By default, ALL input components auto-submit on change.** Every keystroke, checkbox click, or selection triggers a server round-trip and page re-render. This is intentional for reactive UIs.
+
+**ANTI-PATTERN — text_area / text_field / select paired with a button:**
+```ruby
+# WRONG — every keystroke redaws the UI, textarea resize is lost, select jumps
+text_area :prompt, rows: 4
+select :choice, options
+button "Submit" do |s| ... end
+
+# CORRECT — no round-trips until button click
+text_area :prompt, rows: 4, submit: false
+select :choice, options, submit: false
+button "Submit" do |s| ... end
+```
+Any `text_field`, `text_area`, or `select` that feeds into a button action **must** use `submit: false`. Without it, typing causes full page re-renders, textarea resize resets, and the UI flickers on every keystroke.
+
+**For "form-like" behavior** (collect multiple inputs, then act):
+
+Option 1: Use `submit: false` on individual inputs:
+```ruby
+# Checkboxes that don't auto-submit - user can check multiple before action
+items.each do |item|
+  checkbox :"select_#{item.id}", item.name, submit: false
+end
+
+button "Process Selected" do |state|
+  items.each do |item|
+    if state[:"select_#{item.id}"]
+      # act on selected items
+    end
+  end
+end
+```
+
+Option 2: Use `form` block for deferred submission:
+```ruby
+form :my_form do
+  text_field :name
+  select :status, %w[active paused]
+  submit "Save" do |form_values|
+    # All values submitted together
+  end
+  cancel "Reset"
+end
+```
+
+**When to use which:**
+- Default (auto-submit): Filters, toggles, instant feedback
+- `submit: false`: Multi-select lists with action buttons
+- `form` block: Traditional forms with Save/Cancel
+
+### Checkbox Group (Multi-Select with Select All/None)
+```ruby
+# For batch selection (emails, files, items to process)
+checkbox_group :selected_items, select_all: "Select All", select_none: "Clear" do
+  items.each do |item|
+    item item.id do          # Use `item value do`, NOT `checkbox`
+      text item.name
+      # Any components can be nested here
+    end
+  end
+end
+# state[:selected_items] = ["id1", "id3", ...] (array of selected IDs)
+```
+
+**CRITICAL:** Inside `checkbox_group`, ONLY `item` elements are allowed at the top level. You CANNOT use `text`, `header`, `div`, or other components directly inside `checkbox_group` - they must be nested inside an `item` block. If you need section headers, put them OUTSIDE the checkbox_group.
+
+### Display
+```ruby
+text "Plain text with #{state[:value]}"
+md "**Bold** and *italic* markdown"
+header "Section Title"        # h2
+header1 "Page Title"          # h1
+header3 "Subsection"          # h3
+
+# Mermaid diagrams — Mermaid.js loaded lazily from CDN
+mermaid "graph LR; A-->B"                          # basic
+mermaid diagram_code, zoom: true                   # zoom/pan controls
+mermaid diagram_code, compact: true                # reduced padding (use inside card)
+mermaid diagram_code, layout: :elk                 # ELK layout engine for dense graphs
+mermaid diagram_code, theme_vars: { primaryColor: "#6366f1" }  # custom colors
+```
+
+Every diagram, regardless of `zoom:`, also gets an "expand to full screen" button (no opt-in) — a wide diagram's fixed-px labels shrink to fit whatever doc column width it renders in no matter how the layout is tuned, so this is the actual fix for an illegible complex diagram, not just a bigger version of `zoom: true`.
+
+### CRITICAL: `text` Does NOT Render Markdown
+
+**`text` is literal — markdown syntax appears as raw characters.**
+
+```ruby
+# WRONG — renders as: **Select the article PDF:**  (asterisks visible)
+text "**Select the article PDF:**"
+
+# CORRECT — renders as bold text
+md "**Select the article PDF:**"
+
+# BETTER — use semantic headers for section labels
+header3 "Select the article PDF:"
+header4 "What do you want to know?"
+```
+
+**Rule:** Never put `**`, `*`, `#`, or other markdown in a `text` call. Use `md` if you need inline formatting, or `header1`–`header6` for structural labels.
+
+### Tables
+```ruby
+# Basic - explicit headers/rows
+table headers: ["Name", "Size"], rows: [["app.rb", "12kb"]]
+
+# Array of hashes - auto-infer headers
+table [{ name: "Alice", age: 30 }, { name: "Bob", age: 25 }]
+
+# Column DSL with formatters
+table users do
+  column :name
+  column :balance, format: :currency, align: :right
+  column :joined, format: :date
+  column(:active) { |u| u.active? ? "Yes" : "No" }
+end
+
+# Interactive features
+table data, sortable: true, sticky_header: true, striped: true
+
+# Markdown links in cells
+table [{ issue: "[JIRA-123](https://jira.example.com)" }], markdown: true
+
+# Data sources
+table data: :users           # From state
+table file: "data.yaml"      # From file
+
+# Cell style escape hatches: column style: (String|Proc), id_style: true/false, table-level id_column:
+table headers: [...], rows: [...], id_column: false   # disable the default first-column accent
+```
+
+Formatters: `:date`, `:datetime`, `:currency`, `:number`, `:percent`
+
+### Buttons
+```ruby
+button "Click Me" do |s|
+  s[:clicked] = true
+  s[:count] = (s[:count] || 0) + 1
+end
+
+button "Secondary", style: :secondary do |s|
+  # ...
+end
+
+# Client-side clipboard copy -- no server round-trip
+copy_button "Copy summary", text: report_text
+
+# Syntax-highlighted code, with an optional copy affordance (off by default)
+code_block source, lang: "ruby", copy: true
+```
+
+### Interactive IDs and keying
+
+Every interactive component needs an id the server can dispatch on. StreamWeaver
+derives one for you; you only reach for `key:`/`id:` when you want identity to
+survive something the derivation can't see.
+
+**Precedence: `id:` > `key:` > auto-derivation.**
+
+```ruby
+button "Delete" do |s| ... end                  # auto: label + block source location
+button "Delete", key: todo[:id] do |s| ... end  # content-stable: bound to the record
+button "Delete", id: "delete-todo-#{todo[:id]}" # verbatim override -- you own the id
+```
+
+- **auto-derivation** hashes the label plus the block's source location. Two loop
+  iterations render the same label at the same line, so they derive the same id;
+  StreamWeaver auto-disambiguates each repeat occurrence with a `-dup-N` suffix
+  (and warns once, pointing at `key:`). Every button stays independently
+  dispatchable with zero author intervention -- the old silent wrong-callback
+  bug cannot happen.
+- **`key:`** accepts stable scalars ONLY -- String, Symbol, or Integer. Arrays,
+  hashes, and arbitrary objects raise `ArgumentError`, because their
+  stringification is not a stable identity. Never pass a positional index.
+- **`id:`** is the full explicit override: the emitted DOM id is
+  `btn_<label>_<your id>` verbatim, which is what you want when other code
+  (SSE pushes, CSS, tests) targets the element by selector.
+
+**Key by what is unique per position, not by content.** Auto-derived ids
+(including the `-dup-N` suffixes) are POSITION-stable, not CONTENT-stable: they
+hold steady across rerenders of the same list, but inserting or deleting an
+earlier item shifts every later occurrence's suffix. If a row's identity must
+outlive reordering, filtering, or deletion -- per-row Delete/Edit buttons, hover
+cards, anything whose payload is "this record" -- pass `key: record_id`. The
+classic failure is two cards sharing one derived id: hovering the second shows
+the first one's data, and nothing errors.
+
+**`strict_ids`** turns a derived-id collision from a warning into a hard failure,
+so a loop that relies on position-stability can't ship unnoticed:
+
+```ruby
+StreamWeaver::App.new("My App", strict_ids: true) { ... }   # per app
+StreamWeaver.strict_ids = true                              # global (boot file)
+SW_STRICT_IDS=1 ruby my_app.rb                              # env, e.g. in CI
+```
+
+It raises in development (and test), and degrades to a warning when
+`RACK_ENV=production` -- a live page should not 500 over an id the framework
+already disambiguated. The same rules apply to `clickable(action:, key:)`,
+`fragment` names, and feed/canvas-pushed buttons.
+
+### Layout
+```ruby
+card do
+  header3 "Card Title"
+  text "Content"
+end
+
+vstack spacing: :md do
+  text "Vertical"
+  text "Stack"
+end
+
+hstack spacing: :sm do
+  button "Left"
+  button "Right"
+end
+
+columns widths: ['30%', '70%'] do
+  column { text "Sidebar" }
+  column { text "Main" }
+end
+```
+
+### Modal
+```ruby
+button "Open" do |s|
+  s[:my_modal_open] = true
+end
+
+modal :my_modal, title: "Dialog", size: :md do
+  text "Modal content"
+  modal_footer do
+    button "Close" do |s|
+      s[:my_modal_open] = false
+    end
+  end
+end
+```
+
+### Navigation
+```ruby
+# Horizontal navbar — active item is bold/non-clickable, others are links
+navbar do
+  nav_item "Dashboard", href: "/", active: true
+  nav_item "Settings",  href: "/settings"
+end
+
+# Inline link
+link_to "View docs", href: "https://example.com"
+```
+
+### URL Routing (Deep Links & Bookmarks)
+
+Use `route_by` to map a state key's values to URL paths. This enables:
+- Direct URL access (e.g. visiting `/settings` loads the settings page)
+- Browser back/forward navigation
+- Bookmarkable URLs
+- External deep-linking
+
+```ruby
+app "My App" do
+  route_by :page, home: "/", dashboard: "/dashboard", settings: "/settings"
+
+  state[:page] ||= :home
+
+  navbar do
+    nav_item "Home",      href: "/",          active: state[:page] == :home
+    nav_item "Dashboard", href: "/dashboard",  active: state[:page] == :dashboard
+    nav_item "Settings",  href: "/settings",   active: state[:page] == :settings
+  end
+
+  case state[:page]
+  when :home      then # ...
+  when :dashboard then # ...
+  when :settings  then # ...
+  end
+end.run!
+```
+
+**How it works:** When `state[:page]` changes (via button callback or nav click), StreamWeaver emits an `HX-Push-Url` header that updates the browser URL. Visiting `/dashboard` directly seeds `state[:page] = :dashboard` before render. Back/forward uses HTMX to re-fetch the page at the popped URL.
+
+**Important:** `route_by` is opt-in — apps without it are unaffected.
+
+### Route Tabs (`tabs url: true`)
+
+Puts a tab group's active index in a query param, so a tab is bookmarkable:
+
+```ruby
+tabs :view, url: true do        # active tab lives in ?view=<index>
+  tab("Overview") { text "..." }
+  tab("Findings") { text "..." }
+end
+
+# Read state BELOW the declaration — above it, state[:view] is still the raw
+# pre-authority value (param string or stale session index), not the resolved Integer.
+md "Active view: #{state[:view]}"
+```
+
+Tab switching is client-side (History API), so no request is made; back/forward and
+bookmarks work. Multiple groups compose, one param per key (`/?view=2&panel=1`).
+
+**URL authority:** on a full GET the param wins — present and valid → that index,
+absent or invalid → tab 0, never the session value. Same URL, same tabs, always.
+`?view=999`, `?view=abc`, `?view[]=` all return 200 on tab 0; `?view=2` is a valid deep
+link. A route-tab group therefore can't be server-side preset (`state[:view] ||= 1`
+above the declaration is overwritten) — link to `/?view=1` instead.
+
+Raises at build time: reserved keys (`app_id`, `splat`, `captures`, `button_id`),
+duplicate `url:` keys, or `url: true` combined with `lazy: true`. On canvas, `url:` is
+ignored (plain client tabs + one logged warning; the page URL is untouched).
+
+Plain tabs also clamp: an out-of-range index renders tab 0 instead of blank panels.
+
+### Resource Scaffolding
+
+Use `resource` for convention-over-configuration CRUD. One block replaces ~40 lines of route/state/form boilerplate:
+
+```ruby
+resource :post, store: PostStore do
+  field :title,  :string
+  field :body,   :text
+  field :status, :enum, values: %w[draft published]
+end
+```
+
+Generates index / show / new / edit / destroy with deep-linkable URLs, named-route helpers (`posts_path`, `post_path(rec)`, etc.), store validation at startup, and override blocks for any action. Declare `page` / `route` calls before `resource` blocks (first-registered-wins routing chain).
+
+See `docs/resource-dsl.md` for full reference: field types, `only`/`except`, store protocol, `_sw_` state schema, override blocks.
+
+### Record-Bound Forms (`form_for`)
+
+`form_for` is the primitive `resource`'s own `new`/`edit` views build on: seeds fields from a record, infers create vs. update from record identity, coerces + validates on submit, then `store.create`/`update` → flash notice → PRG to the resource's `show` action. Use it inside `resource` override blocks (or standalone) whenever you need more control than the default form gives you:
+
+```ruby
+resource :person, store: PersonStore do
+  field :name, :string
+  field :role, :enum, values: %w[lead champion decision_maker]
+
+  edit do |person|
+    header1 "Edit #{person[:name]}"
+    form_for :person, record: person do
+      submit_label "Save"
+      cancel_label "Cancel"
+    end
+  end
+end
+```
+
+- `record:` present with an `:id` → update mode (`"Save"`); `nil`/absent → create mode (`"Create"`).
+- Seeds the form scope from `record:` only on first render for that id — an unrelated re-render never clobbers an in-progress edit; switching to a different id re-seeds fresh.
+- Validation failures (coercion or a `validate { |values| ... }` block) populate an error `Alert` above the fields and re-render same-request, keeping the user's typed values — never a redirect.
+- `on_success:` overrides the default show/index transition; required for standalone (non-`resource`) usage.
+
+Full reference (all options, in-block DSL, standalone usage): `docs/resource-dsl.md#form_for`.
+
+### Turbo Frame-Style Inline Editing with `form_for`
+
+The learnhotwire.com course's canonical Turbo Frames demo: click a todo's title, it turns into an edit field in place, submit swaps back to the display — no full navigation. Rails does this with two matching-`dom_id` frames; StreamWeaver gets the same *result* (deep-linkable edit state, no hand-written JS, no full page reload — HTMX swaps the container) from `resource` + `form_for`, using the resource's own routed `edit` action instead of a client-side frame swap:
+
+```ruby
+require 'stream_weaver'
+require 'securerandom'
+
+module TodoStore
+  @todos = [{ id: '1', title: 'Buy milk', completed: false }]
+  def self.all;              @todos; end
+  def self.find(id);         @todos.find { |t| t[:id] == id }; end
+  def self.create(attrs);    id = SecureRandom.hex(4); @todos << { id: id, **attrs }; id; end
+  def self.update(id, attrs) t = find(id); t&.merge!(attrs); !!t; end
+  def self.destroy(id);      @todos.reject! { |t| t[:id] == id }; true; end
+end
+
+app 'My Todos' do
+  resource :todo, store: TodoStore do
+    field :title,     :string
+    field :completed, :boolean
+
+    # Row shows the title as plain text with an Edit link — click it to swap
+    # this row's spot for an inline form_for, submit swaps back to the row.
+    index do |todos|
+      header1 'My Todos'
+      todos.each do |todo|
+        hstack do
+          text todo[:title]
+          link_to 'Edit', href: edit_todo_path(todo)
+        end
+      end
+    end
+
+    # /todo/:id/edit — form_for seeds :title/:completed from the record,
+    # submit coerces + validates, calls TodoStore.update, flashes, and
+    # PRGs back to :show (URL pushed, deep-linkable either way).
+    edit do |todo|
+      header1 "Edit #{todo[:title]}"
+      form_for :todo, record: todo do
+        submit_label 'Save'
+        cancel_label 'Cancel'
+      end
+    end
+  end
+end.run!
+```
+
+**Key mapping** (Rails → StreamWeaver): matching `dom_id` frames that swap in place →
+`resource`'s routed `edit` action (`edit_todo_path(todo)`) whose default/override view
+calls `form_for :todo, record: todo`; Rails' `form_with model: @todo` field/value
+seeding + strong-params allowlist → `form_for`'s record seeding + `field` declarations
+(only declared fields are read from submitted state); Rails' controller-driven
+create/update + redirect-back-to-show → `form_for`'s built-in coerce → validate →
+`store.update` → flash → PRG to `show`, all for free. What StreamWeaver does not yet do
+is a same-DOM-fragment swap scoped to just the one row — today the edit view is its own
+routed, deep-linkable page/fragment, not a client-side frame replacement. For the other
+half of the Turbo Frames story — rendering the shell now and letting a slow region land
+later — see [Deferred Fragments](#deferred-fragments-fragment--defer-true) below.
+
+### Deferred Fragments (`fragment ..., defer: true`)
+
+`fragment(:name) { ... }` marks a region of the page that interactions inside it can swap on
+its own, instead of swapping the whole app container. Adding `defer: true` makes it the
+equivalent of Turbo's `turbo_frame_tag ..., src:`: **the block does not run on the initial
+render at all.** The page ships immediately with a placeholder, and the fragment fetches its
+own content right after — no custom JavaScript in your app, just the option:
+
+```ruby
+app 'Dashboard' do
+  header1 'Dashboard'          # renders instantly
+  text "#{Order.count} orders" # renders instantly
+
+  # This block never runs during the page render. The shell responds, the
+  # browser fetches this fragment, and the content swaps in when ready.
+  fragment :revenue_report, defer: true do
+    text expensive_quarterly_rollup   # 1.5s of work, off the critical path
+  end
+end.run!
+```
+
+**Placeholder** — what stands in until the content lands. Three forms:
+
+```ruby
+fragment(:stats, defer: true) { ... }                              # default: small spinner
+fragment(:stats, defer: true, placeholder: 'Loading stats…') { ... } # a String renders as text
+fragment(:stats, defer: true, placeholder: -> { skeleton_rows(5) }) { ... } # a Proc runs as DSL
+```
+
+**How it works**: the deferred fragment renders its placeholder wrapped in an element carrying
+`hx-trigger="load"` pointing at the same signed fragment-update endpoint every in-fragment
+interaction already uses. That fetch re-runs the DSL with this fragment marked as the one to
+materialize, so its block executes and only its content comes back over the wire.
+
+**Things to know**:
+
+- The block is skipped on the shell render, so anything it registers as a side effect (actions,
+  timers) is not registered until the fetch. Keep registration outside deferred blocks.
+- **A named-action button (`button 'X', action: :foo`) inside a deferred fragment does not fire.**
+  The fetch mints its token outside the session's action manifest, so clicking it re-renders the
+  fragment without running the action. Put such buttons in a non-deferred fragment, or use a block
+  button (`button('X') { |s| ... }`), which dispatches by id and is unaffected.
+- Current input values are posted with the fetch, so a deferred fragment can read `state` set by
+  fields elsewhere on the page.
+- Nesting works and chains: a `defer:` fragment inside a plain fragment loads in place; a
+  `defer:` fragment inside another `defer:` fragment loads after its parent does. Because
+  every fetch re-runs the DSL, a nested fetch also runs its ancestors' blocks — two nested
+  1.5s panels cost 1.5s for the outer fetch and 3s for the inner one. Nest deferred
+  fragments for staging, not to divide one expensive block into cheaper pieces.
+- An interaction that swaps the whole app container re-renders the deferred fragment as its
+  placeholder, and it fetches again. That keeps the shell fast on every render rather than
+  paying the slow cost inline.
+- `defer:` is an option on `fragment`. The bare `defer { ... }` display verb is an unimplemented
+  stub that silently drops its block — do not use it.
+
+### Lazy Fragments (`fragment ..., lazy: true`)
+
+`defer: true` fetches the moment the page loads. Adding `lazy: true` holds that fetch until the
+fragment is **visible** — Turbo's `loading="lazy"`. Visible means visible, whatever caused it:
+scrolled into the viewport, or a CSS rule flipping an ancestor out of `display: none`. It is not
+"scrolled near" and it is not "hovered"; a hover only counts because the hover changed `display`.
+
+```ruby
+fragment :revenue_report, lazy: true do
+  text expensive_quarterly_rollup   # runs the first time this region is seen, never before
+end
+```
+
+**`lazy: true` implies `defer: true`** — write both if it reads better, but `lazy:` alone is
+enough. `placeholder:` works the same as on any deferred fragment.
+
+**The two guarantees**:
+
+- **A CSS-hidden fragment never fetches.** `display: none` means no fetch, for as long as it
+  lasts. This is what makes the hover-card recipe below cost nothing on page load.
+- **It fetches exactly once.** The content lands in the DOM and stays there; hiding and
+  re-showing the region does not fetch again.
+
+**How it works**: the placeholder wrapper carries `hx-trigger="intersect once"` instead of
+`hx-trigger="load"`, which htmx backs with an `IntersectionObserver` — the same browser API Turbo
+uses. (`revealed`, the other htmx visibility trigger, reads `getBoundingClientRect()`, which
+reports an all-zero rect for a hidden element and so counts it as revealed; it would fetch every
+hidden fragment on page load. See `docs/research/2026-08-22-lazy-fragments-trigger-decision.md`.)
+The wrapper also gets a `sw-fragment-lazy` class, which disappears with the wrapper once the
+content lands — so `document.querySelectorAll('.sw-fragment-lazy').length` counts what has not
+fetched yet, which is how you verify a hidden fragment stayed hidden.
+
+#### Recipe: hover cards, with no JavaScript
+
+CSS reveals the card; revealing it is what fires the fetch. Nothing on the page has fetched
+anything until the pointer arrives.
+
+```ruby
+app 'Directory' do
+  use_stylesheet <<~CSS
+    .hovercard-host { position: relative; display: inline-block; }
+    .hovercard-pop  { display: none; position: absolute; top: 1.6rem; left: 0; z-index: 20; }
+    .hovercard-host:hover .hovercard-pop { display: block; }
+  CSS
+
+  div(class: 'hovercard-host') do
+    text 'Ada Lovelace'
+    div(class: 'hovercard-pop') do
+      fragment :ada_card, lazy: true, placeholder: 'Loading…' do
+        text expensive_profile_lookup('ada')
+      end
+    end
+  end
+end.run!
+```
+
+#### Recipe: infinite scroll, as nested fragments
+
+**The page the reader is on renders inline; only the *next* page is lazy.** Each response
+carries its own rows plus one placeholder for the page after it, so page N+1 does not exist in
+the DOM until page N has been scrolled past. That is the whole of the pagination logic — no
+scroll handler, no page counter in state.
+
+```ruby
+def scroll_page(number)
+  # THIS page renders now, in whatever response we're already writing.
+  Post.page(number).each { |post| card { text post.title } }
+
+  # Only the NEXT page is deferred.
+  nxt = number + 1
+  if Post.page?(nxt)
+    fragment :"page_#{nxt}", lazy: true, placeholder: 'Loading…' do
+      scroll_page(nxt)   # recursion lives INSIDE the lazy fragment
+    end
+  end
+end
+
+app('Feed') { scroll_page(1) }.run!
+```
+
+**Do not wrap page `number` itself in the lazy fragment.** A deferred block is skipped on the
+shell render, so `fragment(:"page_#{number}", lazy: true) { rows; recurse }` called with `1`
+serves HTML containing no rows at all — just a placeholder. It *looks* correct only because
+page 1's placeholder sits in the initial viewport, so the IntersectionObserver fires
+immediately; a lazy fragment that is already visible fetches at once, which is precisely what
+hides the mistake. Rendering the current page inline is also what Turbo does, and it is what
+keeps the served HTML honest for crawlers and for a reader with no JavaScript.
+
+Nested fragment ids are `parent--child`: page 2's fragment is declared beside page 1's rows so
+its id is `sw-frag-page-2`, and page 3's is declared inside page 2's block, giving
+`sw-frag-page-2--page-3`. Each fetch re-runs its ancestors' blocks (see the deferred nesting
+note above), so keep the per-page work cheap.
+
+#### Recipe: a tab panel that loads when you open it
+
+Route tabs (`tabs :view, url: true`) render inactive panels as `display: none`, so a lazy
+fragment inside one waits until that tab is selected — and then fetches just itself, without the
+whole-container morph the deprecated `tabs ..., lazy: true` mode used. Put the fragment **inside**
+a `tab` block, never beside one at the top level of the `tabs` block (a non-tab child there shifts
+every panel index):
+
+```ruby
+tabs :view, url: true do
+  tab('Summary') { text summary_line }
+  tab('Revenue') do
+    fragment :revenue, lazy: true, placeholder: -> { spinner(label: 'Loading…') } do
+      revenue_table
+    end
+  end
+end
+```
+
+**Things to know**:
+
+- Everything true of `defer:` is true here: the block is skipped on the shell render, current
+  input values ride along with the fetch, a named-action button inside it does not fire (use a
+  block button), and a static export runs the block inline.
+- A full-container swap re-renders a lazy fragment back to its placeholder and **re-arms** it —
+  but lazily. If it is off-screen or hidden when that happens, it waits, where a plain `defer:`
+  fragment would refetch immediately.
+- The wrapper is what the observer watches, so give it something with height. The default spinner
+  placeholder has it; a placeholder that renders nothing gives the observer a zero-area target.
+
+### Feedback
+```ruby
+alert(variant: :success) { text "Saved!" }
+alert(variant: :error) { text "Failed!" }
+# variants: :info, :success, :warning, :error
+```
+
+## Running Modes
+
+### Interactive (default)
+```ruby
+app "My App" do
+  # ...
+end.run!
+```
+Server runs until Ctrl+C. State persists in session cookies (~4KB limit).
+
+**Reset corrupted state:** `ruby my_app.rb --reset` clears the session on first page load.
+
+**Debug logging:** `SW_DEBUG=1 ruby my_app.rb` logs every request with cookie size, state size, and SSE connection counts to stderr.
+
+### Remote/Mobile Access (Tailscale, LAN)
+
+By default, StreamWeaver binds to `127.0.0.1` (localhost only). For access from phones, tablets, or other machines via Tailscale or LAN:
+
+```bash
+STREAMWEAVER_HOST=0.0.0.0 STREAMWEAVER_PORT=4580 ruby my_app.rb
+```
+
+Or in code:
+```ruby
+app "Dashboard" do
+  # ...
+end.run!(host: '0.0.0.0', port: 4580)
+```
+
+**Environment variables** (overridden by code options):
+- `STREAMWEAVER_HOST` — bind address (default: `127.0.0.1`)
+- `STREAMWEAVER_PORT` — fixed port (default: auto-detect)
+
+**Why fixed port matters for mobile:** Auto-port detection finds a different port each restart, breaking bookmarks. Set a fixed port when you need a stable URL.
+
+**Host authorization:** When bound to `0.0.0.0`, StreamWeaver automatically disables Sinatra's host authorization so Tailscale DNS names, LAN IPs, etc. are accepted.
+
+### Agentic (one-shot)
+```ruby
+result = app "Survey" do
+  text_field :name
+  select :priority, ["Low", "High"]
+end.run_once!(auto_close_window: true)
+
+puts result  # => { "name" => "Alice", "priority" => "High" }
+```
+Blocks until user submits, returns form data as hash, exits.
+
+**Important for agentic mode:** Only input component values are returned. State set by button callbacks is NOT included.
+
+## Common Patterns
+
+### Conditional Display
+```ruby
+app "Login" do
+  if state[:logged_in]
+    text "Welcome!"
+    button "Logout" do |s| s[:logged_in] = false end
+  else
+    text_field :username
+    button "Login" do |s| s[:logged_in] = true end
+  end
+end
+```
+
+### List with Add/Remove
+```ruby
+app "Todo" do
+  text_field :new_item
+
+  button "Add" do |s|
+    s[:items] ||= []
+    s[:items] << s[:new_item] if s[:new_item].to_s.strip != ""
+    s[:new_item] = ""
+  end
+
+  state[:items]&.each_with_index do |item, i|
+    hstack do
+      text item
+      button "X" do |s| s[:items].delete_at(i) end
+    end
+  end
+end
+```
+
+### Multi-Step Wizard
+```ruby
+app "Wizard" do
+  state[:step] ||= 1
+
+  case state[:step]
+  when 1
+    text_field :name
+    button "Next" do |s| s[:step] = 2 end
+  when 2
+    select :plan, ["Free", "Pro"]
+    button "Back" do |s| s[:step] = 1 end
+    button "Submit" do |s| s[:done] = true end
+  end
+
+  text "Done!" if state[:done]
+end
+```
+
+## App Options
+
+```ruby
+app "Title",
+  layout: :wide,        # :default, :wide, :full, :fluid
+  theme: :dashboard,    # :default, :dashboard, :document, :doc (artifact-exact editorial; supports dark via data-sw-theme="dark" on <html>)
+  strict_ids: true      # raise (dev) / warn (prod) on derived-id collisions -- see "Interactive IDs and keying"
+do
+  # ...
+end
+```
+
+## Session Persistence
+
+State persists in browser cookies across server restarts. To reset:
+- Clear browser cookies
+- Use incognito mode
+- Add: `button "Reset" do |s| s.clear end`
+
+---
+
+## Canvas Mode (Side-by-Side Panels)
+
+Canvas mode lets scripts display rich interactive UI in a browser panel alongside the terminal.
+Useful for presenting forms, selections, or analysis results that are hard to show in terminal.
+
+### Quick Example (Shell Script)
+
+```bash
+#!/bin/bash
+SESSION="my-panel-$$"
+
+# Open panel in iTerm2 split pane
+streamweaver panel "$SESSION"
+
+# Push UI content
+streamweaver canvas-push "$SESSION" <<'RUBY'
+header1 "Select Options"
+checkbox :option_a, "Enable feature A"
+checkbox :option_b, "Enable feature B"
+radio_group :mode, ["Fast", "Safe", "Balanced"]
+button "Apply"
+RUBY
+
+# Wait for button click, get JSON result
+result=$(streamweaver canvas-wait "$SESSION")
+echo "User selected: $result"
+
+# Cleanup
+streamweaver canvas-close "$SESSION"
+```
+
+### Key Commands
+
+| Command | Purpose |
+|---------|---------|
+| `streamweaver panel SESSION [--layout=LAYOUT] [--theme=THEME] [--fresh]` | Open canvas in iTerm2 split pane |
+| `streamweaver canvas-push SESSION` | Push DSL content (stdin or `<<'RUBY'`) |
+| `streamweaver canvas-wait SESSION [--event TYPE\|--any]` | Wait for a control to dispatch, return JSON (see the control table below) |
+| `streamweaver canvas-close SESSION` | Close the canvas session |
+| `streamweaver canvas-read FILE [FILE\|DIR ...]` | Browse saved canvas DSL files in a local viewer (sidebar + prev/next nav) |
+| `streamweaver export FILE.rb [-o OUT.html] [--inline-images] [--offline]` | Write a canvas DSL doc out as standalone HTML |
+
+`panel` flags: `--layout=` is one of `default`/`wide`/`full`/`fluid` (default `fluid`). `--theme=` selects any registered theme for the session (default `:default`); e.g. `--theme=doc` renders the canvas in the `:doc` theme, including its dark-mode variant. `--fresh` closes any existing session with the same name before creating a new one.
+
+`export` flags: `--inline-images` embeds local images as base64 data URIs so the file is fully portable. `--offline` fetches and inlines mermaid's own library (instead of referencing its CDN) so diagrams render in a viewer whose CSP blocks external scripts entirely — SharePoint's built-in HTML preview is the motivating case; needs network access once, at export time, not at view time. Same capability from `canvas-read`'s nav rail: "⬇ Export HTML" on every file, plus a second "⬇ Export HTML (offline)" link shown only on docs with a mermaid diagram.
+
+### Which canvas controls wake `canvas-wait`
+
+| Control | Canvas event | Payload |
+|---|---|---|
+| `button` | `action` | `button`, `state` |
+| `clickable(action:)` | `action` | `button` (the action token), `state` |
+| `menu_item` with a block | `action` | `button` (the item id), `state` |
+| `form` submit | `action` | `button`, `form`, `values` (the form scope), `state` |
+| `radio_group`, `tag_buttons`, `chip_group` | `change` | `field`, `value`, `state` |
+
+Text, date, select and checkbox fields dispatch no canvas event of their own -- their values ride along in the `state` of whichever `action` follows. `tag_buttons` is the exception among the `change` controls: it has no `x-model`, so its choice reaches the agent in its own `change` event but is *not* in a later `action`'s `state`.
+
+### Important Behavior
+
+- **canvas-wait returns on `action` events by default** - see the control table above; the `change` events from `radio_group`, `tag_buttons` and `chip_group` return only with `--event change` or `--any`
+- **Form state is captured** - JSON includes all checkbox, radio, text field values
+- **Use heredoc for DSL** - `<<'RUBY'` prevents shell interpolation issues
+
+### Canvas DSL
+
+Same components as regular StreamWeaver apps:
+```ruby
+header1 "Title"
+md "**Bold** and `code` work"
+card do
+  checkbox :agree, "I agree to **terms**"  # Markdown in labels
+end
+columns widths: ['50%', '50%'] do
+  column { radio_group :choice, ["A", "B"] }
+  column { checkbox :extra, "Extra option" }
+end
+button "Submit"  # Returns JSON when clicked
+
+# Mermaid diagrams work in canvas-push too
+mermaid "graph LR; A-->B", zoom: true
+```
+
+---
+
+## Canvas Persistence (Two-Tier)
+
+Every `canvas-push` is auto-saved. The user can promote a snapshot to a permanent doc with one click. Both tiers Just Work — you don't need to ask, you don't need to drive a save.
+
+| Tier | Path | Origin | Git? |
+|---|---|---|---|
+| 1 (history) | `~/.streamweaver/history/<session>/<YYYYMMDD_HHMMSS>.rb` | every `canvas-push`, automatic, 7-day cleanup | NO |
+| 2 (docs) | `<git_root>/docs/streamweaver_canvas/<name>.rb` | floating 💾 button in canvas, or curl POST | YES (intentional) |
+
+**For Claude:** if the user says "save this canvas as X", point at the floating Save-as-doc button (bottom-right of the canvas) — they click it, name it, done. Don't reinvent the save flow. As a fallback for non-canvas contexts:
+
+```bash
+curl -sX POST "http://localhost:<bridge-port>/canvas/<session>/save-doc" \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"<doc-name>"}'
+```
+
+**Browsing saved docs:** `streamweaver canvas-read` with no arguments opens the project's `docs/streamweaver_canvas/` directory in a viewer with two sidebar sections:
+- **Docs** (expanded) — explicit saves
+- **History** (collapsed by default) — every auto-saved snapshot, browseable retroactively
+
+History entries also show a 💾 button so the user can promote any past snapshot to a doc without re-pushing.
+
+The reader also discovers docs roots across the whole machine (scan of `$STREAMWEAVER_DOCS_SCAN_ROOTS`, default `~/work`, unioned with an auto-written registry at `~/.streamweaver/docs_roots.log`), grouped by repo with a repo filter — and it renders StreamWeaver-flavored `.org` docs (`#+STREAMWEAVER_DSL:` marker) everywhere `.rb` docs work.
+
+**`.rb` vs `.org` when saving** (`"format":"org"` in the POST body, or the dialog's Org toggle): `.rb` is the full-fidelity format and keeps everything. `.org` is a document — it leaves out live controls (`button`, `radio_group`, `text_field`, `form`, ...), one `#+STREAMWEAVER_OMITTED: <call>` keyword line each, reported as `omitted` in the response's `coverage` alongside `recognized`/`passthrough_verbatim`/`passthrough_lossy`. Saving a session that carries a form is therefore fine in both formats; only `.rb` brings the form back.
+
+## Agent Skills (Install These Before Hand-Rolling the Above)
+
+If you are Claude Code, Codex CLI, Gemini CLI, GitHub Copilot, or another agent that uses the `SKILL.md` convention, StreamWeaver ships three skills that already encode the workflows in this doc as trained procedure — check whether they're loaded before building UI from this doc's raw examples:
+
+- **streamweaver-way** — for building or changing an *interactive* app or feature: inline editing, live search, per-row buttons, hover cards, infinite scroll, or any region slow enough to hold up the page. Encodes the six laws above plus the four benchmark recipes, with the gotchas that actually bite.
+- **streamweaver-visual-companion** — the default choice for mockups, diagrams, layout comparisons, and brainstorming, any time you'd otherwise reach for a chrome-based visual companion or a claude.ai Artifact. Canvas-push is 5-7x cheaper in tokens and never leaves the terminal loop.
+- **streamweaver-doc-builder** — for long-form editorial documents (PRDs, reports, explainers) using the `:doc` theme, proven to reach 1:1 visual parity with a real claude.ai Artifact.
+
+**If those skills don't appear in your available-skills list, ask the user whether to install them** — it's one idempotent command that installs to both Claude Code's own path and the `.agents/skills/` cross-tool alias that Codex CLI, Gemini CLI, and GitHub Copilot all read natively (see `docs/reference/agent-skills-comparison.md` for how each tool discovers skills):
+
+```bash
+streamweaver setup             # global: ~/.claude/skills/ + ~/.agents/skills/ + bash permission (recommended)
+streamweaver install-skill     # project-local instead: .claude/skills/ + .agents/skills/ (no --global)
+```
+
+## Hotwire-Style Navigation Pattern
+
+Layouts with sidebars (or any persistent client-side UI) MUST preserve state across navigation. Full page reloads collapse accordions, scroll-jump, and reset client state. The pattern, on the canvas-read layout, is the reference implementation:
+
+```erb
+<body hx-boost="true"
+      hx-target="#content"
+      hx-select="#content"
+      hx-select-oob="#nav"
+      hx-swap="innerHTML">
+  <nav id="sidebar"> <!-- preserved across navigations --> </nav>
+  <div id="main">
+    <div id="content"> <%= @content_html %> </div>
+    <div id="nav"> <!-- prev/next/counter, OOB-swapped --> </div>
+  </div>
+</body>
+```
+
+Rules for any new layout following this pattern:
+
+1. **Navigation links must be `<a href>`** — `hx-boost` only intercepts anchor clicks. NEVER `<button onclick="location.href=...">`.
+2. **Disabled state renders as `<span>`**, not `<a>` — anchors don't have a real disabled state.
+3. **Keyboard shortcuts call `.click()` on the existing anchor** rather than mutating `location.href`.
+4. **Read current state from the URL at click time**, not from server-baked JS variables — after htmx swaps the page hasn't reloaded; baked variables are stale.
+5. **Update active-link highlights via `htmx:afterSwap` listener** that reads the URL and toggles `.active` (the sidebar isn't re-rendered, so the server-rendered class is stale).
+
+Reference: `lib/stream_weaver/views/canvas/reader_layout.erb`.
+
+**Future direction:** once Idiomorph (bd `stream_weaver-2ds`) lands, the OOB and active-class boilerplate goes away — morph diffs the rendered HTML and surgically updates only what changed, including class attributes. See `docs/streamweaver-frontend-vision.md` for the full thesis.
+
+## Dev Loud, Prod Self-Heal (Stale Action Fallback)
+
+Every named action's token embeds a digest of the app's registered actions
+plus a per-session generation. When a request arrives whose token no longer
+matches either (`lib/stream_weaver/interaction_runner.rb`'s
+`StaleActionDefinition`) — most commonly because the dev server hot-reloaded
+code and the browser is still holding a token minted before the reload —
+`lib/stream_weaver/server.rb`'s `/action/:button_id` route responds `409` +
+`HX-Retarget: #app-container` and re-renders the whole app. **This
+self-healing full-container swap is unconditional and stays byte-for-byte
+identical in production**: a user never sees an error, the app just
+silently recovers.
+
+This is a **deliberate inversion of Hotwire's philosophy**. Turbo Frames
+treat a missing/stale frame target as "content missing" and surface it loud
+by design — Rails' own course material calls this Turbo's single best
+debugging aid, because a silent frame swap during development hides the
+exact wiring bug the author needs to see. StreamWeaver keeps Hotwire's
+signal without inheriting its user-facing cost: **in development only**
+(`RACK_ENV` not `production`/`test` — see `sw_dev_mode?` in server.rb), the
+same 409 response additionally prepends a dismissible `.sw-dev-fallback`
+overlay (`lib/stream_weaver/dev_fallback_overlay.rb`) naming:
+
+- the stale target — the scoped fragment id the token declared (or the
+  action name, when no fragment was declared)
+- the likely cause — action token stale after a code reload (definitions
+  changed) or a server restart/session reset (generation changed)
+
+The overlay is framework-emitted HTML only — a checkbox+label CSS pattern
+dismisses it without a page reload, no inline `onclick`, no script tag, so
+app code stays zero-JS. Default styling comes from `--sw-dev-fallback-*`
+custom properties (`CSS.dev_fallback_css`); restyle via the `.sw-dev-fallback`
+class hook the same way any other framework CSS is overridden.
+
+**Decision note — only one loud-failure cause is reachable through this
+path.** The 409 route only ever raises `StaleActionDefinition` for a
+digest/generation mismatch (a stale token). A separately-missing fragment
+target (e.g. `find_fragment` returning nil after a conditional re-render
+removed it) is a *different*, non-exceptional code path inside
+`InteractionRunner#scoped_response` — it already falls back to the same
+`HX-Retarget: #app-container` swap, but at `200`, not `409`, and isn't
+raised as an exception at all. That branch is out of scope for this
+overlay; only "stale action token" is distinguishable at the 409 rescue
+site today.
+
+## Repo Conventions (Anti-Patterns That Cause Churn)
+
+Common failure modes when LLMs build StreamWeaver apps. Avoid these.
+
+- **Don't launch new servers per visual question.** Use `streamweaver canvas-push` to update a single persistent canvas. Multiple `streamweaver run app.rb` invocations create orphaned processes and port conflicts.
+- **Don't write Python helper scripts.** `streamweaver panel <session>` already detects iTerm vs. other terminals and opens the right thing. Ruby-first; iTerm2 control via `~/work/iterm2_ruby` if needed at all.
+- **Don't search `~`.** It's 2/3 of the home disk. Target `~/work/<project>` or use `uregistry locate <name>`.
+- **Don't `text "**markdown**"`.** `text` does not render markdown — use `md`.
+- **Don't use `spacer` or `divider`.** They don't exist — use `div(style: "height:Npx")`.
+- **Don't `<button onclick="location.href=...">` for navigation.** Bypasses htmx, full page reload, loses sidebar state. Use `<a href>` so `hx-boost` intercepts.
+- **Don't use positional URL indexes** like `?file=2` for shareable resources. Use Rails-style resource URLs (`/docs/:name`, `/history/:session/:timestamp`) — see `route_by` and `resource` (above) and bd `stream_weaver-9ei` for the canvas-read migration.
+- **Don't pass `theme: :light`.** Unrecognized — defaults to `:default`, just omit.
+- **Don't assume port 4567.** StreamWeaver finds a free port, may be 4568+. Read the actual URL from stdout or `streamweaver canvas-list`.
+
+## Detailed Documentation
+
+For comprehensive reference, see these docs:
+
+| Document | Contents |
+|----------|----------|
+| `docs/components_reference.md` | Full component API (all options, variants) |
+| `docs/frontend-only.md` | What survives `canvas-read` and `streamweaver export` (no backend) vs. the live canvas — read before building a doc meant to be exported or browsed read-only |
+| `docs/SERVICE_MODE.md` | Multi-app service mode, CLI commands |
+| `docs/testing.md` | Unit and integration testing |
+| `docs/architecture/how_streamweaver_works.md` | Internal architecture, event flow |
+| `docs/routing.md` | URL routing: `route_by`, `route_with`, parameterized paths, edit routes — **read the Common Pitfalls section before building any app with more than a couple of routes**: `route_with` merges GET state rather than replacing it, and an incomplete `case`/`when` route table fails silently on both the parse and build sides |
+| `docs/crud-patterns.md` | CRUD: create/edit/delete modals, URL-addressable edit pages, store adapters |
+| `docs/streamweaver-frontend-vision.md` | Strategic direction: htmx + Alpine + Idiomorph as a Hotwire-equivalent stack for Ruby devs |
+| `docs/porting-artifacts.md` | Porting a claude.ai Artifact into StreamWeaver at visual parity: dissect, gap-assess, port, verify, promote |
+| `docs/shared-dsl-fragments.md` | Two or more docs for different audiences sharing ONE canonical copy of a table via an `instance_eval`'d fragment file, so they cannot drift — includes the per-mode `__dir__` truth table (export and canvas-read pass a filename to `instance_eval`; org-export and the canvas-push bridge do not) |
+| `docs/tutorials/the-streamweaver-way.md` | **Tutorial** — "Build My Todos: the StreamWeaver Way": the four benchmark features rebuilt step by step, each naming its law, its gotcha, and its measured number. The narrated twin of the `streamweaver-way` skill |
+
+## Live Streaming with `every` Timers
+
+Push live updates to the browser via SSE (Server-Sent Events). No polling, no WebSockets — just `every(seconds)`.
+
+### Periodic Timers
+
+```ruby
+app "Monitor", theme: :dark do
+  div id: "status" do
+    text "Waiting..."
+  end
+
+  every(3) do |streamer|
+    streamer.replace("#status") do
+      div id: "status" do
+        text "Updated at #{Time.now.strftime('%H:%M:%S')}"
+      end
+    end
+  end
+end.run!
+```
+
+The `every` block receives a `streamer` object with these SSE actions:
+
+| Method | Purpose |
+|--------|---------|
+| `streamer.replace(selector) { ... }` | Replace element innerHTML |
+| `streamer.append(selector) { ... }` | Append to element |
+| `streamer.prepend(selector) { ... }` | Prepend to element |
+| `streamer.remove(selector)` | Remove element from DOM |
+| `streamer.add_class(selector, class)` | Add CSS class |
+| `streamer.remove_class(selector, class)` | Remove CSS class |
+
+All methods accept either a block (renders DSL components) or a raw HTML string.
+
+### Multiple Timers with Shared State
+
+Closure variables let timers share state naturally:
+
+```ruby
+app "Dashboard", theme: :dark do
+  div id: "metric" do
+    stat_display value: "\u2014", label: "CPU", color: :blue
+  end
+  div id: "alert-css", style: "display:none"
+
+  latest = { cpu: 0.0 }
+
+  every(3) do |streamer|
+    latest[:cpu] = `sysctl -n vm.loadavg`.scan(/[\d.]+/)[0].to_f
+
+    streamer.replace("#metric") do
+      div id: "metric" do
+        stat_display value: latest[:cpu].to_s, label: "CPU", color: :green
+      end
+    end
+  end
+
+  every(5) do |streamer|
+    # Idempotent CSS injection via replace (not append — avoids duplicates)
+    streamer.replace("#alert-css", "<style>.alert-ring{box-shadow:0 0 0 3px red}</style>")
+    streamer.add_class("#card-cpu", "alert-ring") if latest[:cpu] > 4.0
+  end
+end.run!
+```
+
+### Key Patterns
+
+- **Target elements by `id:`** — use `div id: "my-target"` in initial render, then `streamer.replace("#my-target")`
+- **Re-include `id:` inside replace blocks** — the id must survive replacement
+- **CSS injection via `replace`** — use a hidden placeholder div, not `append("head")` which duplicates on every tick
+- **Always re-apply `add_class`** — new SSE connections miss past class changes, so re-apply each tick
+- **`expandable_card key: :foo` generates `id="card-foo"`** — target it with `#card-foo` in SSE actions
+
+### CRITICAL: Accessing `state` Inside `streamer.replace` Blocks
+
+**The problem:** `streamer.replace("#target") { ... }` evaluates its block in a `FeedBuilder` context, NOT in the App context. This means `state` — which is a method on the App — is **not accessible** inside the block. This will raise `NameError: undefined local variable or method 'state'` at runtime (not at startup).
+
+```ruby
+# WRONG — `state` is not available inside replace blocks
+every(30) do |streamer|
+  streamer.replace("#my-panel") do
+    text "Filter: #{state[:filter]}"  # NameError: undefined method `state'
+  end
+end
+
+# CORRECT — pass state: explicitly
+every(30) do |streamer|
+  streamer.replace("#my-panel", state: state) do
+    text "Filter: #{state[:filter]}"  # works
+  end
+end
+```
+
+The same applies to `streamer.append` and `streamer.prepend`.
+
+### CRITICAL: Helper Methods Inside `streamer.replace` Blocks
+
+Top-level `def` helper methods work inside `streamer.replace` blocks (they're globally accessible). However, if those helpers call `state`, the `state:` keyword must be passed to `replace` — not to the helper itself.
+
+```ruby
+def render_summary(data:, state:)
+  card do
+    text "Mode: #{state[:mode]}"   # state passed as arg — fine
+    stat_display value: data[:count], label: "Items"
+  end
+end
+
+app "Dashboard" do
+  div id: "summary" do
+    render_summary(data: load_data, state: state)
+  end
+
+  every(10) do |streamer|
+    # Pass state: to replace so FeedBuilder exposes it
+    streamer.replace("#summary", state: state) do
+      render_summary(data: load_data, state: state)
+    end
+  end
+end.run!
+```
+
+**Why this matters:** The error appears in the timer thread log (`[StreamWeaver] Timer error: NameError`), not on page load. It's easy to miss during development if the timer interval is long.
+
+### Timer Examples
+
+| File | Description |
+|------|-------------|
+| `examples/timer_showcase.rb` | Live CPU/Memory/Disk with spotlight effects and alert feed |
+| `examples/timer_health_checker.rb` | HTTP endpoint health monitoring with SLA badges |
+
+## Architecture Summary
+
+- **Backend**: Sinatra server, Phlex for HTML
+- **Frontend**: Alpine.js (reactivity) + HTMX (server communication)
+- **State**: Server-side, persisted in session cookies
+- **Updates**: HTMX swaps `#app-container` innerHTML on state changes; SSE pushes for `every` timers
+
+## Common Mistakes
+
+1. **Forgetting state is a hash** - Use `state[:key]`, not `state.key`
+2. **Assuming port 4567, or booting a second instance to "find" the port** - Read the already-running process's stdout for the actual port; a second launch just starts an orphaned duplicate on the next free one
+3. **Missing `.run!`** - App won't start without it
+4. **Agentic mode button state** - Only input values returned, not button-set state
+5. **Wrong checkbox signature** - `checkbox :key, "label"` (key first, then label). NOT `checkbox "label", value: x`
+6. **Using checkbox inside checkbox_group** - Use `item value do...end`, NOT `checkbox`. checkbox_group has its own DSL.
+7. **Putting text/headers inside checkbox_group** - ONLY `item` elements allowed directly inside `checkbox_group`. Put section headers OUTSIDE the checkbox_group block.
+8. **Expecting form-like behavior by default** - ALL inputs auto-submit on change. For multi-select lists where user picks several items then clicks an action button, use `submit: false` on each checkbox. For traditional forms, use the `form` block.
+9. **Using buttons to simulate selection** - Don't set `state[:x] = index` in button callbacks to track which option is selected. Use `select :key, choices, submit: false` or `radio_group :key, choices` instead. Buttons are for actions, not selection state.
+10. **Storing array indices in state** - Indices break when lists change. Store the string name/label and resolve to index at action time.
+11. **Long lists without scroll** - Use `scroll_box(max_height: "400px") do...end` to constrain list height. See `docs/form-patterns.md` for all canonical patterns.
+
+---
+
+## Opal Mode — Static Browser Apps
+
+StreamWeaver apps can be compiled to static JavaScript and deployed without a server via `streamweaver opal-build`.
+
+### Build command
+
+```bash
+streamweaver opal-build app.rb              # outputs to dist/
+streamweaver opal-build app.rb --output /my/dir
+```
+
+Produces `dist/index.html` + `dist/app.js` + `dist/morphdom.min.js`. Deploy `dist/` to GitHub Pages or any static host.
+
+### What works in Opal mode
+
+- `app`, `header`, `text_field`, `checkbox`, `button`, `md`, `div` — all Phase 1 components
+- State is fully in-browser (no server round-trips)
+- Button callbacks via data attributes + delegated event listeners
+- Reactivity: whole-block re-execution + morphdom DOM patching
+
+### What doesn't work in Opal mode (Phase 1)
+
+- `feed`, `streamer`, `service_client` — require a server by definition
+- `form_block` — deferred
+- `chartjs`, `tabs`, `table` — not yet implemented in Adapter::Opal
+
+### Key files
+
+| File | Role |
+|---|---|
+| `lib/stream_weaver/opal_entry.rb` | Browser-only require tree |
+| `lib/stream_weaver/opal/renderer.rb` | String-accumulating view (replaces Phlex) |
+| `lib/stream_weaver/opal/runtime.rb` | State + callback registry |
+| `lib/stream_weaver/opal/bridge.rb` | Wires Ruby to window.SWRuntime |
+| `lib/stream_weaver/opal/builder.rb` | Opal compilation pipeline |
+| `lib/stream_weaver/adapter/opal.rb` | Render methods for browser |