stream_weaver 0.3.0

data/docs/resource-dsl.md

@@ -0,0 +1,342 @@
+# StreamWeaver Resource DSL
+
+Convention-over-configuration CRUD scaffolding. One `resource` block replaces 30–50 lines of route/state/form boilerplate.
+
+---
+
+## Quick Start
+
+```ruby
+require 'stream_weaver'
+
+module PostStore
+  @posts = [{ id: '1', title: 'Hello', body: 'First post', status: 'published' }]
+  def self.all;        @posts; end
+  def self.find(id);   @posts.find { |p| p[:id] == id }; end
+  def self.create(attrs)
+    id = ((@posts.map { |p| p[:id].to_i }.max || 0) + 1).to_s
+    @posts << { id: id, **attrs }; id
+  end
+  def self.update(id, attrs); post = find(id) or return false; post.merge!(attrs); true; end
+  def self.destroy(id);       @posts.reject! { |p| p[:id] == id }; true; end
+end
+
+app 'Blog' do
+  page :home, '/' do
+    header1 'My Blog'
+  end
+
+  resource :post, store: PostStore do
+    field :title,  :string
+    field :body,   :text
+    field :status, :enum, values: %w[draft published]
+  end
+end.run!
+```
+
+That single `resource` block gives you:
+
+| URL | Action |
+|---|---|
+| `GET /posts` | Index — table with View / Edit / Delete per row |
+| `GET /posts/new` | New — form with field inputs, Create button |
+| `GET /post/:id` | Show — card with field values, Edit / Delete buttons |
+| `GET /post/:id/edit` | Edit — form seeded from record, Save button |
+| Delete button | Inline confirmation alert, then destroys record |
+
+All URLs are deep-linkable and browser back/forward works.
+
+---
+
+## DSL Reference
+
+### `resource`
+
+```ruby
+resource :name, store: MyStore, plural: 'custom_plural' do
+  # field, edit_view, new_view, only, except, override blocks
+end
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `store:` | required | Object responding to store protocol (see below) |
+| `plural:` | `"#{name}s"` | Override pluralization for irregular nouns |
+
+**Declare `page` / `route` calls before `resource` blocks.** The routing chain is first-registered-wins; static page routes must appear before resource collection/member routes.
+
+---
+
+### `field`
+
+```ruby
+field :name, :type
+field :name, :type, values: [...]   # for :enum
+```
+
+| Type | Input component rendered |
+|---|---|
+| `:string` | `text_field` |
+| `:text` | `text_area` (4 rows) |
+| `:enum` | `select` with `values:` list |
+| `:boolean` | `checkbox` |
+| `:integer` / `:number` | `text_field` |
+| `:date` | `text_field` |
+
+---
+
+### `edit_view` / `new_view`
+
+```ruby
+edit_view :page    # URL-addressable /resource/:id/edit (default: :modal)
+new_view  :page    # URL-addressable /resource/new    (default: :modal)
+```
+
+---
+
+### `only` / `except`
+
+```ruby
+only   %i[index show]        # whitelist actions
+except %i[destroy]           # blacklist actions
+```
+
+Default set: `[:index, :show, :new, :edit, :destroy]`
+
+---
+
+### Override Blocks
+
+Fully replace any default view. Block runs in App context (`instance_exec`).
+
+```ruby
+resource :goal, store: GoalStore do
+  field :title,   :string
+  field :horizon, :enum, values: %w[month quarter year]
+
+  index do |goals|
+    header1 'Goals'
+    goals.group_by { |g| g[:horizon] }.each do |horizon, gs|
+      header3 horizon.capitalize
+      table gs do
+        column :title
+      end
+    end
+  end
+
+  show do |goal|
+    card { header3 goal[:title]; text goal[:horizon] }
+  end
+end
+```
+
+| Block | Receives | Replaces |
+|---|---|---|
+| `index do \|items\|` | Array of all records | Default index table |
+| `show do \|item\|` | Single record hash | Default show card |
+| `new do \|_\|` | nil | Default new form |
+| `edit do \|item\|` | Single record hash | Default edit form |
+
+App ivars (`@current_form`, `@form_context`) are saved before the block runs and restored after, preventing bleed-through.
+
+---
+
+### `page` and `route`
+
+```ruby
+page :home, '/' do
+  header1 'Welcome'
+end
+
+route :about, '/about'   # same as page with empty block
+```
+
+Declares a static named route. Renders the block when the current URL matches. Use before `resource` blocks.
+
+---
+
+### `form_for`
+
+A resource-bound form primitive: seeds fields from a record, infers create vs. update
+from record identity, renders inputs via the shared field-type table, and wires submit
+to coerce → validate → `store.create`/`update` → flash + PRG. It's what `resource`'s own
+default `new`/`edit` views call under the hood — `form_for` exposes the same machinery
+for use inside your own override blocks.
+
+```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
+
+  new do
+    header1 "New Person"
+    form_for :person do
+      submit_label "Create"
+    end
+  end
+end
+```
+
+| Argument | Default | Description |
+|---|---|---|
+| `resource_name` | `nil` | A registered `resource` name — reuses its `store:`/`fields:` |
+| `record:` | `nil` | The record being edited. `nil`, or an id-less hash, means create mode |
+| `store:` | resource's store | Required if `resource_name` is omitted |
+| `fields:` | resource's fields | Required if `resource_name` is omitted |
+| `name:` | `"#{singular}_form"` | Scope/form name override |
+| `on_success:` | resource's default transition | `Proc`, `instance_exec`'d with the new/updated id |
+| `validate:` | `nil` | `Proc`, called with coerced values, returns `Hash[field, Array[String]]` of extra errors |
+
+Can also be used standalone, without a `resource` block, by passing `store:`/`fields:`
+directly:
+
+```ruby
+form_for store: PersonStore, fields: [
+  StreamWeaver::Field.new(:name, :string, {}),
+  StreamWeaver::Field.new(:age, :integer, {})
+], name: :person_form
+```
+
+**Create vs. update inference** — a `nil` `record:`, or a `record:` whose `:id` is nil,
+means create; a present record with an id means update. This also sets the default
+submit label (`"Create"` / `"Save"`).
+
+**Seeding and dirty-draft safety** — the form's scope is seeded from `record:` only on
+the first render for that record id, and never re-seeded on subsequent re-renders for
+the same id — an unrelated re-render (a sidebar filter, a toast dismiss) never clobbers
+an in-progress edit. Switching to a different record id (e.g. navigating from editing
+person `1` to editing person `2`) re-seeds fresh, so there's no cross-record leakage.
+
+**Validation** — coercion failures (`:integer`/`:number` fields that don't parse) and any
+`validate { }` block errors both populate `state[:"#{name}_form_errors"]`, rendered as a
+single `Alert(variant: :error)` summary above the fields. A validation failure is a
+same-request re-render, not a redirect — the user's just-typed values stay in the scope
+and the store is never called.
+
+**Success** — on a valid submit, `form_for` calls `store.create`/`store.update`, sets
+`flash[:notice]`, and transitions to the resource's `show` action (or `index` if the
+resource doesn't declare `show`) with the URL pushed via the existing PRG mechanism.
+Pass `on_success:` to override the transition — required for standalone (non-`resource`)
+usage, which has no resource action to fall back to.
+
+**In-block DSL** — inside the `form_for do ... end` block:
+
+| Call | Effect |
+|---|---|
+| `submit_label "text"` | Overrides the default submit button label |
+| `cancel_label "text"` | Adds a Cancel button (omitted by default) |
+| `validate { \|values\| ... }` | Registers the extra validation hook described above |
+| any other field/component call | Renders alongside the auto-generated fields, inside the same form |
+
+All three (`submit_label`/`cancel_label`/`validate`) raise if called outside a `form_for`
+block.
+
+**Inline-edit example** — the course's [Turbo Frame inline-editing pattern](for_llms.md#turbo-frame-style-inline-editing-with-form_for)
+(click a title to edit it in place, submit swaps back to the display view) is a direct
+`form_for` use case; see `docs/for_llms.md` for the worked example.
+
+---
+
+## Named-Route Helpers
+
+Defined automatically on the App instance when `resource :post` is declared:
+
+| Helper | Returns |
+|---|---|
+| `posts_path` | `"/posts"` |
+| `new_post_path` | `"/posts/new"` |
+| `post_path(rec)` | `"/post/#{rec[:id]}"` |
+| `edit_post_path(rec)` | `"/post/#{rec[:id]}/edit"` |
+
+For irregular plurals (`plural: 'people'` on `:person`), helpers use the overridden plural: `people_path`, `new_person_path`, etc.
+
+---
+
+## Store Protocol
+
+Stores are duck-typed. Any object (module, class, instance) that responds to these five methods works:
+
+| Method | Signature | Return |
+|---|---|---|
+| `all` | `()` | Array of record hashes |
+| `find` | `(id)` | Record hash or nil |
+| `create` | `(attrs_hash)` | New record id (String) |
+| `update` | `(id, attrs_hash)` | true / false |
+| `destroy` | `(id)` | true / false |
+
+Records are plain hashes with a symbol `:id` key. StreamWeaver validates the store at app startup (not at request time) and raises `ArgumentError` with a clear message listing missing methods.
+
+---
+
+## State Schema (`_sw_` Namespace)
+
+The `_sw_` prefix is reserved. Do not use `state[:_sw_*]` keys in your own code.
+
+| Key | Values | Meaning |
+|---|---|---|
+| `state[:_sw_action]` | `:index`, `:show`, `:new`, `:edit`, page name sym | Current action |
+| `state[:_sw_resource]` | `:post`, `:goal`, etc. / `nil` | Active resource (nil for pages) |
+| `state[:_sw_id]` | String id / nil | Selected record |
+| `state[:_sw_action]` `:destroy_confirm` | — | Delete confirmation (routed via `GET /singular/:id/delete`) |
+| `state[:"#{singular}_form"]` | Hash | Form state (managed by `form` DSL) |
+
+Use `state[:_sw_resource]` and `state[:_sw_action]` in navbar `active:` checks:
+
+```ruby
+navbar do
+  nav_item 'Posts', href: posts_path, active: state[:_sw_resource] == :post
+  nav_item 'Home',  href: '/',        active: state[:_sw_action]   == :home
+end
+```
+
+---
+
+## Route Precedence
+
+Routes are first-registered-wins. Recommended declaration order:
+
+1. `page` / `route` (static exact-match routes)
+2. `resource` blocks (collection then member patterns)
+3. Manual `route_with` rules
+
+```ruby
+app 'Example' do
+  page :home, '/'         # declared first — matched first
+
+  resource :post, store: PostStore do  # declared after page
+    field :title, :string
+  end
+end.run!
+```
+
+---
+
+## Default View Behavior
+
+When no override block is provided:
+
+**Index** — renders a `header1` with the plural name, a "New" button, and a `table` with one column per field plus an actions column with View / Edit / Delete links per row. Delete links navigate to `/singular/:id/delete`.
+
+**Show** — renders a `card` with `header3` (value of first field), one `text` line per field, and an hstack with Edit and Delete buttons. Delete navigates to `/singular/:id/delete`.
+
+**Destroy confirm** — renders a warning `alert` prompting confirmation. "Confirm Delete" calls `store.destroy` and transitions to `:index`; "Cancel" returns to `:index`.
+
+**New** — renders `header1 "New ..."` and a `form` block with inputs auto-generated from field types. Submit calls `store.create`, then transitions to `:show` for the new record.
+
+**Edit** — renders `header1 "Edit ..."`, seeds form state from the record on first load (guarded by a seeded-for key to prevent reset on every re-render), same form inputs as new. Submit calls `store.update`, transitions to `:show`.
+
+---
+
+## Complete Example with Override
+
+See `examples/scaffolding/blog.rb` for a zero-dependency smoke test (~50 lines).
+
+See `examples/scaffolding/utf_lite.rb` for a multi-resource app with a custom index override and `edit_view :page`.

data/docs/routing.md

@@ -0,0 +1,302 @@
+# StreamWeaver URL Routing
+
+StreamWeaver supports URL-addressable views — deep links, browser back/forward, and bookmarkable URLs — without adding a router library. Two mechanisms are available depending on complexity.
+
+**Not looking for state routing?** Everything on this page maps a URL path to *state* — the same StreamWeaver view still renders, just seeded differently. If you need a genuine HTTP endpoint (webhook receiver, JSON API, file download) that bypasses StreamWeaver's page rendering entirely, see [`docs/endpoints.md`](endpoints.md) (`endpoint` DSL) instead.
+
+## How It Works (Internals)
+
+StreamWeaver uses a bidirectional URL ↔ state contract:
+
+- **On GET `/*`**: The path is parsed into a partial state hash and merged into session state before render. This seeds the right view on direct URL load.
+- **After POST actions**: The current state is converted to a path and sent as `HX-Push-Url`, updating the browser URL bar without a full page load.
+
+This means **routing is just state**. A URL like `/goals` means `state[:main_nav] = 2`. A URL like `/initiative/init-001` means `state[:main_nav] = 2, state[:initiative_id] = "init-001"`.
+
+---
+
+## `route_by` — Simple Key→Path Mapping
+
+For apps with a single state key driving navigation (tab switchers, simple page routers):
+
+```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 render_home
+  when :dashboard then render_dashboard
+  when :settings  then render_settings
+  end
+end.run!
+```
+
+**How it works:** `route_by :page, home: "/"` creates a bidirectional map. When `state[:page]` changes (button callback or nav click), StreamWeaver emits `HX-Push-Url: /` automatically. Visiting `/dashboard` directly seeds `state[:page] = :dashboard` before render.
+
+**Limitation:** One state key only. Doesn't handle parameterized paths like `/initiative/:id`.
+
+---
+
+## `route_with` — Bidirectional Parser/Builder
+
+For apps with parameterized routes, multi-key navigation state, or complex URL structures. Requires two lambdas:
+
+- **`parser`**: `path → partial_state_hash | nil` — called on every GET request, **and now also re-run against the requesting tab's own current URL before every htmx POST** (see Pitfall 3). Returns a hash to merge into state, or `nil` to pass through.
+- **`builder`**: `current_state → path_string | nil` — called after every POST action. Returns the new path to push, or `nil` to leave the URL unchanged.
+
+### Example: UTF Dashboard
+
+```ruby
+app "UTF Dashboard", layout: :full do
+  route_with(
+    parser: lambda do |path|
+      case path
+      when '/', ''
+        { main_nav: 0 }
+      when '/tasks'
+        { main_nav: 1 }
+      when '/goals'
+        { main_nav: 2 }
+      when '/secretaries'
+        { main_nav: 3 }
+      when %r{\A/secretary/([^/]+)\z}
+        { main_nav: 3, secretary_name: CGI.unescape(Regexp.last_match(1)) }
+      when '/sessions'
+        { main_nav: 4 }
+      when %r{\A/task/([^/]+)\z}
+        { main_nav: 0, view_task_id: CGI.unescape(Regexp.last_match(1)) }
+      when %r{\A/initiative/([^/]+)/surface/([^/]+)\z}
+        { main_nav: 2,
+          initiative_id: CGI.unescape(Regexp.last_match(1)),
+          surface_id: CGI.unescape(Regexp.last_match(2)) }
+      when %r{\A/initiative/([^/]+)\z}
+        { main_nav: 2, initiative_id: CGI.unescape(Regexp.last_match(1)) }
+      else
+        nil
+      end
+    end,
+
+    builder: lambda do |current_state|
+      if current_state[:view_task_id].to_s.strip != ''
+        "/task/#{CGI.escape(current_state[:view_task_id].to_s)}"
+      elsif current_state[:secretary_name].to_s.strip != ''
+        "/secretary/#{CGI.escape(current_state[:secretary_name].to_s)}"
+      elsif current_state[:initiative_id].to_s.strip != ''
+        "/initiative/#{CGI.escape(current_state[:initiative_id].to_s)}"
+      else
+        case current_state[:main_nav].to_i
+        when 1 then '/tasks'
+        when 2 then '/goals'
+        when 3 then '/secretaries'
+        when 4 then '/sessions'
+        else '/'
+        end
+      end
+    end
+  )
+
+  # ... app body
+end
+```
+
+### Parser Rules
+
+- Return a **hash** to merge into state (only the keys you want to set, not the full state) —
+  **merge, not replace**: any key you don't mention keeps whatever value a *previous* request
+  left in session state. See "Common Pitfalls" below before relying on this for anything beyond
+  a single-view app.
+- Return `nil` to indicate "this path isn't handled by me" — Sinatra will 404
+- Always `CGI.unescape` captured path segments before storing in state
+- Match most-specific patterns first (`:id/surface/:sid` before `:id`)
+
+### Builder Rules
+
+- Return a **path string** (starting with `/`) to push to the browser history
+- Return `nil` to leave the URL unchanged (good for transient state like modal open/close)
+- Check priority: specific context (task detail, initiative detail) before generic tabs
+- Always `CGI.escape` state values interpolated into paths
+
+---
+
+## URL Parameters vs State
+
+Query params (`?key=value`) are automatically synced to state on every GET request via `sync_params_to_state`. You can use them alongside path-based routing:
+
+```
+GET /goals?filter=active
+# → state[:main_nav] = 2 (from path parser)
+# → state[:filter] = "active" (from query param sync)
+```
+
+---
+
+## Navigating Programmatically
+
+To trigger URL updates from button callbacks, just update the state key that the builder watches:
+
+```ruby
+button "View Initiative" do |s|
+  s[:initiative_id] = "init-042"  # builder will push /initiative/init-042
+  s[:main_nav] = 2
+end
+```
+
+No explicit redirect needed — the `after` hook calls `path_for_state` on every POST response automatically.
+
+---
+
+## Edit Routes (CRUD Pattern)
+
+For edit views (`/initiative/:id/edit`), add an edit flag to the route:
+
+```ruby
+# In parser:
+when %r{\A/initiative/([^/]+)/edit\z}
+  { main_nav: 2, initiative_id: CGI.unescape(Regexp.last_match(1)), editing_initiative: true }
+
+# In builder:
+elsif current_state[:initiative_id].to_s.strip != '' && current_state[:editing_initiative]
+  "/initiative/#{CGI.escape(current_state[:initiative_id])}/edit"
+elsif current_state[:initiative_id].to_s.strip != ''
+  "/initiative/#{CGI.escape(current_state[:initiative_id])}"
+```
+
+---
+
+## Common Pitfalls
+
+Three bug classes that show up in any sufficiently large `route_with` app (found in practice in an
+app with ~20 branches and 15 tabs). The first two come from the same source: a `case`/`when` route
+table that isn't exhaustive in one direction or the other. The third is architectural: session
+state is one hash per browser, not per tab.
+
+### Pitfall 1 — a narrow branch leaks a previous view's state
+
+Because parser results are **merged** into session state, not replaced, a branch that only sets
+its own key(s) leaves every other stateful key exactly as an earlier request left it:
+
+```ruby
+# BAD — only sets main_nav; any special-view flag set by a PRIOR request survives untouched
+when "/messages"
+  { main_nav: MESSAGES_TAB_INDEX }
+```
+
+If some other branch earlier set `view_task_id` (a "show this one task, bypass the tab board"
+flag) and your render logic checks `view_task_id` before `main_nav`, navigating to `/messages`
+after having visited `/task/:id` renders the stale task view, not Messages — the URL you're on
+is not what's on screen. This is easy to miss because it's **intermittent**: it only reproduces
+when a session has visited the leaking view before, so it looks like flakiness rather than a
+routing bug.
+
+**Fix**: define one frozen hash listing every "special view" key with its off value, and have
+every branch merge its own keys on top of it, not just `nil`/base-hash-free literals:
+
+```ruby
+SPECIAL_VIEW_RESET = { view_task_id: nil, messages_view_stream: nil, checkin_slug: nil, ... }.freeze
+
+when "/messages"
+  SPECIAL_VIEW_RESET.merge(main_nav: MESSAGES_TAB_INDEX)
+```
+
+Adding a new special view later means adding one key to the list, not remembering to touch every
+existing branch.
+
+### Pitfall 2 — an uncovered `case`/`when` value fails silently, in both directions
+
+A `case current_state[:main_nav].to_i` (or any keyed dispatch) with `when` clauses that don't
+cover every value your app actually uses returns `nil` on the uncovered values — and `nil` from
+a builder means **"leave the URL unchanged"** (see Builder Rules above), not an error. The
+symptom is not a crash, it's silence: clicking a tab that maps to an uncovered index changes what
+renders but never touches the URL bar, so it looks like the click "didn't do anything" to the
+address bar specifically. The same gap on the parser side means the corresponding path never
+seeds that index into state, so a direct GET to a URL nobody wrote a `when` for either falls
+through to `nil` (404) or, if it matches a *different* branch that doesn't set `main_nav` at all
+(e.g. bare `/` only clearing special-view flags), inherits whatever `main_nav` a previous request
+left behind.
+
+**Fix**: audit the full index/key range your app actually dispatches on and confirm every value
+has a `when` clause on **both** the parser and the builder — not just the branch that was
+reported broken. In practice this bug hunts in pairs: if one branch of a route table is
+incomplete, check the others before considering it fixed.
+
+### Pitfall 3 — one session, many tabs
+
+`parser` only ran on GET, so a "special view" flag it sets (Pitfall 1's `SPECIAL_VIEW_RESET`
+pattern) only ever got reset on a real page navigation. Session state is one hash per browser
+(one cookie), not per tab — so once a tab navigated to a dedicated view, that flag stayed true
+for every OTHER tab of the same browser too, and `builder` read the same shared flag on every
+POST from any of them. Symptom: click something in tab A, land on whatever dedicated view tab B
+happens to have open — even a tab that's just sitting in the background, never clicked.
+
+**Fix**: htmx already sends the requesting tab's own on-screen URL on every request
+(`HX-Current-URL`). `parser` is now re-run against that URL — same merge-not-replace GET already
+does — before every htmx POST dispatches, so state gets re-scoped to what THAT tab is actually
+showing before `builder` decides where to push it. A sibling tab's stale flag can't survive
+contact with a real click. A raw (non-htmx) POST has no such header and is left unchanged.
+
+**Consequence for parser authors**: every key your parser returns is now re-asserted on every
+htmx POST, not just at navigation time — put only URL-derived truth in a parser hash, never
+something a POST handler should be free to change without a URL change also occurring.
+
+**Consequence for multi-app (`service.rb`) hosting**: the fix is mount-prefix aware — a URL for
+app A's tab is never applied to app B's state, even though both live in the same session.
+
+## Testing route_with
+
+`route_with`'s parser and builder are plain `path -> hash` / `hash -> path` functions — the
+highest-leverage way to test them is to **extract them out of the inline DSL lambdas** into
+ordinary module methods (e.g. `MyApp::Routing.parse(path)` / `MyApp::Routing.build(state)`), so
+they're unit-testable with no Rack::Test or session harness at all:
+
+```ruby
+parser: ->(path) { MyApp::Routing.parse(path) },
+builder: ->(state) { MyApp::Routing.build(state) }
+```
+
+Then the single most valuable regression test is a **round-trip check over every known path** —
+`build(parse(path)) == path` for each route your app defines. It catches both pitfalls above at
+once: Pitfall 1 shows up as `parse` returning a state hash with leftover keys from nothing (a
+round trip alone won't catch this one directly — pair it with an explicit assertion that
+`parse(path)` matches `SPECIAL_VIEW_RESET.merge(...)` exactly, not just a subset); Pitfall 2
+shows up as `build(parse(path))` returning `nil` or the wrong path for any route whose index
+wasn't wired into the builder's `case`, which is exactly the bug it exists to catch — a route
+that parses fine but never round-trips back to a real URL.
+
+```ruby
+KNOWN_ROUTES = ["/", "/messages", "/task/abc", ...]
+
+KNOWN_ROUTES.each do |path|
+  it "round-trips #{path}" do
+    expect(MyApp::Routing.build(MyApp::Routing.parse(path))).to eq(path)
+  end
+end
+```
+
+Then in the app body:
+
+```ruby
+if state[:editing_initiative] && state[:initiative_id]
+  render_initiative_edit_form(state[:initiative_id])
+elsif state[:initiative_id]
+  render_initiative_detail(state[:initiative_id])
+end
+```
+
+---
+
+## Comparison
+
+| Scenario | Use |
+|---|---|
+| Simple tab nav (one active tab) | `route_by` |
+| Multi-param routes (`/x/:id`, `/x/:id/edit`) | `route_with` |
+| Mixed tab + entity detail | `route_with` |
+| No bookmarkability needed | Neither (omit routing entirely) |