phlex-reactive 0.10.0 → 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(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(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_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
@@ -996,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
@@ -1012,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
@@ -1109,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
@@ -1178,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" }
@@ -1252,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
@@ -1276,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
@@ -1289,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 |
@@ -1299,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
@@ -1363,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.
@@ -1479,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
@@ -1514,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
@@ -1538,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:
 
@@ -1565,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)`) —
@@ -1825,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
@@ -1840,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
@@ -1854,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.
 
@@ -2126,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
@@ -2158,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:

data/app/controllers/phlex/reactive/actions_controller.rb

@@ -85,7 +85,7 @@ module Phlex
         end
 
         event[:outcome] = :ok
-        stream = payload["m"] == "morph" ? component.to_stream_morph : component.to_stream_replace
+        stream = component.to_stream_replace(morph: payload["m"] == "morph")
         render turbo_stream: stream
       rescue Phlex::Reactive::InvalidToken => e
         event[:outcome] = :invalid_token
@@ -119,7 +119,7 @@ module Phlex
         payload = verified_payload
         component_class = resolve_component(payload["c"])
         event[:component] = component_class.name
-        action_def = component_class.reactive_action(reactive_action_name)
+        action_def = component_class.reactive_actions[reactive_action_name.to_sym]
 
         # default-deny
         unless action_def
@@ -189,7 +189,9 @@ module Phlex
         return unless callable
 
         message = callable.call(kind)
-        Phlex::Reactive::Response.flash_stream(:error, message, target: Phlex::Reactive.flash_target)
+        # flash_stream is a private Response builder (issue #182) — the endpoint's
+        # error path is an internal caller, so reach it via send.
+        Phlex::Reactive::Response.send(:flash_stream, :error, message, target: Phlex::Reactive.flash_target)
       rescue => e # rubocop:disable Style/RescueStandardError
         ::Rails.logger&.warn("[phlex-reactive] error_flash raised: #{e.message}") if defined?(::Rails) &&
                                                                                      ::Rails.respond_to?(:logger)
@@ -298,7 +300,7 @@ module Phlex
 
         streams = result.streams
 
-        # Partial update (Response.streams / reply.streams, issue #30): the action
+        # Partial update (reply.streams, issue #30): the action
         # re-rendered only PART of the component and opted out of the full-self
         # replace. Append a tiny token-only stream so the signed token still rolls
         # forward WITHOUT re-rendering (and clobbering) the live inputs. Skip it
@@ -320,7 +322,7 @@ module Phlex
         # for replace AND update of self (both re-render the root via
         # render_component, carrying the token), and still adds the fallback
         # replace when a hand-built `with(...)` stream omits it. Idempotent: a
-        # Response.replace(self)/update(self) already carries the token, so we
+        # reply.replace/update already carries the token, so we
         # don't double the self-render.
         #
         # GUARD 2 (issue #114): GLOBAL, un-scoped — "does ANY stream carry a
@@ -329,7 +331,7 @@ module Phlex
         # scan. Deliberately NOT rx_refreshes_token_for? (target-scoped): scoping
         # this guard would regress update/morph of self on an aliased id.
         #
-        # A self-render reply (Response.replace/update/morph — subject_component
+        # A self-render reply (reply.replace/update/morph — subject_component
         # set) whose streams somehow carry no token gets the full self-replace
         # (defensive, unchanged). A companion-only reply.with (NO subject, NO
         # token_component) that doesn't re-render the root gets a token-ONLY
@@ -483,13 +485,31 @@ module Phlex
       # skipped — zero extra work on the production path.
       def coerce_params(action_def, component_class: nil, action_name: nil)
         dropped = Phlex::Reactive.verbose_errors ? [] : nil
-        raw = params.fetch(:params, {})
+        raw = unwrap_scope(params.fetch(:params, {}), component_class)
 
         coerced = action_def.schema.coerce(raw, dropped)
         log_dropped_params(dropped, action_def.params, component_class, action_name)
         coerced
       end
 
+      # Issue #184: a scoped component's fields POST bracketed (todo[title]), which
+      # Rails expands to { "todo" => { "title" => … } } before the action runs. Peel
+      # exactly ONE scope level so the FLAT schema { title: :string } matches (the
+      # #67 bracket-drop footgun). Only when the component declares reactive_scope
+      # AND the raw params carry that single key mapping to a Hash — otherwise the
+      # raw params pass through untouched (unscoped components + nested_attributes
+      # shapes are unaffected).
+      def unwrap_scope(raw, component_class)
+        scope = component_class.reactive_scope if component_class.respond_to?(:reactive_scope)
+        return raw unless scope
+
+        # At the endpoint `raw` is ActionController::Parameters, so `raw[scope]` is
+        # too — NOT a Hash. Accept either shape (both answer to the schema's
+        # coerce): unwrap only when the scope key maps to a nested params/hash.
+        nested = raw[scope.to_s]
+        nested.is_a?(Hash) || nested.is_a?(ActionController::Parameters) ? nested : raw
+      end
+
       # ---- verbose_errors dropped-param logging --------------------------
       # ParamSchema collects the dropped entries; the controller formats the ONE
       # warn line (with the #16/#21 shape hints). Everything below runs ONLY when
@@ -577,7 +597,7 @@ module Phlex
             diagnostic: :unknown_class
           )
         end
-        unless klass.respond_to?(:reactive_action?) && klass.include?(Phlex::Reactive::Component)
+        unless klass.respond_to?(:reactive_actions) && klass.include?(Phlex::Reactive::Component)
           raise Phlex::Reactive::InvalidToken.new(
             "#{name} resolved but does not include Phlex::Reactive::Component",
             diagnostic: :not_reactive_class

data/app/javascript/phlex/reactive/confirm_predicate.js

@@ -0,0 +1,52 @@
+// The client-side confirm-predicate registry — the multi-field escape hatch for
+// conditional confirmation (issue #179).
+//
+// confirm: { when: { total: 0 }, message: } handles the single-field 80% case
+// declaratively (the reactive_show conditions language), with NO JS. But some
+// soft-validation is multi-field — "warn if the end date precedes the start",
+// "warn if two related totals disagree" — which a single field=value condition
+// can't express. This registry is the seam for that logic: name a pure function
+// with `confirm: { predicate: "name", message: }` (Ruby) and register it here.
+//
+// The seam mirrors compute.js (setComputeReducer) and confirm.js: a settable
+// registry with a lookup the controller calls. Register once at boot:
+//
+//   import { setConfirmPredicate } from "phlex/reactive/confirm_predicate"
+//   setConfirmPredicate("end_before_start", ({ starts_at, ends_at }) =>
+//     ends_at !== "" && ends_at < starts_at)
+//
+// The predicate's signature is (fields) => boolean:
+//
+//   fields — a plain object of { name: value } over the trigger root's collected
+//            controls (the SAME snapshot reactive_compute reads — #collectFields).
+//            Values are the raw control values (strings; a checkbox is a boolean).
+//
+// It returns truthy to WARN (the confirm dialog fires with the declared message)
+// or falsy to PROCEED with no dialog. The predicate is soft-validation UX, NOT
+// authorization: a user can bypass it (devtools, an unregistered name) and the
+// action still hits the endpoint's real authorize/default-deny — never let a
+// predicate stand in for a server-side check.
+//
+// A missing predicate (name never registered) makes the gate a NO-OP: the
+// controller proceeds WITHOUT a dialog and warns, exactly like compute.js's
+// unknown-reducer posture — a stale/typo'd name must not break the page or
+// (worse) block a legitimate action behind a dialog that can never resolve.
+
+const predicates = new Map()
+
+// Register (or replace) the predicate for `key`. `fn` is
+// (fields: Record<string, unknown>) => boolean — truthy warns, falsy proceeds.
+export function setConfirmPredicate(key, fn) {
+  predicates.set(key, fn)
+}
+
+// Look up a registered predicate; undefined when none — the controller then
+// proceeds without a dialog (and warns) rather than throwing or blocking.
+export function confirmPredicate(key) {
+  return predicates.get(key)
+}
+
+// Test seam: clear the registry so a predicate registered in one test can't leak.
+export function __resetConfirmPredicateRegistryForTest() {
+  predicates.clear()
+}

data/app/javascript/phlex/reactive/confirm_predicate.min.js

@@ -0,0 +1,4 @@
+var j=new Map;function u(b,q){j.set(b,q)}function v(b){return j.get(b)}function w(){j.clear()}export{u as setConfirmPredicate,v as confirmPredicate,w as __resetConfirmPredicateRegistryForTest};
+
+//# debugId=2F392605F11792F264756E2164756E21
+//# sourceMappingURL=confirm_predicate.min.js.map

data/app/javascript/phlex/reactive/confirm_predicate.min.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["confirm_predicate.js"],
+  "sourcesContent": [
+    "// The client-side confirm-predicate registry — the multi-field escape hatch for\n// conditional confirmation (issue #179).\n//\n// confirm: { when: { total: 0 }, message: } handles the single-field 80% case\n// declaratively (the reactive_show conditions language), with NO JS. But some\n// soft-validation is multi-field — \"warn if the end date precedes the start\",\n// \"warn if two related totals disagree\" — which a single field=value condition\n// can't express. This registry is the seam for that logic: name a pure function\n// with `confirm: { predicate: \"name\", message: }` (Ruby) and register it here.\n//\n// The seam mirrors compute.js (setComputeReducer) and confirm.js: a settable\n// registry with a lookup the controller calls. Register once at boot:\n//\n//   import { setConfirmPredicate } from \"phlex/reactive/confirm_predicate\"\n//   setConfirmPredicate(\"end_before_start\", ({ starts_at, ends_at }) =>\n//     ends_at !== \"\" && ends_at < starts_at)\n//\n// The predicate's signature is (fields) => boolean:\n//\n//   fields — a plain object of { name: value } over the trigger root's collected\n//            controls (the SAME snapshot reactive_compute reads — #collectFields).\n//            Values are the raw control values (strings; a checkbox is a boolean).\n//\n// It returns truthy to WARN (the confirm dialog fires with the declared message)\n// or falsy to PROCEED with no dialog. The predicate is soft-validation UX, NOT\n// authorization: a user can bypass it (devtools, an unregistered name) and the\n// action still hits the endpoint's real authorize/default-deny — never let a\n// predicate stand in for a server-side check.\n//\n// A missing predicate (name never registered) makes the gate a NO-OP: the\n// controller proceeds WITHOUT a dialog and warns, exactly like compute.js's\n// unknown-reducer posture — a stale/typo'd name must not break the page or\n// (worse) block a legitimate action behind a dialog that can never resolve.\n\nconst predicates = new Map()\n\n// Register (or replace) the predicate for `key`. `fn` is\n// (fields: Record<string, unknown>) => boolean — truthy warns, falsy proceeds.\nexport function setConfirmPredicate(key, fn) {\n  predicates.set(key, fn)\n}\n\n// Look up a registered predicate; undefined when none — the controller then\n// proceeds without a dialog (and warns) rather than throwing or blocking.\nexport function confirmPredicate(key) {\n  return predicates.get(key)\n}\n\n// Test seam: clear the registry so a predicate registered in one test can't leak.\nexport function __resetConfirmPredicateRegistryForTest() {\n  predicates.clear()\n}\n"
+  ],
+  "mappings": "AAkCA,IAAM,EAAa,IAAI,IAIhB,SAAS,CAAmB,CAAC,EAAK,EAAI,CAC3C,EAAW,IAAI,EAAK,CAAE,EAKjB,SAAS,CAAgB,CAAC,EAAK,CACpC,OAAO,EAAW,IAAI,CAAG,EAIpB,SAAS,CAAsC,EAAG,CACvD,EAAW,MAAM",
+  "debugId": "2F392605F11792F264756E2164756E21",
+  "names": []
+}