phlex-reactive 0.11.4 → 0.11.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dec3134e528500e32143217e96b93da16da30322cdf883017db367f645ab1c7d
-  data.tar.gz: ff6d5f992ea6cb7a5558a447f4256b9885170e4e27e1171c62ecf9c92ac221f6
+  metadata.gz: 5c5d8ca344fdd9583bd79ad6e9b162c7a1888d48055dfb36474a3cbc6caf10fe
+  data.tar.gz: c903ed3e437da570c06924055d0e1ad1c9c611c0086431ae8c7d38fc000f8337
 SHA512:
-  metadata.gz: 8952c2437efb9f8d3d8dafd86c2a09658a178ed657e2e4c632a45bc3be17f965f38d518348dd4b8c17609e7937a1793474b40e68db208cec83ef6f50ce28e4c3
-  data.tar.gz: aaddf4f15bd7aa7da26f74e4aca681e4c07c0c3baee62bb9107baf8ea5ab5e244a80b84baeec14fdad79935bede5bb0cf00d7796d4c82eac0f01ace5f916371a
+  metadata.gz: 749fdfd67d453f51c527eb8e058e5b062d04431d3f099aa35a8b9135a38bd2fdc7baa7251eb0ed7d25775bcb6be7f3370958301a0838d89d7893a37f6dd1306b
+  data.tar.gz: 6322de1f369d12c6aff0f187749d4a2f6f090939cce2fb4f4389c9b1a6b7ff1cce3de7d90b4b969706c0997c5d481d8816f45d728dded107445a7455a337f640

data/CHANGELOG.md

@@ -8,6 +8,85 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **Multi-field cross-root targets — `reactive_show_targets` speaks the full
+  conditions language (#209).** A `"#id"` KEY now takes an `if:`/`if_any:`/
+  `unless:` conditions Hash, so an OUTSIDE element can show/hide from a
+  COMBINATION of owned fields — `reactive_show_targets("#trade-warning" =>
+  { if: { type: "trade", price: ..0 } })` — the last case that forced a
+  bespoke two-field JS listener on otherwise-declarative forms. The client
+  folds the target's DNF payload with the SAME per-term owned-field reads as
+  an in-root `reactive_show` (missing owned field reads blank, fail-closed);
+  a target whose referenced fields are ALL unowned is left alone (the
+  single-field skip, generalized). Target-keyed and field-keyed entries mix
+  in the ONE call per root (a field name may never start with `#`, so the
+  key routes unambiguously); existing field-keyed calls emit a byte-identical
+  wire. Declare-time validation stays loud: a bare value, unknown keys, or an
+  empty conditions Hash under a `"#id"` key raises a guided `ArgumentError`.
+
+- **JSON mode for draft nested rows — `reactive_nested_list(:assoc, as: :json)` (#208).**
+  The draft-rows primitive (#208) posts standard Rails
+  `accepts_nested_attributes_for` names. But many apps persist a "new parent +
+  child rows" form by serializing the rows into ONE hidden field and
+  `JSON.parse`-ing it in the controller — adopting the primitive meant rewiring
+  that persistence path. `as: :json` removes the choice: the list keeps the same
+  `<template>` row, `nested_field_name`, and add/remove triggers, but the generic
+  controller now mirrors the surviving rows into a single hidden field as a JSON
+  array on every add / remove / keystroke (the set-value + dispatch contract, so
+  dirty tracking and compute still see it), inferring each JSON key from the
+  trailing bracket segment of a row input's name
+  (`order[line_items_attributes][3][quantity]` → `"quantity"`). A removed row
+  leaves the array (an absent row IS the removal — JSON has no `_destroy`
+  marker). The default (`:attributes`) is unchanged, so existing draft forms are
+  byte-identical. See the "Draft rows for a new parent" README section and the
+  `/docs/example-draft-rows` page.
+
+- **Turnkey APM adapters — `Phlex::Reactive.apm = :appsignal` (#207).** The gem
+  already emits `*.phlex_reactive` `ActiveSupport::Notifications` events (#107), but
+  every reactive action still POSTs to the same endpoint, so an APM rolled all
+  reactive traffic into one blurry `ActionsController#create` transaction and an
+  action-body crash surfaced as an anonymous 500. One config line closes both gaps:
+  - **`Phlex::Reactive.apm = :appsignal` (or `:sentry`, `:datadog`, or a custom
+    object)** names each action as its own `Component#action` transaction/span in the
+    APM, tagged with the component, action, and outcome. The vendor SDK is
+    **runtime-detected** (`defined?(::Appsignal)` …) — never a gemspec dependency, the
+    same optionality invariant as pgbus — so a set-but-absent SDK logs one warning and
+    no-ops. A custom object need only respond to `record_action(payload, duration_ms)`
+    and `record_error(error, payload)`.
+  - **Action-body errors are reported with context.** A previously-uncaught error from
+    an action body (a genuine 500, not a registered 4xx) is now OBSERVED at the
+    endpoint: the `action.phlex_reactive` event is tagged `outcome: :error` (filling the
+    #107 nil-outcome gap), the exception is reported to the APM adapter AND every
+    registered `Phlex::Reactive.on_action_error { |error, ctx| … }` hook WITH the
+    name-only `{ component:, action: }` context, the `error_flash` renders so the actor
+    sees a flash on a crash (500s now flow through the same path the 4xx errors used) —
+    and THEN the error is **re-raised unchanged**, so Rails' own error reporting and the
+    app's middleware fire exactly as before. Each reporter is isolated: a broken reporter
+    (or a raising `error_flash` lambda) can never turn one 500 into a different 500 or
+    swallow the original. The status never changes; the existing 4xx rescues, their
+    statuses, and their outcomes (`invalid_token`/`denied_undeclared`/`not_found`/
+    `unauthorized`/`unverified`) are untouched. Payloads and error tags stay name-only —
+    never the token, params, or state.
+
+- **Draft nested-attribute rows — the "new parent + child rows" form (#208).**
+  A collection whose PARENT isn't persisted yet (a new order accumulating line
+  items) can't be a reactive collection — an unsaved parent has no gid to sign.
+  The pre-save window is now a client-side primitive, the `reactive_tags`
+  posture: `reactive_nested_list(:assoc)` / `reactive_nested_template(:assoc)`
+  mark the container + the server-owned `<template>` holding ONE row's markup;
+  `reactive_nested_add(:assoc)` clones it, swapping every `NEW_ROW` placeholder
+  in the clone's `name`/`id`/`for` for a fresh unique index (clock-seeded
+  monotonic — server-rendered `0..n` and same-millisecond double clicks can't
+  collide) and focusing the new row's first field; `reactive_nested_remove`
+  deletes a draft row from the DOM, or `_destroy`-marks + hides a row carrying
+  a hidden `[_destroy]` input (an edit form's persisted row) so Rails destroys
+  it on save. `nested_field_name(:assoc, :field, index:)` builds the
+  scope-aware Rails wire name (`order[line_items_attributes][i][quantity]`).
+  Zero round trips, no token (works in a `ClientBindings` component); the REAL
+  form submit reconciles parent + rows in ONE request via
+  `accepts_nested_attributes_for`. Several collections can share a root
+  (association-keyed); the row markup is authored ONCE and serves the template,
+  server-rendered edit rows, and the persisted `reactive_collection` flow.
+
 - **`reactive_tags` — the tag-chip input primitive (#203).** The composed
   combobox/tags widget (preload suggestions, type to narrow, Enter/click to add,
   remove chips) with zero bespoke JavaScript and zero round trips. The value is
@@ -67,6 +146,16 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixed
 
+- **A draft (unsaved-parent) token can now round-trip real server actions (#208).**
+  `Component::Identity` already signed a gid-less `{c, state}` token for an
+  unpersisted (or nil) record, but `from_identity` still `fetch`ed the absent
+  `gid` — the FIRST action against a draft crashed with an uncaught `KeyError`
+  (500). It now rebuilds through the record kwarg's **initialize default**
+  (e.g. `def initialize(order: Order.new, …)`), with the declared
+  `reactive_state` riding the token as before; a component whose initialize
+  REQUIRES the record kwarg raises a guided `Phlex::Reactive::Error` naming the
+  fix instead of a bare missing-keyword `ArgumentError`.
+
 - **`have_reactive_value` now reads the field's `.value` property, so it can verify a
   reducer-set disabled/computed field (#204).** The matcher (added in #201) delegated to
   Capybara's `have_field(with:)`, which matches the value **attribute** — but a

data/README.md

@@ -387,7 +387,7 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 | `reactive_field(:param, **attrs)` | The attribute hash that binds a control to an action param (no magic `name:`) — spread onto any control: `input(**reactive_field(:value, value: @record.name))`, `select(**reactive_field(:status)) { … }`. |
 | `reactive_text(:name, initial)` | Mirror a compute output (or a declared input) into a **text node** — a live preview heading, a character counter, `"Hello, {name}"` — via `textContent` (XSS-safe). The text sibling of `reactive_field`; carries no `name`, so it's never POSTed. See [Client-side computes](#client-side-computes-reactive_compute--reactive_text). |
 | `reactive_show(if:/if_any:/unless:)` | **Value-conditional visibility** (the `x-show`/`data-show` case): spread onto the element to show/hide — it toggles `hidden` from the fields' **current values**, client-only, zero round trip. One conditions language: a **Hash is an AND**, an **Array is membership**, a **Range is a threshold**, `if_any:` is OR-of-AND, `unless:` negates. `reactive_values` computes first paint; `disable:` disables a hidden section's controls. See [Value-conditional visibility](#value-conditional-visibility-reactive_show). |
-| `reactive_show_targets(:field, "#id" => value)` | **Cross-root visibility**: the component that owns the field declares which **outside**, id-allowlisted elements it governs (a nav tab, a panel in another pane) — the visibility parallel of `mirror:`. Spread on the **root** via `mix(reactive_root, …)`, **once per root** — several fields go in one call via the hash form. The value uses the same `where`-style vocabulary (`"advanced"`, `%w[a b]`, `10..`). Id selectors only (raise at render + client warn-skip); toggles `hidden` only. See [Value-conditional visibility](#value-conditional-visibility-reactive_show). |
+| `reactive_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_filter(:field, option: nil, group: nil, empty: nil)` | **Client-side option filtering** for a preloaded combobox: spread onto the root and name the **field** that drives it — `reactive_filter(:q)` compiles `:q` to `[name="q"]` (scope-aware) and typing shows/hides the options by their `data-reactive-filter-text` haystack, **zero round trips**. `option:` defaults to `[role=option]`; optional `group:` collapses an all-hidden group header; `empty:` reveals a no-matches node. See [Client-side option filtering](#client-side-option-filtering-reactive_filter). |
 | `reactive_listnav("[role=option]")` | The **standalone** combobox keyboard wiring (Arrow/Enter/Escape) for an input that fires **no action** — the preload-and-filter case. Same behavior as `on(…, listnav:)`, minus the POST. |
 | `reactive_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). See [Tag-chip input](#tag-chip-input-reactive_tags). |
@@ -396,6 +396,9 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 | `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_dirty` / `reactive_dirty warn_unsaved: true` / `reactive_dirty only: %i[...]` | **Dirty tracking**, declared once at the class level, against the DOM's own `defaultValue`/`defaultChecked`/`defaultSelected` — no client state. Marks changed fields + the root `data-reactive-dirty`; `warn_unsaved:` arms a `beforeunload`/`turbo:before-visit` guard; `only:` scopes tracking to named fields. Style with `[data-reactive-dirty]`. See [Dirty-field tracking](#dirty-field-tracking-reactive_dirty). |
 | `nested_update!(:assoc, attrs)` | Map a nested param onto `<assoc>_attributes` with id preservation; update the record. |
+| `reactive_nested_list(:assoc, as: :attributes \| :json)` / `reactive_nested_template(:assoc)` / `reactive_nested_row` | **Draft nested-attribute rows** (the "new parent + child rows" form): the container rows land in, the `<template>` holding ONE row's markup, and the row wrapper marker — all **client-only** form state, keyed by association (several collections per root). `as: :json` (default `:attributes`) serializes the rows into ONE hidden JSON field instead of posting `accepts_nested_attributes_for` names — for an app whose controller `JSON.parse`s a serialized param. See [Draft rows for a new parent](#draft-rows-for-a-new-parent-reactive_nested_). |
+| `reactive_nested_add(:assoc)` / `reactive_nested_remove` | The row triggers, client-only (zero round trips): add clones the template and renumbers its placeholder index; remove deletes a draft row from the DOM, or `_destroy`-marks + hides a persisted row (a hidden `[_destroy]` input present). |
+| `nested_field_name(:assoc, :field, index: nil)` | The Rails `accepts_nested_attributes_for` wire name for one row field — `order[line_items_attributes][NEW_ROW][quantity]` (the template placeholder) by default, a real index when given. Scope-aware under `reactive_scope`. |
 | `reactive_collection :name, item:, container:, count:, empty:, size:` | Declare an add/remove-row list once; actions call `reply.append`/`prepend`/`remove`. See [Reactive collections](#reactive-collections-addremove-rows--count--empty-state). |
 | `reply.replace` / `.morph` / `.update` / `.remove` / `.redirect(url)` / `.with(*)` / `.js(ops)` | Return from an action to control the reply (flash, remove, redirect, multi-stream, server-pushed client ops). See [Controlling the action's reply](#reply--controlling-the-actions-reply). |
 | `reply.append(name, model)` / `.prepend(...)` / `.remove(name, model)` | Add/remove a row in a declared `reactive_collection` (row + count + empty-state in one reply). |
@@ -1016,6 +1019,23 @@ reactive_show_targets(mode: { "#advanced-tab" => "advanced" },
                       kind: { "#premium-note" => %w[gold platinum] })
 ```
 
+**Multi-field targets.** A `"#id"` *key* takes a full `if:`/`if_any:`/`unless:`
+conditions Hash — the same language `reactive_show` speaks — so a cross-root
+target can read a **combination** of owned fields (the case that used to force
+a bespoke two-field JS listener):
+
+```ruby
+reactive_show_targets(
+  "#trade-warning" => { if: { type: "trade", price: ..0 } },  # type == "trade" AND price <= 0
+  mode: { "#advanced-tab" => "advanced" }                     # field-keyed entries mix in the ONE call
+)
+```
+
+The fold is identical to an in-root `reactive_show` (each term reads its own
+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.
+
 ### Client-side computes (`reactive_compute` + `reactive_text`)
 
 Some math should feel instant with **no round trip** — a NEW, unsaved record's
@@ -1252,6 +1272,122 @@ The styled, form-builder-integrated version of this widget (label/errors/
 theming) belongs in your form layer — these helpers are deliberately the
 unstyled primitives, like `reactive_filter` before them.
 
+### Draft rows for a new parent (`reactive_nested_*`)
+
+The "new order + line items" form: the user builds up child rows **before the
+parent exists**. An unsaved parent has no GlobalID to sign, so this pre-save
+window can't be a reactive collection — and every app ends up hand-writing the
+same imperative JS (clone a row, renumber indexes, serialize on submit).
+`reactive_nested_*` is that pattern as a primitive, the `reactive_tags`
+posture: the rows are **form state**, add/remove run **entirely client-side**
+(zero round trips, no token — works in a `ClientBindings` component), and the
+surrounding **real form submit** posts standard Rails
+`parent[assoc_attributes][<index>][field]` names, so
+`accepts_nested_attributes_for` creates the parent + rows in **one request**.
+
+```ruby
+class DraftOrderForm < ApplicationComponent
+  include Phlex::Reactive::ClientBindings
+
+  reactive_scope :order   # names post as order[line_items_attributes][…]
+
+  def view_template
+    div(**reactive_root(id: "draft_order_form")) do
+      form(action: orders_path, method: "post", data: { turbo: "false" }) do
+        input(**reactive_field(:total, type: "number", value: "0"))
+
+        div(**reactive_nested_list(:line_items)) { }             # rows land here
+        template(**reactive_nested_template(:line_items)) { row_fields }
+        button(**reactive_nested_add(:line_items)) { "Add item" }
+
+        button(type: "submit") { "Create order" }
+      end
+    end
+  end
+
+  private
+
+  # ONE row's markup, authored once. The default renders the template
+  # prototype (NEW_ROW placeholder names — the client swaps in a fresh index
+  # per add); pass index: to server-render an edit form's persisted rows.
+  def row_fields(index: nil)
+    kwargs = index.nil? ? {} : { index: }
+    div(**reactive_nested_row) do
+      input(name: nested_field_name(:line_items, :quantity, **kwargs), type: "number")
+      input(name: nested_field_name(:line_items, :price, **kwargs), type: "number")
+      button(**reactive_nested_remove) { "×" }
+    end
+  end
+end
+```
+
+```ruby
+# The model + controller side is plain Rails — the reconcile is one create:
+class Order < ApplicationRecord
+  has_many :line_items, dependent: :destroy
+  accepts_nested_attributes_for :line_items, allow_destroy: true
+end
+
+Order.create!(params.require(:order).permit(:total,
+  line_items_attributes: %i[id quantity price _destroy]))
+```
+
+Clicking add clones your `<template>` row and swaps every `NEW_ROW` in the
+clone's `name`/`id`/`for` attributes for a fresh unique index (clock-seeded and
+strictly monotonic — server-rendered `0..n` indexes and same-millisecond double
+clicks can't collide), then focuses the new row's first field. Remove on a
+draft row deletes it from the DOM — it was never persisted, so removing its
+fields *is* the removal. Remove on a row carrying a hidden `[_destroy]` input
+(an **edit** form's persisted row, rendered with `nested_field_name(:line_items,
+:_destroy, index: i)`) marks it `"1"` and hides the row instead — Rails destroys
+it on save. Several collections can share one root (everything is keyed by the
+association name); nesting a collection inside another's template is not
+supported.
+
+Two boundaries to respect: the DOM is the single source of truth for unsent
+draft rows, so a **server re-render of the root replaces them** — keep
+replace-shaped actions out of a root holding unsent rows. And once the parent
+is saved, the persisted flow takes over: the same row markup renders with real
+indexes, or the list graduates to a [reactive collection](#reactive-collections-addremove-rows--count--empty-state)
+(`reactive_collection` + `reply.append`/`reply.remove`).
+
+**JSON mode — one hidden field instead of `accepts_nested_attributes_for`.**
+If your controller already parses a **serialized JSON param** (the app-rolled
+"stuff the rows into a hidden field, `JSON.parse` on submit" pattern) rather
+than nested attributes, opt the list into `as: :json` and keep your persistence
+path exactly as it is:
+
+```ruby
+div(**reactive_nested_list(:line_items, as: :json)) { }   # + a hidden field to sync
+# the hidden field the client keeps in sync (seed "[]" so an empty submit posts one):
+input(type: "hidden", **reactive_field(:line_items), value: "[]")
+```
+
+```ruby
+# The controller stays hand-rolled — NO accepts_nested_attributes_for:
+rows = JSON.parse(params.require(:order).permit(:line_items)[:line_items].presence || "[]")
+order = Order.create!(total: params[:order][:total])
+rows.each { order.line_items.create!(quantity: it["quantity"], price: it["price"]) }
+```
+
+Everything else is identical — the same `<template>` row, the same
+`nested_field_name`, the same add/remove triggers. In JSON mode the client
+mirrors the surviving rows into that one hidden field as a JSON array on every
+add / remove / keystroke (the set-value + dispatch contract, so dirty tracking
+and compute still see it), inferring each JSON key from the **trailing bracket
+segment** of a row input's name (`order[line_items_attributes][3][quantity]` →
+`"quantity"`). A removed row simply leaves the array (JSON carries no `_destroy`
+marker — an absent row *is* the removal). The per-row `_attributes` names still
+render but are ignored by a controller that doesn't permit them; the JSON field
+is the single source of truth.
+
+Relatedly, a **draft parent can now run real server actions too** (issue #208):
+an unsaved record signs a gid-less `{c, state}` token, and the endpoint rebuilds
+the component through the record kwarg's **initialize default** —
+`def initialize(order: Order.new, …)` — with the declared `reactive_state`
+riding the token. A component whose initialize *requires* the record kwarg
+raises a guided error on the first draft action, telling you to add the default.
+
 **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
@@ -2002,10 +2138,11 @@ Phlex::Reactive.action_path = "/_r/actions"
 Phlex::Reactive.verbose_errors = true
 
 # User-visible flash on endpoint failures (default nil = off). When set, every
-# rescue path (400/403/404) ALSO renders a turbo-stream flash the user sees — at
-# the SAME status it returns today (statuses never change). The lambda receives
-# the failure kind (:tampered/:unknown_class/:not_reactive_class/:forbidden/
-# :not_found), so you can map it to a friendly message:
+# rescue path (400/403/404 AND a 500 crash) ALSO renders a turbo-stream flash the
+# user sees — at the SAME status it returns today (statuses never change). The
+# lambda receives the failure kind (:tampered/:unknown_class/:not_reactive_class/
+# :forbidden/:not_found, or :error for an action-body crash), so you can map it to
+# a friendly message:
 Phlex::Reactive.error_flash = ->(kind) do
   case kind
   when :not_found  then "That item is no longer available."
@@ -2014,6 +2151,17 @@ Phlex::Reactive.error_flash = ->(kind) do
   end
 end
 
+# Turnkey APM integration. Names each action Component#action in AppSignal/Sentry/
+# Datadog and reports action-body crashes with component/action tags. SDK is
+# runtime-detected (no gem dependency); a custom object responding to
+# record_action/record_error works too. See "Observability" above.
+Phlex::Reactive.apm = :appsignal
+
+# Report action-body crashes to any tracker yourself (the DIY escape hatch):
+Phlex::Reactive.on_action_error do |error, ctx|
+  Honeybadger.notify(error, context: { component: ctx[:component], action: ctx[:action] })
+end
+
 # Component-aware wrapper around every action (audit / rate-limit / assert).
 # Sees the resolved component, action name, and COERCED params; runs inside
 # the connection-id scope but OUTSIDE the transaction. See "Two seams" below.
@@ -2293,6 +2441,50 @@ The events fire whether or not you enable the LogSubscriber; the flag only
 controls the gem's own log lines. See
 [docs/performance.md](https://phlex-reactive.zoolutions.llc/docs/performance).
 
+### Turnkey APM adapters (AppSignal, Sentry, Datadog)
+
+Subscribing by hand is the DIY path. For the common trackers there's a one-liner
+that both names the transaction and reports errors — so reactive traffic stops
+rolling into one blurry `ActionsController#create` and a crash arrives at your
+tracker with context:
+
+```ruby
+# config/initializers/phlex_reactive.rb
+Phlex::Reactive.apm = :appsignal   # or :sentry, :datadog, or a custom object
+```
+
+With it set:
+
+- Each reactive action shows in the APM as its OWN transaction/span —
+  `Counter#increment`, not `Phlex::Reactive::ActionsController#create` — tagged
+  with the component, action, and outcome.
+- An action body that raises a genuine error (a 500, not a registered 4xx) is
+  **reported to the tracker with `component`/`action` tags**, then re-raised
+  unchanged so Rails' own error reporting still fires.
+
+The SDK is **runtime-detected** — no gem dependency is added. If the named SDK
+isn't loaded, `apm =` logs one warning at boot and no-ops (the same optionality
+invariant as pgbus). A custom object works too — anything responding to
+`record_action(payload, duration_ms)` and `record_error(error, payload)`.
+
+For a tracker with no built-in adapter, report errors yourself — this hook fires
+on any previously-uncaught action-body error, with the name-only context:
+
+```ruby
+Phlex::Reactive.on_action_error do |error, ctx|
+  Honeybadger.notify(error, context: { component: ctx[:component], action: ctx[:action] })
+end
+```
+
+And to show the user a flash when an action crashes (the SAME hook the 4xx errors
+already use — `kind` is `:error` for a crash):
+
+```ruby
+Phlex::Reactive.error_flash = ->(kind) { "Something went wrong — please retry." }
+```
+
+See [docs/observability.md](https://phlex-reactive.zoolutions.llc/docs/observability).
+
 ### Client debug mode (devtools-lite)
 
 The `LogSubscriber` above is the **server** lens. The client lens is

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

@@ -96,6 +96,13 @@ module Phlex
       rescue *authorization_errors => e
         event[:outcome] = :unauthorized
         reactive_error(:forbidden, deferred_authorization_message(e, component_class), kind: :forbidden)
+      rescue => e # rubocop:disable Style/RescueStandardError
+        # Issue #207, the defer (read) leg: a render that raises uncaught is
+        # OBSERVED (tag + report + flash) then re-raised unchanged, mirroring the
+        # action leg. The defer payload has no `action:` — report_error/the
+        # adapters treat a nil action gracefully (transaction is the component).
+        report_action_error(e, event)
+        raise
       end
 
       def verified_defer_payload
@@ -156,6 +163,42 @@ module Phlex
       rescue *authorization_errors => e
         event[:outcome] = :unauthorized
         reactive_error(:forbidden, authorization_error_message(e, component_class, action_def), kind: :forbidden)
+      rescue => e # rubocop:disable Style/RescueStandardError
+        # Turnkey APM error reporting (issue #207). A previously-UNCAUGHT
+        # action-body error — NOT one of the specific 4xx cases above (those still
+        # win by ordering) — is OBSERVED here and then re-raised UNCHANGED, so
+        # Rails' own error reporting and the app's middleware fire exactly as
+        # today. The status never changes: this catch adds no new 4xx.
+        #   1. tag the event outcome (fills the #107 nil-outcome gap),
+        #   2. report to the APM adapter + on_action_error hooks WITH the name-only
+        #      component/action context (each reporter isolated — see report_error),
+        #   3. render the error_flash for the crash so the actor SEES a flash (500s
+        #      now flow through the same error_flash path 4xx already used), THEN
+        #   4. re-raise. The flash is built but MUST NOT swallow the raise.
+        report_action_error(e, event)
+        raise
+      end
+
+      # OBSERVE a previously-uncaught action-body error (issue #207) without
+      # altering what propagates. Tag the outcome, fan the error out to the APM
+      # adapter + on_action_error hooks (report_error isolates each reporter), and
+      # render the error_flash for the crash. Every step is best-effort and MUST
+      # NOT raise (the caller re-raises the ORIGINAL error immediately after): a
+      # broken reporter is swallowed inside report_error; the flash render is
+      # guarded here. The flash reuses the SAME 4xx machinery — error_flash_stream
+      # degrades to nil on its own failure, and we render at :internal_server_error
+      # so the body (if any) matches the 500 the re-raise ultimately yields.
+      def report_action_error(error, event)
+        event[:outcome] = :error
+        Phlex::Reactive.report_error(error, event)
+
+        flash = error_flash_stream(:error)
+        render turbo_stream: flash, status: :internal_server_error if flash
+      rescue => e # rubocop:disable Style/RescueStandardError
+        # The observation path itself failed — log it, but NEVER let it replace the
+        # action-body error the caller is about to re-raise.
+        ::Rails.logger&.warn("[phlex-reactive] error observation failed: #{e.class}: #{e.message}") if
+          defined?(::Rails) && ::Rails.respond_to?(:logger)
       end
 
       # Reply to an endpoint failure. The status NEVER changes with any flag —