phlex-reactive 0.9.3 → 0.9.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86eeeabfa81b914dae1f3598e3c879892478c712afc5631b500b96cbd9b83757
-  data.tar.gz: d72882a3b92db0f2d542b5ef457a13f9e74fda538cb3ee5db7d2ac5916833515
+  metadata.gz: 9e6f3431087aff47f32d503174b5242c51af5fce1bbdd7832d40a466a5c3a548
+  data.tar.gz: 7bed02791a8b41163bd7b237aa1bb2730ff99496450783eae712bbcb1ae46052
 SHA512:
-  metadata.gz: 884a4c34c7d26930bea2873bae0cf3a1ec0ff82d796179b01fe493187f8001d36283ea1e22daeaa347ab72ca8e74be31773cbba77bf0db41bb38781eb578c340
-  data.tar.gz: 4b75f6edec65f1d84954260305d384ad6674e21ee3fc5f51270e7055e7679a7d1bb209783d6678b2c506259bf6d1688c6a67c991cc013b22a6f66961bfec84f8
+  metadata.gz: f66d90ab48f9210f0bfddf08f14b2a86593118af903574432592b408920656f3d025cd7a8a067b27faf2c42b8456e8e802caf93980cfa967b3fd69eed0c80646
+  data.tar.gz: 6e449424886a2375fc5b64788077086eb7274536eb72d843c9dc5ee0d107e688f573f1a723a283d806dac2897bf55b9e9f432f472bb157360c7d1931aff6aab3

data/CHANGELOG.md

