stream_weaver 0.3.0

data/lib/stream_weaver/skills/streamweaver-way/SKILL.md

@@ -0,0 +1,396 @@
+---
+name: streamweaver-way
+description: Use when building or changing an interactive StreamWeaver app or feature — inline editing, live search/filtering, per-row buttons, hover cards, infinite scroll, tabs, or any region slow enough to hold up the page. Encodes "The StreamWeaver Way": the conventions (fragments, defer:/lazy:, form_for, interactive-id keying, dev-loud/prod-self-heal) that make app code zero-JavaScript by default. For one-off mockups, diagrams, or dashboards to look at, use streamweaver-visual-companion instead; for long-form editorial documents, use streamweaver-doc-builder.
+---
+
+# The StreamWeaver Way
+
+StreamWeaver is an *omakase* layer, not a widget kit: the backend and the frontend were
+designed as one system, so the conventions below are the framework, not style advice.
+Follow them and you write no JavaScript. Fight them and you write a lot.
+
+**Read the laws. Drill into a recipe only when you're building that thing.**
+
+---
+
+## The Laws
+
+**1. Key by what is unique per position on the page, not by what the content is about.**
+Every interactive element needs a server-dispatchable id, and StreamWeaver derives one
+for you (label + block source location, with `-dup-N` auto-disambiguation on repeats), so
+you rarely pass anything. Auto-derived ids are *position*-stable, not *content*-stable:
+insert or delete an earlier row and every later suffix shifts. Reach for `key:` only when
+identity must outlive reordering, filtering, or deletion — per-row Edit/Delete buttons,
+per-row fragments. Then key it by the thing that is unique *per row on this page* (the
+todo), never by what the row happens to display (its assignee) — two rows sharing an
+assignee is the classic collision, and it fails silently: hovering the second card shows
+the first one's data. Precedence is `id:` > `key:` > auto. `key:` takes stable scalars
+only (String/Symbol/Integer; anything else raises). Never key by positional index.
+
+**2. Deferred over hand-rolled timers.** A slow region gets `fragment(..., defer: true)`
+so the shell ships now and the region lands later. Never an `every(...)` poll, never a
+"loading" flag toggled by a second request you wrote yourself. Measured on one 1.5s
+region: initial GET 0.018s instead of 1.5s.
+
+**3. Lazy means visible.** `lazy: true` holds the fetch until the fragment is actually
+*visible* — scrolled into view, or CSS flipping an ancestor out of `display: none`.
+Hidden content costs exactly nothing, and it fetches exactly once. That interlock is what
+buys you hover cards and infinite scroll with no scroll handler and no state counter.
+
+**4. Dev loud, prod self-heals.** A stale action token gets a 409 + full-container
+re-render that is byte-for-byte identical in production — the user never sees an error.
+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": keep the debugging signal, don't charge the user for it. If you see
+that overlay, your wiring is wrong — don't style it away.
+
+**5. State your intent in DSL verbs. Zero custom JavaScript is the default, not an
+aspiration.** All four benchmark features below run with no script tag, no inline JS, no
+hand-written Alpine — only DSL verbs and CSS. If you're reaching for JavaScript, you have
+almost certainly missed a verb. Do not touch adapter internals (`lib/stream_weaver/
+adapter/*`) or emit raw `hx-*` attributes from app code; the verbs own those.
+
+**6. Trilaws as design filters.** Run every feature through all three:
+*Matt* — is it findable and digestible (progressive disclosure for the long tail)?
+*Forrest* — zero friction plus a real perk (if it can be automatic, it must be)?
+*Gloria* — is the default path the correct path (design for the brain you have, not the
+one that remembers to pass the right option)? Law 1's auto-keying is Gloria's Law in
+code: the default already disambiguates, so the silent-wrong-callback bug can't happen.
+
+---
+
+## Core mechanics (everything below builds on these)
+
+```ruby
+app 'My App' do
+  state[:count] ||= 0            # the whole block RE-RUNS on every interaction
+  text "Count: #{state[:count]}"
+  button('+') { |s| s[:count] += 1 }
+end.run!
+```
+
+**`fragment(name) { ... }`** marks a region that interactions *inside it* swap on their
+own, instead of swapping the whole app container. Everything interactive rendered inside
+a fragment is auto-scoped to it — that scoping is the whole mechanism the recipes use.
+
+| Form | Fetch timing | 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) { }` | first time it is visible | hover cards, infinite scroll, tab panels |
+
+`lazy: true` implies `defer: true`. `placeholder:` accepts nothing (small spinner), a
+String (rendered as text), or a Proc (run as DSL). **Give the placeholder height** — the
+observer watches the wrapper, and a zero-area target never intersects.
+
+**Three rules that apply to every deferred/lazy fragment:**
+
+- The block is skipped on the shell render, so anything it *registers* (actions, timers)
+  isn't registered until the fetch. 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.
+
+**`form_for`** is the record-bound form primitive: seeds fields from a record, infers
+create vs. update from record identity, coerces + validates on submit, calls
+`store.create`/`store.update`, flashes, and PRGs. **Only the fields you declare are read
+from the submitted state** — that allowlist is edit-safety by construction, not by
+remembering to pass the right URL.
+
+A **store** is any object answering `all`, `find(id)`, `create(attrs)`, `update(id, attrs)`,
+`destroy(id)`. A plain module over an Array is enough to build all four recipes.
+
+---
+
+## The four benchmark recipes
+
+These are the four Turbo Frames features from the learnhotwire.com course, in
+StreamWeaver, with zero custom JavaScript. Recipe 1 defines the store; recipes 2-4 add
+one method each to it, shown inline. Each is complete and runnable.
+
+### 1. Inline editing (a row becomes a form in place)
+
+One `fragment` per row, keyed by record id, branching on an `editing_id` in state. The
+Edit button and the form submit both swap **just this row**, because both are rendered
+inside that row's fragment.
+
+```ruby
+require 'stream_weaver'
+
+module TodoStore
+  @todos = [{ id: '1', title: 'Buy milk', completed: false },
+            { id: '2', title: 'Ship it',  completed: true }]
+  class << self
+    def all = @todos
+    def find(id) = @todos.find { |t| t[:id] == id.to_s }
+    def create(attrs) = (id = (@todos.size + 1).to_s; @todos << { id: id, **attrs }; id)
+    def update(id, attrs) = (t = find(id)) ? (t.merge!(attrs); true) : false
+    def destroy(id) = (@todos.reject! { |t| t[:id] == id.to_s }; true)
+  end
+end
+
+# Declare ONLY the editable field. A submit through this form cannot reach
+# :completed -- the allowlist is enforced by construction.
+TITLE_ONLY = [StreamWeaver::Field.new(:title, :string, {})].freeze
+
+app 'My Todos' do
+  TodoStore.all.each do |todo|
+    fragment("todo-#{todo[:id]}") do
+      if state[:editing_id].to_s == todo[:id]
+        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]}") { |s| s[:editing_id] = nil }
+      else
+        hstack spacing: :sm do
+          text "#{todo[:completed] ? '☑' : '☐'}  #{todo[:title]}"
+          button('Edit', style: :secondary, key: "edit-#{todo[:id]}") { |s| s[:editing_id] = todo[:id] }
+        end
+      end
+    end
+  end
+end.run!
+```
+
+**Gotchas**
+
+- Per-row buttons **must** carry `key:` (Law 1). Without it the derived ids are
+  position-stable only, and a delete or a filter shifts them under you.
+- `on_success:` is **required** for standalone `form_for` (no `resource` block to fall
+  back to for the post-submit transition).
+- Standalone `form_for` derives its flash noun by stripping `_form` from `name:`, so
+  `:todo_1_form` flashes `"Todo_1 updated."` — cosmetic, known, unfixed.
+- Inside a `resource` block the shorter form works and the transition is free:
+  `form_for :todo, record: todo do submit_label 'Save' end`.
+
+### 2. Scoped live search (submit-as-you-type)
+
+`text_field` auto-submits on input — no Stimulus controller, no debounce code. The only
+decision is **where the field lives**, and it is a real trade-off:
+
+```ruby
+# Add to TodoStore. The blank guard is load-bearing -- see gotchas.
+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
+
+app 'Search' do
+  # B -- field INSIDE the fragment: scoped morph, fewer bytes, focus and caret
+  # survive. Cost: the field re-renders itself on every keystroke.
+  fragment(:results) do
+    text_field :query, placeholder: 'Filter todos…'
+    results = TodoStore.search(state[:query])
+    text "#{results.length} of #{TodoStore.all.length} todos"
+    results.first(8).each { |t| text "• #{t[:title]}" }
+  end
+end.run!
+```
+
+**Gotchas**
+
+- **`text_field :query, updates: :results` is silently accepted and silently ignored.**
+  This is the natural transliteration of Rails' `data: {turbo_frame: :todos}` and it looks
+  right; `updates:` is read only by `button` and `clickable`. There is no
+  `data-turbo-frame` equivalent for inputs yet.
+- Consequently an input can target only its own enclosing fragment or `#app-container`.
+  **A field placed outside the results fragment swaps the whole container** — it works and
+  filters correctly, it just costs the whole body every keystroke. Prefer arrangement B
+  above unless you specifically need the field to never re-render itself.
+- Guard the blank query in your store (`return all if query.to_s.strip.empty?`) or
+  clearing the box makes the whole list vanish.
+- Search is a GET filter, so put the query in the URL via `route_with` if you want it
+  shareable.
+
+### 3. Lazy hover cards (CSS reveals it; revealing it is what fetches it)
+
+Nothing on the page fetches anything until the pointer arrives. Three lines of CSS plus
+`lazy: true` — the two halves interlock.
+
+```ruby
+# Each todo carries a :user_id; UserStore is any lookup, deliberately slow here
+# so "eager or lazy?" is observable.
+module UserStore
+  USERS = { 'u1' => { id: 'u1', name: 'Ada Lovelace', role: 'Engineering' },
+            'u2' => { id: 'u2', name: 'Alan Turing',  role: 'Research' } }.freeze
+  def self.find(id) = USERS[id]
+end
+
+app 'Directory' do
+  use_stylesheet <<~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
+
+  TodoStore.all.each do |todo|
+    user = UserStore.find(todo[:user_id])
+    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
+          card do
+            header3 user[:name]
+            text user[:role]
+          end
+        end
+      end
+    end
+  end
+end.run!
+```
+
+**Gotchas**
+
+- **Key by the todo, not the user.** Two todos sharing an assignee would emit the same
+  fragment name twice; hovering the second shows the first one's card, silently. This is
+  Law 1 in its purest form.
+- `display: none` means no fetch, for as long as it lasts — that is the guarantee that
+  makes six cards cost zero on page load. Don't hide the panel with `visibility: hidden`
+  or `opacity: 0`; those stay visible to the observer and every card fetches eagerly.
+- It fetches **once**. Hover away and back and the landed content stays put.
+- To verify laziness: `document.querySelectorAll('.sw-fragment-lazy').length` counts
+  fragments that have *not* fetched yet.
+
+### 4. Russian-doll infinite scroll (nested lazy fragments)
+
+**The page the reader is on renders in the shell; only the NEXT page is lazy.** Page N's
+rows go out inline, and its block ends by declaring page N+1 as a lazy fragment whose own
+block recurses. Page N+1 does not exist in the DOM — and never fetches — until page N has
+been scrolled past. That recursion is the entire pagination logic: no scroll handler, no
+page counter in state, no "Load more" button.
+
+```ruby
+# One page's slice -- never everything-so-far. Empty return terminates the chain.
+TodoStore::PER_PAGE = 10
+def TodoStore.page(number) = all.drop(([number.to_i, 1].max - 1) * PER_PAGE).first(PER_PAGE)
+
+def scroll_page(number)
+  # THIS page renders now, in whatever response we're already writing.
+  TodoStore.page(number).each { |t| card { text t[:title] } }
+
+  # Only the NEXT page is deferred. The guard is load-bearing: without it the
+  # chain dead-ends in an empty fragment that fetches nothing.
+  nxt = number + 1
+  unless TodoStore.page(nxt).empty?
+    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!
+```
+
+**Gotchas**
+
+- **Do not wrap page 1 in the lazy fragment.** Writing
+  `fragment(:"page_#{number}", lazy: true) { rows; recurse }` and calling it with `1` is
+  the tempting shape and it is wrong: the block is skipped on the shell render (see the
+  three rules above), 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, so
+  the observer fires immediately. A lazy fragment already in the viewport fetches at once,
+  which is exactly what hides this mistake. Render the current page, lazy the next one —
+  that is also what Turbo does, and it is what keeps the shell honest for crawlers, for a
+  reader with no JavaScript, and for anyone reading the served HTML.
+- Have the store return **one page's slice** (`all.drop((n - 1) * PER_PAGE).first(PER_PAGE)`),
+  never everything-so-far. Each response should be a constant size; if payloads grow
+  per page, you're re-sending rows.
+- Each fetch re-runs its ancestors' blocks, so keep per-page work cheap. Nested ids are
+  `parent--child`: page 2's fragment is declared beside page 1's rows, so it is
+  `sw-frag-page-2`; page 3's is declared inside page 2's block, giving
+  `sw-frag-page-2--page-3`.
+- **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 waits until that tab is opened:
+
+  ```ruby
+  tabs :view, url: true do
+    tab('Summary') { text summary_line }
+    tab('Revenue') { fragment(:revenue, lazy: true) { revenue_table } }
+  end
+  ```
+
+---
+
+## Anti-patterns (each one has bitten someone)
+
+- **`defer { ... }`** — the bare verb is not the deferred primitive. It now raises and
+  names the real one: `fragment(:name, defer: true)`.
+- **`every(...)` to refresh a slow region** — that's Law 2. Use `defer:`.
+- **Named-action buttons inside a deferred/lazy fragment** — they don't fire. Block
+  buttons.
+- **Keying by positional index** — `key: i` is exactly the identity that reordering
+  destroys. Key by record id.
+- **`text "**bold**"`** — `text` does not render markdown. Use `md`.
+- **`spacer` / `divider`** — don't exist. `div(style: 'height:24px')`.
+- **`<button onclick="location.href=...">`** — bypasses htmx, full reload, loses state.
+  Use `link_to` / `nav_item` with a real `href`.
+- **Assuming port 4567** — StreamWeaver finds a free port and prints the real URL. Read
+  stdout.
+
+**Catch keying bugs before they ship:** `strict_ids` turns a derived-id collision from a
+warning into a hard failure. It raises in development and test, and degrades to a warning
+in production (a live page shouldn't 500 over an id the framework already disambiguated).
+
+```ruby
+StreamWeaver::App.new('My App', strict_ids: true) { ... }   # per app
+StreamWeaver.strict_ids = true                              # global
+SW_STRICT_IDS=1 ruby my_app.rb                              # env, e.g. in CI
+```
+
+---
+
+## Going deeper (pointers only — these are not summarized here)
+
+**The narrated twin.** `docs/tutorials/the-streamweaver-way.md` — "Build My Todos:
+the StreamWeaver Way" builds these same four features step by step, why-first, each
+step naming the law it obeys, the gotcha it avoids, and the measured number. This
+skill prescribes; the tutorial explains. Point a human at the tutorial. Also runs as
+a `:doc`-theme app: `SW_NO_OPEN=1 ruby examples/tutorials/streamweaver_way_tutorial.rb`.
+
+**The worked example set.** `examples/my_todos/` is all four recipes above in one running
+app, annotated with the Rails mechanism each one mirrors. Boot it with
+`SW_NO_OPEN=1 ruby examples/my_todos/my_todos.rb`, and `SW_HOVERCARD_DELAY=1.5` to feel
+the difference lazy makes.
+
+**`llms.txt` (aliased as `docs/for_llms.md`)** — the full DSL reference. Sections that
+extend this skill, by name:
+
+| Section | What it adds |
+|---|---|
+| Interactive IDs and keying | Full precedence rules, `strict_ids`, `clickable` |
+| Record-Bound Forms (`form_for`) | Every option, in-block DSL, validation semantics |
+| Turbo Frame-Style Inline Editing with `form_for` | The `resource`-based variant of recipe 1 |
+| Deferred Fragments (`fragment ..., defer: true`) | Placeholders, nesting, export behavior |
+| Lazy Fragments (`fragment ..., lazy: true`) | Both guarantees, and all three recipes |
+| Dev Loud, Prod Self-Heal | What the overlay names, and what it can't detect |
+| Resource Scaffolding | `resource` CRUD, named-route helpers |
+| Route Tabs (`tabs url: true`) | Deep-linkable tabs, URL authority ordering |
+| Repo Conventions | The full anti-pattern list |
+
+**Reference docs.** `docs/resource-dsl.md` (`resource` + `form_for` full reference),
+`docs/routing.md` (**read Common Pitfalls before any app with more than a couple of
+routes**), `docs/crud-patterns.md`, `docs/components_reference.md`.
+
+**Decision docs — read when you want the *why*, or are extending the primitive.**
+`docs/research/streamweaver-way-spike-findings.md` (what broke 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).
+
+**Sibling skills.** `streamweaver-visual-companion` for mockups, diagrams, and dashboards
+you just want to look at; `streamweaver-doc-builder` for long-form editorial documents.
+This skill is for apps people interact with.

data/lib/stream_weaver/skills/visual-plan/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: visual-plan
+description: Use before starting any non-trivial implementation task — renders a live canvas showing the implementation map, open decisions, and wireframes so the user can sign off before code is written
+---
+
+# Visual Plan
+
+Pre-flight planning via StreamWeaver canvas. Push a live plan showing what will change and why, flag open decisions, and block for sign-off on anything that needs user input — all before touching any code.
+
+## When to Use
+
+Before any task where:
+- Multiple files will change
+- An architecture decision is open (database choice, API shape, component structure)
+- A UI surface is being added or significantly reworked
+- The user said "show me the plan first"
+
+Skip for trivial edits (one-line fix, rename, config change) — overhead exceeds value.
+
+## !! DO NOT LAUNCH STANDALONE SERVERS PER QUESTION !!
+
+Same rule as the visual companion: **never** run `ruby app.rb` or `streamweaver <file.rb>` for each planning update. Use `canvas-push` to update a single persistent window throughout the session.
+
+## Starting a Plan Session
+
+```bash
+# Open a named canvas panel — opens in iTerm2 split pane, or browser tab elsewhere
+streamweaver panel plan
+
+# Push the initial plan content
+streamweaver canvas-push plan <<'RUBY'
+  header1 "Implementation Plan"
+
+  implementation_map(files: [
+    { path: "lib/foo/bar.rb",      note: "Add #process method for new pipeline step" },
+    { path: "lib/foo/pipeline.rb", note: "Wire bar into pipeline chain" },
+    { path: "spec/foo/bar_spec.rb", note: "Cover happy path and nil input edge case" }
+  ])
+
+  decision(question: "Should bar be stateless or hold config?") do
+    option(id: :stateless, label: "Stateless",
+           detail: "Simple — take config as args each call. Easy to test.",
+           recommended: true)
+    option(id: :stateful,  label: "Stateful",
+           detail: "Holds config in instance. Needed if config is expensive to build.")
+  end
+RUBY
+```
+
+Tell the user: "Check the plan canvas at [url]. Let me know in the terminal if you want to adjust anything."
+
+## The Planning Loop
+
+1. Push the full plan canvas (files + decisions + wireframes)
+2. Tell the user the canvas URL, end your turn
+3. User reviews and responds in the terminal
+4. If a decision needs sign-off: use `canvas-wait` (see below) to block until they click
+5. Once approved: start implementation; push progress updates to the same canvas
+
+**The canvas stays open while you implement.** Push updates as files change.
+
+## DSL Reference
+
+### `implementation_map` — what files change and why
+
+```ruby
+implementation_map(files: [
+  { path: "lib/payments/processor.rb", note: "Add retry logic for network errors" },
+  { path: "lib/payments/errors.rb",    note: "New RetryableError class" },
+  { path: "spec/payments/processor_spec.rb", note: "Cover retry behavior" }
+])
+```
+
+`note:` should explain the why, not the what ("Add retry logic" not "modify method").
+
+### `decision` — open architecture choices
+
+```ruby
+decision(question: "Which caching layer?") do
+  option(id: :redis,   label: "Redis",    detail: "Shared, fast, extra infra dep", recommended: true)
+  option(id: :memory,  label: "In-memory", detail: "Zero dep, lost on restart")
+  option(id: :none,    label: "No cache",  detail: "Simplest — acceptable if <50ms")
+end
+```
+
+Mark the option you'd choose `recommended: true`.
+
+### `callout(:decision)` — tradeoff flags inline
+
+```ruby
+callout(variant: :decision, title: "Auth approach affects test setup") do
+  text "If we use JWT here, the test helpers need to generate tokens — adds ~30 lines to spec/support."
+  text "If we use session cookies, existing test helpers work as-is."
+end
+```
+
+Use for tradeoffs that don't need a full option matrix — a constraint, an implicit choice, a flag for the user.
+
+### `callout(:risk)` — things that could go wrong
+
+```ruby
+callout(variant: :risk, title: "Migration is irreversible") do
+  text "DROP COLUMN is non-reversible in production without a new migration."
+  text "Confirm data is not needed before proceeding."
+end
+```
+
+Use for anything that could bite silently: data loss, breaking changes, non-idempotent operations, external API calls with side effects.
+
+### `wireframe` — UI mockups for new surfaces
+
+```ruby
+wireframe(surface: :browser) do
+  <<~HTML
+    <div class="wf-card">
+      <h2>Invoice #1042</h2>
+      <p class="wf-muted">Due 2026-07-01</p>
+      <button class="primary">Pay now</button>
+    </div>
+  HTML
+end
+```
+
+Surfaces: `:browser`, `:desktop`, `:mobile`, `:phone`, `:tablet`, `:popover`, `:card`, `:widget`, `:panel`.
+
+Use for UI stories where the layout matters. Skip if the change is purely logic or data.
+
+### Combining components
+
+```ruby
+streamweaver canvas-push plan <<'RUBY'
+  header1 "Plan: Add Invoice Detail Page"
+
+  implementation_map(files: [
+    { path: "app/controllers/invoices_controller.rb", note: "Add #show action" },
+    { path: "app/views/invoices/show.html.erb",       note: "New view" },
+    { path: "spec/controllers/invoices_controller_spec.rb", note: "Cover show + 404" }
+  ])
+
+  decision(question: "Render total in controller or view?") do
+    option(id: :controller, label: "Controller",   detail: "Testable, consistent", recommended: true)
+    option(id: :view,       label: "View helper",  detail: "Less boilerplate if reused")
+  end
+
+  callout(variant: :risk, title: "Invoice data includes PII") do
+    text "Confirm auth check on #show — anonymous access must 403, not 404."
+  end
+
+  wireframe(surface: :browser) do
+    '<h1>Invoice #1042</h1><p class="wf-muted">$240.00 due</p><button class="primary">Pay</button>'
+  end
+RUBY
+```
+
+## Blocking for Sign-Off with `canvas-wait`
+
+When a decision needs explicit user approval before you proceed, add interactive controls and wait:
+
+```bash
+streamweaver canvas-push plan <<'RUBY'
+  header2 "Approve to continue"
+  radio_group :db_choice, ["PostgreSQL (recommended)", "SQLite", "Needs more discussion"]
+  button "Approve and proceed"
+RUBY
+
+# Blocks until user clicks the button — prints JSON with their selection
+result=$(streamweaver canvas-wait plan)
+echo "User chose: $result"
+```
+
+`canvas-wait` returns JSON: `{"type":"action","element":"button","value":"Approve and proceed","state":{"db_choice":"PostgreSQL (recommended)"}}`.
+
+Use when the decision changes the implementation path, is hard to reverse, or the user should weigh in before code is written. Skip for low-stakes choices — don't block when the user can redirect in the next turn.
+
+## Updating the Canvas During Implementation
+
+Once approved, keep the canvas live as work progresses:
+
+```bash
+# After each file is written
+streamweaver canvas-push plan <<'RUBY'
+  header1 "Implementation Plan — In Progress"
+
+  implementation_map(files: [
+    { path: "lib/foo/bar.rb",       note: "[done]" },
+    { path: "lib/foo/pipeline.rb",  note: "[wip]" },
+    { path: "spec/foo/bar_spec.rb", note: "[pending]" }
+  ])
+RUBY
+```
+
+The user sees live status without having to ask. The plan evolves from "what will change" to "what has changed."
+
+## Known Gotchas
+
+- **`undefined method` errors on new components** — the canvas bridge may be an orphaned process from a previous session running older code. Fix: `streamweaver canvas-stop && streamweaver panel plan`. The fresh bridge picks up the latest gem code.
+- `spacer` and `divider` don't exist — use `div(style: "height:Npx")`
+- `text` does not render markdown — use `md` for bold/italic/links
+- `decision` block scope: only `option(...)` calls are valid inside it — other DSL methods throw
+- StreamWeaver auto-selects an available port — capture the URL from stdout, don't hardcode 4567
+- Canvas sessions default to `:fluid` (full-width) — good for wide implementation maps; use `--layout=default` for a narrower card