phlex-reactive 0.9.5 → 0.11.0

data/README.md

@@ -233,7 +233,7 @@ rails g phlex:reactive:claude
    └──────── Turbo applies it in ◀──────────────────────────────┘
 
    ...and for OTHER tabs/users:
-   model change → Component.broadcast_replace_to(stream) → pgbus SSE → same morph
+   model change → Component.broadcast_to(stream, replace: model) → pgbus SSE → same morph
 ```
 
 Client actions and server broadcasts **converge on one re-render unit**: the
@@ -326,7 +326,7 @@ The [inline edit example](https://phlex-reactive.zoolutions.llc/docs/example-inl
 | [Cross-tab chat](https://phlex-reactive.zoolutions.llc/docs/example-chat) | Record-backed action **+ pgbus broadcast** → live sync across tabs/browsers |
 | [Live todo list](https://phlex-reactive.zoolutions.llc/docs/example-todo-list) | Per-row components, add/toggle/rename/archive, optimistic toggle + delete, Enter-to-add, broadcast on change |
 | [Inline edit + dirty tracking](https://phlex-reactive.zoolutions.llc/docs/example-inline-edit) | Show ↔ edit toggle plus an "Unsaved" badge + leave-guard, with zero shipped state |
-| [Notifications / badges](https://phlex-reactive.zoolutions.llc/docs/example-notifications) | Pure broadcast — a background event pushes a re-render, plus a `broadcast_js_to` cross-tab pulse |
+| [Notifications / badges](https://phlex-reactive.zoolutions.llc/docs/example-notifications) | Pure broadcast — a background event pushes a re-render, plus a `broadcast_to(js:)` cross-tab pulse |
 | [Reactive collections](https://phlex-reactive.zoolutions.llc/docs/example-collections) | Add/remove rows + a running count + an empty state, declared **once** with `reactive_collection`, optimistic dismiss |
 | [Loading states](https://phlex-reactive.zoolutions.llc/docs/example-loading-states) | `disable_with:` + `busy_on` + `aria-busy`, with a latency toggle to make the pending window visible |
 | [Client-only ops](https://phlex-reactive.zoolutions.llc/docs/example-client-ops) | `on_client` tabs / outside-close menu / accessible drawer — zero fetches, zero custom JS |
@@ -350,11 +350,11 @@ flagship — every feature composed into one believable UI.
 | `.replace(model = nil, morph: false, **opts)` | `<turbo-stream action=replace target=id>` of a freshly built component; `morph: true` adds `method="morph"` |
 | `.update(model = nil, morph: false, **opts)` | `<turbo-stream action=update target=id>` (inner-HTML update); `morph: true` adds `method="morph"` so Turbo morphs the inner HTML in place (issue #113) |
 | `.append(target:)` / `.prepend(target:)` / `.remove` | The other Turbo Stream actions |
-| `.broadcast_replace_to(*streamables, model:, morph: false)` | Broadcast a replace over the stream transport (pgbus SSE / Action Cable); `morph: true` morphs in place |
-| `.broadcast_update_to(*streamables, model:, morph: false)` | Broadcast an inner-HTML update; `morph: true` morphs in place, so a peer editing the component keeps its focus/caret (issue #113) |
-| `.broadcast_append_to(*streamables, target:, model:)` / `_prepend_` / `_remove_` | The other broadcast variants |
-| `.broadcast_replace_to_each(stream_keys, model:, morph: false, exclude:, visible_to:)` / `_update_` / `_append_` / `_prepend_` / `_remove_` | **Render once, fan out** the *same* payload to K different stream keys — a per-tenant loop. K renders + K HMACs collapse to 1 + K cheap channel calls (~9.5× at K=10). Each key is a `[record, :symbol]` pair (or a bare string). Transport opts + `morph:` forward per key. Per-viewer `visible_to:` content stays render-per-call. See [Broadcasting](https://phlex-reactive.zoolutions.llc/docs/broadcasting). |
-| `#to_stream_replace` / `#to_stream_morph` / `#to_stream_remove` | Stream the *already-built* instance (used internally after an action / by `reply`); `#to_stream_morph` morphs in place |
+| `.broadcast_to(*streamables, replace: model, morph: false)` | Broadcast a replace over the stream transport (pgbus SSE / Action Cable); `morph: true` morphs in place |
+| `.broadcast_to(*streamables, update: model, morph: false)` | Broadcast an inner-HTML update; `morph: true` morphs in place, so a peer editing the component keeps its focus/caret (issue #113) |
+| `.broadcast_to(*streamables, append: model, target:)` / `prepend:` / `remove:` | The other broadcast verbs — the verb is a kwarg (exactly one of `replace:`/`update:`/`append:`/`prepend:`/`remove:`/`js:`) |
+| `.broadcast_to(each: stream_keys, replace: model, morph: false, exclude:, visible_to:)` | **Render once, fan out** the *same* payload to K different stream keys — a per-tenant loop. Pass `each:` instead of `*streamables`. K renders + K HMACs collapse to 1 + K cheap channel calls (~9.5× at K=10). Each key is a `[record, :symbol]` pair (or a bare string). Transport opts + `morph:` forward per key. Per-viewer `visible_to:` content stays render-per-call. See [Broadcasting](https://phlex-reactive.zoolutions.llc/docs/broadcasting). |
+| `#to_stream_replace(morph: false)` / `#to_stream_remove` | Stream the *already-built* instance (used internally after an action / by `reply`); `morph: true` morphs in place |
 | `#to_stream_update(morph: false)` | Inner-HTML update of the *already-built* instance; `morph: true` morphs in place (issue #113) |
 
 Use in controllers: `render turbo_stream: Counter.replace(counter)`.
@@ -368,7 +368,7 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 | `action :name, params: { x: :integer }` | Declare a client-invokable action + its param schema. **Default-deny.** |
 | `mark_authorized!` | Inside an action: satisfy the `verify_authorized` guard after a bespoke check the interceptor can't see (a hand-rolled policy). Call it only after your check passes. |
 | `skip_verify_authorized [ :a, :b ]` | Opt a component (bare) or specific actions out of the default-ON `verify_authorized` guard — for a genuinely public component (a counter, a client-only filter). |
-| `reactive_root(**overrides)` | Spread onto the root element: emits the component `id` **and** `reactive_attrs` together, so the controller root always carries `#id`. Preferred over `id:` + `reactive_attrs`. `**overrides` (`class:`/`data:`) deep-merge. |
+| `reactive_root(**overrides)` | Spread onto the root element: emits the component `id` **and** `reactive_attrs` together, so the controller root always carries `#id`. Preferred over `id:` + `reactive_attrs`. `**overrides` (`class:`/`data:`) deep-merge. `compute: :name` binds a client-side compute **at the root** — descriptors plus the `input->reactive#recompute` delegation, so no field needs its own wiring; `nil` collapses to no binding. See [Client-side computes](#client-side-computes-reactive_compute--reactive_text). |
 | `reactive_attrs` | Marks an element reactive + carries the signed token (no `id`). Spread alongside `id:` on the **same** element: `div(id:, **reactive_attrs)`. Prefer `reactive_root`, which can't split them. |
 | `on(:action, event: "click", **params)` | Spread onto a trigger element. Adds `type=button` for clicks. |
 | `on(:action, event: "input", debounce: 300)` | Coalesce rapid events into one round trip after a quiet period (live-as-you-type). |
@@ -384,16 +384,15 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 | `on(:action, once: true)` | Fire at most once, then unbind (Stimulus's native `:once`). |
 | `on_client(:click, js.toggle("#menu"))` | **Client-only** trigger: applies declared DOM ops with ZERO round trip — no token, no POST, ever. Takes the same `window:`/`once:`/`outside:` modifiers. See [Client-only ops](#client-only-ops-on_client--js--zero-round-trips). |
 | `js` | The immutable op builder behind `on_client`: `show`/`hide`/`toggle` (the `hidden` attribute, with an optional `transition:`), `add_class`/`remove_class`/`toggle_class`, `set_attr`/`remove_attr`/`toggle_attr` (allowlisted names), `focus`/`focus_first`, `text` (set `textContent` — XSS-safe), and `dispatch` — chainable. |
-| `reactive_input(:param, **attrs)` / `reactive_select(:param, **attrs)` | Render a control already bound to an action param (no magic `name:`). |
-| `reactive_field(:param, **attrs)` | The attribute hash behind the above — spread onto any control. |
+| `reactive_field(:param, **attrs)` | The attribute hash that binds a control to an action param (no magic `name:`) — spread onto any control: `input(**reactive_field(:value, value: @record.name))`, `select(**reactive_field(:status)) { … }`. |
 | `reactive_text(:name, initial)` | Mirror a compute output (or a declared input) into a **text node** — a live preview heading, a character counter, `"Hello, {name}"` — via `textContent` (XSS-safe). The text sibling of `reactive_field`; carries no `name`, so it's never POSTed. See [Client-side computes](#client-side-computes-reactive_compute--reactive_text). |
-| `reactive_show(:field, equals:/not:/in:)` | **Value-conditional visibility** (the `x-show`/`data-show` case): spread onto the element to show/hide — it toggles `hidden` from the named field's **current value**, client-only, zero round trip. One literal predicate: `equals:`, `not:`, or `in: [...]`; `equals: true` reads a checkbox's checked state. See [Value-conditional visibility](#value-conditional-visibility-reactive_show). |
-| `reactive_show_targets(:field, "#id" => { equals: … })` | **Cross-root visibility**: the component that owns the field declares which **outside**, id-allowlisted elements it governs (a nav tab, a panel in another pane) — the visibility parallel of `mirror:`. Spread on the **root** via `mix(reactive_root, …)`, **once per root** — several fields go in one call via the hash form (`reactive_show_targets(mode: { … }, kind: { … })`). Id selectors only (raise at render + client warn-skip); same literal predicates; toggles `hidden` only. See [Value-conditional visibility](#value-conditional-visibility-reactive_show). |
-| `reactive_filter(input:, option:, group: nil, empty: nil)` | **Client-side option filtering** for a preloaded combobox: spread onto the root — typing in the named input shows/hides the options by their `data-reactive-filter-text` haystack, **zero round trips**. Optional `group:` collapses an all-hidden group header; `empty:` reveals a no-matches node. See [Client-side option filtering](#client-side-option-filtering-reactive_filter). |
+| `reactive_show(if:/if_any:/unless:)` | **Value-conditional visibility** (the `x-show`/`data-show` case): spread onto the element to show/hide — it toggles `hidden` from the fields' **current values**, client-only, zero round trip. One conditions language: a **Hash is an AND**, an **Array is membership**, a **Range is a threshold**, `if_any:` is OR-of-AND, `unless:` negates. `reactive_values` computes first paint; `disable:` disables a hidden section's controls. See [Value-conditional visibility](#value-conditional-visibility-reactive_show). |
+| `reactive_show_targets(:field, "#id" => value)` | **Cross-root visibility**: the component that owns the field declares which **outside**, id-allowlisted elements it governs (a nav tab, a panel in another pane) — the visibility parallel of `mirror:`. Spread on the **root** via `mix(reactive_root, …)`, **once per root** — several fields go in one call via the hash form. The value uses the same `where`-style vocabulary (`"advanced"`, `%w[a b]`, `10..`). Id selectors only (raise at render + client warn-skip); toggles `hidden` only. See [Value-conditional visibility](#value-conditional-visibility-reactive_show). |
+| `reactive_filter(:field, option: nil, group: nil, empty: nil)` | **Client-side option filtering** for a preloaded combobox: spread onto the root and name the **field** that drives it — `reactive_filter(:q)` compiles `:q` to `[name="q"]` (scope-aware) and typing shows/hides the options by their `data-reactive-filter-text` haystack, **zero round trips**. `option:` defaults to `[role=option]`; optional `group:` collapses an all-hidden group header; `empty:` reveals a no-matches node. See [Client-side option filtering](#client-side-option-filtering-reactive_filter). |
 | `reactive_listnav("[role=option]")` | The **standalone** combobox keyboard wiring (Arrow/Enter/Escape) for an input that fires **no action** — the preload-and-filter case. Same behavior as `on(…, listnav:)`, minus the POST. |
-| `reactive_compute :name, inputs: { title: :string, qty: :number }, outputs:` | **Typed** inputs: a `:string` reaches the JS reducer raw, a `:number` is coerced through `Number`. The array form (`inputs: %i[a b]`) stays all-numeric. |
+| `reactive_compute :name, inputs: { title: :string, qty: :number }, outputs:` | **Typed** inputs: a `:string` reaches the JS reducer raw, a `:number` is coerced through `Number`. The array form (`inputs: %i[a b]`) stays all-numeric; the **permit-style** form (`inputs: [:qty, title: :string]`) mixes both — bare symbols default `:number`, a trailing hash types the exceptions. `outputs:` is the field allowlist; a reducer-result key also paints any owned `reactive_text` node by presence and any `mirror:` id, so an `outputs:` entry that exists only to reach a text node is redundant (harmless — a widening). |
 | `reactive_compute :name, ..., mirror: { sum: "#summary-sum" }` | **Cross-root text mirrors**: paint a compute value into declared, id-allowlisted nodes **outside** the reactive root (a recap in another tab pane) via `textContent` — no bespoke listener. See [Cross-root mirrors](#cross-root-mirrors-mirror--painting-a-recap-outside-the-root). |
-| `reactive_root(track_dirty: true, warn_unsaved: true)` / `reactive_field(:param, dirty: true)` | **Dirty tracking** against the DOM's own `defaultValue`/`defaultChecked`/`defaultSelected` — no client state. Marks changed fields + the root `data-reactive-dirty`; `warn_unsaved:` arms a `beforeunload`/`turbo:before-visit` guard. Style with `[data-reactive-dirty]`. See [Dirty-field tracking](#dirty-field-tracking-dirty--track_dirty--warn_unsaved). |
+| `reactive_dirty` / `reactive_dirty warn_unsaved: true` / `reactive_dirty only: %i[...]` | **Dirty tracking**, declared once at the class level, against the DOM's own `defaultValue`/`defaultChecked`/`defaultSelected` — no client state. Marks changed fields + the root `data-reactive-dirty`; `warn_unsaved:` arms a `beforeunload`/`turbo:before-visit` guard; `only:` scopes tracking to named fields. Style with `[data-reactive-dirty]`. See [Dirty-field tracking](#dirty-field-tracking-reactive_dirty). |
 | `nested_update!(:assoc, attrs)` | Map a nested param onto `<assoc>_attributes` with id preservation; update the record. |
 | `reactive_collection :name, item:, container:, count:, empty:, size:` | Declare an add/remove-row list once; actions call `reply.append`/`prepend`/`remove`. See [Reactive collections](#reactive-collections-addremove-rows--count--empty-state). |
 | `reply.replace` / `.morph` / `.update` / `.remove` / `.redirect(url)` / `.with(*)` / `.js(ops)` | Return from an action to control the reply (flash, remove, redirect, multi-stream, server-pushed client ops). See [Controlling the action's reply](#reply--controlling-the-actions-reply). |
@@ -428,6 +427,23 @@ Register during boot only: the registry is **frozen after initialization**, so a
 runtime `param_type` call raises. A schema referencing a registered type is
 validated at declaration like any built-in.
 
+**Named param schemas (`Phlex::Reactive.param_schema`).** Register a reusable
+schema once so sibling components stop duplicating a verbatim params Hash that
+drifts — follows the same boot-only contract as `param_type`:
+
+```ruby
+# config/initializers/phlex_reactive.rb
+Phlex::Reactive.param_schema :todo, title: :string, done: :boolean
+
+# then, in any component:
+action :save, params: :todo
+
+# or compose it into a bigger schema:
+action :bulk, params: { **Phlex::Reactive.param_schema(:todo), note: :string }
+```
+
+Reading an unregistered name raises, listing the ones that are registered.
+
 **File uploads (`:file`).** Declare `:file` (or `[:file]` for multiple) to accept
 an uploaded file in a reactive action — attach a document/receipt/image to the
 record without dropping out to a bespoke controller. When the reactive root holds
@@ -686,7 +702,7 @@ is not disabled mid-typing. On settle the text is restored only if it still
 matches what was swapped in; a morph that rendered a **new** server label is left
 alone.
 
-### Dirty-field tracking (`dirty:` / `track_dirty:` + `warn_unsaved:`)
+### Dirty-field tracking (`reactive_dirty`)
 
 Show "unsaved changes", enable **Save** only when something changed, or warn
 before navigating away — Livewire's `wire:dirty` — **without shipping any client
@@ -696,17 +712,32 @@ zero extra bytes. `input.defaultValue` / `defaultChecked` / `option.defaultSelec
 phlex-reactive reads that baseline straight from the DOM — nothing to snapshot,
 nothing to sign.
 
+`reactive_dirty` is declared **once, at the class level**, alongside your other
+macros (`reactive_record`/`reactive_state`/`action`) — not as a `reactive_root` or
+`reactive_field` keyword:
+
 ```ruby
-div(**reactive_root(track_dirty: true, warn_unsaved: true)) do
-  input(**reactive_field(:title, value: @todo.title, dirty: true))
-  span(class: "unsaved-badge") { "Unsaved" }   # shown via [data-reactive-dirty] CSS
-  button(**on(:save, disable_with: "Saving…")) { "Save" }
+class TodoForm < ApplicationComponent
+  include Phlex::Reactive::Component
+
+  reactive_record :todo
+  reactive_dirty warn_unsaved: true
+  action :save, params: { title: :string }
+
+  def view_template
+    div(**reactive_root) do
+      input(**reactive_field(:title, value: @todo.title))
+      span(class: "unsaved-badge") { "Unsaved" }   # shown via [data-reactive-dirty] CSS
+      button(**on(:save, disable_with: "Saving…")) { "Save" }
+    end
+  end
 end
 ```
 
-- **`track_dirty: true`** on the root wires every input under it to a full
-  re-scan on change. **`dirty: true`** on a single `reactive_field` opts that one
-  field in (use it when only some fields should count).
+- **`reactive_dirty`** (no args) wires every input under the root to a full
+  re-scan on change. **`reactive_dirty only: %i[title]`** scopes tracking to the
+  named fields only — each carries its own descriptor instead of the root
+  delegating for the whole subtree (use it when only some fields should count).
 - On each change the client re-scans **every field the root owns** in one pass and
   marks:
   - each changed field with **`data-reactive-dirty="true"`**, and
@@ -739,15 +770,16 @@ and the badge clears with no reload. (Turbo 8 morph preserves a focused field's
 in-progress value while writing the fresh defaults — the post-morph re-scan is
 what keeps the root count honest in that state.)
 
-**`warn_unsaved: true`** arms a navigate-away guard gated on the **live** dirty
-count: `beforeunload` (a real browser unload) and `turbo:before-visit` (a Turbo
-in-app navigation). A clean form never blocks. **Caveats:** browsers show their
-own generic `beforeunload` copy (your message string is legacy and ignored), and
-`turbo:before-visit` **does not fire on restoration visits** (Back/Forward) — a
-documented Turbo gap, not a phlex-reactive one.
+**`reactive_dirty warn_unsaved: true`** arms a navigate-away guard gated on the
+**live** dirty count: `beforeunload` (a real browser unload) and
+`turbo:before-visit` (a Turbo in-app navigation). A clean form never blocks.
+**Caveats:** browsers show their own generic `beforeunload` copy (your message
+string is legacy and ignored), and `turbo:before-visit` **does not fire on
+restoration visits** (Back/Forward) — a documented Turbo gap, not a
+phlex-reactive one.
 
 **Out of scope (v1):** rich-text / `contenteditable` editors have no `default*`
-baseline and are **not** tracked. Combining `reactive_field(dirty:)` with your own
+baseline and are **not** tracked. Combining `reactive_field` with your own
 `data:`/`on(...)` still needs `mix(...)` (a bare merge clobbers the `data-action`
 the descriptor rides on — the same rule as everywhere else).
 
@@ -788,7 +820,7 @@ the same chain covers the rest of the client-only vocabulary:
 
 ```ruby
 button(**on_client(:click, js
-  .toggle("#menu", transition: %w[transition-opacity opacity-0 opacity-100])
+  .toggle("#menu", transition: { during: "transition-opacity", from: "opacity-0", to: "opacity-100" })
   .toggle_attr(:root, "aria-expanded")   # accessible disclosure state
   .focus_first("#menu")                   # move focus into the opened menu
   .dispatch("app:menu-toggled", detail: { open: true }))) { "Menu" }
@@ -814,7 +846,7 @@ button(**on_client(:click, js
   another component or a plain Stimulus controller can react to a client-only
   interaction — `to:` picks the element (default: the component root), `detail:`
   is the payload.
-- **`transition: [during, from, to]`** on `show`/`hide`/`toggle` animates the
+- **`transition: { during:, from:, to: }`** on `show`/`hide`/`toggle` animates the
   visibility flip: `during`+`from` are applied, then `from`→`to` swaps on the next
   frame, and the helper classes are cleaned up on `animationend` (with a timeout
   fallback, so an element with no animation never leaves them stuck). The op chain
@@ -892,52 +924,58 @@ free as an ordinary action-param name (`on(:switch, key: "pgbus")` still passes
 
 `on_client` covers the *unconditional* client-only interactions; the last gap
 was **show/hide from a form field's current value** — the Alpine `x-show` /
-Datastar `data-show` / Livewire `wire:show` case ("reveal the details panel
-*while* this select isn't `none`"). That used to force a hand-written
-`change`-listener Stimulus controller back into an otherwise declarative form.
-`reactive_show` closes it: spread it onto the element to show/hide, name the
-controlling field, declare **one literal predicate** — the generic controller
-toggles the `hidden` attribute from the field's current value on every
-`input`/`change`. Client-only, **no token, no POST, ever**:
+Datastar `data-show` / Livewire `wire:show` case. `reactive_show` closes it with
+ONE Ruby-native conditions language: spread it onto the element to show/hide and
+declare an `if:` / `if_any:` / `unless:` condition with `where`-style values —
+the generic controller toggles the `hidden` attribute from the fields' current
+values on every `input`/`change`. Client-only, **no token, no POST, ever**:
 
 ```ruby
 def view_template
   div(**reactive_root) do
     select(name: "mode") { shipping_options }
-    div(**reactive_show(:mode, not: "off", hidden: @order.mode == "off")) { shipping_details }
+    div(**reactive_show(unless: { mode: "off" })) { shipping_details }
 
     input(type: "checkbox", name: "gift")
-    div(**reactive_show(:gift, equals: true, hidden: true)) { gift_message_field }
+    div(**reactive_show(if: { gift: true })) { gift_message_field }
 
     select(name: "size") { size_options }
-    div(**reactive_show(:size, in: %w[l xl], hidden: true)) { surcharge_note }
+    div(**reactive_show(if: { size: %w[l xl] })) { surcharge_note }        # membership
+
+    input(type: "number", name: "quantity")
+    div(**reactive_show(if: { quantity: 10.. })) { bulk_note }             # threshold
   end
 end
 ```
 
-- **One predicate per binding** — `equals:`, `not:`, or `in:` (a list); zero or
-  two raise at render (a dead binding must not silently no-op). Values are
-  **stringified literals** matched against the field's value — never an
-  expression, so there is no eval surface.
-- **Field reads follow the collection rules**: a checkbox compares its
-  *checked* state as `"true"`/`"false"` (so `equals: true` is the checkbox
-  form — its `.value` is the constant `"on"`, and it wins over the hidden
-  input Rails pairs with it); a radio group reads the **checked** radio's
-  value (`""` when none is); everything else reads `.value`. Ownership is the
-  usual rule — a nested reactive component's fields and bindings belong to the
-  nested component.
-- **Initial state**: the client seeds visibility at connect and reconciles
-  after a morph, but render the initial `hidden:` yourself (from the same
-  server state that renders the field, as above) so the first paint doesn't
-  flash.
-- **Extra attrs ride through the helper** (`reactive_show(:mode, not: "off",
-  class: "panel", data: { testid: "details" })`) and deep-merge — a bare
-  `data:` spread *beside* it would clobber the binding, same as `on(...)`.
+- **The value language**: a **Hash is an AND** (multiple keys ANDed), an
+  **Array is membership**, a **Range is a threshold** (`10..` ≥ 10, `..10` ≤ 10,
+  `...10` < 10, `10..20` between), `true`/`false` compare a checkbox's checked
+  state, `nil` matches blank. `unless:` **negates** and composes with `if:`.
+  Never an expression — every term is a declared literal, so there is no eval
+  surface. A blank/non-numeric value fails a numeric term **closed** (hidden).
+- **OR-of-AND** — `if_any:` takes an array of AND-hashes (`if_any: [{ director:
+  true }, { shareholder: true, role: "individual" }]`), so
+  `director || (shareholder && individual)` is **one flat binding**, no nested
+  wrapper divs, no hand-applied distributive law.
+- **First paint is computed for you** — declare `reactive_values` once
+  (`def reactive_values = { mode: @order.mode, gift: @order.gift? }`) and every
+  binding whose fields are all provided renders the correct initial `hidden:`
+  server-side. No per-section mirror method, no flash. An explicit `hidden:`
+  always wins; a per-call `values:` override merges over `reactive_values`.
+- **`reactive_scope :form`** lets bindings and `reactive_values` use bare
+  symbols while the client resolves `[name="form[field]"]`.
+- **`disable: true`** disables a hidden section's own controls so a
+  switched-away value never submits (the stale-value fix).
+- **Field reads follow the collection rules**: a checkbox compares its *checked*
+  state; a radio group reads the **checked** radio's value; everything else
+  reads `.value`. Ownership is the usual rule — a nested reactive component's
+  fields and bindings belong to the nested component.
 - **Composes with computes**: a `reactive_compute` output write dispatches a
   real `input` event, so a *derived* value can drive visibility too.
-- Presentational only, strictly weaker than the js ops: it reads an owned
-  field and toggles `hidden` on an owned element — no `innerHTML`, no
-  attribute freedom. Cross-root writes take the **declared** escape below.
+- Presentational only, strictly weaker than the js ops: it reads owned fields
+  and toggles `hidden` (+ optionally `disabled`) on owned elements — no
+  `innerHTML`, no attribute freedom. Cross-root writes take the escape below.
 
 **Cross-root targets (`reactive_show_targets`).** A plain `reactive_show` is
 root-scoped by design — but "a mode selector reveals dependent sections
@@ -946,13 +984,13 @@ sidebar note) routinely puts the dependents **outside** the control's root.
 `reactive_show_targets` is the declared escape, the visibility parallel of the
 [cross-root text mirror](#cross-root-mirrors-mirror--painting-a-recap-outside-the-root):
 the component that **owns** the field declares which outside ids it governs,
-spread on the **root**:
+spread on the **root**, using the same `where`-style values:
 
 ```ruby
 div(**mix(reactive_root, reactive_show_targets(:mode,
-  "#advanced-tab"   => { equals: "advanced" },
-  "#advanced-panel" => { equals: "advanced" },
-  "#basic-note"     => { not: "advanced" }))) do
+  "#advanced-tab"   => "advanced",            # equals
+  "#advanced-panel" => "advanced",
+  "#premium-note"   => %w[gold platinum]))) do  # membership
   select(name: "mode") { mode_options }
   # …
 end
@@ -961,11 +999,10 @@ end
 Same posture as `mirror:`: **opt-in and declared, never implicit** — a plain
 `reactive_show` stays root-isolated; targets are **single id selectors only**
 (a class/compound selector raises at render AND is warn-and-skipped by the
-client — two-sided default-deny); the predicate is the same literal-only
-vocabulary; and the toggle is `hidden` only. The field read stays **owned** —
-you can only drive outside visibility from a field the declaring root owns. A
-target id not on the page is silently skipped, so a target inside an
-unrendered tab pane is fine.
+client — two-sided default-deny); values use the same vocabulary; and the
+toggle is `hidden` only. The field read stays **owned** — you can only drive
+outside visibility from a field the declaring root owns. A target id not on the
+page is silently skipped, so a target inside an unrendered tab pane is fine.
 
 **One call per root.** Phlex `mix` space-joins duplicate string `data:`
 values, so a *second* `reactive_show_targets` call on the same root would
@@ -973,8 +1010,8 @@ concatenate two JSON payloads into an unparseable attribute (the client warns
 and ignores it). Several fields go in **one call** via the hash form:
 
 ```ruby
-reactive_show_targets(mode: { "#advanced-tab" => { equals: "advanced" } },
-                      kind: { "#premium-note" => { not: "basic" } })
+reactive_show_targets(mode: { "#advanced-tab" => "advanced" },
+                      kind: { "#premium-note" => %w[gold platinum] })
 ```
 
 ### Client-side computes (`reactive_compute` + `reactive_text`)
@@ -991,9 +1028,8 @@ reactive_compute :preview,
   inputs: { title: :string, qty: :number },  # typed: :string raw, :number → Number
   outputs: %i[title_preview char_count]       # written with no round trip
 
-div(**mix(reactive_root, reactive_compute_attrs(:preview))) do
-  input(**mix(reactive_field(:title, value: @post.title),
-              data: { action: "input->reactive#recompute" }))
+div(**reactive_root(compute: :preview)) do
+  input(**reactive_field(:title, value: @post.title))
   h2    { reactive_text(:title_preview, @post.title) }  # a text-node output
   small { reactive_text(:char_count) }                  # another text-node output
 end
@@ -1007,18 +1043,31 @@ setComputeReducer("preview", ({ title }) => ({
 }))
 ```
 
+- **`reactive_root(compute: :name)` binds AND listens at the root.** It emits the
+  compute descriptors plus the `input->reactive#recompute` delegation on the root
+  element, so no field needs any per-field compute wiring. `nil` (e.g.
+  `reactive_root(compute: (:preview unless @post.persisted?))`) collapses to no
+  binding at all — one expression for conditional compute.
 - **Typed inputs.** `inputs:` takes a **hash** to type each input: a `:number` is
   coerced through `Number` (blank/NaN → 0 — the array-form default), a `:string`
   reaches the reducer **raw** so a live text preview reads real text. The **array
-  form** (`inputs: %i[a b]`) stays all-numeric and byte-identical on the wire.
+  form** (`inputs: %i[a b]`) stays all-numeric and byte-identical on the wire. The
+  **permit-style form** (`inputs: [:qty, title: :string]`) combines both in one
+  declaration — bare symbols default to `:number`, a trailing hash types the
+  exceptions.
 - **`reactive_text(:name, initial)`** mirrors a value into a **text node** via
-  `textContent` (XSS-safe by construction). An output whose name matches an owned
-  form field writes that field's `.value`; an output with **no** matching field
-  writes every owned `[data-reactive-text="<name>"]` node. It carries **no
-  `name`**, so it's never collected or POSTed as a param.
-- **Reducer-less mirrors.** A declared **input** also mirrors into its own
-  `reactive_text(:same_name)` node on every keystroke with **no reducer at all** —
-  so `reactive_text(:title)` is a live field echo out of the box.
+  `textContent` (XSS-safe by construction). Every reducer-result key paints any
+  matching sink: an owned **field** if declared in `outputs:`, any owned
+  **`reactive_text`** node by presence, or a declared **`mirror:`** id — so an
+  `outputs:` entry that exists only to reach a text node is redundant (existing
+  declarations keep working; it's a widening, not a breaking change). It carries
+  **no `name`**, so it's never collected or POSTed as a param.
+- **Reducer-less mirrors, and reactive_values seeding.** A declared **input** also
+  mirrors into its own `reactive_text(:same_name)` node on every keystroke with
+  **no reducer at all** — so `reactive_text(:title)` is a live field echo out of
+  the box. And `reactive_text(:name)` called with **no explicit `initial`** seeds
+  its first paint from `reactive_values` when the component declares one and
+  covers that name — the same no-flash first-paint contract `reactive_show` uses.
 - **Seed the server render.** Your `view_template` must seed each mirror with the
   same derived value the reducer would (`reactive_text(:char_count, "5/80")`), or
   a later morph repaints stale text — the same reconcile contract the whole
@@ -1104,13 +1153,13 @@ root instead:
 
 ```ruby
 div(**mix(reactive_root, reactive_filter(
-  input:  "#exercise-search",       # the input whose value drives the filter
-  option: "[role=option]",          # the elements to show/hide
-  group:  "[data-filter-group]",    # optional: collapse a header when all its options hide
-  empty:  "#no-matches"             # optional: reveal when 0 options match
+  :q,                               # the FIELD that drives the filter → [name="q"] (scope-aware)
+  group: "[data-filter-group]",     # optional: collapse a header when all its options hide
+  empty: "#no-matches"              # optional: reveal when 0 options match
 ))) do
   # STANDALONE keyboard nav — no action on the input, so typing never POSTs.
-  input(id: "exercise-search", type: "search", **reactive_listnav("[role=option]"))
+  # name: "q" is the field reactive_filter(:q) binds to; option: defaults to [role=option].
+  input(name: "q", type: "search", **reactive_listnav("[role=option]"))
 
   categories.each do |category, exercises|
     div(data: { filter_group: "" }) do
@@ -1173,17 +1222,17 @@ button(**on(:increment), data: { testid: "inc" }) { "+" }
 **Binding inputs to action params (drop the magic `name:`).** A field's value
 travels with an action only if its `name` equals the param. Hand-writing
 `name: "value"` on every input is easy to forget — the action then silently gets
-nothing. `reactive_input`/`reactive_select` emit the binding for you (the trigger
-stays on the button, so focusing the field doesn't dispatch and collapse edit
-mode):
+nothing. `reactive_field` returns the attribute hash that carries the binding —
+spread it onto any control (the trigger stays on the button, so focusing the
+field doesn't dispatch and collapse edit mode):
 
 ```ruby
 action :save, params: { value: :string, status: :string }
 
 def view_template
   span(**reactive_root) do
-    reactive_input(:value, value: @record.name)            # <input name="value" …>
-    reactive_select(:status) do                            # <select name="status">…</select>
+    input(**reactive_field(:value, value: @record.name))    # <input name="value" …>
+    select(**reactive_field(:status)) do                    # <select name="status">…</select>
       %w[open closed].each { |s| option(value: s, selected: s == @record.status) { s } }
     end
     button(**mix(on(:save), data: { testid: "save" })) { "Save" }
@@ -1247,7 +1296,7 @@ gains a seam.
 By default an action re-renders its component in place. To do more, **return**
 `reply.<verb>` — a subject-bound builder available in every component. It governs
 only the actor's HTTP reply (cross-tab updates still use
-`broadcast_*_to(..., exclude: reactive_connection_id)`). Returning anything else
+`broadcast_to(..., exclude: reactive_connection_id)`). Returning anything else
 keeps the default, so existing actions are unaffected.
 
 `reply` reads cleanly: the component is the implicit subject (no `self` to
@@ -1271,7 +1320,7 @@ def add(item:) = reply.replace.stream(Totals.update(@order))               # mul
 def update(name:) = (@row.update!(name:); reply.morph)
 
 # Re-render a COMPANION element (a heading mirroring the edited name) alongside self:
-def rename(value:) = (@account.update!(name: value); reply.replace.also_update("page_heading", html: @account.name))
+def rename(value:) = (@account.update!(name: value); reply.replace.also(page_heading: @account.name))
 
 # Update ONLY part of the component (issue #30): re-stream just the total cell,
 # NOT the whole row. reply.streams emits exactly your streams plus a tiny
@@ -1284,8 +1333,8 @@ def update(quantity:, price:) = (@item.update!(quantity:, price:); reply.streams
 |---|---|
 | `reply.replace` / `reply.update(morph: false)` | re-render in place (default; `replace` swaps the whole element via outerHTML, `update` swaps only the inner HTML) |
 | `reply.morph` / `reply.replace(morph: true)` / `reply.update(morph: true)` | re-render in place via Idiomorph (`method="morph"`) — preserves the focused `<input>` + caret; for per-field reactive editing (`replace` #28; `update` #113) |
-| `.also_update(target, html:)` | also re-render a companion element by DOM id; `html` is a plain string (escaped) or a Phlex component |
-| `.also_replace(component, morph: false)` | also re-render another Streamable component, targeting its own `#id`; `morph: true` morphs it in place |
+| `.also(target => content, …)` | **UPDATE** (inner HTML) companion elements by DOM id; `content` is a plain string (escaped) or a Phlex component. The argument *type* picks the action — pairs mean `update` |
+| `.also(component, morph: false)` | **REPLACE** another Streamable component at its own `#id` (`morph: true` morphs in place). A component argument means `replace` |
 | `.flash(level, content, target: …)` | append a flash; `content` is a plain string (escaped, wrapped in a level-carrying `<div>` — see [Flash levels](#flash-levels)) or a Phlex component (rendered verbatim; off-request — no Rails `flash`); target defaults to `Phlex::Reactive.flash_target` (`"flash"`) |
 | `reply.remove` | remove the element (backed by `Streamable#to_stream_remove`) |
 | `reply.redirect(url)` | client-side `Turbo.visit` (pass a `*_url`); rides a `reactive:visit` turbo-stream, not an HTTP 3xx |
@@ -1294,7 +1343,7 @@ def update(quantity:, price:) = (@item.update!(quantity:, price:); reply.streams
 | `.defer(component, placeholder:, morph:)` | take an **expensive segment off the actor's critical path** (issue #165) — the reply returns immediately and the real render streams to the SAME actor when ready; see [Deferred segments](#deferred-segments-replydefer--reactive_lazy) |
 | `reply.with(*streams)` / `#stream(*more)` | multi-stream (self re-render still injected for the token) |
 
-`.flash`/`.stream`/`.also_*` are additive on a self-replace, so the component's
+`.flash`/`.stream`/`.also` are additive on a self-replace, so the component's
 signed token always refreshes. **`reply.streams`** is the exception that proves
 the rule: it deliberately skips the full-self replace (so your hand-built streams
 update only the targets you name) and refreshes the token via a tiny inert
@@ -1358,7 +1407,7 @@ Semantics you can rely on:
   the action's transaction committed; a rollback or a denied action leaks no
   deferred render (and enqueues no job).
 - **Actor-scoped** — the deferred render reaches only the actor; peers keep
-  getting updates via `broadcast_*_to` (use both when both need the value).
+  getting updates via `broadcast_to` (use both when both need the value).
 - **Superseding** — a newer action for the same target aborts the in-flight
   deferred render; a fast typist never gets stale totals painted over fresh ones.
 - **Interactive on arrival** — the streamed root carries a fresh action token.
@@ -1474,12 +1523,14 @@ Prefer your own markup? Two escape hatches:
 #    (you own the markup entirely, including the level styling):
 reply.replace.flash(:error, Alert.new(level: :error, message: msg))
 
-# 2. Or configure a flash component ONCE — string flashes render through it
-#    (instantiated new(level:, content:)); component content still bypasses it:
-Phlex::Reactive.flash_component = MyFlash   # default nil → the built-in wrapper
+# 2. Or configure a flash component ONCE — string flashes render through it;
+#    component content still bypasses it. flash_component is an app-owned
+#    CALLABLE (issue #182): it maps (level, content) to your component —
+#    the gem never guesses kwargs:
+Phlex::Reactive.flash_component = ->(level, content) { MyFlash.new(level:, content:) }   # default nil → the built-in wrapper
 ```
 
-#### Server-pushed client ops (`reply.js` + `broadcast_js_to`, issue #97)
+#### Server-pushed client ops (`reply.js` + `broadcast_to(js:)`, issue #97)
 
 Sometimes the server needs the client to do something other than swap HTML —
 focus the next field after a save, dispatch an app event to a toast host, add an
@@ -1509,11 +1560,11 @@ transport (Action Cable **or** pgbus) — a background nudge to all viewers:
 
 ```ruby
 # In a model/job: light up the bell in every viewer's tab, minus the actor's own.
-Notifications::Badge.broadcast_js_to(user, :alerts,
-  js.add_class("#bell", "has-unread"), exclude: reactive_connection_id)
+Notifications::Badge.broadcast_to(user, :alerts,
+  js: js.add_class("#bell", "has-unread"), exclude: reactive_connection_id)
 ```
 
-`broadcast_js_to` **refuses focus-class ops** (`focus`/`focus_first` raise
+`broadcast_to` with `js:` **refuses focus-class ops** (`focus`/`focus_first` raise
 `ArgumentError`): broadcasting focus would steal it in every subscriber's tab, so
 focus is an actor-reply concern only. Everything else is a fair broadcast (class
 and attribute toggles, `dispatch`). As with `on_client`, the ops are
@@ -1533,7 +1584,7 @@ record can be there purely for **identity + authorization** while the action's
 real job is to recompute **live, unsaved form values** the user is mid-edit. The
 record is re-located and instantiated on each action (`from_identity`), never
 auto-saved and never auto-broadcast; persistence and cross-tab broadcast are both
-opt-in (you call `record.update!` / `broadcast_*_to` yourself). Pair that with
+opt-in (you call `record.update!` / `broadcast_to` yourself). Pair that with
 `reply.streams` and you get a first-class "authorize via the row, compute over
 the params, stream a partial update, touch neither the DB nor peer tabs" action:
 
@@ -1560,9 +1611,10 @@ Broadcasting is deliberately omitted so peer tabs with their own in-flight edits
 aren't clobbered. Authorize the record as always — identity is never permission.
 
 > **Under the hood.** `reply.<verb>` returns a `Phlex::Reactive::Response` — the
-> immutable value object the endpoint reads. You can build one directly
-> (`Phlex::Reactive::Response.replace(self)`) and it still works, but `reply` is
-> the preferred surface; treat `Response` as an internal detail.
+> immutable value object the endpoint reads. `reply` is the ONE documented door
+> (issue #182): the old `Phlex::Reactive::Response.replace(self)` class verbs
+> are removed and raise a guided `ArgumentError` naming the `reply.<verb>`
+> rewrite; treat `Response` as an internal detail.
 > **`html:`/`content` escaping.** A plain string is **HTML-escaped** by Turbo, so
 > `html: @account.name` is safe even for user-supplied values. To emit intentional
 > markup, pass a **Phlex component** (`html: Heading.new(name: @record.name)`) —
@@ -1820,12 +1872,13 @@ class NotificationsList < ApplicationComponent
 
   def add(title:)
     todo = Todo.create!(title:)
-    reply.append(:notifications, todo)   # append row + bump count + clear empty-state
+    reply.append(todo, to: :notifications)   # append row + bump count + clear empty-state
   end
 
   def dismiss(id:)
-    Todo.find(id).destroy!
-    reply.remove(:notifications, id)     # remove row + bump count + restore empty-state at 0
+    todo = Todo.find(id)
+    todo.destroy!
+    reply.remove(todo, from: :notifications)   # remove row + bump count + restore empty-state at 0
   end
 
   # view_template renders the count, the container <ul>, and the empty-state on
@@ -1835,9 +1888,9 @@ end
 
 | Builder | Reply (one `Response`) |
 |---|---|
-| `reply.append(name, model)` | append the row into the container + update the count + remove the empty-state when the list crosses 0→1 |
-| `reply.prepend(name, model)` | as `append`, but the row goes to the top |
-| `reply.remove(name, model)` | remove the row by its `dom_id` + update the count + append the empty-state back when the list crosses →0 |
+| `reply.append(model, to: name)` | append the row into the container + update the count + remove the empty-state when the list crosses 0→1 |
+| `reply.prepend(model, to: name)` | as `append`, but the row goes to the top |
+| `reply.remove(model, from: name)` | remove the row by its `dom_id` + update the count + append the empty-state back when the list crosses →0 |
 
 - **`size:` is the source of truth** — it's *re-counted* server-side after the
   mutation, so the badge and the empty-state are correct-by-construction (no
@@ -1849,11 +1902,11 @@ end
   (correct on the first click, silently rejected after); the helper bakes the
   refresh in so you never hit it.
 - **`remove` takes the record or its `dom_id` string** — a just-destroyed
-  ActiveRecord still answers `dom_id` correctly, so `reply.remove(:items, todo)`
+  ActiveRecord still answers `dom_id` correctly, so `reply.remove(todo, from: :items)`
   works; pass the raw id only if your row `#id` matches `ActiveRecord::RecordIdentifier`.
 - **Reply governs the actor's HTTP response only.** For a *cross-tab* live list
   (other viewers see the row appear) keep broadcasting the row with
-  `NotificationRow.broadcast_append_to(..., exclude: reactive_connection_id)` —
+  `NotificationRow.broadcast_to(..., append: model, exclude: reactive_connection_id)` —
   `reactive_collection` is the per-actor add/remove + count + empty-state wrapper,
   not a replacement for the broadcast.
 
@@ -2121,7 +2174,7 @@ end
 
 [pgbus](https://github.com/mhenrixon/pgbus) replaces Action Cable's transport
 with Postgres SSE and fixes its reliability gaps. With it installed,
-`broadcast_*_to` and `turbo_stream_from` route over pgbus automatically:
+`broadcast_to` and `turbo_stream_from` route over pgbus automatically:
 
 ```ruby
 class Message < ApplicationRecord
@@ -2153,7 +2206,8 @@ events, all under the `phlex_reactive` namespace:
 |-------|-------|---------|
 | `action.phlex_reactive` | once per request | `component`, `action`, `outcome` (`ok`/`denied_undeclared`/`invalid_token`/`not_found`/`unauthorized`/`unverified`) |
 | `render.phlex_reactive` | per component render | `component`, `bytesize` |
-| `broadcast.phlex_reactive` | per `broadcast_*_to` (Action Cable **and** pgbus) | `component`, `stream_action`, `streamables` |
+| `broadcast.phlex_reactive` | per `broadcast_to` call (Action Cable **and** pgbus) | `component`, `stream_action`, `streamables` |
+| `defer.phlex_reactive` | once per deferred render (the `reply.defer` pull/push endpoint) | `component`, `outcome` (`ok`/`no_content`/`invalid_token`/`not_found`/`unauthorized`) |
 
 Payloads carry **names, the outcome, and sizes only** — never the token, params,
 or state, so an event can't leak a secret. Subscribe from an initializer: