phlex-reactive 0.4.8 → 0.9.0

data/README.md

@@ -12,8 +12,7 @@ hand-picking Turbo Stream targets.**
 
 ```ruby
 class Counter < ApplicationComponent
-  include Phlex::Reactive::Streamable
-  include Phlex::Reactive::Component
+  include Phlex::Reactive::Component   # pulls in Streamable too
 
   reactive_state :count
   action :increment
@@ -92,6 +91,14 @@ That's all for **importmap** apps: the engine mounts the action endpoint at
 `/reactive/actions` and auto-pins (and preloads) the client runtime, and the
 installer adds the eager registration below to your Stimulus entrypoint.
 
+Verify the whole install any time with the doctor — it checks the route, the
+Stimulus registration, CSRF, the identity verifier, and every component, printing
+`✓/✗/?` with a fix for each failure:
+
+```bash
+bin/rails phlex_reactive:doctor
+```
+
 <details>
 <summary>What the installer wires (or do it by hand)</summary>
 
@@ -128,8 +135,10 @@ import ReactiveController from "phlex/reactive/reactive_controller"
 application.register("reactive", ReactiveController)
 ```
 
-The JS ships at `app/javascript/phlex/reactive/reactive_controller.js` in the
-gem; point your bundler at the gem path or copy it in. See
+The gem ships a prebuilt, minified `reactive_controller.min.js` (~22 KB vs the
+~106 KB commented source) with a linked sourcemap, and auto-pins it for importmap
+apps — so browsers load the small file while devtools still shows the real code.
+Point your bundler at the gem path or copy the `.min.js` (+ its `.map`) in. See
 [docs/installation.md](https://phlex-reactive.zoolutions.llc/docs/installation).
 </details>
 
@@ -141,7 +150,9 @@ for broadcasting.
 
 Two host-app setups make the first reactive component *silently do nothing* —
 components render, but no action ever fires, with no error pointing at the cause.
-The gem now logs a warning for each, but here are the fixes:
+Run `bin/rails phlex_reactive:doctor` first — it flags both of these (and more)
+with the fix inline. The gem also logs a warning for each at boot; here are the
+fixes:
 
 **A catch-all route shadows `POST /reactive/actions`.** The engine appends its
 route *after* everything in your `config/routes.rb`, so a bottom-of-file
@@ -224,15 +235,13 @@ GlobalID; the server re-finds it on each action. **Always prefer this.**
 
 ```ruby
 class Todos::Item < ApplicationComponent
-  include Phlex::Reactive::Streamable
   include Phlex::Reactive::Component
 
-  reactive_record :todo
+  reactive_record :todo             # identity AND the default #id: dom_id(@todo)
   action :toggle
   action :rename, params: { title: :string }
 
   def initialize(todo:) = @todo = todo
-  def id = dom_id(@todo)            # stable per-record DOM id == Turbo target
 
   def toggle
     authorize! @todo, :update?      # YOU authorize — the token only proves identity
@@ -253,6 +262,17 @@ class Todos::Item < ApplicationComponent
 end
 ```
 
+> **One include, default `#id` (issue #81).** `include Phlex::Reactive::Component`
+> pulls in `Streamable` automatically (the explicit two-include form still works
+> and is a harmless no-op). A record-backed component also gets `#id` for free —
+> `dom_id(record)`, exactly the id nearly every one wrote by hand — so `def id`
+> is only needed to override it, and an explicit `def id` always wins.
+> **Caveat:** two *different* component classes rendering the *same* record on
+> one page both default to the same `dom_id` and collide — give one an explicit
+> prefixed id: `def id = dom_id(@todo, "rich")`. State-backed components still
+> must define `#id` (they're frequently multi-instance, so a class-name default
+> would silently collide; the loud `NotImplementedError` stays).
+
 ### 2. State-backed (signed instance vars)
 
 Sign small, JSON-serializable instance vars into the token. Use it **alone** for
@@ -275,14 +295,21 @@ The [inline edit example](https://phlex-reactive.zoolutions.llc/docs/example-inl
 | Example | What it shows |
 |---|---|
 | [Counter](https://phlex-reactive.zoolutions.llc/docs/example-counter) | State-backed, the smallest reactive component |
-| [Payment split](https://phlex-reactive.zoolutions.llc/docs/example-payment-split) | Live sum-to-total rebalancer — nested bracketed params, a disabled computed field, auto-collected siblings (#64–#67) |
+| [Payment split](https://phlex-reactive.zoolutions.llc/docs/example-payment-split) | Nested bracketed params, auto-collected siblings, and a live `reactive_compute` + `reactive_text` preview (#64–#67, #104) |
 | [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/delete, Enter-to-add, broadcast on change |
-| [Inline edit](https://phlex-reactive.zoolutions.llc/docs/example-inline-edit) | Show ↔ edit mode toggle, replacing a Stimulus controller + 3 routes |
-| [Notifications / badges](https://phlex-reactive.zoolutions.llc/docs/example-notifications) | Pure broadcast (no client action) — a job pushes a re-render |
-
-The cross-tab chat in ~60 lines of Ruby (and zero JS) is the showcase — see
-[docs/examples/chat.md](https://phlex-reactive.zoolutions.llc/docs/example-chat).
+| [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 |
+| [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 |
+| [Failure surface](https://phlex-reactive.zoolutions.llc/docs/example-failure) | `error_flash` + `data-reactive-error` + `dismiss_after:` — what you get for free when an action fails |
+| [Team inbox (flagship)](https://phlex-reactive.zoolutions.llc/docs/example-team-inbox) | The whole toolkit in one UI: collection rows, optimistic archive that **reverts on failure**, cross-tab broadcast, an `on_client` kebab, error flashes |
+
+Every page renders its **real** reactive component inline (source read straight
+off the file), so the demo and the code can never drift. The
+[Team inbox](https://phlex-reactive.zoolutions.llc/docs/example-team-inbox) is the
+flagship — every feature composed into one believable UI.
 
 ---
 
@@ -292,12 +319,16 @@ The cross-tab chat in ~60 lines of Ruby (and zero JS) is the showcase — see
 
 | Method | Use |
 |---|---|
-| `#id` (you implement) | Stable DOM id == Turbo Stream target. Must match the root element's `id`. |
+| `#id` | Stable DOM id == Turbo Stream target. Must match the root element's `id`. Record-backed components default to `dom_id(record)` (issue #81); everything else implements it (`def id`). An explicit `def id` always wins. |
 | `.replace(model = nil, morph: false, **opts)` | `<turbo-stream action=replace target=id>` of a freshly built component; `morph: true` adds `method="morph"` |
-| `.update` / `.append(target:)` / `.prepend(target:)` / `.remove` | The other Turbo Stream actions |
+| `.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_append_to(*streamables, target:, model:)` / `_update_` / `_prepend_` / `_remove_` | The broadcast variants |
-| `#to_stream_replace` / `#to_stream_morph` / `#to_stream_update` / `#to_stream_remove` | Stream the *already-built* instance (used internally after an action / by `reply`); `#to_stream_morph` 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 |
+| `#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)`.
 
@@ -305,7 +336,7 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 
 | Macro / helper | Use |
 |---|---|
-| `reactive_record :name` | Record-backed identity (GlobalID). State = the DB. |
+| `reactive_record :name` | Record-backed identity (GlobalID). State = the DB. Also defaults `#id` to `dom_id(record)`. |
 | `reactive_state :a, :b` | Signed instance-var identity. Standalone, or combined with `reactive_record` to sign transient UI state alongside the row. |
 | `action :name, params: { x: :integer }` | Declare a client-invokable action + its param schema. **Default-deny.** |
 | `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. |
@@ -315,15 +346,53 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 | `on(:action, event: "keydown.enter")` | Fire only on a specific key — Enter-to-submit / Escape-to-cancel — via Stimulus's native keyboard filter (`event:` passes straight through). See [Keyboard triggers](#keyboard-triggers-enter-to-submit--escape-to-cancel). |
 | `on(:action, confirm: "Sure?")` | Gate a destructive trigger behind a confirmation. Defaults to `window.confirm`; override the dialog with [`setConfirmResolver`](#custom-confirmation-dialogs-setconfirmresolver). |
 | `on(:search, listnav: "[role=option]")` | Add combobox keyboard navigation — Arrow keys move a client-side highlight, Enter picks (clicks the option's own trigger), Escape clears. See [Combobox keyboard navigation](#combobox-keyboard-navigation-listnav). |
+| `on(:close_menu, outside: true)` | Fire only for events **outside** this component's root (close-a-dropdown-on-outside-click). Window-bound; never `preventDefault`s, so links elsewhere keep navigating. |
+| `on(:track, event: "scroll", window: true, throttle: 250)` | `window:` binds the trigger to the window (page-level scroll/resize); `throttle:` rate-limits leading-edge — first event fires, the rest drop until the window elapses. Mutually exclusive with `debounce:`. |
+| `on(:toggle, optimistic: { checked: :keep })` | Apply a reversible **visual hint** the instant the trigger fires (before the round trip); revert it if the action fails. Cosmetic only. See [Optimistic hints](#optimistic-visual-hints-optimistic). |
+| `on(:save, disable_with: "Saving…")` | Disable the trigger + swap its text while the action is pending (a disabled button also swallows a rapid double-click). Shorthand for `loading: { disable: true, text: "Saving…" }`. See [Loading states](#declarative-loading-states-loading--disable_with). |
+| `on(:save, loading: { disable: true, class: "opacity-50", text: "…" })` | Full loading form: `disable:`, a loading `class:` (on the trigger or a `to:` target), a `text:` swap. Reverts on settle. |
+| `busy_on(:save)` | Mark any element so it carries `data-reactive-busy` **only while `save` is in flight** — a spinner styled with pure CSS, zero Ruby. See [Loading states](#declarative-loading-states-loading--disable_with). |
+| `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`, 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_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_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_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). |
 | `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(*)` | Return from an action to control the reply (flash, remove, redirect, multi-stream). See [Controlling the action's reply](#reply--controlling-the-actions-reply). |
+| `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). |
 | `reply.append(name, model)` / `.prepend(...)` / `.remove(name, model)` | Add/remove a row in a declared `reactive_collection` (row + count + empty-state in one reply). |
 
-Param types: `:string` (default), `:integer`, `:float`, `:boolean`, `:file`.
-Anything not in the schema is dropped before reaching your method.
+Param types: `:string` (default), `:integer`, `:float`, `:boolean`, `:file`,
+`:date`, `:datetime`, `:decimal`. Anything not in the schema is dropped before
+reaching your method. `:date`/`:datetime` parse ISO8601 (a value that won't
+parse is dropped — the keyword default applies); `:decimal` parses through
+`BigDecimal` (dropped on a non-numeric value). The schema is **compiled once at
+declaration**: a typo'd type symbol (`params: { count: :interger }`) raises
+`Phlex::Reactive::UnknownParamType` at class load, not silently coercing to a
+string at click time.
+
+**Custom param types (`Phlex::Reactive.param_type`).** Register your own type in
+an initializer — the block receives the raw client value and returns the coerced
+value, or `Phlex::Reactive::ParamSchema::DROP` to reject it (the keyword default
+then applies, keeping the drop-don't-fabricate contract):
+
+```ruby
+# config/initializers/phlex_reactive.rb
+Phlex::Reactive.param_type(:money) do |value|
+  /\A\d+(\.\d{1,2})?\z/.match?(value.to_s) ? BigDecimal(value) : Phlex::Reactive::ParamSchema::DROP
+end
+
+# then, in any component:
+action :charge, params: { amount: :money }
+def charge(amount:) = @invoice.charge!(amount) # amount is a BigDecimal or unset
+```
+
+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.
 
 **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
@@ -426,6 +495,304 @@ Omit `debounce:` for the immediate-dispatch default.
 input(**mix(on(:update, event: "input", debounce: 300), name: "quantity", value: @item.quantity))
 ```
 
+**Event modifiers — `outside:`, `window:`, `once:`, `throttle:`.** Four more
+`on(...)` options cover the page-level trigger patterns that otherwise need a
+hand-written Stimulus controller:
+
+- `outside: true` fires the action only for events whose target is **outside**
+  this component's root — the close-a-dropdown-on-outside-click pattern. An
+  event inside the root is a complete client-side no-op. Implies `window:`.
+- `window: true` binds the trigger to the window (Stimulus's native `@window`)
+  for page-level events like `scroll`/`resize`. Window-bound triggers are
+  **never `preventDefault`-ed** — a mounted dropdown must not kill link clicks
+  elsewhere on the page — and skip the forced `type="button"`.
+- `once: true` fires at most once, then unbinds (Stimulus's `:once`).
+- `throttle: 250` rate-limits **leading-edge**: the first event fires
+  immediately, further events are dropped until the window elapses. The mirror
+  of `debounce:` (trailing-edge) — passing both raises `ArgumentError`.
+
+```ruby
+# A dropdown that closes itself on any click outside — no Stimulus controller.
+div(**mix(reactive_root, on(:close_menu, outside: true))) do
+  button(**on(:toggle_menu)) { "Menu" }
+  ul { menu_items } if @open
+end
+
+# Throttled page-scroll tracking.
+div(**mix(reactive_root, on(:track, event: "scroll", window: true, throttle: 500)))
+```
+
+These four (like `debounce:`/`confirm:`/`listnav:`) are **reserved keyword
+names** on `on(...)` — no longer usable as free action params.
+
+### Optimistic visual hints (`optimistic:`)
+
+Every reactive action waits a full round trip for its visual change — and it's
+worse than neutral for a checkbox: the client `preventDefault`s the trigger, so
+an `on(:toggle)` checkbox never even **flips** until the morph arrives.
+`optimistic:` gives Livewire's "flip it client-side, let the morph correct" (and
+React's `useOptimistic`): a small, **always-reversible**, cosmetic vocabulary
+applied the instant the trigger fires and **reverted** if the round trip fails.
+
+Hints are visual **only** — never data, never a computed value (that would be
+client state the DOM can't be trusted to hold). Supported ops in the hint hash:
+
+- `toggle_class:` / `add_class:` / `remove_class:` — a class string or array,
+  applied to the **trigger** by default, or to a `to:` selector scoped to the
+  root (`to: :root` targets the root element itself).
+- `checked: :keep` — for a **click-bound** checkbox/radio, the client skips its
+  unconditional `preventDefault` so the **native flip happens now** (a bare
+  toggle click has no navigation default to lose). `on(...)` also skips the
+  forced `type="button"` it normally adds to click triggers — that would destroy
+  the very checkbox being toggled — so you supply the real `type="checkbox"` /
+  `type="radio"`. On a `change`-bound control the flip is already native
+  (`change` isn't cancelable) — `:keep` then only contributes the failure revert.
+- `hide: true` — hides the target immediately.
+
+```ruby
+# A checkbox that flips instantly; the label paints in the same gesture. The
+# morph reconciles from server truth; a failure snaps both back.
+input(type: "checkbox", checked: @todo.done,
+  **mix(on(:toggle, event: "change", optimistic: { checked: :keep, toggle_class: "is-done", to: ".status" }),
+    name: "done"))
+
+# Instant delete: hide the row NOW, remove it on the reply.
+button(**on(:destroy, confirm: "Delete?", optimistic: { hide: true, to: :root })) { "Delete" }
+```
+
+**The success/failure contract (load-bearing):**
+
+- **On failure** — any branch (`redirected` / `http` / `content-type` /
+  `network`, plus a client-side `apply` throw) — the client replays the exact
+  **inverse** ops, guarded by `isConnected` (a detached row is skipped, it's
+  gone anyway). The hint stored on the queued request, so the serialized
+  per-controller queue reverts the **right** request's hint.
+- **On success there is NO cleanup.** A reply that re-renders the root
+  **overwrites** the hint with server truth. A reply that does **not** re-render
+  the root (`reply.remove`, streams-only) **leaves the hint standing** — that's
+  the `hide: true` + `reply.remove` instant-delete recipe working as intended:
+  the row hides, then removes, and never flashes back.
+
+`optimistic:` (like `debounce:`/`confirm:`/`throttle:`) is a **reserved keyword
+name** on `on(...)`. An unknown hint op, a `checked:` value other than `:keep`,
+or a non-hash raises at render — a dead hint fails loudly, never silently.
+
+### Declarative loading states (`loading:` / `disable_with:`)
+
+Between the click and the morph, the user needs to see that something is
+happening — and a mutating button needs to stop a rapid double-click from firing
+twice. `loading:` / `disable_with:` are Livewire's `wire:loading` +
+`phx-disable-with` and LiveView's `phx-click-loading`, without a Stimulus
+controller. Both are **reserved keyword names** on `on(...)`.
+
+The moment a request is **enqueued** — covering the queue wait, not just the
+fetch — the trigger and root get the always-on busy vocabulary, and (if declared)
+the loading hint applies; everything reverts when the round trip settles
+(success **or** failure), guarded so a re-rendered trigger is never clobbered.
+
+**`disable_with:` — the common case.** Disable the trigger and swap its text
+while pending. A disabled button fires no further clicks, so a rapid double-click
+enqueues exactly **one** POST (the queue only serializes tokens — it does not
+dedupe; the disable is what dedupes):
+
+```ruby
+button(**on(:save, disable_with: "Saving…")) { "Save" }
+```
+
+**`loading:` — the full form.** A hash of:
+
+- `disable: true` — disable the trigger while pending.
+- `class: "…"` / `[ … ]` — a loading class on the **trigger**, or on a `to:`
+  selector scoped to the root (`to: :root` targets the root element itself).
+- `text: "Saving…"` — swap the trigger's `textContent` while pending.
+
+```ruby
+button(**on(:destroy, confirm: "Sure?", loading: { disable: true, class: "opacity-50 pointer-events-none" })) { "Delete" }
+```
+
+`disable_with: "Saving…"` is the shorthand for `{ disable: true, text: "Saving…" }`
+and, if you pass both, merges over an explicit `loading:` (its `text`/`disable`
+win). An unknown loading key or a non-hash `loading:` raises at render.
+
+**The `aria-busy` + `data-reactive-busy` contract (always on — zero Ruby).**
+Independent of any `loading:` hint, **every** reactive round trip marks the DOM
+for the whole enqueue→settle window, so you can style spinners and dimming with
+pure CSS:
+
+- the **trigger** and the **root** carry `data-reactive-busy="<action>"` (a
+  **space-separated set** on the root, so two concurrent actions never clobber);
+- the **root** carries `aria-busy="true"` (driven by a pending counter — it
+  clears only when the last in-flight request settles, so overlapping actions
+  don't clear it early);
+- `busy_on(:action)` marks any element inside the root so **it** gets
+  `data-reactive-busy` toggled **only while that action is in flight** — a scoped
+  spinner:
+
+```ruby
+button(**on(:save, disable_with: "Saving…")) { "Save" }
+span(**busy_on(:save), class: "spinner")
+```
+
+phlex-reactive ships **no CSS** for these — you own the styling. A minimal
+example (not shipped — copy into your app's stylesheet):
+
+```css
+/* Reveal a busy_on / aria-busy spinner only while its action is in flight. */
+.spinner { display: none; }
+[data-reactive-busy] .spinner,
+[data-reactive-busy].spinner { display: inline-block; }
+
+/* Dim the whole component during any round trip. */
+[aria-busy="true"] { opacity: 0.6; transition: opacity 120ms ease; }
+```
+
+The disable + text swap apply **only at enqueue**, never during a `debounce:`
+quiet period — so a debounced `input` trigger (whose element *is* the text field)
+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:`)
+
+Show "unsaved changes", enable **Save** only when something changed, or warn
+before navigating away — Livewire's `wire:dirty` — **without shipping any client
+state**. The trick: the browser already holds the last server-rendered value with
+zero extra bytes. `input.defaultValue` / `defaultChecked` / `option.defaultSelected`
+**are** the attributes from the last render. So **dirty = current ≠ default**, and
+phlex-reactive reads that baseline straight from the DOM — nothing to snapshot,
+nothing to sign.
+
+```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" }
+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).
+- 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
+  - the root with **`data-reactive-dirty="<count>"`** (the attribute is **absent
+    at zero** — so `[data-reactive-dirty]` matches iff the form is dirty).
+- The re-scan is a **full pass**, not a per-field toggle — required for radio
+  groups: deselecting a radio fires no event on the *deselected* one, so only
+  re-scanning everything keeps its flag honest.
+
+**The CSS vocabulary (you own the styling — phlex-reactive ships none):**
+
+```css
+/* Reveal an "unsaved" badge only while the form has changes. */
+.unsaved-badge { display: none; }
+[data-reactive-dirty] .unsaved-badge { display: inline; }
+
+/* Outline just the fields that changed. */
+[data-reactive-dirty] { outline: 2px solid gold; }
+
+/* Enable Save only when dirty (pair with a :disabled default). */
+[data-reactive-dirty] button[data-testid="save"] { pointer-events: auto; opacity: 1; }
+```
+
+**Baselines reset on the server's re-render.** A plain replace re-connects the
+controller (re-scan on `connect`); an in-place **morph** keeps the element
+connected and fires no Stimulus lifecycle, so the client also re-scans on
+`turbo:morph-element` after the morph writes fresh `default*` attributes. So a
+`reply.morph` save renders the field with the new value as its **new default**,
+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.
+
+**Out of scope (v1):** rich-text / `contenteditable` editors have no `default*`
+baseline and are **not** tracked. Combining `reactive_field(dirty:)` 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).
+
+### Client-only ops (`on_client` + `js`) — zero round trips
+
+Not every interaction needs the server. A tab switch, a dropdown, an accordion
+— purely visual state — used to mean either a wasteful signed round trip or the
+very Stimulus controller this gem exists to eliminate. `on_client` binds a DOM
+event to a chain of **declared DOM operations** that the one generic controller
+applies locally: **no token, no params, no POST, ever.**
+
+```ruby
+def view_template
+  div(**mix(reactive_root, on_client(:click, js.hide("#menu"), outside: true))) do
+    # Tabs: one op chain per tab — hide all panels, show one, restyle the tabs.
+    button(**on_client(:click, js.hide(".panel").show("#panel-2")
+      .remove_class(".tab", "active").add_class("#tab-2", "active"))) { "Tab 2" }
+
+    # A menu that opens client-side and closes on ANY outside click (the root
+    # carries the window-bound trigger above).
+    button(**on_client(:click, js.show("#menu"))) { "Menu" }
+    div(id: "menu", hidden: true) { menu_items }
+  end
+end
+```
+
+The `js` builder is immutable (each verb returns a new chain) and its
+vocabulary is a fixed whitelist mirrored by the client: `show`/`hide`/`toggle`
+flip the `hidden` attribute; `add_class`/`remove_class`/`toggle_class` take one
+or more classes. Targets are CSS selectors resolved **within the component's
+root** (nested reactive components are never touched — same ownership rule as
+field collection); `:root` targets the root element itself; `global: true` on
+an op escapes to the whole document. An op name the client doesn't recognize
+logs a warning and is skipped — the rest of the chain still applies.
+
+**Attributes, focus, dispatch, and transitions.** Beyond visibility and classes,
+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_attr(:root, "aria-expanded")   # accessible disclosure state
+  .focus_first("#menu")                   # move focus into the opened menu
+  .dispatch("app:menu-toggled", detail: { open: true }))) { "Menu" }
+```
+
+- **`set_attr(to, name, value)` / `remove_attr(to, name)` / `toggle_attr(to, name)`**
+  mutate an attribute. The **attribute name is allowlisted, enforced twice** — at
+  build time in Ruby (an offending name raises) and again in the client
+  interpreter (a hand-built op is warned and skipped). Refused: **event handlers**
+  (`on*` → XSS), **URL-bearing** names (`href`, `src`, `srcdoc`, `action`,
+  `formaction`, `xlink:href` → a `javascript:` navigation surface), and **`style`**
+  (CSS injection — use classes). The **intended surface** is class ops plus
+  `hidden`, `disabled`, `open`, `selected`, and any `aria-*` / `data-*` attribute.
+- **`focus(to)`** focuses the first match; **`focus_first(to)`** focuses the first
+  focusable descendant of the match (e.g. the first menuitem inside an opened
+  menu).
+- **`dispatch(name, to: nil, detail: {})`** emits a **bubbling `CustomEvent`** so
+  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
+  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
+  is never blocked — later ops (a `focus`, a `dispatch`) run immediately.
+
+`window:`, `once:`, and `outside:` compose exactly like `on(...)`'s event
+modifiers: the dropdown above closes on any click outside the component, and
+window-bound triggers never `preventDefault`, so links elsewhere keep working.
+
+**Client ops are ephemeral UI — the one contract to internalize.** Any server
+re-render of the component (an action reply, a broadcast, a morph) rebuilds
+from server state and resets whatever the ops toggled: the menu closes, the tab
+snaps back. That is by design — the same caveat LiveView's JS commands carry.
+For state that must survive a re-render (an edit mode, a selection the server
+should know about), use a signed `action` instead; `on_client` is for state the
+server should never care about.
+
 **Auto-collected sibling fields — the read contract.** A reactive action doesn't
 just receive its own trigger's value: the client gathers **every named control**
 in the reactive root (`input[name]`, `select[name]`, `textarea[name]`, and named
@@ -482,6 +849,53 @@ free as an ordinary action-param name (`on(:switch, key: "pgbus")` still passes
 > trigger to its own element (the field saves on Enter; a Cancel button — or the
 > field's own blur — handles Escape), as above.
 
+### Client-side computes (`reactive_compute` + `reactive_text`)
+
+Some math should feel instant with **no round trip** — a NEW, unsaved record's
+running total, a live title preview, a character counter. `reactive_compute`
+declares a client-side reducer (a plain JS function registered once) that runs on
+`input` and writes derived values straight into the DOM. When the component also
+carries `on(...)`, the debounced POST still fires and the server reply reconciles
+— the compute just paints first.
+
+```ruby
+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" }))
+  h2    { reactive_text(:title_preview, @post.title) }  # a text-node output
+  small { reactive_text(:char_count) }                  # another text-node output
+end
+```
+
+```js
+// Register the reducer once at boot. Its signature is (values, { changed }).
+import { setComputeReducer } from "phlex/reactive/compute"
+setComputeReducer("preview", ({ title }) => ({
+  title_preview: title, char_count: `${title.length}/80`,
+}))
+```
+
+- **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.
+- **`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.
+- **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
+  new-vs-persisted split relies on.
+
 ### Combobox keyboard navigation (`listnav:`)
 
 A searchable list needs Arrow keys to move a highlight, Enter to pick, Escape to
@@ -647,14 +1061,15 @@ def update(quantity:, price:) = (@item.update!(quantity:, price:); reply.streams
 
 | Builder | Reply |
 |---|---|
-| `reply.replace` / `reply.update` | re-render in place (default; `replace` is an outerHTML swap, `update` morphs inner HTML) |
-| `reply.morph` / `reply.replace(morph: true)` | re-render in place via Idiomorph (`method="morph"`) — preserves the focused `<input>` + caret; for per-field reactive editing (issue #28) |
+| `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 |
-| `.flash(level, content, target: …)` | append a flash; `content` is a plain string (escaped) or a Phlex component (off-request — no Rails `flash`); target defaults to `Phlex::Reactive.flash_target` (`"flash"`) |
+| `.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 |
 | `reply.streams(*streams)` | **partial update** — emit exactly these streams (no full-self replace) + a tiny token-only refresh, so live inputs survive; for per-field grid editing (issue #30) |
+| `.js(ops, target: …)` | also push **client DOM ops** (focus, dispatch, class/attr toggles) over a `reactive:js` stream, applied AFTER the render — `reply.morph.js(js.focus("[name=next]"))` focuses the morphed field (issue #97) |
 | `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
@@ -664,6 +1079,79 @@ update only the targets you name) and refreshes the token via a tiny inert
 `reactive:token` stream instead — the token rolls forward without re-rendering
 (and clobbering) the component's live inputs.
 
+#### Flash levels
+
+The level reaches the wire (issue #77). **String** content is wrapped in a
+level-carrying `<div>`, so `:error` and `:notice` are styleable:
+
+```html
+<div class="reactive-flash reactive-flash--error" data-reactive-flash-level="error">
+  Save failed
+</div>
+```
+
+Style against `.reactive-flash--{level}` (the class) and hook scripts/tests on
+`data-reactive-flash-level` (the data attribute). The string keeps the same
+injection contract as before, applied inside the wrapper: a plain string is
+HTML-escaped (a model value can't inject markup); an `html_safe` string passes
+verbatim.
+
+Prefer your own markup? Two escape hatches:
+
+```ruby
+# 1. Pass a Phlex component as the content — rendered VERBATIM, no wrapper
+#    (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
+```
+
+#### Server-pushed client ops (`reply.js` + `broadcast_js_to`, 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
+unread badge — WITHOUT re-rendering to make it happen. `reply.<verb>.js(ops)`
+chains a `reactive:js` stream carrying declared client DOM ops (the same `js`
+builder as [`on_client`](#client-only-ops-on_client--js--zero-round-trips))
+onto any reply. The op stream rides **after** the render streams, so a focus op
+sees the freshly rendered/morphed DOM:
+
+```ruby
+def save(title:)
+  @todo.update!(title:)
+  # Morph in place, THEN focus the next field + tell a toast host we saved:
+  reply.morph.js(js.focus("[name=next_field]").dispatch("app:saved", detail: { id: @todo.id }))
+end
+```
+
+`target:` scopes op resolution on the client; it defaults to the bound
+component's id for `replace`/`morph`/`update` (so `@root` and component-relative
+selectors just work), and to document-scope for a subject-free `reply.with`.
+
+The same ops broadcast to **every** subscriber of a stream over the usual
+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)
+```
+
+`broadcast_js_to` **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
+whitelist-interpreted client-side — an unknown op warns and is skipped — and the
+ops attribute is HTML-escaped, so a value can't break out of it. `reactive:js`
+is not a self-render: it never counts toward the token refresh, so the reply's
+signed token still rolls forward exactly as it would without the ops.
+
+> **Ephemeral by design.** Like `on_client`, server-pushed ops are transient UI:
+> the next server re-render of the component resets whatever they toggled. State
+> that must survive a re-render belongs in a signed `action`, not an op.
+
 #### Record-authorized, transient-state actions (issue #64)
 
 A `reactive_record` component isn't obligated to persist or broadcast — the
@@ -677,7 +1165,6 @@ the params, stream a partial update, touch neither the DB nor peer tabs" action:
 
 ```ruby
 class Invoice::PaymentFields < ApplicationComponent
-  include Phlex::Reactive::Streamable
   include Phlex::Reactive::Component
 
   reactive_record :invoice   # identity + authorization ONLY — not persisted here
@@ -708,6 +1195,229 @@ aren't clobbered. Authorize the record as always — identity is never permissio
 > rendered and auto-escaped through the renderer — or an `html_safe` string for
 > raw HTML you control.
 
+### Failure UX & lifecycle events
+
+The generic controller dispatches three bubbling, composed `CustomEvent`s
+around every action round trip, so an app can toast an error, instrument
+latency, veto a dispatch, or build retry UI **without forking the controller**:
+
+| Event | When | `event.detail` |
+|-------|------|----------------|
+| `reactive:before-dispatch` | after the trigger's `preventDefault`/`confirm:`, **before** debounce/enqueue | `{ action, params, element }` — cancelable: `event.preventDefault()` skips the round trip entirely (nothing is scheduled) |
+| `reactive:applied` | after the response's token was captured and the streams were handed to `Turbo.renderStreamMessage` | `{ action, params, html }` |
+| `reactive:error` | in every failure branch of the round trip | `{ action, params, kind, status?, body?, retry }` |
+
+`reactive:error`'s `kind` tells you **what** failed:
+
+| `kind` | Meaning | Extra detail |
+|--------|---------|--------------|
+| `redirected` | the POST was redirected (an auth `before_action` / CSRF guard bounced it) | `status`, `retry` |
+| `http` | non-2xx response (403 default-deny/authorization, 400 bad token, 404 record gone, 500 …) | `status`, `body`, `retry` |
+| `content-type` | 200, but not a turbo-stream (an HTML error page, a misconfigured route) | `status`, `retry` |
+| `timeout` | the request took longer than the configured window (default 30s) and was aborted — the server may or may not have finished | `retry` |
+| `offline` | the browser was offline (`navigator.onLine === false`) when the action fired — the fetch was never sent | `retry` |
+| `network` | `fetch` itself rejected (DNS, connection reset, an interface drop mid-flight) — the server never saw the request | `retry` |
+| `apply` | the server processed the action successfully, but something AFTER the fetch threw (a malformed response, a Turbo render error) | no `retry` |
+
+`apply` covers a throw in the controller's own post-fetch code — not a
+throwing listener on `reactive:applied` itself. Per the DOM spec,
+`EventTarget#dispatchEvent` never propagates a listener's exception back to
+its caller (it's reported to the console instead), so a listener that throws
+can't surface as `reactive:error` at all — it just logs and the round trip is
+otherwise unaffected.
+
+`detail.retry()` re-enters the controller's request queue: it re-reads the
+**freshest** signed token and re-collects the component's fields at send time,
+so nothing stale is replayed. It fires no second `reactive:before-dispatch`
+(one veto per user gesture), and it no-ops with a `console.warn` once the
+component has left the DOM. The existing `console.error` logging is unchanged —
+the events add hooks, they don't replace the log.
+
+**`kind: "apply"` carries no `retry()` at all** — by the time this fires the
+server has already completed the mutation, so retrying would re-POST an
+action that already succeeded (potentially a non-idempotent one). Every kind
+EXCEPT `apply` is retriable.
+
+#### Request timeout (`kind: "timeout"`)
+
+A server that never responds used to wedge a component's request queue forever
+(each action chains on the previous one) — the spinner never cleared and every
+later action froze. Now the fetch is bounded by `AbortSignal.timeout`: after the
+window (default **30 s**) it aborts, fires `reactive:error` `kind: "timeout"`,
+and the queue advances so the component keeps working. Configure the window with
+a page-stable meta (app-authored, following the same pattern as the action path):
+
+```erb
+<meta name="phlex-reactive-timeout" content="15000"> <%# 15s #%>
+```
+
+> **Non-goal — no automatic replay.** A timed-out POST **may have succeeded
+> server-side** (the server just answered too late). phlex-reactive never
+> auto-replays a request, and even a manual `retry()` can double-apply a
+> non-idempotent action. Make retryable actions idempotent, or gate your retry
+> UI accordingly.
+
+#### Offline (`kind: "offline"`)
+
+When the browser is offline (`navigator.onLine === false`) at send time, the
+action short-circuits **before the fetch** — the edit is never half-sent — and
+fires `reactive:error` `kind: "offline"` with a `retry()`. The check lives at the
+network boundary, so a request that enqueued while online but reaches the wire
+after a connection drop is reported as `offline`, not `network`.
+
+`phlex-reactive` also mirrors `data-reactive-offline` onto `<html>` whenever the
+browser goes offline (kept in sync by the `online`/`offline` events) — a **pure
+CSS hook**, zero app JS:
+
+```css
+[data-reactive-offline] .save-button { opacity: .5; pointer-events: none }
+[data-reactive-offline] .offline-banner { display: block }
+```
+
+```js
+// Auto-retry a specific action when the connection returns:
+document.addEventListener("reactive:error", (e) => {
+  if (e.detail.kind === "offline") {
+    addEventListener("online", () => e.detail.retry(), { once: true })
+  }
+})
+```
+
+#### Latency simulator (development aid)
+
+On localhost the click→morph round trip is **~5 ms**, so the pending affordances
+you just wired — `aria-busy`, `disable_with:`, `busy_on`, optimistic hints —
+flash by too fast to actually *see* while developing or demoing them. That's the
+same problem LiveView solves with `liveSocket.enableLatencySim(ms)`.
+
+`phlex-reactive` ships the equivalent. Because importmap module exports aren't
+reachable from the DevTools console, the two functions are exposed on a
+`window.PhlexReactive` handle — but **only** when your layout opts in with a
+development-gated meta:
+
+```erb
+<%# app/views/layouts/application.html.erb, inside <head> — DEVELOPMENT ONLY %>
+<%= tag.meta(name: "phlex-reactive-env", content: "development") if Rails.env.development? %>
+```
+
+Then, from the browser console:
+
+```js
+PhlexReactive.enableLatencySim(400)   // delay EVERY action by 400ms
+// …click around; aria-busy, spinners, disable_with, optimistic hints are now visible…
+PhlexReactive.disableLatencySim()     // back to full speed
+```
+
+The delay is read live before each fetch (so toggling takes effect on the very
+next action, no reload) and persists to `sessionStorage` — it clears when the tab
+closes, so you can't accidentally leave it on across sessions. A one-time console
+banner reminds you while it's active.
+
+Without the meta there is **no global handle at all** and the per-request read
+short-circuits on a `null` — **zero production surface**. It's purely a
+development convenience, gated by markup you author.
+
+The events bubble from the component's root element (or from `document` when
+the root was detached by the failing round trip), so they compose with plain
+Stimulus listening — a global toaster is one attribute on an ancestor:
+
+```html
+<body data-controller="toast" data-action="reactive:error->toast#show">
+```
+
+```js
+// toast_controller.js
+show(event) {
+  const { kind, status, retry } = event.detail
+  this.flash(`Action failed (${kind}${status ? ` ${status}` : ""})`, { onRetry: retry })
+}
+```
+
+Or veto/instrument at the document level:
+
+```js
+document.addEventListener("reactive:before-dispatch", (event) => {
+  if (offline) event.preventDefault()           // cancel: nothing is enqueued
+})
+document.addEventListener("reactive:applied", ({ detail }) => {
+  metrics.count(`reactive.${detail.action}.ok`)
+})
+```
+
+One honest caveat on timing: `reactive:applied` means the turbo-streams were
+**handed to Turbo** — `renderStreamMessage` applies them asynchronously, so the
+DOM mutation may complete a tick later. If you need post-morph timing, listen
+to Turbo's own events (`turbo:before-stream-render` and friends).
+
+#### Showing the user a failure (not just the console)
+
+The events above are the *hook* — but a user who just wants to see "that
+didn't work" shouldn't have to write a toast controller. There are three
+built-in ways to surface a failure, cheapest first:
+
+**1. In-action validation replies (already works).** For a failure your action
+*knows about* — a validation error, a business rule — return a flash directly.
+It renders at **200** (a normal reply, not an error):
+
+```ruby
+def rename(title:)
+  return reply.replace.flash(:error, "Title can't be blank") if title.blank?
+  @todo.update!(title:)
+end
+```
+
+**2. `Phlex::Reactive.error_flash` — server-rendered flashes on endpoint
+failures.** For the failures the *endpoint* catches (bad token, default-deny,
+authorization, missing record — the 400/403/404 rescue paths), set a lambda and
+every one renders a turbo-stream flash the user sees, at the **same status** it
+already returns (statuses never change):
+
+```ruby
+# config/initializers/phlex_reactive.rb
+Phlex::Reactive.error_flash = ->(kind) { "Something went wrong (#{kind})." }
+```
+
+The client now **renders non-OK turbo-stream bodies** (previously it read the
+body only for the console and discarded it), so an `error_flash` — or a plain
+controller replying `status: :unprocessable_entity` with a turbo-stream flash —
+lands in your flash region. The failing component's root also gets
+`data-reactive-error="<kind>"`, so you can style it in **pure CSS** with zero JS,
+and the next successful action clears it:
+
+```css
+[data-reactive-error] { outline: 2px solid var(--danger); }
+```
+
+> **Note.** A 400 (invalid token) reply never refreshes the client's held token
+> — the identity token is not a nonce, it stays retry-valid. The client only
+> adopts a fresh token from a body that re-renders *this* element's id, so a
+> foreign/error body can't swap it out.
+
+**3. Offline fallback (no server to render anything).** A `network` failure
+reached no server, so there's nothing to render. Opt in with a server-rendered
+`<template>` in your layout — on a network failure the client clones it into the
+flash region (it's your trusted markup, cloned verbatim — no client templating):
+
+```erb
+<template data-reactive-error-flash>
+  <div class="reactive-flash reactive-flash--error">You appear to be offline.</div>
+</template>
+```
+
+#### Self-dismissing flashes (`dismiss_after:`)
+
+A flash that never cleans itself up piles up. Pass `dismiss_after:` (ms) and the
+flash removes itself after the timeout — driven by a **document-level** handler,
+so it self-cleans both reply-delivered and **broadcast-delivered** flashes (the
+flash container is a plain host-app div with no controller attached):
+
+```ruby
+reply.replace.flash(:error, "Couldn't save — try again", dismiss_after: 4000)
+```
+
+It wraps string content with `data-reactive-dismiss-after="4000"`; a verbatim
+Phlex component owns its own lifecycle and is left untouched.
+
 ### Reactive collections (add/remove rows + count + empty-state)
 
 An add/remove-row list — line items, attachments, tags, comments, a
@@ -722,7 +1432,6 @@ Declare the collection on the container component, then `reply.append` /
 
 ```ruby
 class NotificationsList < ApplicationComponent
-  include Phlex::Reactive::Streamable
   include Phlex::Reactive::Component
 
   reactive_collection :notifications,
@@ -794,14 +1503,77 @@ Phlex::Reactive.verifier = ActiveSupport::MessageVerifier.new(ENV["REACTIVE_KEY"
 
 # Change the endpoint path (default "/reactive/actions"):
 Phlex::Reactive.action_path = "/_r/actions"
+
+# Diagnostic error bodies + dropped-param logging (default: Rails.env.local? —
+# on in development AND test, off in production):
+Phlex::Reactive.verbose_errors = true
+
+# User-visible flash on endpoint failures (default nil = off). When set, every
+# rescue path (400/403/404) ALSO renders a turbo-stream flash the user sees — at
+# the SAME status it returns today (statuses never change). The lambda receives
+# the failure kind (:tampered/:unknown_class/:not_reactive_class/:forbidden/
+# :not_found), so you can map it to a friendly message:
+Phlex::Reactive.error_flash = ->(kind) do
+  case kind
+  when :not_found  then "That item is no longer available."
+  when :forbidden  then "You don't have permission to do that."
+  else                  "Something went wrong — please try again."
+  end
+end
+
+# Component-aware wrapper around every action (audit / rate-limit / assert).
+# Sees the resolved component, action name, and COERCED params; runs inside
+# the connection-id scope but OUTSIDE the transaction. See "Two seams" below.
+Phlex::Reactive.around_action do |ctx, &action|
+  RateLimiter.check!(ctx.request.remote_ip, ctx.action_name) # raise -> 403
+  result = action.call
+  AuditLog.record!(actor: Current.user, action: ctx.action_name)
+  result # <- REQUIRED: return the continuation's value
+end
 ```
 
+#### Two seams: HTTP-layer (`base_controller_name`) vs component-layer (`around_action`)
+
+There are two places to wrap a reactive action, and they see different things:
+
+| | Base controller (`base_controller_name`) | `Phlex::Reactive.around_action` |
+|---|---|---|
+| **Layer** | HTTP request | the resolved component action |
+| **Sees** | headers, session, `request` | the component instance, action name, **coerced** params, `request` |
+| **Runs** | full Rails filter chain | inside `with_connection_id`, **outside** the transaction |
+| **Use for** | auth, CSRF, coarse per-IP rate limiting | audit logging, component-aware rate limiting, assertions |
+
+Plain Rails `around_action` / `rate_limit` on a dedicated base controller already
+covers attributes, authentication, and coarse per-IP throttling — but that layer
+never sees the resolved component, the declared action name, or the coerced
+params, and can't sit *inside* the connection-id scope yet *outside* the action's
+transaction. `Phlex::Reactive.around_action` is that component-aware seam. `ctx` is
+a frozen `Phlex::Reactive::ActionContext` (`component`, `action_name`, `params`,
+`request`); the fold runs *after* token verify, default-deny, and param coercion,
+so a wrapper can never widen what's invokable.
+
+**Contract — each wrapper MUST return `action.call`'s value.** The endpoint
+type-checks the action's return for a `Phlex::Reactive::Response`; a wrapper that
+ends on its logger's return value instead silently downgrades every reply to the
+implicit self-replace. A wrapper raising a registered `authorization_errors` error
+renders as 403; an unregistered raise is a 500. Multiple wrappers nest in
+registration order (last-registered outermost). Tests reset the stack with
+`Phlex::Reactive.reset_around_actions!`.
+
 If you set a custom `action_path`, expose it to the client:
 
 ```erb
 <meta name="phlex-reactive-action-path" content="<%= Phlex::Reactive.action_path %>">
 ```
 
+The client request timeout (default 30 s) is likewise an app-authored meta —
+there is no server-side setting, so drop it in your layout head if 30 s is wrong
+for your slowest action:
+
+```erb
+<meta name="phlex-reactive-timeout" content="15000"> <%# 15s, in ms #%>
+```
+
 ---
 
 ## Security
@@ -827,6 +1599,60 @@ real, so read this once.
   but if you have *public* reactive components, ensure the action path isn't
   force-redirected to a login page for logged-out users.
 
+### Token payload versioning
+
+The signed identity payload carries a version (`"v"`,
+`Phlex::Reactive::TOKEN_VERSION`) so a future change to the token *shape* can
+**upgrade tokens already in flight** instead of breaking every open page at
+deploy. When you change the shape, bump `TOKEN_VERSION` and register an upgrader:
+
+```ruby
+# config/initializers/phlex_reactive.rb
+Phlex::Reactive.register_token_upgrader(0) do |payload|
+  payload.merge("gid" => rewrite_old_gid(payload["gid"]))
+end
+```
+
+On verify, the payload runs through the upgrader chain (oldest → current) before
+your component rebuilds from it. A pre-versioning token (no `"v"`) is read as-is
+— introducing versioning invalidated nothing. It **fails closed**: a token signed
+by a *newer* deploy than the running code (a rollback) verifies its signature but
+carries an unknown version, so `Phlex::Reactive.verify` returns `nil` and the
+endpoint answers 400 — never guessing a shape it doesn't understand. See
+[the security guide](https://phlex-reactive.zoolutions.llc/docs/security#token-lifetime-rotation)
+for depth.
+
+### Debugging endpoint failures (`verbose_errors`)
+
+Every endpoint failure is warn-logged as `[phlex-reactive] …` in **every**
+environment. With `Phlex::Reactive.verbose_errors` on (the default in
+development and test via `Rails.env.local?`; off in production), the failure
+response ALSO carries a plain-text diagnostic body — the client already prints
+it via `console.error` — and param coercion warn-logs every dropped key with
+its full bracketed path and reason (`undeclared` / `uncoercible`), including a
+hint when a flat name looks like the bracketed twin of a declared nested key
+(or vice versa). What each status means:
+
+- **400** — token signature invalid (stale token from before a deploy?
+  `secret_key_base` mismatch?), a token class that no longer resolves, or a
+  class that resolved but doesn't include `Phlex::Reactive::Component`
+- **403** — an undeclared action (the body lists the declared actions) or a
+  registered authorization error raised inside the action
+- **404** — the signed GlobalID no longer resolves (record deleted)
+
+The flag never changes a status — only the body and the coercion log.
+
+The same flag also makes `on(:typo)` fail loudly at **render** time: when
+`verbose_errors` is on, `on(:name)` raises `Phlex::Reactive::Error` (listing the
+declared actions) if `:name` isn't declared on that component — so a misspelled
+or forgotten `action` surfaces the moment you load the page in dev/test, instead
+of as an unexplained 403 on click. Production (flag off) keeps the permissive
+emit, so a stale page after a deploy that removed an action never 500s on render.
+A component that declares no actions of its own (a cross-component dispatch
+helper — a child row rendering a trigger for its container's action) is skipped;
+`on_client` triggers are never checked (they aren't declared actions). The
+server's default-deny stays the security boundary — this is a dev-time courtesy.
+
 See [docs/security.md](https://phlex-reactive.zoolutions.llc/docs/security) for the threat model and a checklist.
 
 ---
@@ -881,15 +1707,13 @@ end
 
 ```ruby
 class Counter < ApplicationComponent
-  include Phlex::Reactive::Streamable
   include Phlex::Reactive::Component
 
-  reactive_record :counter
+  reactive_record :counter   # also defaults #id to dom_id(@counter)
   action :increment
   action :decrement
 
   def initialize(counter:) = @counter = counter
-  def id = dom_id(@counter)
 
   def increment = @counter.increment!(:value)
   def decrement = @counter.decrement!(:value)
@@ -936,19 +1760,149 @@ See [docs/broadcasting.md](https://phlex-reactive.zoolutions.llc/docs/broadcasti
 
 ---
 
+## Observability
+
+The hot paths emit `ActiveSupport::Notifications` events, so an APM (AppSignal,
+Datadog, Skylight) sees reactive traffic at the **component level** — which
+component/action a slow request was, render time, and broadcast fan-out. Three
+events, all under the `phlex_reactive` namespace:
+
+| Event | Fires | Payload |
+|-------|-------|---------|
+| `action.phlex_reactive` | once per request | `component`, `action`, `outcome` (`ok`/`denied_undeclared`/`invalid_token`/`not_found`/`unauthorized`) |
+| `render.phlex_reactive` | per component render | `component`, `bytesize` |
+| `broadcast.phlex_reactive` | per `broadcast_*_to` (Action Cable **and** pgbus) | `component`, `stream_action`, `streamables` |
+
+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:
+
+```ruby
+ActiveSupport::Notifications.subscribe("action.phlex_reactive") do |*args|
+  event = ActiveSupport::Notifications::Event.new(*args)
+  MyAPM.record("reactive.#{event.payload[:outcome]}", event.duration,
+    component: event.payload[:component], action: event.payload[:action])
+end
+```
+
+To watch reactive traffic in your own log without an APM, flip on the bundled
+`LogSubscriber` (default off) — one compact line per event at DEBUG:
+
+```ruby
+# config/initializers/phlex_reactive.rb
+Phlex::Reactive.log_events = true
+# [reactive] Counter#increment ok (3.1ms)
+# [reactive] render Counter 512B (0.9ms)
+# [reactive] broadcast replace Counter →2 (1.4ms)
+```
+
+The events fire whether or not you enable the LogSubscriber; the flag only
+controls the gem's own log lines. See
+[docs/performance.md](https://phlex-reactive.zoolutions.llc/docs/performance).
+
+### Client debug mode (devtools-lite)
+
+The `LogSubscriber` above is the **server** lens. The client lens is
+`console.error` on a failure plus the [lifecycle events](#failure-ux--lifecycle-events)
+— but on the *successful-but-wrong* path (which streams arrived? did a token
+refresh come?) there was nothing to see. `Phlex::Reactive.debug` fills that gap:
+
+```ruby
+# config/initializers/phlex_reactive.rb
+Phlex::Reactive.debug = Rails.env.development?
+```
+
+With it on, every reactive root carries `data-reactive-debug="true"` and the
+generic controller `console.group`s **every dispatch** in the browser:
+
+```text
+▼ reactive #todo_42 rename → 200 (48ms)
+    params: [title] + collected: [title]
+    encoding: json
+    streams: replace → #todo_42
+    token: refreshed ✓
+```
+
+The trace carries **names and outcomes only** — the explicit param names and the
+collected sibling-field names (never their **values**, which may be sensitive),
+the request encoding (`json`/`multipart`), the HTTP status, the response's stream
+actions + targets, whether a token refresh arrived (**never the token value**),
+and the round-trip time. Off (the default) it does nothing — a single attribute
+check per dispatch, no string building — so it is safe to leave gated on
+`Rails.env.development?`.
+
+---
+
+## Testing
+
+`Phlex::Reactive::TestHelpers` is the public test surface — mix it in once and
+never reach for a private method or a hand-rolled POST:
+
+```ruby
+# spec/rails_helper.rb
+RSpec.configure do |c|
+  c.include Phlex::Reactive::TestHelpers                  # run_reactive + matchers
+  c.include Phlex::Reactive::TestHelpers, type: :request  # + the HTTP helpers
+end
+```
+
+**`run_reactive` — the no-HTTP action driver.** It runs the action through the
+SAME contract the endpoint enforces — default-deny, the signed identity
+round-trip (a record-backed component's row is re-found), schema coercion, the
+transaction wrapper — with no HTTP, and returns a `Result`. So a unit test can't
+pass on a component that would fail a real click:
+
+```ruby
+result = run_reactive(Counter.new(count: 0), :set, count: "42")  # client sends strings
+expect(result).to have_reactive_replace("counter")
+expect(result.component.instance_variable_get(:@count)).to eq(42)  # :integer, cast
+
+# default-deny, deleted-record, and authorization all surface as the real failures:
+expect { run_reactive(Counter.new(count: 0), :drop_table) }
+  .to raise_error(Phlex::Reactive::TestHelpers::UndeclaredReactiveAction)
+```
+
+`Result` answers `replace?` / `remove?` / `redirect?` / `redirect_url` /
+`streams` / `response`, plus `component` (the instance rebuilt from identity, the
+one the action ran against). A registered authorization error **raises** (the
+endpoint maps it to 403). Matchers: `have_reactive_replace`,
+`have_reactive_remove`, `have_reactive_token_for` — the last pins the token
+refresh so a reply that would silently break the next click fails your test.
+
+**HTTP helpers** — `post_reactive_action(component_or_class, act, params:, payload:)`
+and `post_reactive_multipart(...)` POST a signed token to
+`Phlex::Reactive.action_path` exactly as the client does. **Token minting** —
+`reactive_token_for(component_or_class, payload = {})`.
+
+> `verbose_errors` defaults ON in test (it changes only an error BODY, never a
+> status). Asserting an empty failure body? Set
+> `Phlex::Reactive.verbose_errors = false` in your setup.
+
+See [the testing guide](https://phlex-reactive.zoolutions.llc/docs/testing) for
+the full layer-by-layer walkthrough.
+
+---
+
 ## Documentation
 
 - [Installation & bundler setups](https://phlex-reactive.zoolutions.llc/docs/installation)
 - [Mental model & architecture](https://phlex-reactive.zoolutions.llc/docs/architecture)
+- [Actions & events (the `on(...)` API)](https://phlex-reactive.zoolutions.llc/docs/actions-events)
 - [Security & threat model](https://phlex-reactive.zoolutions.llc/docs/security)
 - [Broadcasting & live updates](https://phlex-reactive.zoolutions.llc/docs/broadcasting)
 - [Transport: pgbus vs Action Cable](https://phlex-reactive.zoolutions.llc/docs/transport-pgbus)
 - [Testing reactive components](https://phlex-reactive.zoolutions.llc/docs/testing)
 - [Performance & benchmarking](https://phlex-reactive.zoolutions.llc/docs/performance)
 - Examples: [counter](https://phlex-reactive.zoolutions.llc/docs/example-counter) ·
+  [payment split](https://phlex-reactive.zoolutions.llc/docs/example-payment-split) ·
   [chat](https://phlex-reactive.zoolutions.llc/docs/example-chat) · [todo list](https://phlex-reactive.zoolutions.llc/docs/example-todo-list) ·
   [inline edit](https://phlex-reactive.zoolutions.llc/docs/example-inline-edit) ·
-  [notifications](https://phlex-reactive.zoolutions.llc/docs/example-notifications)
+  [notifications](https://phlex-reactive.zoolutions.llc/docs/example-notifications) ·
+  [collections](https://phlex-reactive.zoolutions.llc/docs/example-collections) ·
+  [file uploads & custom types](https://phlex-reactive.zoolutions.llc/docs/example-uploads) ·
+  [loading states](https://phlex-reactive.zoolutions.llc/docs/example-loading-states) ·
+  [client-only ops](https://phlex-reactive.zoolutions.llc/docs/example-client-ops) ·
+  [failure surface](https://phlex-reactive.zoolutions.llc/docs/example-failure) ·
+  [team inbox](https://phlex-reactive.zoolutions.llc/docs/example-team-inbox)
 
 ## Credits & prior art