phlex-reactive 0.11.3 → 0.11.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23b25b41281afc59503c63e9e4fbcee696d1265b96682c1c97bfd0adf385055d
-  data.tar.gz: 7204885d357720c85e57c8b44192d6e000f91c985346177a7ddcefc28f7451cc
+  metadata.gz: a7758f95f9e1a35e71bf870416d6e042367b7ca19bb2a1c3b618939e72aa5775
+  data.tar.gz: 2203a04fcf550a95e828945e56d06ed1b335fc430a1fdb8669f566893aa17c7d
 SHA512:
-  metadata.gz: 2afb0dfef67df5cc60f176db516ca7c4ed5553e7f24a9df9ff098dc7a897e1085594c698661d437f8ea336b4eab5d6bc76b884073f0f52b37b09a8f5fe4bd711
-  data.tar.gz: 411a32490ecdc9224d18e5db37b443286d1d3e47210e733e2cb9e6083aac5af2ac5ead6f96e54ab1cf0629483addd3f888de209976a6b2161259c5a6d9c0a93e
+  metadata.gz: 311c87cf131ec0db83082089133b32dcc0583aa49203950ff59495929a2b512d72bedff7ced52747b2074bbce16a6b32eac99249e2b985cb19acfb9afce3a1ab
+  data.tar.gz: 5856533fe3e2207246082a56f6709d732f32db50b8a8c6f1e2f3c8bd74b0f5b2c2330440e0c2b4c9bc078d785d33b85e95ae22f7edc91f746df959f86819fa37

data/CHANGELOG.md

@@ -8,6 +8,73 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **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
+  FORM state in a hidden **comma-joined** field the root names
+  (`reactive_tags(:tags)`, scope-aware like `reactive_filter`); the chip list is
+  a client projection of that field, rebuilt per change by cloning a
+  server-owned `<template>` chip (`textContent` writes only — never
+  `innerHTML`). Three client-only triggers: `reactive_tags_add` (Enter adds the
+  typed text — composed after `reactive_listnav`, a highlighted option wins and
+  Enter never submits the enclosing form), `reactive_tags_option(tag)` (click a
+  suggestion to add its declared tag), `reactive_tags_remove(tag)` (a chip's
+  remove button; no arg inside the template — the client fills it per chip).
+  Tags dedupe case-insensitively; a comma-separated paste splits; a declared tag
+  containing a comma raises at render. Selected suggestions hide + mark
+  `data-reactive-tags-selected` (`reactive_filter` keeps them hidden through
+  re-filters) and resurface on removal; a morph re-projects the chips from the
+  field's server value; every write dispatches a real `input` event on the
+  hidden field so `reactive_dirty`/`reactive_show`/`reactive_compute` see it.
+  Works in a token-less `ClientBindings` component — nothing here POSTs.
+
 - **A global reactive-activity signal — the analogue of Turbo's progress bar (#201).**
   The client now maintains a document-level count of in-flight reactive operations
   across ALL roots — incremented when a dispatch round trip or a deferred render
@@ -47,6 +114,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

@@ -390,10 +390,15 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 | `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_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). |
+| `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`. 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). |
 | `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)` / `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). 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). |
@@ -1194,6 +1199,148 @@ 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.
 
+### Tag-chip input (`reactive_tags`)
+
+The composed combobox/tags widget: preload suggestions, type to narrow, Enter or
+click to add, remove chips — the classic bespoke `tags` Stimulus controller,
+gone. The value is **form state** (like text in an input), never component
+state: it lives in a hidden **comma-joined** field inside your form, the client
+maintains it with **zero round trips**, and the surrounding form submit carries
+it to the server (`tags.split(",")` on your side). Because nothing here needs a
+signed action, the widget works in a token-less `ClientBindings` component too.
+
+```ruby
+div(**mix(reactive_root, reactive_tags(:tags), reactive_filter(:tag_query))) do
+  input(type: :hidden, **reactive_field(:tags), value: @post.tags.join(","))
+
+  div(data: { reactive_tags_list: true }) do        # chips render here
+    @post.tags.each { chip(it) }                    # server-rendered first paint
+  end
+  template(data: { reactive_tags_template: true }) { chip }  # the chip markup, server-owned
+
+  # listnav FIRST, tags_add second: Enter picks the highlighted option;
+  # free text adds only when nothing is highlighted. Never submits the form.
+  input(name: "tag_query", **mix(reactive_listnav, reactive_tags_add))
+
+  SUGGESTIONS.each do |tag, haystack|
+    button(**mix(reactive_tags_option(tag),          # click → add (client-only)
+      data: { reactive_filter_text: haystack })) { tag }
+  end
+end
+
+# One chip method serves both forms: with a tag it's the server-rendered chip,
+# without it's the template prototype (the client fills text + remove param).
+def chip(tag = nil)
+  span(class: "chip", data: { reactive_tag: tag }) do
+    span(data: { reactive_tag_text: true }) { tag }
+    button(**(tag ? reactive_tags_remove(tag) : reactive_tags_remove)) { "×" }
+  end
+end
+```
+
+The chip list is a **client projection of the hidden field** — the field is the
+single source of truth. Every change re-clones your `<template>` per tag,
+writing the tag through `textContent` only (never `innerHTML` — the XSS-safe
+`reactive_text` posture) and stamping the remove button's tag param. Tags dedupe
+case-insensitively (first casing wins); a comma-separated paste splits into
+individual tags; a declared tag containing a comma **raises at render** (it
+would corrupt the joined value). An already-selected suggestion is hidden and
+marked `data-reactive-tags-selected` — `reactive_filter` keeps it hidden through
+re-filters — and resurfaces when its chip is removed. A server re-render/morph
+re-projects the chips from the field's fresh server value, and each write
+dispatches a real `input` event on the hidden field, so `reactive_dirty`,
+`reactive_show`, and `reactive_compute` all see it.
+
+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`).
+
+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
@@ -1944,10 +2091,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."
@@ -1956,6 +2104,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.
@@ -2235,6 +2394,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 —