phlex-reactive 0.4.8 → 0.9.1

data/CHANGELOG.md

@@ -6,8 +6,870 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-07-03
+
+Consolidates everything since 0.2.6; tags 0.2.7–0.4.8 shipped without changelog
+sections, so this section spans the whole run to 0.9.0. The jump from 0.4.8 to
+0.9.0 signals the Tier-2 API wave (#79–#120) and the run-up to 1.0, leaving 0.9.x
+room for dogfood fixes.
+
+### Upgrading from 0.4.x
+
+- **BREAKING — an unknown param-type symbol now raises at boot, not at click
+  time (#109).** A `params:` schema declared with a type the library doesn't know
+  (a typo like `:strng`, or a type you meant to register) raises
+  `Phlex::Reactive::UnknownParamType` when the component class loads — the schema
+  is compiled once at declaration. Fix the typo or register the type. Previously a
+  bad type symbol slipped through to the request and failed obscurely per click.
+- **Minimum Ruby is now 3.4** (was 3.2). Enabling the `it` block parameter
+  requires 3.4, so `required_ruby_version` is `>= 3.4.0`. Stay on the 0.3.x line
+  if you need Ruby 3.2/3.3.
+- **`optimistic:` / `loading:` / `disable_with:` are now RESERVED `on(...)`
+  keywords** (#98, #99), joining `window:` / `once:` / `outside:` / `throttle:`
+  from #80. If an action of yours took a free param literally named `optimistic`,
+  `loading`, or `disable_with`, rename it — those names now configure the
+  client-side hint/loading behavior instead of passing through as an action param.
+- **`flash_builder` → `stream_builder` rename (#113) — no action needed.** The
+  builder does far more than flashes, so it was renamed;
+  `Phlex::Reactive.flash_builder` and `reset_flash_builder!` remain **permanent
+  aliases** (no deprecation). Listed only for grep-ability if you referenced the
+  old names.
+- **The client runtime now ships pre-minified (#148) — zero change for importmap
+  consumers.** The engine pins the `.min.js` build (106 KB → 22 KB, ~7.7 KB
+  gzipped) with a linked sourcemap, so devtools still shows readable source. If
+  you vendor the client file by hand, re-vendor from the minified build (the
+  dummy app's `spec/dummy/public/vendor/reactive_controller.js` is that build).
+
+### Security
+
+- **The signed-token version (`v`) now fails closed on a malformed value.**
+  `upgrade_token` type-guards `v` before comparing it: a non-integer or negative
+  `v` (only producible with the signing key, or by operator error — `v` lives
+  inside the signed blob) now returns `nil` → `400` through the endpoint's
+  `|| raise(InvalidToken)`, instead of a 500 on the `v > TOKEN_VERSION`
+  comparison or silently treating a negative `v` as a legacy passthrough. The
+  fail-closed-on-rollback contract (a `v` newer than this code understands → 400)
+  is unchanged.
+- **The raw-array `js([...])` / `broadcast_js_to([...])` escape hatch now
+  re-applies the attribute-name allowlist server-side.** The `JS` builder rejects
+  event-handler (`on*`), URL-bearing, and `style` attribute names at build time;
+  the raw `[[op, args], …]` form skipped that Ruby-side check and relied on the
+  client interpreter alone. `Phlex::Reactive::JS.assert_ops_allowed!` restores
+  full server-side parity (defense in depth — the client still enforces it too),
+  so a hand-built ops array can't emit an `onclick`/`href`/`style` attr op.
+
+### Changed
+
+- **One inheritance-aware registry behind the Component DSL; `component.rb` split
+  into cohesive concerns (#115).** All five class-level registries
+  (`reactive_actions`, `reactive_state_keys`, `reactive_collections`,
+  `reactive_computes`, `reactive_record_key`) now resolve through
+  `Phlex::Reactive::Component::Registry` with ONE semantic:
+  resolve-through-superclass at read time, memoized per class against a
+  generation counter bumped on any registry write. **The one visible behavior
+  change** (previously divergent): a parent class declaring an action/state
+  key/collection/compute AFTER a subclass had been read is now visible to that
+  subclass — pre-#115 the four collection registries snapshot-dup'd the parent
+  on first access (the late declaration was silently invisible), while
+  `reactive_record_key` walked live; the hot-path identity memos could go stale
+  split-brain against the live key. All covered by the new registry-inheritance
+  contract suite. Zero public API change: every reader keeps its exact
+  signature, `reactive_compute_def(name)` is added as the reader form matching
+  `reactive_collection_def` (the `reactive_compute(name)` getter stays a
+  permanent alias), and the token hot path is measured byte-identical
+  (unchanged i/s within noise; identical allocations). `component.rb` is now an
+  aggregator over `component/{registry,dsl,identity,helpers}.rb` — pure code
+  motion, constant paths unchanged.
+
+### Performance
+
+- **Ship a minified client runtime — `reactive_controller.js` 106 KB → 22 KB
+  (−79%; ~7.7 KB gzipped).** The authored client modules are comment-dense on
+  purpose (the source is the documentation, and the JS suite imports it), so the
+  gem no longer ships that source to browsers. `rake build:js` (bun) produces a
+  minified twin of each module — `reactive_controller.min.js`,
+  `confirm.min.js`, `compute.min.js` — each with a linked sourcemap that
+  embeds the original source, so devtools still shows the readable code. The
+  engine now pins and precompiles the `.min.js` (plus its `.map`); the bare
+  specifiers are unchanged, so **no consumer edit is required** — importmap apps
+  transparently load the small file. The confirm/compute override seams stay
+  separately pinned (not bundled in), so `import { setConfirmResolver } from
+  "phlex/reactive/confirm"` still works. The bun minifier output is
+  deterministic (byte-identical across bun patch releases), so the artifacts are
+  committed and shipped in the gem — consumers need no bun — and CI (`rake
+  build:js_check`) rebuilds and fails on drift. The system suite now runs the
+  vendored minified build in a real browser under both Puma and Falcon, so the
+  code that ships is the code that is proven. Measured on bun 1.3.14.
+- **Multi-key broadcast fan-out is ~9.5× faster (#119).** Measured, transport
+  doubled out, K=10 stream keys: a hand loop over `broadcast_replace_to` →
+  `broadcast_replace_to_each` moves 2.88k i/s (347 μs) → 27.3k i/s (37 μs)
+  (**9.5×**, and within ~4% of a single 1-key broadcast — K renders + K HMACs
+  collapse to 1 + 1), allocations 1250 obj / 186 KB → 151 obj / 22 KB (**−88%**
+  objects, 0 retained). Same-machine before/after on the new
+  `benchmark/micro/broadcast.rb`; numbers on the performance docs page.
+- **`#extractToken` per-id regex memoization (#118).** The client's
+  `#extractToken` (`reactive_controller.js`) compiled its two self-matching
+  `RegExp` objects — the `reactive:token` matcher and the self replace/update
+  matcher — on **every** response, even though the root's `id` is page-stable.
+  They are now memoized on the instance keyed on `this.element.id`, rebuilt only
+  when the id changes (a re-render that re-identifies the root must scan for the
+  new target, never a stale one — covered by a new id-change bun test). The regex
+  **patterns are byte-identical**; only their allocation moved, so token
+  self-matching semantics are unchanged (the #44/#46/#47 pins stay green).
+  **Measured, not assumed** (`rake bench:client`, bun 1.3 / M2 Max): before/after
+  is within run-to-run noise (~4.4 µs on a 2 KB body, ~9–11 µs on a 500 KB 200-row
+  collection, both sides), because `#extractToken` is already **~0.25% of the
+  `DOMParser` ceiling** (~4 ms on that 500 KB body) — removing two allocations per
+  call sits below the timing floor of the dispatch-driven bench. It is a
+  correctness/cleanliness win on a hot path, **not** a throughput change; per the
+  issue's decision rule, recorded as "measured — not worth further optimization"
+  and closed.
+
 ### Added
 
+- **`broadcast_*_to_each` — render-once, multi-key broadcast fan-out (#119).**
+  `broadcast_*_to` concatenates its `*streamables` into ONE stream key, so
+  pushing the same component to K DIFFERENT keys (a per-tenant loop — "the list
+  page stream AND the dashboard stream") with a hand-written loop was K builds +
+  K renders + K identity HMACs for BYTE-IDENTICAL HTML. Every verb now has an
+  `_each` sibling — `broadcast_replace_to_each` / `_update_` / `_append_` /
+  `_prepend_` / `_remove_` — taking an enumerable of stream keys (each a
+  `[record, :symbol]` pair or a bare string): it renders the component **once**
+  and loops only the cheap channel call. Transport opts (`exclude:` /
+  `visible_to:`) and `morph:` forward **per key** exactly as the single-key verbs
+  do, so the pgbus path suppresses the actor's echo on every stream and the
+  Action Cable path is unchanged (the no-opts call passes no unknown keyword —
+  the pgbus-optionality invariant holds; the old-pgbus-shape double guards the
+  `ArgumentError` regression). Per-VIEWER `visible_to:` content (different HTML
+  per viewer) stays the irreducible render-per-call case. Pure composition of the
+  existing private helpers; no change to any single-key method.
+- **`benchmark/micro/broadcast.rb` — the missing broadcast bench (#119).** The
+  broadcast render path was a named hot path (`.claude/rules/performance.md`)
+  with no bench. It doubles the transport out and measures the server-side
+  build + render + HMAC cost at 1 key, a hand K-key loop, and `_to_each` over K
+  keys — auto-discovered by `rake bench:micro`. It also benched `model_param_name`
+  (the audit's measure-first candidate: 815k i/s, 8 obj/call — immaterial next to
+  the ~37 μs build, so **measured and left alone**, no memoization).
+- **`benchmark/micro/verify.rb` — isolate token verify/sign cost; the
+  digest/serializer question is now measured and closed (#120).** `verify` runs
+  before anything else on every reactive request (a garbage-token flood pays it),
+  and `sign` runs once per rendered component (N× for an N-row collection) — yet
+  neither had ever been measured in isolation (`token.rb` covers sign-side
+  *assembly*, not the HMAC), and the default digest/serializer was never compared.
+  The new bench (auto-discovered by `rake bench:micro`, no harness change) reports
+  four verify cost classes — **valid** state/record (~136k/147k i/s, 20 obj), a
+  **tampered** token that pays the full constant-time HMAC compare (~203k i/s,
+  ~6× slower than garbage), and a **garbage** flood that bails at format parsing
+  (~1.2M i/s, 4 obj) — plus `sign` ×1 (~155k i/s, 12 obj) and the **collection
+  cost** `sign` ×100 (~1.6k i/s, 1200 obj, linear). It also compares the app
+  default (SHA1, json+marshal) against SHA256 and a strict JSON serializer for
+  both verify and sign: **every variant falls within measurement noise**, so
+  phlex-reactive **ships no runtime change and no opt-in recipe** — the setter
+  (`Phlex::Reactive.verifier = …`) is documented as the escape hatch if your own
+  profile ever shows verify hot, but the data says it will not. Verification
+  semantics, purpose scoping, and default-deny are untouched — this issue
+  *measures*. Numbers and the "measured, closed" verdict are on the performance
+  page. Pure tooling + docs; no production-code change.
+
+- **Client dispatch micro-bench harness — `rake bench:client` (#116).** The client
+  hot path (`app/javascript/.../reactive_controller.js`) was named a hot path in
+  `.claude/rules/performance.md` but had **no bench of any kind** — every claim
+  about `#extractToken` / `#collectFields` / `recompute` cost was a guess the
+  perf prime directive forbids, and it blocked the client-perf issues that need a
+  before/after. `benchmark/client/` now holds bun-runnable
+  [mitata](https://github.com/evanwashere/mitata) benches that drive those three
+  paths through the controller's **public surface only** (`dispatch()` /
+  `recompute()`) — **no `__bench` exports, nothing under `app/javascript/`
+  changes**, so the vendored-client re-sync rule is never tripped. `rake
+  bench:client` shells to `bun run benchmark/client/index.bench.js`, writes
+  `tmp/benchmarks/client.txt` alongside `micro.txt`, and **fails the task on a
+  crashed bench** (mitata runs with `throw: true`, matching the `bench:micro`
+  contract). New dev-only dependencies: **mitata + happy-dom** (a JS DOM engine
+  for the `collectFields`/`recompute` fixtures). Baselines are documented on the
+  performance page with honest framing: the happy-dom numbers are
+  **engine-relative** (valid for same-machine before/after deltas, not an
+  absolute browser cost), while the regex-only `#extractToken` numbers are
+  **engine-faithful** under bun/JSC. Pure tooling — no production-code change.
+
+- **`morph:` on the update verbs (#113).** The `update` family now takes the same
+  `morph:` flag `replace` already had, closing the verb-matrix asymmetry: Turbo 8
+  supports `method="morph"` on `action="update"`, so an inner-HTML update can morph
+  in place instead of swapping. This matters most for a **cross-tab
+  `broadcast_update_to`** into a component a peer is editing — a plain update tore
+  down their focus/caret; `morph: true` patches the inner HTML in place and keeps
+  it. Threaded through every update surface:
+  - `Streamable.update(model, morph: true)` (class builder) and
+    `#to_stream_update(morph: true)` (instance primitive) — emit
+    `method="morph"`.
+  - `broadcast_update_to(*streamables, morph: true)` — carries the attr through
+    `attributes:` (the broadcast path has no `method:` kwarg), so it works on
+    **both** Action Cable and pgbus; the pgbus-absent fallback is unchanged.
+  - `Response.update(component, morph: true)` and `Reply#update(morph: true)` —
+    `reply.update(morph: true)`.
+
+  **Default `false` everywhere → byte-identical to today** (no `method=` attribute),
+  so existing components are unaffected. No new dependency — Idiomorph ships with
+  `turbo-rails >= 2.0`.
+
+- **Component-aware `around_action` seam (#112).** Register a wrapper with
+  `Phlex::Reactive.around_action { |ctx, &action| … }` and it folds into the
+  endpoint **between** `with_connection_id` and the action's transaction — so it
+  sees the resolved component instance, the declared action name, and the
+  **coerced** params (a frozen `Phlex::Reactive::ActionContext`), and a rejection
+  never opens a transaction. This is the seam for audit logging, component-aware
+  rate limiting, and assertions; the base controller (`base_controller_name`)
+  stays the seam for HTTP-layer concerns (auth, CSRF, coarse per-IP throttling)
+  that don't need the resolved action. Contract: **each wrapper MUST return
+  `action.call`'s value** — the endpoint type-checks the action's return for a
+  `Phlex::Reactive::Response`, so a wrapper that returns its logger's result
+  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. Wrappers nest in registration order (last-registered outermost). The
+  empty stack (the default) adds only one `Array#empty?` check to the hot path;
+  `Phlex::Reactive.reset_around_actions!` resets it for tests. See the README
+  "Two seams" section and the security page.
+
+- **Versioned identity-token payload + upgrader chain (#111).** Every signed
+  token now carries a `"v"` key (`Phlex::Reactive::TOKEN_VERSION`, currently `1`),
+  and `Phlex::Reactive.verify` runs the payload through an upgrader chain before
+  your component rebuilds from it. This is infrastructure for the NEXT breaking
+  shape change (a rename, per-token expiry, a nonce): instead of every open page
+  breaking at deploy — an old-shape token verifies fine, then blows up later in
+  `from_identity` — the old payload upgrades transparently. Contract:
+  - A token minted **before** versioning existed carries no `"v"`; it is read as
+    version 0 (today's shape) and passes through byte-identical — introducing
+    versioning **invalidated nothing in flight**.
+  - When you change the shape, bump `TOKEN_VERSION` and register
+    **`Phlex::Reactive.register_token_upgrader(old_version) { |payload| … }`**;
+    upgraders run oldest → current.
+  - A token from a **newer** version than the running code (a rolled-back deploy)
+    **fails closed** — `verify` returns `nil`, so the endpoint answers 400, the
+    same path as a tampered token. Never fail-open.
+
+  `from_identity` ignores the extra `"v"` key, so existing components are
+  unaffected. Perf: the one added key costs +3 objects / +480 bytes per
+  `reactive_token` (a single `Hash#merge`); HMAC signing dominates and is
+  unchanged, so throughput is within measurement noise.
+
+- **Public `Phlex::Reactive::TestHelpers` + a no-HTTP `run_reactive` action
+  driver (#110).** The gem now ships the test surface it used to keep private.
+  Mix it in (`config.include Phlex::Reactive::TestHelpers`) for:
+  - **`run_reactive(component, :act, **params)`** — the no-HTTP unit driver. It
+    runs the action through the SAME security contract the endpoint enforces —
+    **default-deny** (an undeclared action raises
+    `Phlex::Reactive::TestHelpers::UndeclaredReactiveAction`), the **signed
+    identity round-trip** (a record-backed component's row is re-found; a deleted
+    record raises `ActiveRecord::RecordNotFound`, the endpoint's 404), **schema
+    coercion** (#109), and the same **transaction wrapper** — with no HTTP, and
+    returns a `Result`. A registered authorization error RAISES (the endpoint
+    maps it to 403). So a unit test can no longer pass on a component that would
+    fail a real click.
+  - **`Result`** — wraps the action's return: `replace?` / `remove?` /
+    `redirect?` / `redirect_url` / `streams` / `response`, plus `component` (the
+    instance rebuilt from identity — the one the action ran against). A legacy
+    action returning an arbitrary value reads as an implicit replace.
+  - **`reactive_token_for(component_or_class, payload = {})`** — mint a token the
+    way a component does (class form via the public `Phlex::Reactive.sign`;
+    instance form wraps the private `reactive_token`). No more
+    `component.send(:reactive_token)`.
+  - **`post_reactive_action` / `post_reactive_multipart`** — POST a signed token
+    to **`Phlex::Reactive.action_path`** (never a hardcoded `/reactive/actions`,
+    so a remounted path is honored) exactly as the client encodes it.
+  - **Matchers** `have_reactive_replace`, `have_reactive_remove`,
+    `have_reactive_token_for` (RSpec; loaded only when RSpec is present, so a
+    Minitest app asserts on `Result` predicates directly). The token matcher pins
+    the #44/#46 refresh regression class for adopters.
+
+  The gem's own request suite now runs THROUGH the public module (dogfooding),
+  and the component-generator spec template + the testing docs teach the public
+  API — every `send(:reactive_token)` instruction is gone.
+
+- **`Phlex::Reactive::ParamSchema` — declaration-time validation + app-registerable
+  param types (#109).** The ~200 lines of param coercion moved out of
+  `ActionsController` into a standalone `Phlex::Reactive::ParamSchema`, **compiled
+  once** when you declare an action (`ParamSchema.compile(params)`) instead of
+  interpreted on every request. Two adopter-facing wins:
+  - **Typos fail loud, at boot.** A schema naming an unknown type symbol
+    (`params: { count: :interger }`) now raises
+    **`Phlex::Reactive::UnknownParamType`** (an `ArgumentError` subclass) at class
+    load — validated recursively through nested-hash and array-of-hash element
+    types — instead of silently coercing the value to a `String` at click time.
+  - **New built-in types + custom registration.** `:date`/`:datetime` (ISO8601,
+    dropped on a parse failure) and `:decimal` (`BigDecimal`, dropped on a
+    non-numeric value) join the built-ins, so a date/decimal param no longer needs
+    `:string` + hand-parsing. Register your own with
+    **`Phlex::Reactive.param_type(:money) { |v| … }`** in an initializer — return
+    `Phlex::Reactive::ParamSchema::DROP` to reject a value (the keyword default
+    then applies, keeping the drop-don't-fabricate contract). The registry is
+    frozen after boot, so registration is initializer-only.
+
+  Behavior is otherwise **byte-for-byte identical**: every existing built-in keeps
+  its exact semantics (`"abc".to_i → 0`, not a drop; the `:file` duck-type drop;
+  the array/hash drop rules; the `#16`/`#21`/`#24`/`#39` bracket-expansion and
+  deep-merge matrix), and the `verbose_errors` dropped-param collector (`#82`/`#87`)
+  threads through unchanged — a `nil` collector is still the zero-cost production
+  path. Coercion is now unit-tested directly (`spec/phlex/reactive/param_schema_spec.rb`)
+  in addition to the request-spec integration cover. Bench (`rake bench:one[coerce_params]`),
+  same machine: ~35.5k → ~36.0k i/s, 207 → 202 obj/call (the memoized `Boolean`
+  type replaces a per-call instantiation), 0 retained — unchanged within noise.
+
+- **Client debug mode (devtools-lite) — `console.group` every dispatch (#108).**
+  The `LogSubscriber` (#107) is the *server* lens; this is the *client* one. Set
+  `Phlex::Reactive.debug = true` (default off; the initializer template suggests
+  `Rails.env.development?`) and `reactive_attrs`/`reactive_root` stamp
+  `data-reactive-debug="true"` on the root — the string `"true"`, not a
+  boolean-true attr, which Phlex renders valueless and the client would read as
+  falsy. The generic controller then `console.group`s **every dispatch** with the
+  action, the explicit param **names** + collected sibling-field **names** (never
+  their values — they may be sensitive), the request encoding (`json`/`multipart`),
+  the HTTP status, the response's stream actions + targets (parsed from the body
+  the controller **already read** — no re-fetch), whether a token refresh arrived
+  (a boolean — **never the token value**), and the round-trip ms:
+  `▼ reactive #todo_42 rename → 200 (48ms)`. This finally surfaces the
+  *successful-but-wrong* path (the #30/#44/#46/#50 token-threading series: which
+  streams arrived? did a refresh come?), which `console.error` + the #79 lifecycle
+  events never covered. **Zero cost when off** — one attribute check per dispatch,
+  no string building — measured on the render/token micro benches: **0 extra
+  allocations** per render and no throughput change. See the Client debug mode
+  section of the README.
+
+- **`ActiveSupport::Notifications` on the hot paths + an opt-in `LogSubscriber`
+  (#107).** The gem now emits three events under the `phlex_reactive` namespace,
+  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 — where before it saw nothing:
+  - `action.phlex_reactive` — one per request; payload `component`, `action`,
+    `outcome` (`ok`/`denied_undeclared`/`invalid_token`/`not_found`/`unauthorized`).
+  - `render.phlex_reactive` — per render; payload `component`, `bytesize`.
+  - `broadcast.phlex_reactive` — per `broadcast_*_to` (fires on Action Cable
+    **and** pgbus); payload `component`, `stream_action`, `streamables` count.
+
+  Payloads carry **names, the outcome, and sizes only** — never the token,
+  params, or state, so an event can't leak a secret; an `invalid_token` event has
+  no trusted component name (the token didn't verify) and omits it. Statuses and
+  the endpoint flow are unchanged — the instrument only wraps the existing paths.
+  An unsubscribed `instrument` is cheap (a few objects per call, **zero
+  retained** — measured on the render micro bench) so the hot paths carry it
+  unconditionally. Flip on `Phlex::Reactive.log_events = true` (default off) to
+  get one compact debug line per event: `[reactive] Counter#increment ok (3.1ms)`.
+  See the Observability section of the README and the performance docs page.
+
+- **`bin/rails phlex_reactive:doctor` — validate the whole install (#106).** Five
+  closed issues (#3 boot/eager-load, #26 route shadowing, #42 lost request, #48
+  unregistered controller, #57 importmap 404) were pure integration papercuts
+  that only surfaced **after** something already broke. The doctor turns "nothing
+  happens, why?" into an actionable checklist you run before or after setup. It
+  prints `✓/✗/?` with a fix for each failure and checks: the action route
+  resolves (reuses the boot route-shadow guard), the `reactive` controller is
+  registered in a Stimulus entrypoint (importmap **or** esbuild/bun **or** a
+  layout), `csrf_meta_tags` is referenced (**advisory `?`** — never a hard fail,
+  so a Phlex-only layout isn't false-flagged), the identity verifier round-trips,
+  `base_controller_name` constantizes, every declared `action :name` has a public
+  method (mirrors the endpoint's `public_send`), and every component resolves a
+  stable `#id` (a state-backed class with no `#id` is flagged; a record-backed
+  class on the #81 default is fine). It is **read-only** — no client surface, no
+  component instantiation, default-deny untouched — and exits non-zero on a hard
+  failure so CI or a setup script can gate on it.
+- **Install generator hardening (#106).** The generator now also detects
+  `app/javascript/application.js` (esbuild/bun/webpack) as a Stimulus entrypoint,
+  not just the importmap-style `controllers/index.js`, and its post-install output
+  ends by telling you to run `bin/rails phlex_reactive:doctor` to verify.
+
+### Performance
+
+- **Nested-root fast path for the client field walks (#117).** `#collectFields`,
+  `recompute`, and `#listnavOptions` computed field ownership (the issue #15
+  "is this element mine, not a nested reactive root's?" check) with a per-element
+  `el.closest('[data-controller~="reactive"]')` walk on every matched field —
+  `recompute`'s `#ownedField` did a **fresh** `querySelectorAll('[name="…"]')` +
+  `closest()` filter **per declared input AND per output on every keystroke**
+  (~60 DOM queries on a 30-field calculator). A new `#ownershipFilter()` hoists
+  the decision to **once per op**: with no nested reactive root (the common case)
+  it returns a constant-true predicate and the per-field `closest()` walk is
+  skipped entirely; when a nested root is present it falls back to the exact
+  `#ownsField` closest() check, so issue #15 scoping is byte-identical. `recompute`
+  additionally resolves its inputs and outputs through a per-call, **first-wins**
+  `byName` memo (`if (owns(el)) break` on the first owned match — last-wins would
+  change radio-group / Rails hidden+checkbox behavior). Measured same-machine
+  before/after (bun + happy-dom, engine-relative): **recompute ~31 µs → ~23 µs per
+  keystroke (~25%)** on the 30-input calculator, 0 retained bytes/call;
+  `#collectFields` (once per dispatch, dominated by the dispatch overhead) stays
+  within noise. A **method/keystroke-level** win, not a request-level one. Field
+  ownership is unchanged for every component; the issue #15 nested-root bun tests
+  pass untouched. New coverage: `spec/javascript/reactive_recompute_ownership.test.js`
+  proves first-wins resolution for duplicate owned names and nested-root rejection.
+
+### Changed
+
+- **Structured `Phlex::Reactive::Stream` value object — the endpoint stops
+  regex-sniffing its own generated turbo-stream HTML (#114).** The action endpoint
+  used to reverse-engineer stream *semantics* out of *markup*: it substring-scanned
+  every stream for `data-reactive-token-value` and regexed the opening
+  `<turbo-stream>` tag's `action="…"` against a self-render allowlist to decide
+  whether a stream already refreshed the component's signed token. The gem was
+  parsing strings it had just built, and every new stream shape needed a new patch
+  to the heuristics. Now every `to_stream_*` instance primitive and every
+  `Streamable` class builder (`replace`/`update`/`append`/`prepend`/`remove`)
+  returns a `Phlex::Reactive::Stream` — an `ActiveSupport::SafeBuffer` subclass
+  that IS an html_safe String (so it drops into `render turbo_stream:`, ERB/Phlex
+  interpolation, and Turbo test-helper substring asserts unchanged) but also
+  carries `rx_action` / `rx_target` / `rx_renders_root?` set **structurally at
+  construction** plus `rx_carries_token?` computed **once from ground truth** (a
+  build-time scan of the actual bytes, never inferred from the builder kind — the
+  cosmos#1939 guard). The endpoint reads those fields instead of regexing markup;
+  `renders_root: false` on `append`/`prepend` encodes the #44 lesson (a child row's
+  own token in an append `<template>` can never count as the container's refresh)
+  in the *type*, not a regex. Raw strings (`reply.with(…)`, interpolated or
+  `gsub`'d streams) keep the pre-#114 regex path as a permanent fallback, gated on
+  `stream.is_a?(Stream)`. **The wire format is byte-identical** — same
+  token-refresh decisions (#30/#44/#46/#50 pins all green), different mechanism.
+  This is an architecture/correctness win, not a speedup: `rake bench:request`
+  before/after moves within measurement noise (allocations +1 obj/req state-backed,
+  +5 obj/req record-backed; throughput swings inside the ±15–28% error bars).
+
+- **`Phlex::Reactive.flash_builder` → `stream_builder` (and `reset_flash_builder!`
+  → `reset_stream_builder!`) (#113).** The memoized `Turbo::Streams::TagBuilder`
+  is used well beyond flashes — `reactive_collection` row removal, count-companion
+  updates, `also_update` — so the `flash_` name misled. Renamed to `stream_builder`
+  / `reset_stream_builder!`. **`flash_builder` and `reset_flash_builder!` stay as
+  permanent aliases** (no deprecation warnings), so the engine's reload hook and
+  any app code keep working unchanged. Purely a rename — behavior is identical.
+
+- **BREAKING (declaration-time): an unknown param type symbol now raises (#109).**
+  Before, a schema naming a type the coercer didn't recognize (a typo like
+  `params: { count: :interger }`, or a type never registered) fell through to a
+  silent `String` coercion. Now `Component.action` compiles the schema through
+  `Phlex::Reactive::ParamSchema.compile` and raises
+  **`Phlex::Reactive::UnknownParamType`** (an `ArgumentError` subclass) at class
+  load. The fix is to correct the typo or register the type
+  (`Phlex::Reactive.param_type(:name) { |v| … }` in an initializer). This only
+  affects schemas that were *already* silently mis-coercing; a valid schema is
+  unchanged.
+
+- **`on(:typo)` fails at render, not click (#105).** A misspelled or forgotten
+  action used to render fine and only surface as an unexplained **403 on click**
+  (the endpoint's default-deny). Now, when **`Phlex::Reactive.verbose_errors`** is
+  on (the default in development and test via `Rails.env.local?`), **`on(:name)`
+  raises `Phlex::Reactive::Error`** at **render** time if `:name` isn't declared
+  on that component — the message lists the declared actions, the same loud-
+  failure courtesy `reactive_compute_attrs` already gives an undeclared compute.
+  You catch the typo the moment you load the page instead of hunting a mystery
+  403.
+  - **Production is unchanged.** With `verbose_errors` off (the production
+    default) `on()` keeps today's permissive emit, so a stale page after a deploy
+    that removed an action **never 500s on render**.
+  - **Cross-component dispatch still works.** A component that declares **no
+    actions of its own** — a child row rendering a trigger for its container's
+    action and sending the container's token (e.g. a notification row → the list's
+    `:dismiss`) — is skipped: it can't self-validate against a registry it doesn't
+    own. `on_client` triggers are never checked (they aren't declared actions).
+  - **Not the security boundary.** This is a dev-time aid; the server's
+    default-deny stays the enforcement. The check is one flag-gated hash lookup
+    with **zero added allocations** on the `on()`/render/token hot paths (measured:
+    `on(:increment)` and `to_stream_replace` allocate byte-identically before and
+    after; the prod path short-circuits on the flag before the lookup).
+
+### Added
+
+- **`reactive_text` mirrors + typed compute inputs (#104).** Mirror a form field
+  into a **text node** — a live preview heading, a character counter,
+  `"Hello, {name}"` — with **no round trip and no bespoke Stimulus controller**.
+  Datastar's `data-text` / Alpine's `x-text`, but declared on the component.
+  - **`reactive_text(:name, initial)`** renders `span(data: { reactive_text:
+    name }) { initial }` — the **text sibling of `reactive_field`**. The client
+    writes it via **`textContent`** (XSS-safe by construction, never `innerHTML`).
+    It carries **no `name`**, so `#collectFields` never sweeps it into the POSTed
+    params.
+  - **Typed compute inputs.** `reactive_compute :x, inputs: { title: :string,
+    qty: :number }, outputs:` types each input: a `:number` is coerced through
+    `Number` (blank/NaN → 0), a `:string` reaches the reducer **raw** — so a live
+    text preview reads real text, not `NaN`. The **array form** (`inputs: %i[a
+    b]`) stays all-numeric and **byte-identical on the wire** (a JSON array); the
+    hash form emits a JSON object of name→type.
+  - **Output resolution.** A compute output whose name matches an owned form
+    field writes that field's `.value` (the existing change-guarded `input`
+    dispatch). An output with **no** matching field writes every owned
+    `[data-reactive-text="<name>"]` node via `textContent` — change-guarded too,
+    but **no** input dispatch (a text node has no listener contract).
+  - **Reducer-less identity mirrors.** A separate always-run pass syncs each
+    declared **input**'s raw value into its own `reactive_text(:same_name)` node
+    on every keystroke — so `reactive_text(:title)` is a live field echo with **no
+    registered reducer at all**.
+  - **Seed the server render.** `view_template` must seed each mirror with the
+    same derived value the reducer would, or a later morph repaints stale text —
+    the same reconcile contract the new-vs-persisted split already documents.
+
+- **Dirty-field tracking + unsaved-changes guard (#103).** Show "unsaved
+  changes", enable **Save** only when something changed, or warn before navigating
+  away — Livewire's `wire:dirty` — **without shipping any client state**. 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**, read straight
+  from the DOM.
+  - **`reactive_root(track_dirty: true)`** wires every input under the root to a
+    full re-scan on change; **`reactive_field(:title, dirty: true)`** opts a single
+    field in. On each change the client re-scans **every owned field in one pass**
+    (the ownership guard excludes nested reactive roots) and marks each changed
+    field `data-reactive-dirty="true"` and the root `data-reactive-dirty="<count>"`
+    (**absent at zero**). The full pass — not a per-field toggle — is required for
+    radio groups: the deselected radio fires no event, so only re-scanning
+    everything keeps its flag honest. File inputs and `contenteditable` editors
+    (no `default*` baseline) are out of scope in v1.
+  - **CSS vocabulary, zero Ruby.** `[data-reactive-dirty] .unsaved-badge { … }`
+    reveals a badge; `[data-reactive-dirty]` on a field outlines just the changed
+    control — the same pure-CSS pattern as `[data-reactive-busy]`.
+  - **Baselines reset on the server re-render.** A plain replace re-connects and
+    re-scans in `connect()`; an in-place morph keeps the element connected and
+    fires no Stimulus lifecycle, so a `turbo:morph-element` listener re-scans after
+    the morph writes fresh `default*` attributes — a `reply.morph` save clears the
+    markers with no reload. (`reactive:applied` fires *before* the DOM mutation, so
+    it is **not** a valid reset hook and is deliberately not used.)
+  - **`warn_unsaved: true`** arms a navigate-away guard gated on the **live** dirty
+    count — `beforeunload` and `turbo:before-visit`; a clean form never blocks.
+    Documented caveats: browsers show their own generic `beforeunload` copy, and
+    `turbo:before-visit` does not fire on restoration (Back/Forward) visits.
+  - Both `reactive_root` kwargs are **consumed before the `mix`** (otherwise an
+    unconsumed kwarg would render as a literal HTML attribute); `track_dirty` and
+    `dirty:` **token-join** their `input->reactive#trackDirty` descriptor onto any
+    existing `data-action` (they don't clobber it), so combining with your own
+    `data:`/`on(...)` still needs `mix(...)`.
+
+- **Latency simulator dev aid — `PhlexReactive.enableLatencySim(ms)` /
+  `disableLatencySim()` (#102).** On localhost the click→morph round trip is
+  ~5 ms, so the pending/loading/optimistic affordances added in #98/#99/#100
+  (`aria-busy`, `disable_with:`, `busy_on`, optimistic hints) flash by too fast to
+  see while developing or demoing them — the reason LiveView ships
+  `liveSocket.enableLatencySim(ms)`. Two named exports from the client controller
+  (the `setConfirmResolver` precedent) persist a per-action delay to
+  `sessionStorage` under `"phlex-reactive:latency"`; `#perform` reads it live
+  right before the `fetch` — after the busy window has already opened at enqueue —
+  and awaits it, so the affordances become observable. The delay is session-scoped
+  (clears when the tab closes, so you can't leave it on across sessions), read
+  fresh per request (toggling takes effect on the next action with no reload), and
+  a one-time console banner reminds you while it's active.
+  - **Console handle, dev-gated.** importmap module exports are unreachable from
+    the DevTools console, so the bootstrap attaches
+    `window.PhlexReactive = { enableLatencySim, disableLatencySim }` — but **only**
+    when the app authored `<meta name="phlex-reactive-env" content="development">`.
+    The meta is app-authored (the engine can't inject into the host layout); the
+    install generator's initializer ships the commented snippet, and the README
+    documents it. Without the meta there is **no global handle** and `#perform`
+    short-circuits on the `null` `sessionStorage` read — **zero production
+    surface**. This finally lets a system spec observe `aria-busy` in a real
+    browser (previously impossible on a ~5 ms trip), under both Puma and Falcon.
+
+- **Request timeout + offline handling — `reactive:error` kinds `timeout` and
+  `offline` (#101).** A server that never responded used to wedge a component's
+  request queue *forever* — each action chains on the previous one, so one hung
+  `fetch` froze every future action and the `finally` that clears `aria-busy` /
+  the loading state never ran. Going offline just fail-fast-looped each click as
+  `kind: "network"`. Two mechanisms close this:
+  - **Timeout.** The fetch is bounded by `AbortSignal.timeout(ms)` — default
+    **30 s**, configurable via a page-authored `<meta name="phlex-reactive-timeout">`
+    (same pattern as the action-path meta; no server setting). On abort it fires
+    `reactive:error` `kind: "timeout"` (retriable) and the queue advances, so the
+    component recovers. `AbortSignal.timeout()` rejects with a `TimeoutError`
+    `DOMException` (NOT `AbortError`), correctly distinguished from a genuine
+    network `TypeError` in the fetch catch.
+  - **Offline.** A gate at the **network boundary** (`#perform`, send time — so a
+    request that enqueued while online but reaches the wire after a drop is still
+    caught) short-circuits when `navigator.onLine === false`: it fires
+    `reactive:error` `kind: "offline"` (retriable) and never sends, so the edit is
+    not half-sent. `data-reactive-offline` is mirrored onto `<html>` (kept in sync
+    by the `online`/`offline` events) as a pure-CSS hook, zero app JS.
+  - **Explicit non-goal:** no automatic replay. A timed-out POST may have
+    succeeded server-side, so even manual `retry()` can double-apply a
+    non-idempotent action — make retryable actions idempotent or gate retry UI.
+- **User-visible failure surface — render error bodies, `error_flash`,
+  `dismiss_after:` (#100).** A failing action used to show the user *nothing*:
+  the client read a non-OK body only for the console and discarded it, the
+  endpoint's rescue paths could log but not display anything, a network failure
+  had no server to render, and flashes never cleaned themselves up. Four pieces
+  close the gap, all opt-in and status-preserving:
+  - **Client renders non-OK turbo-stream bodies.** When `!response.ok` but the
+    Content-Type is a turbo-stream, the body is now applied (an `error_flash`, or
+    a plain controller's `status: :unprocessable_entity` validation reply, is
+    SHOWN). The root gets `data-reactive-error="<kind>"` (styleable in pure CSS),
+    cleared on the next success. Token safety is preserved: a 400 body never
+    refreshes the held identity token (`#extractToken` no-ops unless a stream
+    re-renders this element's id).
+  - **`Phlex::Reactive.error_flash`** (default `nil`) — a `->(kind) { "message" }`
+    lambda. When set, every rescue path (400/403/404) renders a turbo-stream flash
+    into `flash_target` at the **same status** it returns today. Composes with
+    `verbose_errors`: the flash wins the response body, the diagnostic still logs.
+    A lambda that raises degrades gracefully (falls back to the bare/diagnostic
+    body — never a 500).
+  - **Offline fallback** — a server-rendered `<template data-reactive-error-flash>`
+    the client clones into the flash region on a `network` failure (trusted
+    markup, cloned verbatim — no client templating).
+  - **`dismiss_after:` on `reply.flash`** — `reply.replace.flash(:error, msg,
+    dismiss_after: 4000)` self-removes the flash after the timeout via a
+    **document-level** handler (so it self-cleans broadcast-delivered flashes too).
+    Wraps string content; a verbatim Phlex component owns its own lifecycle.
+- **Declarative loading states — `loading:` / `disable_with:` on `on(...)` +
+  `busy_on(:action)` (#99).** Between the click and the morph the UI was fully
+  live and unchanged: no per-trigger feedback, buttons stayed enabled, and a
+  rapid double-click enqueued a full duplicate POST (the queue serializes tokens,
+  it does not dedupe). This adds Livewire's `wire:loading` + `phx-disable-with`
+  without a Stimulus controller. `disable_with: "Saving…"` disables the trigger
+  and swaps its text while pending — and because a disabled button fires no
+  further clicks, a double-click now enqueues exactly **one** POST (the disable
+  is the dedup). `loading: { disable:, class:, text:, to: }` is the full form:
+  a loading class on the trigger or a `to:` target, plus disable + text. Both
+  apply at **enqueue** (covering the queue wait, not just the fetch) and revert
+  on settle — **guarded** so a disconnected trigger is skipped and a
+  server-rendered new label is never clobbered; the disable/text swap deliberately
+  do NOT apply during a `debounce:` quiet period, so a debounced `input` is not
+  disabled mid-typing. Independently, **every** round trip now carries an
+  always-on busy vocabulary for the whole enqueue→settle window — no Ruby needed:
+  `data-reactive-busy="<action>"` on the trigger and root (a **space-separated
+  set** on the root so concurrent actions don't clobber), `aria-busy` on the root
+  (via a **pending counter**, cleared only when the last request settles), and
+  `busy_on(:action)` to scope `data-reactive-busy` onto a spinner only while that
+  action is in flight. Style it with pure CSS (`[data-reactive-busy] .spinner { … }`).
+  The trigger is now captured from `event.currentTarget` (not `event.target`), so
+  a `<button><span>` click disables/relabels the button, not the inner span.
+  Emitted as `data-reactive-loading-param` (JSON) via the guarded-append pattern,
+  so the bare-`on()` hot path stays byte-identical. **`loading:` and
+  `disable_with:` are now RESERVED keyword names on `on(...)`** — like
+  `debounce:`/`confirm:`/`throttle:`/`optimistic:`, they can no longer be used as
+  free action params.
+- **`optimistic:` on `on(...)` — declared, reversible visual hints (#98).**
+  Reactive interactions no longer wait a full round trip for their first visual
+  change — and a checkbox no longer fails to flip at all (the client's
+  unconditional `preventDefault` used to suppress the native flip until the
+  morph). `optimistic:` applies a small, always-reversible, **cosmetic**
+  vocabulary the instant the trigger fires and **reverts** it if the action
+  fails — Livewire's "flip it client-side, let the morph correct". Supported
+  hints: `toggle_class:`/`add_class:`/`remove_class:` (on the trigger, or a `to:`
+  selector scoped to the root), `checked: :keep` (a click-bound checkbox/radio
+  skips `preventDefault` so it flips natively now), and `hide: true`. Hints are
+  visual only (never data, never client state), applied **once per flushed
+  enqueue** (a debounced trigger can't flap per keystroke), and reverted from
+  every failure branch (redirected/http/content-type/network + client apply),
+  guarded by `isConnected`. On **success there is no cleanup**: a root re-render
+  overwrites the hint with server truth, while a reply that does not re-render
+  the root (`reply.remove`, streams-only) leaves it standing — that's the
+  `hide: true` + `reply.remove` instant-delete recipe. Emitted as
+  `data-reactive-optimistic-param` (JSON) following the guarded-append pattern of
+  `debounce:`/`confirm:`/`throttle:`, so the bare-`on()` hot path stays
+  byte-identical. **`optimistic:` is now a RESERVED keyword name on `on(...)`** —
+  like `debounce:`/`confirm:`/`throttle:`/`listnav:`, it can no longer be used as
+  a free action param.
+- **`on_client(event, ops)` + the `js` op builder — client-side DOM commands
+  with ZERO round trips (#95).** Purely-visual interactions (tabs, dropdowns,
+  accordions, class toggles) no longer cost a signed server round trip or a
+  hand-written Stimulus controller. `js` is an immutable, chainable builder of
+  declared DOM operations — `show`/`hide`/`toggle` (the `hidden` attribute) and
+  `add_class`/`remove_class`/`toggle_class` — and `on_client(:click, js.…)`
+  binds them to a DOM event the ONE generic controller applies locally via a
+  new `runOps` action: **no token, no params, no fetch, ever** (the system spec
+  wraps `window.fetch` with a counter and asserts zero). The op vocabulary is a
+  fixed whitelist mirrored client-side: an unknown op name warns and is skipped
+  while the rest of the chain still applies (client-side default-deny —
+  `Object.hasOwn`-guarded so inherited Object members can't masquerade as ops),
+  and malformed ops JSON degrades to a no-op. Targets are CSS selectors
+  resolved WITHIN the component's root — nested reactive roots are never
+  touched (the issue-#15 ownership rule) — with `:root` for the root element
+  itself and a per-op `global: true` document escape. `window:`/`once:`/
+  `outside:` compose exactly like `on(...)`'s #80 modifiers (outside-click
+  closes a dropdown; window-bound triggers never `preventDefault`). Builder
+  validation is loud at render time (a non-selector target or an empty class
+  list raises; `on_client` rejects a non-`Phlex::Reactive::JS` or empty chain)
+  rather than silent in the browser. Client ops are EPHEMERAL UI by design: any
+  server re-render resets them — the LiveView JS-commands caveat, documented in
+  the README — so state that must survive a re-render stays a signed `action`.
+  Same-machine `rake bench` before/after: the token/render/coerce hot paths are
+  untouched (state-backed token 201k → within noise; allocations byte-identical
+  at 11/47 per token, 113 per render) — `on_client` is a new, separate path.
+- **`js` client ops: allowlisted attribute ops, focus, dispatch, and animated
+  transitions (#96).** The client-only vocabulary from #95 grows to cover the
+  interactions apps otherwise fall back to hand-written Stimulus for. New builder
+  verbs: `set_attr(to, name, value)` / `remove_attr(to, name)` /
+  `toggle_attr(to, name)` for attribute state (the value rides as a string, so a
+  boolean flag is a real `"true"`, never a valueless attribute); `focus(to)` and
+  `focus_first(to)` (the first focusable descendant of the match — the opened-menu
+  → first-menuitem case); and `dispatch(name, to: nil, detail: {})`, a **bubbling
+  `CustomEvent`** other components/controllers can react to (raw
+  `element.dispatchEvent` — the shared controller SHADOWS Stimulus's `this.dispatch`
+  helper). `show`/`hide`/`toggle` gain a `transition: [during, from, to]` keyword:
+  the class lists are applied around the visibility flip and cleaned up on
+  `animationend`, with a `setTimeout` fallback so a non-animated element never
+  leaves them stuck and never hangs the chain (later ops run immediately —
+  cleanup is fire-and-forget). The **attribute-name allowlist is the
+  security-critical part, enforced on BOTH sides (two-sided default-deny)**: at
+  build time in `js.rb` (an offending name raises `ArgumentError`) and again in the
+  client interpreter (a forged/hand-built op is `console.warn`-ed and skipped, so
+  it can't bypass the Ruby guard). Refused, case-insensitively: event handlers
+  (`/\Aon/i` → XSS), the URL-bearing set (`href`, `src`, `srcdoc`, `action`,
+  `formaction`, `xlink:href` → a `javascript:` navigation surface), and `style`
+  (CSS injection). The intended surface — class ops plus `hidden`, `disabled`,
+  `open`, `selected`, `aria-*`, `data-*` — is documented in the README. Covered by
+  Ruby specs (each verb's JSON shape; the allowlist raises for every refused name,
+  case-insensitively), bun tests (attr ops apply; the interpret-time allowlist
+  warns + skips a forged op; focus lands; `dispatch` emits a bubbling event with
+  detail; the transition swaps `from`→`to` on the next frame and cleans up on both
+  `animationend` and the timeout fallback), and a system spec that opens a drawer
+  with a real fade, sets `aria-expanded`, and focuses the first control under Puma
+  AND Falcon. Refs #96.
+- **`reply.js(...)` + `broadcast_js_to` — server-pushed DOM ops over a
+  `reactive:js` stream action (#97).** The server can now tell 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 in every viewer's tab — WITHOUT
+  re-rendering to make it happen. `Response#js(ops)` (surfaced on the reply facade
+  as `reply.<verb>.js(ops)`) chains a `reactive:js` op stream onto ANY reply via
+  the immutable `stream()` plumbing, and `Streamable.broadcast_js_to(*streamables,
+  ops, exclude:, visible_to:, target:)` pushes the SAME ops to every subscriber of
+  a stream over `Turbo::StreamsChannel` (Action Cable AND pgbus — transport opts
+  pass through `broadcast_transport_opts` like every other broadcast). `ops` is a
+  `js` chain (or a raw `[[op, args]]` array), interpreted by the SAME frozen
+  `CLIENT_OPS` whitelist as `on_client` through a THIRD custom stream action
+  (`registerReactiveJs`, a sibling of `reactive:visit`/`reactive:token`): an
+  unknown op warns + is skipped (client-side default-deny). **The ordering contract
+  is correctness-critical**: the op stream is emitted AFTER all render streams, so
+  a `focus("[name=next]")` op sees the post-render/post-morph DOM (Turbo applies
+  streams in document order) — a system spec proves focus lands on a freshly
+  morphed field under Puma AND Falcon. **The broadcast builder REJECTS focus-class
+  ops** (`focus`/`focus_first` → `ArgumentError`): broadcasting focus would steal
+  it in every subscriber's tab, so focus is an actor-reply concern only. The ops
+  attribute is HTML-escaped exactly like `to_stream_token` (a raw interpolation
+  would be an injection vector), and `reactive:js` is NOT a self-render — it never
+  trips `#extractToken` or `carries_token_for?`, so the reply's token refresh is
+  untouched (pinned by a bun test and a request spec). Covered by Ruby specs
+  (immutable chaining; ops-last ordering; escaping; the broadcast focus rejection;
+  transport-opt pass-through with the pgbus-absent path unchanged), bun tests (the
+  handler applies ops via the shared interpreter; `target` root scoping; token
+  safety), a request spec (both streams in order with the token intact), and the
+  focus system spec. Refs #97.
+
+- **`on(...)` event modifiers — `window:`, `once:`, `outside:`, `throttle:`
+  (#80).** Four trigger patterns that previously forced a hand-written Stimulus
+  controller are now declarable on `on(...)`. `outside: true` fires the action
+  only for events whose target is OUTSIDE the component's root — the
+  close-a-dropdown-on-outside-click pattern; an event inside the root is a
+  complete client-side no-op (bailing before `preventDefault` and before the
+  `reactive:before-dispatch` lifecycle event). It implies `window: true`, which
+  binds the trigger via Stimulus's native `@window` descriptor for page-level
+  events (`scroll`/`resize`). Window-bound triggers are NEVER
+  `preventDefault`-ed — a mounted dropdown must not kill native link clicks
+  elsewhere on the page — and skip the forced `type="button"`; the client
+  decides this from `data-reactive-window-param` (emitted as an explicit
+  `"true"` string — Phlex renders a boolean `true` attribute VALUELESS, which
+  Stimulus's param reader sees as `""`, falsy). `once: true` appends Stimulus's
+  `:once` action option (fire at most once, then unbind). `throttle:`
+  (milliseconds) 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`. Suppression
+  timers are keyed on action + target (window scroll events all share
+  `event.target === document`, so two window-bound triggers on one component
+  must not collide) and torn down on `disconnect()`. The bare `on(:x)` emission
+  is pinned byte-identical by spec — the four names become RESERVED `on(...)`
+  kwargs, no longer usable as free action params.
+
+- **Single include + a default `#id` for record-backed components (#81).**
+  `include Phlex::Reactive::Component` now pulls in
+  `Phlex::Reactive::Streamable` automatically (ActiveSupport::Concern's
+  dependency mechanism includes Streamable into the base FIRST — exactly the
+  manual order the old two-include ceremony established), so one include is
+  enough; the legacy explicit double include remains a harmless no-op. And a
+  record-backed component (`reactive_record :todo`) gets `#id` for free:
+  `dom_id(record)` via the render-context-free `Streamable#dom_id` — the id
+  virtually every such component wrote by hand. An explicit `def id` always
+  wins (normal method lookup). Deliberately NO class-name default for
+  state-backed components — they're frequently multi-instance, so a class-name
+  id would silently collide; they (and bare Streamable classes) keep the loud
+  `NotImplementedError`, now with a message that says how to fix it. Caveat:
+  two different component classes rendering the SAME record on one page
+  collide on the default — give one a prefixed id
+  (`def id = dom_id(@todo, "rich")`). The component generator emits the new
+  short form. Same-machine `rake bench` before/after: allocations on the
+  render/token hot paths are byte-identical (192 obj per `to_stream_replace`,
+  100 per `render_component`, 47 per record-backed token, retained 0) and
+  throughput is unchanged within run-to-run noise — the default costs one
+  `respond_to?` + two memoized reads, and only for components that didn't
+  define `#id`.
+
+- **`reactive_compute` reducers are told which field changed — one reducer can
+  express a multi-way/mutual rebalance (#75).** A compute reducer now receives a
+  second argument, `meta = { changed }`: the name of the declared input the
+  triggering `input` event edited, or `null` (a direct `recompute()` call, or a
+  target this root doesn't own / didn't declare as an input — nested reactive
+  roots stay excluded per #15). That's exactly what the mutual-rebalance shape
+  ("three fields that must always sum to a total") needs — given the same value
+  snapshot, the reducer branches on WHICH field is the free/derived one:
+
+  ```js
+  setComputeReducer("three_way_split", ({ field_a, field_b, field_c, total }, { changed }) => {
+    if (changed === "field_c") return { field_a: total - field_c - field_b }
+    return { field_c: total - field_a - field_b }
+  })
+  ```
+
+  Fully backward compatible: a one-argument reducer just ignores `meta` — no
+  Ruby DSL change, no markup change. One contract to know: because an output
+  write dispatches a real change-guarded `input` event (#76), `recompute`
+  re-enters with `changed` = the OUTPUT field's name (when it's also a declared
+  input), so a branching reducer must be **convergent** — the re-entrant pass
+  must compute the values already in the DOM so the change guard settles the
+  chain (the example above does: deriving `field_a` back from the just-written
+  `field_c` reproduces its current value; no write, no event, settled in one
+  bounce). Documented in `compute.js`'s header and the `reactive_compute` docs;
+  covered by bun unit tests including the issue's three-way rebalance verbatim
+  with a bounded reducer-call count.
+
+- **`Phlex::Reactive.verbose_errors` — diagnostic endpoint error bodies +
+  dropped-param logging (#82).** An endpoint failure used to be a bare
+  `head 400/403/404` and a silently-dropped param left no trace — debugging
+  "nothing happens" meant reading the gem source. Now every failure is
+  warn-logged as `[phlex-reactive] …` in EVERY environment, and with
+  `verbose_errors` on (default `Rails.env.local?` — development AND test; off
+  in production) the response also carries a plain-text diagnostic body the
+  client already prints via `console.error`: a tampered/stale token (400,
+  distinguishing signature-invalid from a token class that no longer resolves
+  from a class that isn't reactive — `InvalidToken` now carries a `diagnostic`),
+  an undeclared action (403, listing the declared actions), a registered
+  authorization error (403, naming the error class and the action), and a
+  missing record (404, naming the GlobalID). Param coercion additionally logs
+  every dropped key with its full bracketed path and reason
+  (`undeclared` / `uncoercible`), hinting when a flat name looks like the
+  bracketed twin of a declared nested key (the #16/#21 confusion). Statuses
+  never change with the flag, the client needs no changes, and the production
+  coercion path does zero extra work (nil collector, early-return guards) —
+  `rake bench:one[coerce_params]` before/after is unchanged within noise
+
+- **Client lifecycle CustomEvents — `reactive:before-dispatch` /
+  `reactive:applied` / `reactive:error` with `retry()` (#79).** The generic
+  controller now dispatches three bubbling, composed events around every action
+  round trip, so an app can toast an error, veto a dispatch, instrument latency,
+  or build retry UI without forking the one controller.
+  `reactive:before-dispatch` is cancelable and fires once per user gesture —
+  post-`preventDefault`, post-`confirm:`, PRE-debounce — with
+  `{ action, params, element }`; `event.preventDefault()` skips the round trip
+  entirely (nothing is scheduled, debounced or not). `reactive:applied` fires
+  with `{ action, params, html }` after the fresh token was captured and the
+  streams were handed to `Turbo.renderStreamMessage` (Turbo applies them
+  asynchronously — listen to Turbo's own events for post-morph timing).
+  `reactive:error` fires in every failure branch with
+  `{ action, params, kind, status?, body?, retry? }` where `kind` is one of
+  `redirected | http | content-type | network` (all retriable) or `apply` —
+  the fetch itself succeeded and the server already completed the mutation,
+  but something AFTER it threw INSIDE THE CONTROLLER (a malformed response, a
+  Turbo render error — NOT a throwing `reactive:applied` listener, whose
+  exception `dispatchEvent` never propagates back per the DOM spec, so it
+  can't reach this catch); `apply` carries NO `retry` at all, since retrying
+  would re-POST an action that already succeeded. `retry()`
+  (when present) re-enters the request queue — re-reading the freshest signed
+  token and re-collecting the fields at send time, refiring no second
+  before-dispatch — and no-ops with a `console.warn` once the component left
+  the DOM. Events go out via raw
+  `dispatchEvent` (Stimulus's `this.dispatch` helper is shadowed by the
+  controller's own `dispatch` action method) on the root element, falling back
+  to `document` when a plain replace detached it; the existing `console.error`
+  logging is unchanged. Composes with plain Stimulus listening —
+  `data-action="reactive:error->toast#show"` on an ancestor. Covered by unit
+  (JS) and real-browser system specs; README "Failure UX & lifecycle events"
+  and the security docs page document the contract.
+
 - **Combobox keyboard navigation — `on(:search, …, listnav: "[role=option]")` (#72).**
   A search/combobox trigger can now declare client-side list navigation: Arrow
   Up/Down move a highlight among the option elements IN-BROWSER (no round trip),
@@ -58,9 +920,10 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   ```
 
   The generic controller runs the named reducer on `input`, writes only the
-  declared outputs (leaving the edited field + caret alone), and fires `input` on
-  each field it sets so a chained summary repaints — matching the server's
-  `set_value` + `dispatch("input")` contract. A missing/unregistered reducer is a
+  declared outputs (leaving the edited field + caret alone), and — for each
+  output whose value actually changed — dispatches a bubbling `input` event on
+  the field so a chained summary repaints, matching the server's `set_value` +
+  `dispatch("input")` contract (see #76). A missing/unregistered reducer is a
   no-op (a page never breaks because a binding wasn't wired up). When the same
   component ALSO carries `on(...)` (a persisted record, or a draft you sync), that
   debounced POST still fires and the server reply reconciles — so `reactive_compute`
@@ -127,6 +990,18 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Documentation
 
+- **Corrected the broadcast render-cost mental model — "N subscribers = N
+  renders" was wrong (#78).** A `broadcast_*_to` call renders the component
+  ONCE and passes the finished `html:` to `Turbo::StreamsChannel`, so every
+  subscriber of that stream shares one payload (the per-subscriber cost is
+  transport-side). The render cost is per CALL — broadcasting one change to K
+  different stream keys is K builds + K renders + K token signings of
+  byte-identical HTML — and per-viewer rendering (`visible_to:`-style content)
+  is the irreducible render-per-viewer case. Fixed in the performance docs
+  page, the render micro-bench comment, and CLAUDE.md; also repointed stale
+  `docs/performance.md` references to the docs app's performance page
+  (`docs/app/views/docs/pages/performance.rb`). No behavior changed.
+
 - **The auto-collected-params contract, spelled out (#64, #65, #66, #67).** Four
   gaps surfaced from building one model-scoped form (numeric fields that rebalance
   live). No behavior changed — the README now documents what the code already
@@ -206,6 +1081,48 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixed
 
+- **`reactive_compute` output writes never fired real `input` events — chained
+  repaints were dead in production (#76).** The controller's `recompute()` wrote
+  each output with a bare `field.value = …` under a comment claiming the write
+  fires the field's `input` listeners. Only the bun-test fake's custom `value`
+  setter did that — real browsers never fire `input` on a programmatic `.value`
+  write — so anything listening on a computed field (a chained summary repaint,
+  a second compute) silently never ran outside the test suite. The controller now
+  dispatches a real bubbling `new Event("input")` after each output write, and
+  the write is **change-guarded**: a field is written (and the event dispatched)
+  ONLY when the reducer's value differs from the field's current value
+  (String-compared). The guard is load-bearing, not an optimization — the shipped
+  `payment_split` example declares overlapping inputs/outputs, so an
+  unconditional dispatch would re-enter `input->reactive#recompute` forever;
+  with the guard, chains settle deterministically (the re-entrant pass writes
+  nothing and stops). The bun-test fake now matches real DOM (no auto-fire on
+  `.value` assignment; listeners run only through the controller's explicit
+  `dispatchEvent`), with unit coverage for the unchanged-write no-op, the
+  single bubbling dispatch, loop termination on the payment_split shape, and a
+  chained listener firing via the dispatched event — plus a real-browser system
+  assertion that a derived field repaints after typing. The misleading comments
+  in `reactive_controller.js` and `compute.js` now describe the real contract.
+
+- **`reply.flash` discarded its level — `:error` and `:notice` emitted
+  byte-identical streams (#77).** `Response.flash_stream` declared the level as
+  `_level` and never used it, so an app could not style errors red without
+  abandoning the flash helper — while the public API and every README example
+  pass a level. String flash content is now wrapped in
+  `<div class="reactive-flash reactive-flash--{level}"
+  data-reactive-flash-level="{level}">…</div>`, so the level reaches the wire as
+  a style hook (class) and a script/test hook (data attribute); the level is
+  HTML-escaped before landing in either attribute. **This intentionally changes
+  the wire output for string flashes** (previously the bare string was appended
+  with no wrapper) — restyle against `.reactive-flash--{level}` if you targeted
+  the raw text node. The string itself keeps the exact pre-existing injection
+  contract, now applied inside the wrapper: a plain String is HTML-escaped, an
+  `html_safe` String passes verbatim. Phlex **component** content still renders
+  VERBATIM — byte-identical to before, no wrapper (the caller owns the markup;
+  a spec pins it). New config `Phlex::Reactive.flash_component = MyFlash`
+  (default nil) renders string flashes through your own component instead of
+  the default wrapper — instantiated `MyFlash.new(level:, content:)` and
+  rendered through the existing render path; component content bypasses it.
+
 - **`reactive_controller.js` used a relative `./confirm.js` import that 404'd under
   importmap-rails + Propshaft — taking down every Stimulus controller on the page (#57).**
   The #55 confirm resolver added `import { confirmResolver } from "./confirm.js"` to the
@@ -687,7 +1604,10 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   scaffolds a reactive component (and an RSpec spec when the app uses RSpec),
   state-backed by default or record-backed with `--record`.
 
-[Unreleased]: https://github.com/mhenrixon/phlex-reactive/compare/v0.2.3...HEAD
+[Unreleased]: https://github.com/mhenrixon/phlex-reactive/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/mhenrixon/phlex-reactive/compare/v0.2.6...v0.9.0
+[0.2.6]: https://github.com/mhenrixon/phlex-reactive/compare/v0.2.5...v0.2.6
+[0.2.5]: https://github.com/mhenrixon/phlex-reactive/compare/v0.2.4...v0.2.5
 [0.2.4]: https://github.com/mhenrixon/phlex-reactive/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/mhenrixon/phlex-reactive/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/mhenrixon/phlex-reactive/compare/v0.2.1...v0.2.2