@@ -6,8 +6,208 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Changed
+
+- **BREAKING: `verify_authorized` is ON by default (#168).** A reactive action
+  that completes **without any authorization call now raises**
+  `Phlex::Reactive::AuthorizationNotVerified` — **rolling back the transaction**
+  (fail-closed, stronger than Pundit's after-the-fact check). This is the
+  presence-side complement to `authorization_errors`: a forgotten `authorize!`
+  becomes a loud 500 your error tracker sees, not a silent hole. The guard
+  detects a call to any `Phlex::Reactive.authorization_methods` name
+  (default `%i[authorize! authorize allowed_to?]` — Pundit/CanCanCan/ActionPolicy)
+  **or** `mark_authorized!`, made anywhere during the action (a helper the action
+  calls counts too). **Three remedies** for each action:
+  1. call your authorization method (`authorize! @record, :update?`);
+  2. call `mark_authorized!` after a bespoke check the interceptor can't see;
+  3. declare `skip_verify_authorized` (whole component) or
+     `skip_verify_authorized :action_name` (specific actions) for an
+     intentionally public action.
+  Turn it off globally with `Phlex::Reactive.verify_authorized = false` (the
+  install-generator initializer documents the knob). The `action.phlex_reactive`
+  instrumentation event gains a new `:unverified` outcome. A new **advisory**
+  doctor check flags mutating actions with no detected authorization call
+  (heuristic — a helper may authorize indirectly; never a hard fail).
+
 ### Added
 
+- **Compound & numeric `reactive_show` predicates — `all:`/`any:` and
+  `gte:`/`gt:`/`lte:`/`lt:` (#176).** Value-conditional visibility now spans
+  **more than one field** and **numeric thresholds**, staying inside the
+  eval-free "declared literal predicate" contract. `all:` / `any:` fold a list of
+  per-field terms (`{ field:, equals:/not:/in:/gte:/… }`) with one fixed
+  connective — AND vs OR over the same literal vocabulary, no expression surface;
+  one flat binding replaces wrapper-div nesting and is the only way to express OR.
+  `gte:`/`gt:`/`lte:`/`lt:` compare `Number(value)` against a literal number baked
+  into the binding (the RHS must be a real `Numeric` — a typo fails at render); a
+  non-numeric field value is `NaN` → hidden, the safe reveal-on-threshold default.
+  Numeric predicates work standalone, as a compound term, and inside a
+  `reactive_show_targets` map. Malformed terms fold **false** (fail-closed:
+  default-deny). The single-field `reactive_show(:field, equals:)` form is
+  unchanged; the additions are backwards compatible.
+
+- **Installable Claude debugging skill + `rails g phlex:reactive:claude` (#168).**
+  The gem ships a `phlex-reactive-debugging` skill (the doctor → inventory → find
+  → browser `report()` → MCP workflow + a failure table) under `lib/`, and the
+  new generator copies it into a host app's `.claude/skills/` and writes the MCP
+  server entry to `.mcp.json` — only when absent (it never rewrites an existing
+  `.mcp.json`; it prints the snippet instead). A new **Debugging & tooling** docs
+  page ties the four surfaces together; the security page documents
+  `verify_authorized`; the instrumentation table gains the `:unverified` outcome;
+  the README gains a Debugging & tooling section + the config rows.
+
+- **On-demand client inspector — `phlex/reactive/inspect` (#168).** A standalone
+  JS module (the `confirm.js`/`compute.js` precedent — **zero hot-path cost**, no
+  edit to `reactive_controller.js`, loaded only when imported) that scans the live
+  DOM and maps every reactive root + bound trigger back to the server
+  `Component#action` names. From the browser console:
+  `(await import("phlex/reactive/inspect")).report()` prints a `console.table` of
+  every reactive root — its `id`, decoded token payload (component class, gid,
+  state keys, token version — try/catch base64+JSON decode, degrading to
+  `{ opaque: true }` on a Marshal-serialized payload), status attrs, triggers
+  (action + event + params + debounce/throttle/confirm), client-only ops,
+  computes, the `name`d fields the dispatch would collect, and the
+  show/filter/text binding families. Triggers are scoped to the **nearest** root,
+  so nested roots aren't double-attributed. The server↔client mapping is
+  by-name: `scan()`'s `component` + trigger `action` strings are exactly the
+  identifiers `phlex_reactive:actions` and the MCP tools list. Pinned by the
+  engine (not preloaded); pure read, never mutates the page.
+
+- **Read-only diagnostic MCP server (#168).** `bin/rails phlex_reactive:mcp`
+  starts a stdio [MCP](https://modelcontextprotocol.io) server exposing five
+  read-only tools — `phlex_reactive_doctor`, `phlex_reactive_components`,
+  `phlex_reactive_actions` (optional `component:` filter), `phlex_reactive_find`
+  (fuzzy search + Prism method source), `phlex_reactive_config` (redacted) — so
+  Claude Code inside a host app can introspect the live reactive registry when
+  debugging. The `mcp` gem is **optional and lazy**: it is NOT a gemspec runtime
+  dependency; `Phlex::Reactive::MCP.load!` requires it on demand with a helpful
+  message when missing (the pgbus pattern), and the gem-dependent tool tree stays
+  out of the Zeitwerk autoloader — a host app without `mcp` boots and eager-loads
+  unaffected. Every tool is read-only and non-destructive (no arbitrary-query or
+  mutation tool) and reports names/paths/schemas only — never a token, secret, or
+  runtime state; `phlex_reactive_config` never emits the verifier or
+  `secret_key_base`. Consumer `.mcp.json`:
+  `{ "mcpServers": { "phlex-reactive": { "command": "bin/rails", "args": ["phlex_reactive:mcp"] } } }`.
+  Known constraint: stdio MCP needs a clean stdout — an initializer that `puts`
+  breaks the transport (same caveat as pgbus).
+
+- **verify_authorized runtime guard (#168).** New
+  `Phlex::Reactive::Authorization` (fiber-local tracking window, method
+  interception, the enforcement decision), `mark_authorized!` instance helper,
+  the `skip_verify_authorized` DSL (registry #6, inherits like the other five),
+  and `Phlex::Reactive.verify_authorized` / `authorization_methods` config
+  (`defined?`-guarded so an explicit override sticks). See the breaking note
+  above for the behavior and remedies.
+
+- **Action inventory — `Phlex::Reactive::Inspector` + rake tasks (#168).** A new
+  read-only introspection layer that answers "what reactive actions exist in this
+  app, where are they defined, and is each authorized?" without grepping.
+  `Phlex::Reactive::Inspector.components` discovers every constant-backed reactive
+  component from the loaded `Streamable` registry; `.find(query)` fuzzy-matches
+  one (exact > prefix > substring > subsequence, on both the demodulized and the
+  full name). Each action reports its declared param schema, `file:line`, the full
+  `def … end` source (extracted with **Prism**, degrading to `nil` on an
+  unreadable/unparseable file — never raising), and a **heuristic** authorization
+  status (a Prism scan for a configured authorization method or
+  `mark_authorized!` in the body — advisory only, since a helper may authorize
+  indirectly). Two shipped rake tasks surface it: `bin/rails
+  phlex_reactive:actions` (plain-text table, `FORMAT=json` for tooling) and
+  `bin/rails "phlex_reactive:find[query]"` (ranked matches; top match in detail
+  with each action's method source). Output is names/paths/schemas only — never
+  tokens, secrets, or runtime state (the instrumentation privacy contract
+  extended to tooling). `Doctor` now delegates its `constant_backed_component?`
+  filter to the Inspector so the endpoint-rebuild predicate lives in one place.
+
+- **Deferred reply segments — `reply.defer` (#165).** An expensive part of a
+  reply (a cross-aggregate rollup, a report) no longer stalls the actor's
+  interaction: `reply.streams(cheap).defer(SessionTotals.new(workout:))`
+  returns the cheap streams immediately and streams the real render to the
+  SAME actor when it finishes. Keep-content default (the stale value stays
+  visible, marked `data-reactive-defer-pending` + `aria-busy` for CSS
+  shimmer); `placeholder: true` / a component swaps a skeleton in;
+  `morph: true` morphs the arrival (the mode rides INSIDE the signed token).
+  Transactional (the directive rides the post-commit reply — a rollback or a
+  denied action leaks nothing), actor-scoped (peers keep `broadcast_*_to`),
+  superseding (a newer action for the same target aborts the in-flight
+  deferred render — no stale paint), and interactive on arrival (fresh action
+  token). Delivery is transport-adaptive (`Phlex::Reactive.defer_transport`,
+  default `:auto`): a parallel fetch to the new `POST /reactive/defer`
+  endpoint everywhere (purpose-scoped, short-TTL defer token —
+  `defer_token_ttl`, default 120s; `reply.defer` tokens are **actor-bound**
+  to the requesting session so a leaked one can't be redeemed elsewhere,
+  `reactive_lazy` shell tokens are unbound by necessity — they render
+  before a session exists — with the TTL + `authorize!` as their bound;
+  never interchangeable with action tokens),
+  or a **durable pgbus one-shot stream + `DeferredRenderJob`** when pgbus's
+  reactive Streams and ActiveJob are present (`defer_job_queue` config; the
+  durable since-id replay closes the broadcast-before-subscribe race, and the
+  broadcast tears down its own subscription). The push lane's one-shot queue is
+  reclaimed by pgbus's age-based orphan-stream sweep (**pgbus ≥ 0.9.10**; run
+  the Dispatcher with `streams_orphan_threshold` set); we never eager-drop it
+  (that would reopen the delivery race). The one-shot key is sized to the live
+  pgbus `queue_prefix` budget, so a non-default prefix can't overflow it; the
+  render job broadcasts a cleanup on ANY failure so the actor's pending state
+  always resolves. Every capability gap degrades to the fetch lane — the
+  Action-Cable-or-pgbus invariant holds. **Profile first:** an app-side N+1
+  looks exactly like framework lag; defer is for segments that are genuinely
+  expensive after the synchronous path is cheap.
+
+- **Lazy initial mount — `reactive_lazy` (#165).** The same machinery for the
+  FIRST render (Livewire `#[Lazy]`): the page ships the component's
+  placeholder shell (`deferred_placeholder`, or a built-in pending shell) with
+  the defer token on the root; the client fetches the real content on connect
+  AND after a Turbo page-refresh morph (so a lazy component survives a
+  `turbo:reload`). `reactive_lazy tag: :tr` (etc.) ships a shell element that
+  matches a `<tr>`/`<li>` root instead of an invalid `<div>`.
+  Reactive-machinery renders (an action's self-replace, broadcasts, the defer
+  endpoint/job) stay REAL, so actions never pay two round trips.
+
+- **pgbus capability gates.** `Phlex::Reactive.pgbus?` and `.pgbus_streams?`
+  (the documented broadcast-accepts-`:exclude` probe, now actually
+  implemented) plus `.defer_push_capable?` for the defer push lane.
+
+- **Client-side option filtering — `reactive_filter` (#163).** The other half
+  of #72's combobox: **preload the options, type to narrow — zero round
+  trips.** Spread `reactive_filter(input:, option:, group:, empty:)` onto the
+  root and the generic controller shows/hides each option on every keystroke by
+  a case-folded substring match against its `data-reactive-filter-text`
+  haystack (falling back to the option's own text) — no POST, no token, no
+  bespoke per-feature Stimulus controller. Optional `group:` collapses a header
+  whose every contained option is hidden; optional `empty:` reveals a
+  no-matches node at 0 visible. Selectors resolve within the root only (nested
+  reactive roots untouched), state seeds at connect and re-applies after a
+  morph, and blank selectors raise at render (a dead binding must fail loudly).
+  Composes with keyboard nav and per-row selection: a filtered-out option also
+  drops out of the Arrow-key path and loses its highlight, so Enter can never
+  pick an invisible row — selection itself stays a signed `on(:select)` action.
+- **Standalone combobox keyboard nav — `reactive_listnav` (#163).** The same
+  Arrow/Enter/Escape wiring `on(…, listnav:)` appends, without the dispatch
+  descriptor — for the preload-and-filter input that fires **no** action (an
+  `on()` trigger would POST per keystroke). Spread
+  `reactive_listnav("[role=option]")` onto the input; Enter still picks by
+  clicking the highlighted option's own signed trigger.
+- **Cross-root `reactive_show` targets — `reactive_show_targets` (#164).** A
+  field can now drive the visibility of declared elements **outside** its
+  reactive root — the nav tab, the panel in another tab pane, the sidebar note
+  a mode selector governs — the visibility parallel to the #159 cross-root
+  text mirror. The component that **owns** the field declares which outside
+  ids it governs, spread on the root:
+  `mix(reactive_root, reactive_show_targets(:mode, "#advanced-tab" =>
+  { equals: "advanced" }, "#basic-note" => { not: "advanced" }))`. Same
+  posture as `mirror:`: opt-in and declared, never implicit (a plain
+  `reactive_show` stays root-isolated, #15 untouched); targets are **single id
+  selectors only** — a class/compound selector raises at declare time AND is
+  warn-and-skipped by the client (two-sided default-deny); the predicate is
+  the same literal-only `reactive_show` vocabulary; the toggle is `hidden`
+  only. The field read stays **owned** — you can only drive outside visibility
+  from a field the declaring root owns. A target id not on the page is
+  silently skipped (an unrendered tab pane is normal); the cross-root pass
+  shares the owned-binding pass's field-read memo (one read per field per
+  sync). No map declared → one `getAttribute` and out. **One call per root**:
+  Phlex `mix` space-joins duplicate string data values, so a second call's
+  JSON would corrupt the attr (the client warns and ignores it) — several
+  fields go in one call via the hash form
+  (`reactive_show_targets(mode: { … }, kind: { … })`).
 - **Value-conditional visibility — `reactive_show` (#161).** The `x-show` /
   `data-show` / `wire:show` case — show/hide an element from a form field's
   **current value** — no longer needs a hand-written `change`-listener Stimulus
@@ -45,6 +245,18 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
     can opt out of the reply's target-root scope to document-wide resolution
     (previously it was silently ignored when a `target` was set).
 
+### Performance
+
+- The defer machinery adds nothing measurable to the existing hot paths
+  (same-machine, same-checkout before/after vs `main`): `to_stream_replace`
+  14.4k → 14.2k i/s (within ±3.7% noise), identity token 199.9k → 196.7k i/s
+  (state-backed) / 93.7k → 93.5k (record-backed), allocations byte-identical.
+  New `benchmark/micro/defer_token.rb`: `sign_defer` ~120k i/s, `verify_defer`
+  ~99k i/s, full fetch-lane directive build ~11 µs/segment, 0 retained. Defer
+  is a **latency-shape** change, not a throughput one — the A/B spec
+  (`spec/requests/deferred_latency_spec.rb`) pins that a 120 ms segment cost
+  moves OFF the actor's reply and onto the deferred leg; it never disappears.
+
 ## [0.9.0] - 2026-07-03
 
 Consolidates everything since 0.2.6; tags 0.2.7–0.4.8 shipped without changelog

data/README.md

@@ -189,6 +189,33 @@ If reactive elements are on the page but the controller never connected, the
 runtime logs a console warning (`[phlex-reactive] found N element(s) with
 data-controller="reactive" but the reactive controller never connected …`).
 
+### Debugging & tooling
+
+Four read-only introspection surfaces answer "what's reactive, where is it
+defined, is it authorized, and what does this page POST?" — plus an installable
+Claude Code toolkit. See the [Debugging & tooling
+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:find[counter]" # fuzzy-find one; prints each action's method source
+bin/rails phlex_reactive:mcp             # a read-only MCP server (needs `gem "mcp"`)
+```
+
+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):
+
+```js
+(await import("phlex/reactive/inspect")).report()
+```
+
+Install the debugging skill + MCP config for Claude Code in one command:
+
+```bash
+rails g phlex:reactive:claude
+```
+
 ---
 
 ## The mental model in one picture
@@ -339,6 +366,8 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 | `reactive_record :name` | Record-backed identity (GlobalID). State = the DB. Also defaults `#id` to `dom_id(record)`. |
 | `reactive_state :a, :b` | Signed instance-var identity. Standalone, or combined with `reactive_record` to sign transient UI state alongside the row. |
 | `action :name, params: { x: :integer }` | Declare a client-invokable action + its param schema. **Default-deny.** |
+| `mark_authorized!` | Inside an action: satisfy the `verify_authorized` guard after a bespoke check the interceptor can't see (a hand-rolled policy). Call it only after your check passes. |
+| `skip_verify_authorized [ :a, :b ]` | Opt a component (bare) or specific actions out of the default-ON `verify_authorized` guard — for a genuinely public component (a counter, a client-only filter). |
 | `reactive_root(**overrides)` | Spread onto the root element: emits the component `id` **and** `reactive_attrs` together, so the controller root always carries `#id`. Preferred over `id:` + `reactive_attrs`. `**overrides` (`class:`/`data:`) deep-merge. |
 | `reactive_attrs` | Marks an element reactive + carries the signed token (no `id`). Spread alongside `id:` on the **same** element: `div(id:, **reactive_attrs)`. Prefer `reactive_root`, which can't split them. |
 | `on(:action, event: "click", **params)` | Spread onto a trigger element. Adds `type=button` for clicks. |
@@ -359,6 +388,9 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 | `reactive_field(:param, **attrs)` | The attribute hash behind the above — spread onto any control. |
 | `reactive_text(:name, initial)` | Mirror a compute output (or a declared input) into a **text node** — a live preview heading, a character counter, `"Hello, {name}"` — via `textContent` (XSS-safe). The text sibling of `reactive_field`; carries no `name`, so it's never POSTed. See [Client-side computes](#client-side-computes-reactive_compute--reactive_text). |
 | `reactive_show(:field, equals:/not:/in:)` | **Value-conditional visibility** (the `x-show`/`data-show` case): spread onto the element to show/hide — it toggles `hidden` from the named field's **current value**, client-only, zero round trip. One literal predicate: `equals:`, `not:`, or `in: [...]`; `equals: true` reads a checkbox's checked state. See [Value-conditional visibility](#value-conditional-visibility-reactive_show). |
+| `reactive_show_targets(:field, "#id" => { equals: … })` | **Cross-root visibility**: the component that owns the field declares which **outside**, id-allowlisted elements it governs (a nav tab, a panel in another pane) — the visibility parallel of `mirror:`. Spread on the **root** via `mix(reactive_root, …)`, **once per root** — several fields go in one call via the hash form (`reactive_show_targets(mode: { … }, kind: { … })`). Id selectors only (raise at render + client warn-skip); same literal predicates; toggles `hidden` only. See [Value-conditional visibility](#value-conditional-visibility-reactive_show). |
+| `reactive_filter(input:, option:, group: nil, empty: nil)` | **Client-side option filtering** for a preloaded combobox: spread onto the root — typing in the named input shows/hides the options by their `data-reactive-filter-text` haystack, **zero round trips**. Optional `group:` collapses an all-hidden group header; `empty:` reveals a no-matches node. See [Client-side option filtering](#client-side-option-filtering-reactive_filter). |
+| `reactive_listnav("[role=option]")` | The **standalone** combobox keyboard wiring (Arrow/Enter/Escape) for an input that fires **no action** — the preload-and-filter case. Same behavior as `on(…, listnav:)`, minus the POST. |
 | `reactive_compute :name, inputs: { title: :string, qty: :number }, outputs:` | **Typed** inputs: a `:string` reaches the JS reducer raw, a `:number` is coerced through `Number`. The array form (`inputs: %i[a b]`) stays all-numeric. |
 | `reactive_compute :name, ..., mirror: { sum: "#summary-sum" }` | **Cross-root text mirrors**: paint a compute value into declared, id-allowlisted nodes **outside** the reactive root (a recap in another tab pane) via `textContent` — no bespoke listener. See [Cross-root mirrors](#cross-root-mirrors-mirror--painting-a-recap-outside-the-root). |
 | `reactive_root(track_dirty: true, warn_unsaved: true)` / `reactive_field(:param, dirty: true)` | **Dirty tracking** against the DOM's own `defaultValue`/`defaultChecked`/`defaultSelected` — no client state. Marks changed fields + the root `data-reactive-dirty`; `warn_unsaved:` arms a `beforeunload`/`turbo:before-visit` guard. Style with `[data-reactive-dirty]`. See [Dirty-field tracking](#dirty-field-tracking-dirty--track_dirty--warn_unsaved). |
@@ -905,7 +937,45 @@ end
   real `input` event, so a *derived* value can drive visibility too.
 - Presentational only, strictly weaker than the js ops: it reads an owned
   field and toggles `hidden` on an owned element — no `innerHTML`, no
-  attribute freedom, no cross-root writes.
+  attribute freedom. Cross-root writes take the **declared** escape below.
+
+**Cross-root targets (`reactive_show_targets`).** A plain `reactive_show` is
+root-scoped by design — but "a mode selector reveals dependent sections
+elsewhere on the page" (a nav tab, a panel in a *different* tab pane, a sticky
+sidebar note) routinely puts the dependents **outside** the control's root.
+`reactive_show_targets` is the declared escape, the visibility parallel of the
+[cross-root text mirror](#cross-root-mirrors-mirror--painting-a-recap-outside-the-root):
+the component that **owns** the field declares which outside ids it governs,
+spread on the **root**:
+
+```ruby
+div(**mix(reactive_root, reactive_show_targets(:mode,
+  "#advanced-tab"   => { equals: "advanced" },
+  "#advanced-panel" => { equals: "advanced" },
+  "#basic-note"     => { not: "advanced" }))) do
+  select(name: "mode") { mode_options }
+  # …
+end
+```
+
+Same posture as `mirror:`: **opt-in and declared, never implicit** — a plain
+`reactive_show` stays root-isolated; targets are **single id selectors only**
+(a class/compound selector raises at render AND is warn-and-skipped by the
+client — two-sided default-deny); the predicate is the same literal-only
+vocabulary; and the toggle is `hidden` only. The field read stays **owned** —
+you can only drive outside visibility from a field the declaring root owns. A
+target id not on the page is silently skipped, so a target inside an
+unrendered tab pane is fine.
+
+**One call per root.** Phlex `mix` space-joins duplicate string `data:`
+values, so a *second* `reactive_show_targets` call on the same root would
+concatenate two JSON payloads into an unparseable attribute (the client warns
+and ignores it). Several fields go in **one call** via the hash form:
+
+```ruby
+reactive_show_targets(mode: { "#advanced-tab" => { equals: "advanced" } },
+                      kind: { "#premium-note" => { not: "basic" } })
+```
 
 ### Client-side computes (`reactive_compute` + `reactive_text`)
 
@@ -1023,6 +1093,58 @@ Enter **clicks the highlighted option** — so selection runs through its normal
 Escape clears the highlight. Only the highlight is client-side — the selection
 stays a real signed action, and the highlight is never shipped as trusted state.
 
+### Client-side option filtering (`reactive_filter`)
+
+`listnav:` is the keyboard half of a combobox; `reactive_filter` is the other
+half: **preload the options, type to narrow — zero round trips.** For a small,
+static catalog a server search per keystroke is pure latency (the data was
+already known at first paint), and a bespoke hide/show Stimulus controller is
+exactly the per-feature JS this gem exists to remove. Declare the filter on the
+root instead:
+
+```ruby
+div(**mix(reactive_root, reactive_filter(
+  input:  "#exercise-search",       # the input whose value drives the filter
+  option: "[role=option]",          # the elements to show/hide
+  group:  "[data-filter-group]",    # optional: collapse a header when all its options hide
+  empty:  "#no-matches"             # optional: reveal when 0 options match
+))) do
+  # STANDALONE keyboard nav — no action on the input, so typing never POSTs.
+  input(id: "exercise-search", type: "search", **reactive_listnav("[role=option]"))
+
+  categories.each do |category, exercises|
+    div(data: { filter_group: "" }) do
+      h3 { category }
+      exercises.each do |exercise|
+        # The haystack is server-rendered — pack in synonyms/categories.
+        button(**mix(
+          on(:select, id: exercise.id),
+          role: "option",
+          data: { reactive_filter_text: exercise.search_text }
+        )) { exercise.name }
+      end
+    end
+  end
+
+  div(id: "no-matches", hidden: true) { "No matches" }
+end
+```
+
+On every keystroke the generic controller lowercases the input's value and
+toggles `hidden` on each option by a **substring match** against its
+`data-reactive-filter-text` haystack (falling back to the option's own text) —
+a declared literal match, never an expression, so there is no eval surface. A
+group whose every contained option is hidden collapses with them; the empty
+node reveals at 0 visible. Everything resolves **within this root only** and
+re-applies after a morph.
+
+It composes: `reactive_listnav` gives the input Arrow/Enter/Escape **without an
+action** (Arrow keys skip filtered-out options; `on(…, listnav:)` requires a
+dispatching trigger — wrong for an input that must never POST), and each option
+stays its own signed `on(:select)` trigger. Only *filtering* is client-side —
+selection still round-trips as a real signed action. Blank selectors raise at
+render: a dead binding must fail loudly, not no-op in the browser.
+
 **Combining `on(...)` / `reactive_attrs` with your own attributes.** Both return
 a hash that includes a `data:` key. Spreading them *and* passing another `data:`
 (or `class:`, `id:`) would clobber it — use Phlex's `mix` to deep-merge. For the
@@ -1169,6 +1291,7 @@ def update(quantity:, price:) = (@item.update!(quantity:, price:); reply.streams
 | `reply.redirect(url)` | client-side `Turbo.visit` (pass a `*_url`); rides a `reactive:visit` turbo-stream, not an HTTP 3xx |
 | `reply.streams(*streams)` | **partial update** — emit exactly these streams (no full-self replace) + a tiny token-only refresh, so live inputs survive; for per-field grid editing (issue #30) |
 | `.js(ops, target: …)` | also push **client DOM ops** (focus, dispatch, class/attr toggles) over a `reactive:js` stream, applied AFTER the render — `reply.morph.js(js.focus("[name=next]"))` focuses the morphed field (issue #97) |
+| `.defer(component, placeholder:, morph:)` | take an **expensive segment off the actor's critical path** (issue #165) — the reply returns immediately and the real render streams to the SAME actor when ready; see [Deferred segments](#deferred-segments-replydefer--reactive_lazy) |
 | `reply.with(*streams)` / `#stream(*more)` | multi-stream (self re-render still injected for the token) |
 
 `.flash`/`.stream`/`.also_*` are additive on a self-replace, so the component's
@@ -1178,6 +1301,155 @@ update only the targets you name) and refreshes the token via a tiny inert
 `reactive:token` stream instead — the token rolls forward without re-rendering
 (and clobbering) the component's live inputs.
 
+#### Deferred segments (`reply.defer` + `reactive_lazy`)
+
+> **Profile first.** An app-side N+1 or a missing eager-load *looks exactly
+> like framework lag* — a scoreboard re-rendering on every debounced keystroke
+> once "felt slow" here, and the real cause was `2 + N` queries per keystroke,
+> fixed with one eager load and no gem change. Make the synchronous path cheap
+> before you make it async; reach for `defer` only when a reply segment is
+> **genuinely** expensive (a cross-aggregate rollup, a report, an external call).
+
+Everything in a `reply` renders synchronously on the request thread, so one
+expensive segment stalls the actor's whole interaction. `reply.defer` takes it
+off the critical path — the actor's reply returns immediately and the real
+HTML streams to **that same actor** the moment the render finishes:
+
+```ruby
+action :update, params: { weight_kg: :float, reps: :integer, rpe: :float }
+def update(weight_kg:, reps:, rpe:)
+  authorize! @set, :update?
+  @set.update!(weight_kg:, reps:, rpe:)
+
+  reply
+    .streams(volume_cell_stream)                  # instant, cheap — synchronous
+    .defer(SessionTotals.new(workout: @workout))  # expensive — deferred
+end
+```
+
+Be honest about the trade: **defer improves the actor's reply latency and makes
+time-to-full-content slightly worse** (one extra hop). It moves cost off the
+critical path; it never removes it.
+
+While the deferred render is pending, the target keeps its current (stale)
+content and carries `data-reactive-defer-pending` + `aria-busy` — style the
+window in pure CSS:
+
+```css
+[data-reactive-defer-pending] { opacity: .5; }
+```
+
+Options:
+
+```ruby
+reply.defer(comp)                             # keep-content default (above)
+reply.defer(comp, placeholder: true)          # comp's deferred_placeholder, or a built-in shell
+reply.defer(comp, placeholder: Skeleton.new)  # explicit skeleton (component, or an html_safe string)
+reply.defer(comp, morph: true)                # arrival morphs in place (mode rides INSIDE the signed token)
+```
+
+`deferred_placeholder` (optional, on the deferred component) returns a Phlex
+component instance, an `html_safe` string, or a plain string (escaped — data,
+not markup).
+
+Semantics you can rely on:
+
+- **Transactional** — the directive rides the reply, which only renders after
+  the action's transaction committed; a rollback or a denied action leaks no
+  deferred render (and enqueues no job).
+- **Actor-scoped** — the deferred render reaches only the actor; peers keep
+  getting updates via `broadcast_*_to` (use both when both need the value).
+- **Superseding** — a newer action for the same target aborts the in-flight
+  deferred render; a fast typist never gets stale totals painted over fresh ones.
+- **Interactive on arrival** — the streamed root carries a fresh action token.
+- **Failure-visible** — a failed deferred fetch clears the pending state, sets
+  `data-reactive-error="defer"`, and emits `reactive:error` with a `retry()`;
+  `render?` false resolves to a 204 (pending cleared, content kept).
+
+**Delivery** is transport-adaptive (`Phlex::Reactive.defer_transport`, default
+`:auto`): a parallel authenticated fetch to `POST /reactive/defer` everywhere
+(carrying a purpose-scoped, short-TTL signed identity token —
+`defer_token_ttl`, default 120s; an action token is rejected at the defer
+endpoint and vice versa), or — when pgbus's reactive Streams **and** ActiveJob
+are present — a **durable one-shot pgbus stream** rendered by
+`Phlex::Reactive::DeferredRenderJob` off the request thread
+(`defer_job_queue` config; the durable replay closes the
+broadcast-before-subscribe race). `:fetch` forces the fetch lane; `:stream`
+requests push and degrades to fetch with a warning when the capability is
+absent. Both lanes are invisible to your action code.
+
+> **The push lane's queue lifecycle.** Each deferred segment on the push lane
+> mints a durable one-shot pgbus stream. Its queue is reclaimed by pgbus's
+> **age-based orphan-stream sweep** (pgbus **≥ 0.9.10**) — ensure the pgbus
+> **Dispatcher is running** with `streams_orphan_threshold` set (its default).
+> We do **not** drop the queue from the render job: an eager drop would destroy
+> a not-yet-consumed message and reopen the very broadcast-before-subscribe race
+> the durable lane exists to close. On pgbus ≤ 0.9.9 the sweep only reaped
+> *empty* queues (which a durable stream never becomes), so a one-shot queue
+> leaked — upgrade to ≥ 0.9.10, or stay on the pull lane
+> (`defer_transport = :fetch`, the universal default, which needs no cleanup).
+
+**Security of the defer token.** The defer endpoint re-renders the real
+component, whose fresh root carries a normal (non-expiring) action token — so a
+defer token is, within its TTL, a render of that identity and a path to that
+identity's action token. What bounds the damage in every case: **the signature
+proves identity, not permission** — the harvested action token is useless
+against `authorize!` in the action, which re-checks the *current* actor.
+Authorize every mutating action; the token, defer or otherwise, is never the
+authority.
+
+The two defer-token channels are bound differently, by their leak surface:
+
+- **`reply.defer` tokens** ride an **action's HTTP response** (which can transit
+  a logging proxy, a shared HAR, an APM that captures bodies) — the real
+  cross-infrastructure leak vector. They are **actor-bound**: signed under the
+  requesting session (`Phlex::Reactive.defer_binding_for(request)`, the
+  persisted session id by default — override to bind to your own actor identity,
+  e.g. a user id), so a leaked one can't be redeemed in another session.
+- **`reactive_lazy` shell tokens** live in the **page HTML the actor already
+  fetched** over their own session (a small leak surface) — and *can't* be
+  actor-bound anyway, because the shell renders on a fresh visit before the
+  session exists (Rails establishes it during that response). They are minted
+  **unbound**; the TTL + `authorize!` are their bound.
+
+Apps with no persisted session (the `ActionController::Base` default, a
+token-auth API) mint every defer token unbound — there too the TTL +
+`authorize!` are the whole bound. Set `Phlex::Reactive.base_controller_name` to
+a session-bearing controller, or override `defer_binding_for`, to bind
+`reply.defer` tokens to your actor identity.
+
+**Lazy initial mount** — the same machinery for the *first* render
+(Livewire's `#[Lazy]`): declare `reactive_lazy` and the page ships the
+placeholder shell; the client fetches the real content on connect. Every
+reactive-machinery render (an action's self-replace, broadcasts, the defer
+endpoint) stays REAL, so actions never pay two round trips:
+
+```ruby
+class SessionTotals < ApplicationComponent
+  include Phlex::Reactive::Component
+
+  reactive_record :workout
+  reactive_lazy                       # first render = placeholder shell
+  # reactive_lazy tag: :tr            # for a <tr>/<li> root the shell must match
+
+  def deferred_placeholder = TotalsSkeleton.new   # optional
+end
+```
+
+The lazy shell's `<div>` root would be invalid inside `<tbody>`/`<ul>`, so a
+component whose real root is a `<tr>`/`<li>` sets `reactive_lazy tag: :tr` (etc.)
+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`.
+
+> **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
+> restored from cache, that placeholder can appear stuck (the directive that
+> would have filled it is long gone). It self-corrects on the next action;
+> deferred **content** is never lost server-side. Lazy mounts (which carry the
+> token on the shell) don't have this — they re-fetch on restore.
+
 #### Flash levels
 
 The level reaches the wire (issue #77). **String** content is wrapped in a
@@ -1597,6 +1869,14 @@ Phlex::Reactive.base_controller_name = "ApplicationController"
 Phlex::Reactive.authorization_errors = [Pundit::NotAuthorizedError]
 # or: [ActionPolicy::Unauthorized]
 
+# verify_authorized (ON by default): an action that authorizes NOTHING raises
+# AuthorizationNotVerified inside the transaction (the mutation rolls back —
+# fail-closed). Satisfy it by calling one of authorization_methods, calling
+# mark_authorized! after a bespoke check, or declaring skip_verify_authorized on
+# a genuinely public component/action. Set the method names to match your library:
+Phlex::Reactive.authorization_methods = %i[authorize! authorize allowed_to?]
+# Phlex::Reactive.verify_authorized = false   # turn the guard off (not recommended)
+
 # Use your ApplicationController to render components (app helpers / Current):
 Phlex::Reactive.renderer = ApplicationController
 
@@ -1871,7 +2151,7 @@ events, all under the `phlex_reactive` namespace:
 
 | Event | Fires | Payload |
 |-------|-------|---------|
-| `action.phlex_reactive` | once per request | `component`, `action`, `outcome` (`ok`/`denied_undeclared`/`invalid_token`/`not_found`/`unauthorized`) |
+| `action.phlex_reactive` | once per request | `component`, `action`, `outcome` (`ok`/`denied_undeclared`/`invalid_token`/`not_found`/`unauthorized`/`unverified`) |
 | `render.phlex_reactive` | per component render | `component`, `bytesize` |
 | `broadcast.phlex_reactive` | per `broadcast_*_to` (Action Cable **and** pgbus) | `component`, `stream_action`, `streamables` |