phlex-reactive 0.13.3 → 0.14.0

data/README.md

@@ -109,7 +109,129 @@ import ReactiveController from "phlex/reactive/reactive_controller"
 application.register("reactive", ReactiveController)
 ```
 
-Register eagerly (not lazily) so a click immediately after load is never missed.
+Eager registration is the simple, safe default. To load the controller lazily
+instead, import `phlex/reactive/early` eagerly (the engine pins it with
+`preload: true`) so the triggers below are not lost while it loads:
+
+```js
+// app/javascript/application.js — before any controller loads
+import "phlex/reactive/early"
+```
+
+It gzips to under 1.3 KB and has no Stimulus import. A trigger (`on(...)` or
+`on_client(...)`) that fires before the controller connects — a click while a
+lazily loaded controller is still downloading, a custom event dispatched as soon
+as the page is interactive — is queued, its native default is stopped exactly
+where the controller would stop it, and the controller replays it when it
+connects. Each root announces that moment with a bubbling `reactive:connect`
+event and a `data-reactive-connected` attribute. Without the import, register
+the controller eagerly: an event that fires before connect is otherwise lost.
+
+A queued trigger older than 10 s when its controller connects is dropped (a
+warning under `data-reactive-verbose`), as is one whose element left the page.
+Change the window with `Phlex::Reactive.early_event_ttl_ms` and a meta tag:
+
+```erb
+<meta name="phlex-reactive-early-ttl" content="<%= Phlex::Reactive.early_event_ttl_ms %>">
+```
+
+Good to know:
+
+- Every firing before connect is replayed (up to 50), so give a high-frequency
+  trigger (`input`, `mouseover`) a `debounce:` or `throttle:` as usual.
+- If you already wait for the controller yourself and then dispatch (a
+  `getControllerForElementAndIdentifier` polling loop), remove that loop when
+  you add the import, or the trigger fires twice.
+- `data-reactive-connected` is set at connect; an in-place morph strips it
+  again. Listen for `reactive:connect` rather than reading the attribute later.
+- Until the controller connects, a captured link or form trigger has its
+  native behavior stopped and nothing else happens. If the controller never
+  loads, or the entry is dropped (older than the TTL, its element gone, more
+  than 50 queued), that click or submit does nothing.
+- `window:` triggers — how a **hotkey** is usually bound
+  (`on(:toggle, event: "keydown.k", window: true)` or
+  `on_client("keydown.k", …, window: true)`) — are captured too: a hotkey
+  pressed anywhere on the page before the controller connects is replayed,
+  and it wakes a dormant root. Two differences from element-bound triggers:
+  the keypress is never prevented (a browser shortcut on the same key keeps
+  working, as it does once connected), and it is replayed only if the
+  controller connects within 1.5 s of the keypress (or the TTL above, if
+  shorter) — later, the user has moved on. Two roots sharing a hotkey both
+  hear it, as they do once connected: one press wakes both and each handles
+  it. A `once: true` hotkey replayed before connect stays spent for the
+  root until it disconnects — keep its trigger element stable across replies
+  (a reply that morphs the root but swaps that element leaves the hotkey
+  dead until the next disconnect), or bind the hotkey without `once:`.
+- Not captured, so still lost before connect: `outside:` triggers (an outside
+  click before connect has nothing to close, and recording it would wake a
+  dormant dropdown on every click); key filters beyond Stimulus's default key
+  names; and every other controller action — only `on(...)` (`reactive#dispatch`) and
+  `on_client(...)` (`reactive#runOps`) are replayed, not the built-in
+  `nestedAdd`/`nestedRemove`, `tagsAdd`/`tagsPick`, `listnav*` or `recompute`
+  bindings.
+
+**Dormant roots: mount on first use.** Loading the controller lazily only helps
+on pages with no reactive root: a root renders `data-controller="reactive"`, and
+that is what makes Stimulus load and connect it. A root that only matters after
+a gesture (a closed dialog, a menu that loads on open) can stay dormant instead:
+
+```ruby
+class ItemsPanel < ApplicationComponent
+  include Phlex::Reactive::Component
+
+  reactive_dormant # every root of this component (inherited)
+  action :load
+
+  def view_template
+    div(**mix(reactive_root, on(:load, event: "panel:opened", once: true))) { … }
+  end
+end
+
+div(**reactive_root(dormant: true)) { … } # or one render at a time
+```
+
+A dormant root renders `data-reactive-dormant="reactive"` in place of the
+controller attribute, so nothing mounts and a lazily loaded controller is not
+fetched. The first `on(...)`/`on_client(...)` trigger that reaches it — a
+`window:` hotkey pressed anywhere on the page included, an `outside:` one
+not — wakes it:
+`phlex/reactive/early` moves the identifier into `data-controller`, Stimulus
+loads and connects the controller, and the trigger is replayed once.
+
+- **It needs `import "phlex/reactive/early"`.** Without that module nothing
+  wakes the root: a link or form trigger just does its native thing (the link
+  navigates, the form posts), and a dormant root nested inside an awake one
+  hands its triggers to the OUTER component (they run the outer's action of
+  that name with the outer's token, or get a 403).
+  `bin/rails phlex_reactive:doctor` lists the dormant components and says
+  where it found the import (an app JS entry, or an inline module script in a
+  view or component). With more than one import map, every map needs the
+  `phlex/reactive/early` pin: the doctor names each one without it, and
+  `Phlex::Reactive.importmaps = -> { { "landing" => landing_map } }` adds maps
+  that are not `Rails.application.importmap`.
+- The actor's own reply, a `reactive_lazy(on:)` materialize and the defer
+  endpoint render the root awake, since that page's controller is loaded by
+  then. Everything else renders it dormant: the page, a broadcast (`broadcast_to`,
+  also inside an action), a page refresh, a deferred render pushed over a
+  stream. If one of those lands on an awake root, the next trigger wakes it
+  again. A `to_stream_replace` you build inside an action and send to other
+  pages yourself is rendered awake, so broadcast with `broadcast_to` instead.
+- Use it for a root whose only behavior is its triggers. What the controller
+  does at connect (`reactive_persist` restore, `reactive_compute` seeding,
+  show/filter sync, dirty tracking) waits for the wake, and the browser
+  inspector (`inspect.js`) does not list a dormant root.
+- With `reactive_lazy`: an event shell (`reactive_lazy on: "panel:opened"`) can
+  be dormant, and that event wakes and loads it in one go. `on: :visible`
+  cannot (its shell has no trigger to wake on; declaring both raises), and a
+  plain `reactive_lazy` shell always mounts, because it fetches on connect. On
+  a lazy component use the class-level `reactive_dormant`: the shell is rendered
+  by the framework and never sees a per-render `reactive_root(dormant: true)`.
+- With a controller of your own on the same root, list it first:
+  `mix({ data: { controller: "dropdown" } }, reactive_root)`. Waking appends
+  `reactive`, which then matches what an awake reply renders; in the other
+  order the first morph reply reconnects both controllers once.
+- A dormant root nested inside an awake one belongs to the outer root until it
+  wakes: its fields are collected with the outer root's actions.
 </details>
 
 ### Scaffold a component
@@ -135,13 +257,178 @@ import ReactiveController from "phlex/reactive/reactive_controller"
 application.register("reactive", ReactiveController)
 ```
 
-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
+The gem ships a prebuilt, minified `reactive_controller.min.js` (the whole
+client in one file, about 25 KB gzipped) with a linked sourcemap, and
+auto-pins it for importmap apps — so browsers load the small file while
+devtools still shows the real code. It imports three small modules by their
+bare names — `phlex/reactive/confirm`, `phlex/reactive/confirm_predicate` and
+`phlex/reactive/compute`, the seams you can override — so point your bundler
+at the gem's `app/javascript` directory (one prefix alias for
+`phlex/reactive`), or alias the controller and those three names. See
 [docs/installation.md](https://phlex-reactive.zoolutions.llc/docs/installation).
 </details>
 
+### The split client (opt-in): a smaller core, features on demand
+
+`phlex/reactive/reactive_controller` is **one file with everything in it**.
+That is the default, and nothing about it changes: one import, the whole
+client, nothing fetched later.
+
+The same client also ships split in two, for an app that wants the smallest
+possible script on its light pages:
+
+```js
+// instead of "phlex/reactive/reactive_controller" — never both
+import ReactiveController from "phlex/reactive/core"
+application.register("reactive", ReactiveController)
+```
+
+`phlex/reactive/core` is the controller **without** its feature modules. It
+imports one the first time a root on the page needs it:
+
+| Module | Gzipped | Default client | Split client |
+|---|---:|---|---|
+| `phlex/reactive/reactive_controller` | 26.1 KB | loaded with your controllers | not loaded |
+| `phlex/reactive/core` | 12.4 KB | not loaded (it is inside the file above) | loaded with your controllers |
+| `phlex/reactive/features/persist` (`reactive_persist` drafts) | 3.2 KB | inside the one file | fetched when a root declares `reactive_persist`, or a `persist_state` / `persist_clear` op runs |
+| `phlex/reactive/features/defer` (`reply.defer`, `reactive_lazy`) | 2.8 KB | inside the one file | fetched when a root is a `reactive_lazy` shell, a morph turns one into a shell, or a `reply.defer` arrives |
+| `phlex/reactive/features/form` (dirty tracking, `warn_unsaved`, the paste-trigger gate) | 1.0 KB | inside the one file | fetched when a root tracks dirty fields or holds a `paste_into` trigger |
+| `phlex/reactive/features/effects` (`reactive_effects`, `dismiss_after`) | 1.7 KB | inside the one file | fetched when a root declares an effect, or when the first stream that needs it arrives: one with an effect, or with a dismissing flash |
+| `phlex/reactive/features/bindings` (`reactive_show`, show targets, `reactive_on_complete`, `reactive_filter`, `reactive_tags`, nested rows, the conditional `confirm:`) | 5.4 KB | inside the one file | fetched when a root declares one of them, or holds a trigger with a conditional confirm |
+| `phlex/reactive/features/compute` (`reactive_compute`, `reactive_text`) | 2.1 KB | inside the one file | fetched when a root carries a compute binding |
+| `phlex/reactive/features/hints` (`optimistic:`, `busy:`) | 1.0 KB | inside the one file | fetched when a root holds a trigger that declares a hint |
+| `phlex/reactive/features/devtools` (the latency simulator, the zero-target warnings, the debug trace) | 1.6 KB | inside the one file | fetched with the core on a page that carries `<meta name="phlex-reactive-env" content="development">` or while a delay is stored for the tab; at connect for a root in debug mode; otherwise the first time a verbose root has something to warn about. In production with none of these, never |
+| `phlex/reactive/early` | 1.2 KB | on every page, if you import it | the same |
+
+That is the whole split: everything that can leave the core has. What
+remains in it — the request pipeline, the signed token, field collection,
+client ops and `on_client` bindings, early-trigger replay, list navigation —
+is what every reactive page uses.
+
+**What you trade.** With the default client a feature is simply there when a
+root connects. With the split client the **first** root of a page load that
+needs a feature waits for one small request (cached afterwards; on a Turbo
+visit the module is already loaded and nothing waits). While it waits:
+
+- a `reactive_persist` root shows what the server rendered. What the user
+  changes is kept and drafted when the module arrives (also when they leave
+  the page before it does); an action they fire waits for the
+  restore and posts the restored values — unless the module is slower than
+  the feature timeout (10 s), fails to load, or the root leaves the page
+  first, in which case it goes out with the values on the page;
+- a `reactive_lazy` shell shows its placeholder a moment longer; an `on:`
+  event that fires in that window loads the shell once the module is there;
+- a stream that brings the page's first effect or dismissing flash — a
+  broadcast, an action's reply — is rendered when the effects module has
+  arrived, so that very stream is animated and its flash dismissed on time
+  (`dismiss_after:` counts from the render). Every stream that arrives while
+  it waits renders after it, in order. The wait is capped at one second
+  (under an import that never settles, each later stream that needs the
+  feature pays its own one-second hold — bounded, never wedged — and a plain
+  stream behind it waits with it, for order);
+  after that the streams render without the effect, and a flash they brought
+  is dismissed counting from the module's arrival instead. A root that
+  declares an effect loads the module when it connects, so this only happens
+  on a page where no root does;
+- a dirty-tracked form counts an edit made in the window when the module
+  arrives. `warn_unsaved:` does not prompt for a navigation in the window
+  itself: preload the module on a page where that matters (below);
+- a form's bindings — `reactive_show`, `reactive_filter`, the tag chips, the
+  nested-row JSON field — show what the server rendered until the module
+  arrives, then seed from the fields as they are: a choice made in the window
+  is kept and reflected, a tag picked in the window is added, a conditional
+  `confirm:` asks once the module can evaluate it (and proceeds without a
+  dialog if the module cannot load or is slower than the feature timeout —
+  the endpoint's authorization is the real gate). Because the JSON-mode rows
+  write a field a request collects, a root with any of these holds its
+  requests until the module is here (bounded as above);
+- a `reactive_compute` root shows the server's values for its outputs until
+  the module arrives (about 20–25 ms with the module served from the same
+  host, measured on the split client in the browser suite; one request's
+  worth on a real network), then seeds; an edit made in the window is
+  recomputed from the value the user typed, never overwritten. Such a root
+  holds its requests until the module is here, for the same reason;
+- a trigger with an `optimistic:` or `busy:` hint: its request waits for the
+  hints module (at most the feature timeout); the hint applies if the module
+  arrives in time, and after a timeout or a failed load the request goes out
+  without it — once either way. The busy markers (`aria-busy`,
+  `data-reactive-busy`, `busy_on`) are on from the click, as always; a
+  failure after a late apply still reverts the optimistic hint. A root whose
+  triggers declare a hint loads the module when it connects, so this is the
+  first click of a page's first root at most. In that window a
+  `busy: { disable: true }` hint cannot stop a second click: three rapid
+  clicks are three ordered requests (the default bundle's synchronous
+  disable blocks the second and third);
+- the latency simulator delays a request from the first one on (the request
+  waits for the module); a zero-target warning on a verbose root, or a debug
+  trace, is logged once the module is here. `enableLatencySim` /
+  `disableLatencySim` are exported by `phlex/reactive/features/devtools`
+  here, not by the controller.
+
+None of that exists with the default client.
+
+**Taking the small core without the network wait.** Preload the features
+you know a page uses:
+
+```ruby
+# config/importmap.rb — after the engine's own pins
+pin "phlex/reactive/core", to: "phlex/reactive/core.min.js", preload: true
+pin "phlex/reactive/features/persist", to: "phlex/reactive/features/persist.min.js", preload: true
+pin "phlex/reactive/features/form", to: "phlex/reactive/features/form.min.js", preload: true # the unsaved guard a task after connect
+pin "phlex/reactive/features/bindings", to: "phlex/reactive/features/bindings.min.js", preload: true # show/filter/tags a task after connect
+pin "phlex/reactive/features/compute", to: "phlex/reactive/features/compute.min.js", preload: true # computed fields a task after connect
+```
+
+(or a `<link rel="modulepreload">` on the pages that need it). The module is
+then already loaded, so there is no network wait — but a preloaded module
+still arrives through `import()`, which resolves in a later task: the
+feature connects in the task **after** `connect()`, not inside it (measured:
+with `modulepreload` the compute seed lands 29–51 ms after `reactive:connect`
+on localhost), `featuresReady` is pending for that moment, and the first
+root's request gate applies to it. The default bundle is the only way to get
+connect-time seeds. A root that is
+[dormant](#installation) fetches nothing at all — not the core, not a feature —
+until its first trigger; the trigger is then replayed after the core has
+loaded, and waits for a feature like any other.
+
+**Bundlers.** The core reaches a feature with a literal
+`import("phlex/reactive/features/persist")`. Give your bundler **one prefix
+alias** for the gem's JavaScript directory, which covers the core, the seams
+and every feature, now and later:
+
+```js
+// esbuild (build script)
+import * as esbuild from "esbuild"
+import { execSync } from "node:child_process"
+const gemJs = `${execSync("bundle show phlex-reactive").toString().trim()}/app/javascript`
+
+await esbuild.build({
+  // …
+  splitting: true, format: "esm", // each feature becomes its own chunk
+  plugins: [{
+    name: "phlex-reactive",
+    setup(build) {
+      build.onResolve({ filter: /^phlex\/reactive\// }, ({ path }) => ({ path: `${gemJs}/${path}.min.js` }))
+    },
+  }],
+})
+```
+
+(Vite/webpack: the same rule as a prefix `resolve.alias` for `phlex/reactive`.)
+Without code splitting the features are bundled into your entry, which is the
+default client with extra steps. With exact per-module aliases the build fails
+on the feature it cannot find (esbuild: `Could not resolve
+"phlex/reactive/features/persist"`). If you pin copied
+files by hand in an import map, pin `phlex/reactive/core` and each
+`phlex/reactive/features/*` too; a feature that cannot be imported logs one
+console error naming it, marks the root `data-reactive-error="feature"`, emits
+`reactive:error` (`kind: "feature"`) and does nothing. The specifiers are
+bare, not relative, because Propshaft serves each file under its own digest
+and only the import map can resolve one to another (issue #57).
+
+**One or the other.** Each entry carries its own copy of the client's state.
+Loading both logs `the client was loaded twice` to the console.
+
 **Requirements:** Rails 7.1+, Phlex 2 (`phlex-rails`), Turbo 8+ (for morphing),
 and a Phlex `ApplicationComponent` base class. pgbus is optional but recommended
 for broadcasting.
@@ -199,10 +486,15 @@ guide](https://phlex-reactive.zoolutions.llc/docs/tooling) for the full workflow
 ```bash
 bin/rails phlex_reactive:doctor          # validate the whole install (✓/✗/? + a fix each)
 bin/rails phlex_reactive:actions         # every component × action: params, file:line, auth
+bin/rails phlex_reactive:actions UNVERIFIED=1 # only actions with no detected authorization AND no skip
 bin/rails "phlex_reactive:find[counter]" # fuzzy-find one; prints each action's method source
 bin/rails phlex_reactive:mcp             # a read-only MCP server (needs `gem "mcp"`)
 ```
 
+The `auth` column reads `authorized*` (an authorization call was detected — a
+heuristic), `skipped` / `skipped (class)` (declared `skip_verify_authorized`,
+per action or component-wide), or `unverified` (neither — review these).
+
 In the browser console, map every reactive root + trigger on the page back to its
 server `Component#action` names (a standalone module — zero cost until imported):
 
@@ -372,6 +664,7 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 | `skip_verify_authorized [ :a, :b ]` | Opt a component (bare) or specific actions out of the default-ON `verify_authorized` guard — for a genuinely public component (a counter, a client-only filter). |
 | `reactive_root(**overrides)` | Spread onto the root element: emits the component `id` **and** `reactive_attrs` together, so the controller root always carries `#id`. Preferred over `id:` + `reactive_attrs`. `**overrides` (`class:`/`data:`) deep-merge. `compute: :name` binds a client-side compute **at the root** — descriptors plus the `input->reactive#recompute` delegation, so no field needs its own wiring; `nil` collapses to no binding. See [Client-side computes](#client-side-computes-reactive_compute--reactive_text). |
 | `reactive_attrs` | Marks an element reactive + carries the signed token (no `id`). Spread alongside `id:` on the **same** element: `div(id:, **reactive_attrs)`. Prefer `reactive_root`, which can't split them. |
+| `reactive_dormant` / `reactive_root(dormant: true)` | Mount the controller on first use: the root renders `data-reactive-dormant="reactive"` instead of `data-controller="reactive"` until one of its triggers fires. Class-level and inherited (`reactive_dormant false` turns it off again), or per render (`reactive_attrs(dormant: true)` too). Needs `import "phlex/reactive/early"`. See the dormant roots note under [Installation](#installation). |
 | `on(:action, event: "click", **params)` | Spread onto a trigger element. Adds `type=button` for clicks. |
 | `on(:action, event: "input", debounce: 300)` | Coalesce rapid events into one round trip after a quiet period (live-as-you-type). |
 | `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). |
@@ -385,15 +678,17 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 | `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`, `text` (set `textContent` — XSS-safe), `dispatch`, `submit` (requestSubmit the target's own form), `paste_into` (read the clipboard into a field, gesture-gated), and `persist_state`/`persist_clear` (the `reactive_persist` draft) — chainable. |
+| `js` | The immutable op builder behind `on_client`: `show`/`hide`/`toggle` (the `hidden` attribute, with an optional `transition:` and `expanded:`), `add_class`/`remove_class`/`toggle_class`, `set_attr`/`remove_attr`/`toggle_attr` (allowlisted names; `toggle_attr` also flips between two values), `focus`/`focus_first`, `text` (set `textContent` — XSS-safe), `dispatch`, `submit` (requestSubmit the target's own form, optionally through a `submitter:`), `paste_into` (read the clipboard into a field, gesture-gated), and `persist_state`/`persist_clear` (the `reactive_persist` draft) — chainable. |
 | `reactive_field(:param, **attrs)` | The attribute hash that binds a control to an action param (no magic `name:`) — spread onto any control: `input(**reactive_field(:value, value: @record.name))`, `select(**reactive_field(:status)) { … }`. |
 | `reactive_text(:name, initial)` | Mirror a compute output (or a declared input) into a **text node** — a live preview heading, a character counter, `"Hello, {name}"` — via `textContent` (XSS-safe). The text sibling of `reactive_field`; carries no `name`, so it's never POSTed. See [Client-side computes](#client-side-computes-reactive_compute--reactive_text). |
 | `reactive_show(if:/if_any:/unless:)` | **Value-conditional visibility** (the `x-show`/`data-show` case): spread onto the element to show/hide — it toggles `hidden` from the fields' **current values**, client-only, zero round trip. One conditions language: a **Hash is an AND**, an **Array is membership**, a **Range is a threshold**, `if_any:` is OR-of-AND, `unless:` negates. `reactive_values` computes first paint; `disable:` disables a hidden section's controls. See [Value-conditional visibility](#value-conditional-visibility-reactive_show). |
+| `reactive_enable(if:/if_any:/unless:)` | The sibling of `reactive_show` that flips the element's **own `disabled`** (a button, a fieldset) instead of `hidden` — same conditions, same `reactive_values` first paint. `button(**reactive_enable(if: { "ids[]" => { checked: 1.. } }))`. See [Bulk selection](#bulk-selection-reactive_select_all-reactive_count-reactive_enable). |
+| `reactive_select_all("ids[]")` / `reactive_count("ids[]")` | A checkbox **group**'s header box (ticks/unticks every owned box; shows checked / indeterminate / unchecked) and its ticked count as text — re-synced on every change and when rows are appended or removed. See [Bulk selection](#bulk-selection-reactive_select_all-reactive_count-reactive_enable). |
 | `reactive_show_targets(:field, "#id" => value)` | **Cross-root visibility**: the component that owns the field declares which **outside**, id-allowlisted elements it governs (a nav tab, a panel in another pane) — the visibility parallel of `mirror:`. Spread on the **root** via `mix(reactive_root, …)`, **once per root** — several fields go in one call via the hash form. The value uses the same `where`-style vocabulary (`"advanced"`, `%w[a b]`, `10..`); a `"#id"` **key** takes a full conditions Hash for a **multi-field** predicate (`"#warn" => { if: { type: "trade", price: ..0 } }`). Id selectors only (raise at render + client warn-skip); toggles `hidden` only. See [Value-conditional visibility](#value-conditional-visibility-reactive_show). |
 | `reactive_persist(key:, ttl: 7.days)` | **Client-only drafts**: spread on the **root** (once) and the generic controller keeps a `localStorage` draft of every **owned** control — debounced write on `input`, immediate on `change`, flushed on disconnect, restored into **blank** controls on the next connect (`restore: :always` lets the draft win), cleared by a successful Turbo submit / `ttl` / `js.persist_clear`. Never hidden/file/password; `reactive_persist_skip` opts a control out; `fields:` narrows. See [Client-only drafts](#client-only-drafts-reactive_persist). |
 | `js.persist_state(step: 2)` / `js.persist_clear` | The draft ops (actor-only): merge a flat state bag into the draft (restored as `data-reactive-persist-state` + the `reactive:persist-restored` event) / forget the draft. |
 | `reactive_filter(:field, option: nil, group: nil, empty: nil)` | **Client-side option filtering** for a preloaded combobox: spread onto the root and name the **field** that drives it — `reactive_filter(:q)` compiles `:q` to `[name="q"]` (scope-aware) and typing shows/hides the options by their `data-reactive-filter-text` haystack, **zero round trips**. `option:` defaults to `[role=option]`; optional `group:` collapses an all-hidden group header; `empty:` reveals a no-matches node. `input:` is the escape hatch — a raw CSS selector for a **name-less** driving input (`input: "#tags_query"`), the form-builder case. See [Client-side option filtering](#client-side-option-filtering-reactive_filter). |
-| `reactive_listnav("[role=option]")` | The **standalone** combobox keyboard wiring (Arrow/Enter/Escape) for an input that fires **no action** — the preload-and-filter case. Same behavior as `on(…, listnav:)`, minus the POST. |
+| `reactive_listnav("[role=option]")` | The **standalone** combobox keyboard wiring (Arrow/Enter/Escape) for an input that fires **no action** — the preload-and-filter case. Same behavior as `on(…, listnav:)`, minus the POST. `reactive_listnav(focus: true)` is the **roving-focus** variant for a `role="menu"` container: Arrow Down/Up move real focus among `[role=menuitem]` (wrapping), Home/End jump to the edges; Enter/Space stay native and Escape is yours to bind. |
 | `reactive_tags(:tags)` | **Tag-chip input** (the combobox/tags widget): spread onto the root and name the hidden field that stores the **comma-joined** value — the client maintains that field + the chip list entirely client-side (form state, zero round trips), rebuilding chips from your server-owned `<template>`. Composes with `reactive_filter` (type to narrow) and `reactive_listnav` (Enter picks the highlighted option). `name:` is the escape hatch — a **verbatim** wire name (`name: "user[tags]"`, never re-scoped), the form-builder case. See [Tag-chip input](#tag-chip-input-reactive_tags). |
 | `reactive_tags_add` / `reactive_tags_option(tag)` / `reactive_tags_remove(tag)` | The tags triggers, all **client-only**: `reactive_tags_add` on the query input adds the typed text on Enter (mix it **after** `reactive_listnav`; Enter never submits the enclosing form); `reactive_tags_option` makes a preloaded suggestion add its declared tag on click; `reactive_tags_remove` is a chip's remove button (no arg inside the template — the client fills the tag per chip). |
 | `reactive_compute :name, inputs: { title: :string, qty: :number }, outputs:` | **Typed** inputs: a `:string` reaches the JS reducer raw, a `:number` is coerced through `Number`, a `:boolean` is a checkbox's checked state. The array form (`inputs: %i[a b]`) stays all-numeric; the **permit-style** form (`inputs: [:qty, title: :string]`) mixes both — bare symbols default `:number`, a trailing hash types the exceptions. `outputs:` is the field allowlist; a reducer-result key also paints any owned `reactive_text` node by presence and any `mirror:` id, so an `outputs:` entry that exists only to reach a text node is redundant (harmless — a widening). |
@@ -583,6 +878,12 @@ action :save, params: {invoice: {date: :string, status: :string}}
 > `invoice[…]` (any `Form(model:)`-style form), nest the schema under `invoice:`
 > to match. When in doubt, read a field's real `name` attribute and shape the
 > schema to it.
+>
+> The exception is `reactive_scope :invoice`: the endpoint expands the names and
+> then peels that one level, on the JSON body and the multipart one alike, so the
+> flat schema is the one to declare. Bare params posted beside the scoped fields
+> (a trigger's `on(:save, note: "x")`) stay at the top level next to them; as
+> on the client, an explicit `on(...)` param wins over a field of the same name.
 
 **Nested reactive components compose.** A reactive component rendered inside
 another is its own root — field collection stops at nested
@@ -823,9 +1124,11 @@ 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.)
+and the badge clears with no reload — for a focused field, once the saved value
+matches what is in the box. (A morph keeps a focused field's
+in-progress value while writing its fresh default — the client does that, issue
+#338, since Turbo's stream morph would overwrite it — and the post-morph re-scan
+is what keeps the root count honest in that state.)
 
 **`reactive_dirty warn_unsaved: true`** arms a navigate-away guard gated on the
 **live** dirty count: `beforeunload` (a real browser unload) and
@@ -892,7 +1195,10 @@ button(**on_client(:click, js
 ```
 
 - **`set_attr(to, name, value)` / `remove_attr(to, name)` / `toggle_attr(to, name)`**
-  mutate an attribute. The **attribute name is allowlisted, enforced twice** — at
+  mutate an attribute. `toggle_attr(to, name, on, off)` (#271) flips **between two
+  values** instead of toggling presence — `toggle_attr("#trigger", "aria-expanded",
+  "true", "false")`; an absent attribute becomes `on`, and one value or two equal
+  values raise at build time. 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`,
@@ -920,7 +1226,15 @@ button(**on_client(:click, js
   from `on_client` / `reply.js` / a reducer's `$ops`, refused in
   `broadcast_to(js:)` (a broadcast would force-submit every subscriber's form).
   Binding a submit op to the `submit` event itself raises at render — it would
-  re-fire itself forever.
+  re-fire itself forever. **`submitter:`** (a CSS selector, resolved with the
+  op's own scoping) submits *through* that control —
+  `form.requestSubmit(submitter)` — so the request carries its `name=value`:
+  `js.submit("#bulk", submitter: "#delete-submit")` posts `action=delete`. It
+  composes with `on_client(…, confirm:)` (a cancelled confirm submits nothing).
+  A submitter that is not a submit control of that form warns and falls back to
+  a plain `requestSubmit()`. Note that a selector target resolves *inside* the
+  root, so when the form **is** the reactive root, use the default target:
+  `js.submit(submitter: "#delete-submit")`.
 - **`paste_into(to)`** reads the clipboard into a field on a **user gesture**
   (issue #228): `navigator.clipboard.readText()`, then the field gets the text
   through the **normal `input` pipeline** — `.value` is set, a bubbling `input`
@@ -940,6 +1254,14 @@ button(**on_client(:click, js
   (a broadcast that reads every subscriber's clipboard would be hostile). The
   op is async fire-and-forget — chained siblings apply immediately, never
   waiting for the read.
+- **`expanded:`** on `show`/`hide`/`toggle` (#271) keeps a disclosure trigger's
+  `aria-expanded` honest: `js.toggle("#menu", expanded: "#trigger")` writes the
+  op's **intended** state (`show` → `"true"`, `hide` → `"false"`, `toggle` → the
+  state after the flip: `"true"` when the target was hidden, `"false"` when it
+  was visible) onto the target — set before any transition runs. It resolves
+  with the op's own scoping (`:root`, a root-scoped selector, or document-wide
+  under `global: true`). Pair it with one disclosure target; with several, the
+  last one wins.
 - **`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
@@ -950,6 +1272,32 @@ button(**on_client(:click, js
 modifiers: the dropdown above closes on any click outside the component, and
 window-bound triggers never `preventDefault`, so links elsewhere keep working.
 
+**Several bindings on one element (#271).** Each `on_client` call emits one
+self-describing **binding record** — its descriptor, flags, `confirm:` and ops —
+so two calls compose through `mix`. The descriptors token-join; the records
+space-join (spaces inside a record ride as `\u0020`); the client runs only the
+record whose descriptor matches the firing event (event type, key filter,
+window-boundness):
+
+```ruby
+div(**mix(reactive_root,
+          on_client(:click, js.hide("#menu", expanded: "#trigger"), outside: true),
+          on_client("keydown.esc", js.hide("#menu", expanded: "#trigger").focus("#trigger"))))
+# data-action="click@window->reactive#runOps keydown.esc->reactive#runOps"
+# data-reactive-ops-param='{"on":"click","window":true,"outside":true,"ops":[…]} {"on":"keydown.esc","ops":[…]}'
+```
+
+An outside guard or a `confirm:` belongs to its own binding only — it never
+gates a sibling. Two element-bound `:click` calls on the same `<button>` still
+collide on the forced `type="button"` (`mix` renders `type="button button"`):
+chain the ops into one call instead.
+
+**An accessible menu with no custom JS.** Pair the above with
+`reactive_listnav(focus: true)` on the `role="menu"` list — Arrow Down/Up rove
+real focus among `[role=menuitem]` (wrapping), Home/End jump to the edges — and
+the whole WAI-ARIA menu-button pattern is declared ops. See the
+[client-only ops example](https://phlex-reactive.zoolutions.llc/docs/example-client-ops).
+
 **The general autosubmit story.** With `submit` in the vocabulary, the classic
 `onchange="this.form.requestSubmit()"` filter form is one declared line — no
 bespoke controller, no reactive action, and Turbo Drive turns the resulting
@@ -1070,7 +1418,10 @@ end
   length** — exact (`{ length: 6 }`) or an Integer Range (`{ length: 6.. }`,
   `{ length: 4..8 }`). Length counts **codepoints** on both sides (Ruby
   `String#length`, client `[...value].length`), so multibyte input agrees; a
-  blank field has length 0. `unless:` **negates** and composes with `if:`.
+  blank field has length 0. **`{ checked: … }` counts the ticked boxes of a
+  checkbox group** — `{ "ids[]" => { checked: 1.. } }` (see
+  [Bulk selection](#bulk-selection-reactive_select_all-reactive_count-reactive_enable)).
+  `unless:` **negates** and composes with `if:`.
   Never an expression — every term is a declared literal, so there is no eval
   surface. A blank/non-numeric value fails a numeric term **closed** (hidden).
 - **OR-of-AND** — `if_any:` takes an array of AND-hashes (`if_any: [{ director:
@@ -1150,6 +1501,70 @@ field; a missing owned field reads as blank — fail-closed). Every referenced
 field must be owned by the declaring root; a target whose fields are all
 unowned is left alone, like the single-field skip.
 
+### Bulk selection (`reactive_select_all`, `reactive_count`, `reactive_enable`)
+
+A list with a checkbox per row, a "select all" header, a "Delete (2)" count and
+actions that stay disabled until something is ticked — with no per-list
+JavaScript controller:
+
+```ruby
+class PostsTable < Phlex::HTML
+  include Phlex::Reactive::ClientBindings
+
+  def initialize(posts:) = @posts = posts
+
+  # First paint: nothing ticked (an Array of checked values, or a count).
+  def reactive_values = { "ids[]" => [] }
+
+  def view_template
+    div(**reactive_root) do
+      form(id: "bulk", action: "/posts/bulk", method: "post") do
+        input(type: "checkbox", **reactive_select_all("ids[]"))     # header
+        @posts.each do |post|
+          label { input(type: "checkbox", name: "ids[]", value: post.id); plain post.title }
+        end
+
+        span(**reactive_count("ids[]")) { "0" }                     # ticked count
+        fieldset(**reactive_enable(if: { "ids[]" => { checked: 1.. } })) { bulk_fields }
+        button(type: "button",
+               **mix(reactive_enable(if: { "ids[]" => { checked: 1.. } }),
+                     on_client(:click, js.submit("#bulk", submitter: "#delete-submit"),
+                               confirm: "Delete the selected posts?"))) { "Delete" }
+        button(type: "submit", name: "bulk_action", value: "delete", hidden: true, id: "delete-submit")
+      end
+    end
+  end
+end
+```
+
+- **`reactive_select_all(group)`** — the header box. Its edit ticks or unticks
+  every **owned** box named `group` and dispatches `input` + `change` on each one it
+  flips, so computes, shows and completions re-run. Its own state follows the
+  group: **checked** when all are ticked, **indeterminate** when some are,
+  unchecked when none are. Give the header no `name` (it would post).
+- **`reactive_count(group)`** — writes the ticked count via `textContent`
+  (change-guarded). Seed the first paint in its block.
+- **`{ checked: n }` / `{ checked: 1.. }`** — a term in the shared conditions
+  language: how many owned boxes of the group are ticked, with the same Integer
+  and Range shapes as `length:`. It works in `reactive_show`, `reactive_enable`,
+  `reactive_on_complete`, `reactive_show_targets` and a conditional `confirm:`,
+  and it is evaluated on the server for first paint from `reactive_values` (an
+  Array of the checked values is counted; an Integer is the count).
+- **`reactive_enable(if:/if_any:/unless:)`** — `reactive_show`'s sibling: the
+  same conditions, the same first paint (`disabled:`) and the same re-evaluation
+  triggers, but it flips the element's own `disabled`. An explicit `disabled:`
+  wins.
+- **Rows added or removed later** (a Turbo stream `append`/`remove`, a morph)
+  re-sync the header, the count, `reactive_enable` and `reactive_show` (and its targets): a root with a group binding
+  watches its subtree and re-syncs when a checkbox is added or removed.
+- **Ownership** is the usual rule (#15): a nested reactive root's boxes are
+  never counted or flipped by the outer root.
+- The group is a field name resolved like any `reactive_show` field: a bare
+  name takes `reactive_scope`, a bracketed one (`"ids[]"`) is used verbatim.
+- **`js.submit(to, submitter:)`** submits the form through the hidden submit
+  button, so the POST carries `bulk_action=delete` (see the
+  [op vocabulary](#client-only-ops-on_client--js--zero-round-trips)).
+
 ### Client-only drafts (`reactive_persist`)
 
 "Don't make me start over": a public application form, a multi-step wizard,
@@ -1194,7 +1609,11 @@ wire attr: `data-reactive-persist='{"key":"village-apply","ttl":604800,"debounce
   `reactive_show` section, `reactive_on_complete` (armed, never fired),
   `reactive_filter` and a `reactive_compute` root all read the restored values
   on first paint — no synthetic events. A morph or broadcast re-render is
-  server truth and is **never** re-restored.
+  server truth and is **never** re-restored. (With the opt-in
+  [split client](#the-split-client-opt-in-a-smaller-core-features-on-demand)
+  the first `reactive_persist` root of a page load restores a moment after it
+  connects, once the draft module has arrived; that section lists what holds
+  in between.)
 - **`restore: :blank`** (default) — a draft value lands only in a control the
   server rendered **blank**, so a 422 re-render's submitted values beat an
   older draft. `restore: :always` lets the draft win.
@@ -1926,7 +2345,8 @@ def add(item:) = reply.replace.stream(Totals.update(@order))               # mul
 
 # Per-field reactive editing (a "spreadsheet" grid): a debounced save fires
 # while the user is still typing/tabbing. Morph in place so the focused <input>
-# and its in-progress value survive the re-render (issue #28). Note the action is
+# and its in-progress value survive the re-render (issues #28, #338) — even when
+# the render differs (the model strips "Hello " to "Hello"). Note the action is
 # named `update`, yet `reply.morph` is unambiguous — the verb is on `reply`:
 def update(name:) = (@row.update!(name:); reply.morph)
 
@@ -1943,7 +2363,7 @@ def update(quantity:, price:) = (@item.update!(quantity:, price:); reply.streams
 | Builder | Reply |
 |---|---|
 | `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) |
+| `reply.morph` / `reply.replace(morph: true)` / `reply.update(morph: true)` | re-render in place via Idiomorph (`method="morph"`) — preserves the focused `<input>`/`<textarea>`, its caret AND what was typed in it (the render's value becomes its new default; other fields take the server's value; `data-reactive-morph-value` on a field lets the morph overwrite it while focused, #338); for per-field reactive editing (`replace` #28; `update` #113) |
 | `.also(target => content, …)` | **UPDATE** (inner HTML) companion elements by DOM id; `content` is a plain string (escaped) or a Phlex component. The argument *type* picks the action — pairs mean `update` |
 | `.also(component, morph: false)` | **REPLACE** another Streamable component at its own `#id` (`morph: true` morphs in place). A component argument means `replace` |
 | `.flash(level, content, target: …)` | append a flash; `content` is a plain string (escaped, wrapped in a level-carrying `<div>` — see [Flash levels](#flash-levels)) or a Phlex component (rendered verbatim; off-request — no Rails `flash`); target defaults to `Phlex::Reactive.flash_target` (`"flash"`) |
@@ -2103,6 +2523,134 @@ to ship a matching shell element. The client re-fetches the real content both on
 connect AND after a Turbo page-refresh **morph** (which re-shows the shell while
 keeping the element connected), so a lazy component survives a `turbo:reload`.
 
+**Load on first use** — `on:` defers the *request itself* until an event
+reaches the shell, or until it scrolls into view (issue #276):
+
+```ruby
+reactive_lazy on: "panel:opened"          # a DOM event on (or bubbling into) the shell
+reactive_lazy on: :visible                # IntersectionObserver, no DOM event involved
+reactive_lazy on: { visible: "200px" }    # …with a rootMargin
+```
+
+`:visible` fires when the shell first enters the viewport grown by the
+rootMargin, so a margin can load it slightly before it scrolls into view. In an
+engine without `IntersectionObserver` a `:visible` shell materializes right
+after connect, so it still loads, just not lazily.
+
+The shell makes no request on page load and materializes exactly once; the
+real render has no trigger, so later events are no-ops. It carries the
+identity token (no expiry, unlike the defer token), so it works on a page left
+open past `defer_token_ttl`. The framework-owned `__materialize` act rides the
+action endpoint, runs no action, shares the defer endpoint's authorization
+step (registered error → 403, `render?` false → the shell stays), and answers
+403 for any component that isn't `reactive_lazy(on:)`. Like the defer endpoint
+it is a read: it skips `around_actions`, `verify_authorized` and the pgbus
+connection-id scope, so enforce tenant scoping or rate limits in your base
+controller or in the render.
+
+A failed load is not retried on its own. A Turbo morph of the root handles the
+rest: real content morphed back into the shell re-materializes at once (one
+request), and a shell that is still unloaded is re-armed, which is also a
+failed load's retry path. **Give the shell the real root's tag** (`tag: :ul`
+for a `<ul>` root): with the default `<div>` shell on a `<ul>`/`<tr>` root,
+Turbo swaps the node instead of morphing it, and an already-open panel shows
+its skeleton until its event fires again. With matching tags, a page that
+refresh-morphs pays one request per loaded `on:` component per refresh;
+`data-turbo-permanent` on the real root opts it out. See the
+deferred-rendering docs page.
+
+**Reuse across page views** — `cache:` makes the real render a GET the browser
+may keep privately, so a fragment that is the same on every page (a menu, an
+account summary) is not fetched and rendered again on every page view (issue
+#277):
+
+```ruby
+class AccountMenu < ApplicationComponent
+  include Phlex::Reactive::Component
+
+  reactive_lazy cache: { max_age: 10.minutes }   # combine with on: / tag: freely
+
+  def id = "account-menu"
+  def reactive_cache_viewer  = Current.user&.id                   # who this render is for
+  def reactive_cache_version = Current.user&.shortcuts_updated_at # optional: busts the URL
+  def view_template = Current.user.shortcuts.each { |s| a(href: s.url) { s.label } }
+end
+```
+
+The shell carries a stable signed URL (`/reactive/fragment/<signed id>?v=…&u=…`)
+instead of a per-render token; the client GETs it and the endpoint answers
+`Cache-Control: max-age=600, private` with an ETag. With `on:` this is "load on
+first open, reuse across page views" with no app JavaScript, and a refresh morph
+re-materializes from the browser cache instead of costing a request.
+
+The shell stays in the page in the fragment's place: a record-less `on:` +
+`cache:` shell with a viewer and a version is about 290 B gzipped (it carries
+the URL and no token). Defer what is clearly bigger than that — roughly 1 KB
+gzipped or more — or slow to render; a dozen links is cheaper inline. See the
+deferred-rendering page for the numbers.
+
+What keeps a private cache safe:
+
+- **Never `public`.** `max_age` is capped by
+  `Phlex::Reactive.fragment_cache_max_age_limit` (1 hour). Every error — a 4xx,
+  a 204, and anything your base controller answers first (401, a redirect) — is
+  `no-store`.
+- **One viewer's copy never reaches the next.** By default the reply says
+  `Vary: Cookie`, so a copy is reused only while the browser sends identical
+  cookies. Rails' cookie session store issues a new session cookie on every
+  response, so there that means "within one page" (a refresh morph), not across
+  page views. Define `reactive_cache_viewer` to key the URL on the viewer
+  instead: the endpoint re-computes it in the requesting session and makes the
+  reply cacheable only when the URL names that viewer. Return everything the
+  render depends on besides the identity and the version (user, tenant, locale).
+  `u` is an opaque keyed digest. A blank value (`nil`, `false`, `""`, an Array
+  with a blank part) names nobody and is never a shared "anonymous" key: that
+  render falls back to `Vary: Cookie`, so `Current.user&.id` is safe as is.
+  Return a value unique per viewer: it is expanded like a cache key, so `0`,
+  `"0"` and `[0]` are one viewer, and `true` — or an unsaved record — is
+  everyone (return `nil` for guests).
+- **Opt-in only.** The fragment id is MACed under its own purpose: it is not
+  an identity or defer token and those are not fragment ids (400 either way). A
+  component without `cache:` is not reachable over GET (404). The id names no
+  viewer, but it carries the signed state / record GlobalID in a URL — signed,
+  not encrypted, so keep secrets out of `reactive_state`.
+- **A read.** No action, no `around_actions`, no transaction; `v` and `u` only
+  shape the browser's cache key. Authorize in the render, as for any lazy
+  component. A cacheable reply carries no `Set-Cookie`; a request during which
+  any callback (before, around or after) changed the session, set or consumed a
+  flash, minted a CSRF token, or wrote a cookie keeps that write and is answered `no-store` instead —
+  so an app that writes the session on every request (Devise `timeoutable`) gets
+  no caching. Session writes made outside the controller (Rack middleware, a
+  CSP nonce generator that writes the session) are not seen, and are lost on a
+  cacheable reply. The endpoint itself never reads
+  the flash, so a notice waiting for the next page view survives a fragment
+  load. A filter may tighten the policy (`no_store`, `expires_now`, a shorter
+  `max-age`, `must-revalidate`), never loosen it. The ETag is the body only —
+  `etag { }` blocks are not applied.
+- **No CSRF tokens.** A render that embeds a form authenticity token or
+  `csrf_meta_tags` is served `no-store` with a warning rather than cached.
+- **No CSP nonces.** A `nonce="…"` inside a cached fragment is replayed from the
+  cache and will not match the page's.
+- **Nested lazy components render eagerly inside the fragment.** The fragment
+  is a real render, so a `reactive_lazy` child (whatever its own `on:`/`cache:`)
+  renders its template as part of the parent's copy: no expiring defer token,
+  but under the parent's URL, viewer key and `max_age` — so the parent's viewer
+  and version must cover what the child varies on.
+
+With `on:`, a `cache:` component loads on the defer lane rather than the action
+pipeline: `reactive:before-dispatch` still fires and can veto it (a vetoed
+shell, cached or not, ignores later events until the next morph), but a failed
+load emits `reactive:error` (`kind: "defer"`) with a `retry()`. A reply that was
+redirected or is not a turbo-stream is a failed load, never rendered.
+
+Within `max_age` the browser does not ask the server, so a revoked permission
+or a sign-out is not seen until the copy expires: keep `max_age` short for
+sensitive content and send `Clear-Site-Data: "cache"` on sign-out. If you move
+the endpoint (`Phlex::Reactive.fragment_path`), render
+`<meta name="phlex-reactive-fragment-path" content="…">` in your layout's
+`<head>`; without it the client refuses the URL (`reactive:error`), and
+`phlex_reactive:doctor` says so.
+
 > **One edge case:** a `reply.defer(placeholder:)` shell (the action-driven,
 > not page-mount, form) carries no token of its own — the transient directive
 > owns its delivery. If a page is snapshotted by Turbo mid-defer and later
@@ -2258,6 +2806,22 @@ latency, veto a dispatch, or build retry UI **without forking the controller**:
 | `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` |
+| `feature` | a part of the client that loads on demand (a feature module, e.g. the `reactive_persist` drafts) could not be used on this root | `feature`, `phase`, `error`; no `action`, no `retry` |
+
+`feature` only occurs with the opt-in
+[split client](#the-split-client-opt-in-a-smaller-core-features-on-demand):
+the default client has every feature inside its one file. The error carries
+the module's name and a `phase`: `"load"` (the import failed — it stays failed
+until the page is reloaded, because browsers cache a failed module),
+`"timeout"` (not there after 10 s; the root carried on without it, and it
+still connects if it arrives), `"connect"` (it threw while wiring the root) or
+`"detect"`. The root's other behavior keeps working, and the root is marked
+`data-reactive-error="feature"` each time it connects for as long as the page
+lives. What a missing feature costs: without `persist` a form keeps no draft;
+without `defer` a plain `reactive_lazy` shell never loads (its pending marker
+is cleared, so it does not shimmer forever) while a `reactive_lazy(on:)` shell
+still loads through the plain action. The 10 s is
+`<meta name="phlex-reactive-feature-timeout" content="ms">` in `<head>`.
 
 `apply` covers a throw in the controller's own post-fetch code — not a
 throwing listener on `reactive:applied` itself. Per the DOM spec,
@@ -2635,6 +3199,44 @@ bug). It emits:
 3. an inert `reactive:token` refresh, so the container's signed token rolls
    forward and the list is not act-once-only.
 
+#### Honest pending markup: `pending_template` (opt-in)
+
+The markers dim a *live* row. When the pending state should be real markup — a
+"Queued" badge, a button that is genuinely gone rather than hidden by
+`pointer-events: none` — define `pending_template` on the row component (private
+is fine). `reply.pending` then also **replaces** each such row with it, just
+before marking it:
+
+```ruby
+class TransferRow < ApplicationComponent
+  include Phlex::Reactive::Streamable
+  include Phlex::Reactive::Component
+
+  def view_template
+    li(**mix(reactive_attrs, id:)) { span { @transfer.label }; button(**on(:retry)) { "Retry" } }
+  end
+
+  private
+
+  def pending_template
+    li(**mix(reactive_attrs, id:)) { span { @transfer.label }; span(class: "badge") { "Queued" } }
+  end
+end
+```
+
+A row without the hook is byte-identical to the marker-only reply.
+
+- **Keep the root's `id`.** The settle targets it; a `pending_template` without
+  `id="<the row's id>"` raises before anything is enqueued.
+- **Keep `reactive_attrs`** if the row carries its own token — the swapped row
+  signs the row class's real name, so its next action verifies as usual.
+- **Un-pending is the settle's job.** Markers are attributes any settle strips;
+  swapped markup is only undone by a settle that replaces (`s.replace`) or
+  removes (`s.remove`) the row. A flash-only settle, `finish: true`, or a failed job clears the markers
+  but leaves the pending markup in place.
+- It is a *template* method, unlike `deferred_placeholder` (which returns inner
+  content for a shell the gem owns): here the row's own root is swapped.
+
 | `reply.pending(...)` | |
 |---|---|
 | `records` | one record, an enumerable of records, or built Streamable components |
@@ -3294,6 +3896,26 @@ the groups the client cleared by name, without the `[]`, the way a form body
 sends them. **Token minting** —
 `reactive_token_for(component_or_class, payload = {})`.
 
+**System helpers** (`Phlex::Reactive::TestHelpers::System`, Capybara-gated) —
+`wait_for_reactive`, `have_reactive_value`, `have_reactive_text`, and request
+counting: `reset_reactive_requests!` baselines, `have_reactive_requests(n,
+kind: nil)` waits until nothing is in flight and asserts exactly `n` action
+(`kind: :action`) or deferred-render (`kind: :defer`) requests, and
+`reactive_request_count` returns `{ action:, defer: }`. The client keeps the
+totals on `<html data-reactive-requests>` under the verbose gate only. The
+matcher waits for requests in flight, not ones yet to start (a debounced
+trigger, a defer the reply is about to start): wait for the UI outcome first.
+A defer pushed over a pgbus stream makes no request and is not counted. A
+`reactive_lazy cache:` fragment GET counts as `:defer` per `fetch()` call, even
+when the browser cache answers it: assert "no network request" with Resource
+Timing (`transferSize === 0`).
+
+```ruby
+reset_reactive_requests!
+find("#open-panel").click
+expect(page).to have_reactive_requests(1)
+```
+
 > `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.