phlex-reactive 0.11.4 → 0.11.6

data/lib/generators/phlex/reactive/install/templates/phlex_reactive.rb.erb

@@ -35,6 +35,26 @@
 # flag only controls the gem's own log lines. See the README Observability section.
 # Phlex::Reactive.log_events = true
 
+# Turnkey APM integration. Set to :appsignal / :sentry / :datadog and each
+# reactive action shows in your APM as its OWN transaction ("Counter#increment"),
+# not one blurry ActionsController#create — and an action-body crash is reported
+# to the tracker WITH component/action tags (plus a flash to the user if you set
+# error_flash below). The SDK is runtime-detected: if it isn't loaded, this logs
+# one warning and no-ops (no gem dependency is added). Pass a custom object
+# responding to record_action(payload, duration_ms) / record_error(error, payload)
+# to integrate any other tool.
+# Phlex::Reactive.apm = :appsignal
+#
+# For a tracker with no built-in adapter, report errors yourself — this fires on
+# any previously-uncaught action-body error, with the name-only context:
+# Phlex::Reactive.on_action_error do |error, ctx|
+#   Honeybadger.notify(error, context: { component: ctx[:component], action: ctx[:action] })
+# end
+#
+# Show the user a flash when an action crashes (500) — the SAME hook the 4xx
+# errors already use; `kind` is :error for a crash:
+# Phlex::Reactive.error_flash = ->(kind) { "Something went wrong — please retry." }
+
 # Client debug mode (devtools-lite). When on, every reactive root carries
 # data-reactive-debug="true" and the browser console.groups EVERY dispatch —
 # action, param/collected field NAMES (never values), request encoding, HTTP

data/lib/phlex/reactive/apm/adapter.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module APM
+      # The adapter contract (issue #207). A custom APM integration need only be an
+      # object responding to these two methods — it does NOT have to subclass this;
+      # the class documents the interface and gives the built-in vendor adapters a
+      # shared home for the small helpers they all use.
+      #
+      #   record_action(payload, duration_ms)
+      #     payload is the name-only action/defer event payload
+      #     ({ component:, action:, outcome: } — action:/nil for defer). Name the
+      #     APM transaction and tag the outcome. Called on EVERY reactive action.
+      #
+      #   record_error(error, payload)
+      #     error is the raised exception; payload is the same name-only hash. Report
+      #     the exception to the tracker WITH component/action tags. Called only on a
+      #     previously-uncaught action-body error (a 500), just before the re-raise.
+      #
+      # A built-in adapter also answers `.available?` (a runtime `defined?(SDK)`
+      # probe) so the resolver can no-op when the SDK isn't loaded.
+      class Adapter
+        # The APM transaction name for a payload: "Component#action", or just the
+        # component when there's no action (a defer event), or nil when there's no
+        # trusted component (an invalid_token event carries none).
+        def transaction_name(payload)
+          component = payload[:component]
+          return nil unless component
+
+          action = payload[:action]
+          action ? "#{component}##{action}" : component
+        end
+
+        # Present but not enforced — a bare Adapter is not a usable APM. The vendor
+        # subclasses override all three.
+        def self.available? = false
+        def record_action(_payload, _duration_ms) = nil
+        def record_error(_error, _payload) = nil
+      end
+    end
+  end
+end

data/lib/phlex/reactive/apm/appsignal.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module APM
+      # AppSignal adapter (issue #207). Activates only when `::Appsignal` is loaded
+      # — never a gemspec dependency. Names the current transaction `Component#action`
+      # (so reactive traffic stops rolling into one ActionsController#create blob) and
+      # tags component/action/outcome; reports an action-body error with those tags.
+      class Appsignal < Adapter
+        def self.available? = defined?(::Appsignal) ? true : false
+
+        def record_action(payload, _duration_ms)
+          name = transaction_name(payload)
+          return unless name
+
+          ::Appsignal.set_action(name)
+          ::Appsignal.add_tags(tags(payload))
+        end
+
+        # Report the error with tags. AppSignal 4.x removed the positional
+        # tags/namespace args from set_error and requires the BLOCK form
+        # (set_error(error) { add_tags(...) }); 3.x accepts the positional hash.
+        # Branch on the method's arity so the adapter works on both majors without
+        # pinning a version — the capability-detection posture applied within a gem.
+        def record_error(error, payload)
+          if set_error_takes_tags?
+            ::Appsignal.set_error(error, tags(payload))
+          else
+            ::Appsignal.set_error(error) { ::Appsignal.add_tags(tags(payload)) }
+          end
+        end
+
+        private
+
+        # True on AppSignal 3.x, where set_error accepts a positional tags arg
+        # (arity != 1). On 4.x set_error takes only the error (arity 1) + a block.
+        def set_error_takes_tags?
+          ::Appsignal.method(:set_error).arity != 1
+        end
+
+        def tags(payload)
+          {
+            "reactive_component" => payload[:component],
+            "reactive_action" => payload[:action],
+            "reactive_outcome" => payload[:outcome]&.to_s
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/apm/datadog.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module APM
+      # Datadog adapter (issue #207, dd-trace-rb). Activates only when
+      # `::Datadog::Tracing` is loaded. Renames the ACTIVE span `Component#action`
+      # + tags it, so the reactive action shows as its own resource in the trace;
+      # marks the active span errored on an action-body crash. No-ops with no
+      # active span (never opens one itself — that's the app's tracer's job).
+      class Datadog < Adapter
+        def self.available?
+          return false unless defined?(::Datadog::Tracing)
+
+          ::Datadog.respond_to?(:configuration)
+        end
+
+        def record_action(payload, _duration_ms)
+          span = active_span
+          return unless span
+
+          name = transaction_name(payload)
+          span.resource = name if name
+          span.set_tag("reactive.component", payload[:component]) if payload[:component]
+          span.set_tag("reactive.action", payload[:action]) if payload[:action]
+          span.set_tag("reactive.outcome", payload[:outcome].to_s) if payload[:outcome]
+        end
+
+        def record_error(error, payload)
+          span = active_span
+          return unless span
+
+          span.set_error(error)
+          span.set_tag("reactive.component", payload[:component]) if payload[:component]
+          span.set_tag("reactive.action", payload[:action]) if payload[:action]
+        end
+
+        private
+
+        def active_span = ::Datadog::Tracing.active_span
+      end
+    end
+  end
+end

data/lib/phlex/reactive/apm/sentry.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module APM
+      # Sentry adapter (issue #207). Activates only when `::Sentry` is loaded AND
+      # initialized. Sentry's chief value here is error reporting: an action-body
+      # crash is captured WITH component/action tags. record_action names the
+      # transaction on the current scope for the successful path.
+      class Sentry < Adapter
+        def self.available?
+          return false unless defined?(::Sentry) && ::Sentry.respond_to?(:initialized?)
+
+          ::Sentry.initialized?
+        end
+
+        def record_action(payload, _duration_ms)
+          name = transaction_name(payload)
+          return unless name
+
+          ::Sentry.configure_scope { it.set_transaction_name(name) }
+        end
+
+        def record_error(error, payload)
+          ::Sentry.capture_exception(error, tags: tags(payload))
+        end
+
+        private
+
+        def tags(payload)
+          {
+            reactive_component: payload[:component],
+            reactive_action: payload[:action],
+            reactive_outcome: payload[:outcome]&.to_s
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/apm/subscriber.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module APM
+      # The ASN-driven half of the APM integration (issue #207). Subscribes to
+      # action.phlex_reactive / defer.phlex_reactive and hands each event's
+      # name-only payload + duration to the resolved adapter's record_action —
+      # so the APM names the transaction `Component#action` and tags the outcome.
+      #
+      # A plain ActiveSupport::Notifications subscriber (NOT a LogSubscriber): a
+      # LogSubscriber dispatches by the FULL event method, but we want the SAME
+      # record_action for both action and defer events and to hold a reference to
+      # the adapter instance. install/uninstall manage exactly one subscription so
+      # a re-attach with the same adapter never double-reports.
+      class Subscriber
+        # The events whose duration+outcome we forward to the APM as a named
+        # transaction. render/broadcast are left to the app (a Datadog child-span
+        # adapter can subscribe to them itself) — the action IS the transaction.
+        EVENTS = /\A(?:action|defer)\.phlex_reactive\z/
+
+        class << self
+          # Install a single bus subscription for `adapter`. Idempotent for the
+          # SAME adapter: a repeat call is a no-op. A DIFFERENT adapter replaces
+          # the previous subscription (an app that swaps apm at boot wins last).
+          def install(adapter)
+            return if @adapter.equal?(adapter) && @subscription
+
+            uninstall
+            @adapter = adapter
+            subscriber = new(adapter)
+            @subscription = ::ActiveSupport::Notifications.subscribe(EVENTS) do |*args|
+              subscriber.call(::ActiveSupport::Notifications::Event.new(*args))
+            end
+          end
+
+          def uninstall
+            ::ActiveSupport::Notifications.unsubscribe(@subscription) if @subscription
+            @subscription = nil
+            @adapter = nil
+          end
+
+          def installed? = !@subscription.nil?
+        end
+
+        def initialize(adapter)
+          @adapter = adapter
+        end
+
+        # Route an already-built Event to record_action. Named after the event's
+        # leading segment (action/defer) so the synthesized-event unit spec can
+        # call subscriber.action(event) exactly like the LogSubscriber spec.
+        def call(event)
+          @adapter.record_action(event.payload, event.duration)
+        end
+        alias action call
+        alias defer call
+      end
+    end
+  end
+end

data/lib/phlex/reactive/apm.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # Turnkey APM integration (issue #207). The gem already emits `*.phlex_reactive`
+    # ActiveSupport::Notifications events (issue #107); this namespace turns them
+    # into per-component visibility in AppSignal / Sentry / Datadog with ONE config
+    # line — `Phlex::Reactive.apm = :appsignal` — instead of every app hand-writing
+    # the subscribe block and each vendor's transaction-naming / error-tagging API.
+    #
+    # The vendor adapters are RUNTIME capability-detected (`defined?(::Appsignal)`
+    # etc.), never a gemspec dependency — the same optionality invariant as pgbus.
+    # A set-but-absent SDK logs one warning and no-ops.
+    module APM
+      # Symbol => built-in adapter class. Resolved lazily (at attach time), so the
+      # adapter class is only referenced when an app actually opts into it.
+      BUILT_INS = {
+        appsignal: "Phlex::Reactive::APM::Appsignal",
+        sentry: "Phlex::Reactive::APM::Sentry",
+        datadog: "Phlex::Reactive::APM::Datadog"
+      }.freeze
+
+      class << self
+        # Resolve `Phlex::Reactive.apm` to a live adapter instance, or nil.
+        #   * nil            -> nil (off; no warning)
+        #   * an object      -> returned verbatim (a custom adapter)
+        #   * a known Symbol -> the built-in adapter instance IF its SDK is loaded,
+        #                       else nil + one warning
+        #   * an unknown Symbol -> nil + one warning
+        def detect(apm)
+          return nil if apm.nil?
+          return apm unless apm.is_a?(Symbol)
+
+          klass_name = BUILT_INS[apm]
+          unless klass_name
+            known = BUILT_INS.keys.map(&:inspect).join(", ")
+            return warn_and_nil("apm = #{apm.inspect} — unknown APM flavour (known: #{known})")
+          end
+
+          klass = klass_name.constantize
+          # Memoize the instance PER SYMBOL so repeated detect/attach! calls return
+          # the SAME object — Subscriber.install keys idempotency on adapter
+          # identity (equal?), so a fresh klass.new each time would double-subscribe.
+          return (built_in_instances[apm] ||= klass.new) if klass.available?
+
+          warn_and_nil("apm = #{apm.inspect} set but #{apm} is not loaded — no-op. " \
+                       "Require the SDK (or remove the setting).")
+        end
+
+        # Attach the APM Subscriber to the notification bus if an adapter resolves.
+        # Called once from the engine's after_initialize when Phlex::Reactive.apm
+        # is set. Idempotent within a boot: a second call with the SAME adapter is
+        # a no-op. Returns the attached adapter (or nil when nothing resolved).
+        def attach!(apm = Phlex::Reactive.apm)
+          adapter = detect(apm)
+          return nil unless adapter
+
+          Subscriber.install(adapter)
+          # Hold the adapter so the endpoint's error seam (report_error) can reach
+          # record_error without re-running detection per request.
+          Phlex::Reactive.resolved_apm_adapter = adapter
+          adapter
+        end
+
+        # Drop the installed subscriber + adapter AND the memoized built-in
+        # instances. Tests only (so a stubbed SDK doesn't leak a stale adapter into
+        # the next example).
+        def reset!
+          Subscriber.uninstall
+          Phlex::Reactive.resolved_apm_adapter = nil
+          @built_in_instances = nil
+        end
+
+        private
+
+        # Symbol => memoized built-in adapter instance. One instance per flavour for
+        # the life of the process (cleared only by reset! in tests), so detect is
+        # identity-stable and attach! stays idempotent.
+        def built_in_instances
+          @built_in_instances ||= {}
+        end
+
+        def warn_and_nil(message)
+          logger = Phlex::Reactive.send(:default_logger)
+          logger&.warn("[phlex-reactive] #{message}")
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/component/dsl.rb

@@ -475,10 +475,19 @@ module Phlex
             kwargs = {}
 
             if reactive_record_key
-              record = GlobalID::Locator.locate(payload.fetch("gid"))
-              raise(ActiveRecord::RecordNotFound, "reactive record missing") unless record
-
-              kwargs[reactive_record_key] = record
+              if (gid = payload["gid"])
+                record = GlobalID::Locator.locate(gid)
+                raise(ActiveRecord::RecordNotFound, "reactive record missing") unless record
+
+                kwargs[reactive_record_key] = record
+              else
+                # A DRAFT token (issue #208): Component::Identity signs no gid
+                # for an unsaved (or nil) record. Omit the kwarg — the
+                # component's initialize default seeds a fresh draft, mirroring
+                # first render — so a draft parent can run real server actions
+                # (its transient identity rides in the signed state instead).
+                ensure_draft_default!
+              end
             end
 
             if reactive_state_keys.any?
@@ -496,6 +505,20 @@ module Phlex
 
             new(**kwargs)
           end
+
+          # A draft token can only rebuild through the record kwarg's initialize
+          # default (issue #208). A component whose initialize REQUIRES the
+          # record can't render drafts — teach the fix instead of exploding
+          # with a bare missing-keyword ArgumentError deep in new(**kwargs).
+          def ensure_draft_default!
+            return unless instance_method(:initialize).parameters.include?([:keyreq, reactive_record_key])
+
+            raise Phlex::Reactive::Error,
+              "#{self}: the action token carries no record gid (the #{reactive_record_key} was unsaved " \
+              "when rendered — a draft), but initialize requires `#{reactive_record_key}:`. Give the " \
+              "kwarg a default (e.g. `#{reactive_record_key}: nil` or a fresh record) so the draft " \
+              "can rebuild through it."
+          end
         end
       end
     end

data/lib/phlex/reactive/component/helpers.rb

@@ -724,6 +724,139 @@ module Phlex
           attrs
         end
 
+        # Draft nested-attribute rows (issue #208) — the "new parent + child
+        # rows" primitive. A form that builds child rows BEFORE the parent
+        # exists (a new order accumulating line items) can't be a reactive
+        # collection: an unsaved parent has no gid to sign, so there is nothing
+        # to round-trip. These helpers run that pre-save window entirely
+        # CLIENT-SIDE, the reactive_tags posture: the rows are FORM state (like
+        # text in an input), never component state — add/remove round-trips
+        # nothing, and the surrounding REAL form submit carries Rails'
+        # accepts_nested_attributes_for names so the server reconciles parent +
+        # rows in ONE create.
+        #
+        # The wiring (all inside one reactive root, itself inside the real
+        # <form> that will POST the parent):
+        #
+        #   div(**reactive_root) do
+        #     div(**reactive_nested_list(:line_items)) { }            # rows land here
+        #     template(**reactive_nested_template(:line_items)) do    # ONE row's markup (server-owned)
+        #       div(**reactive_nested_row) do
+        #         input(name: nested_field_name(:line_items, :quantity))  # …[NEW_ROW][quantity]
+        #         button(**reactive_nested_remove) { "×" }
+        #       end
+        #     end
+        #     button(**reactive_nested_add(:line_items)) { "Add row" }
+        #   end
+        #
+        # Clicking add clones the template and swaps every NEW_ROW in the
+        # clone's name/id/for attributes for a fresh unique index, so each row
+        # posts as its own `…_attributes[<index>][field]` group. Remove on a
+        # draft row deletes it from the DOM; remove on a row carrying a hidden
+        # `[_destroy]` input (a persisted row in an edit form, rendered with
+        # nested_field_name(index: item_index)) marks it "1" and hides the row
+        # — Rails destroys it on save. The DOM is the single source of truth;
+        # a server re-render of the root REPLACES the rows, so keep replace-
+        # shaped actions out of a root holding unsent draft rows.
+        #
+        # Several collections can share one root — every marker/trigger is
+        # keyed by the association name. Nesting a collection INSIDE another's
+        # template is not supported (the placeholder swap would hit both).
+        # Once the parent is saved, the persisted flow takes over: the same row
+        # markup renders with real indexes, or graduates to a reactive
+        # collection (reactive_collection + reply.append/remove).
+
+        # The index placeholder a template row carries in its field names; the
+        # client swaps it for a fresh unique index on every add. Referenced by
+        # both sides of the wire — change it nowhere.
+        NESTED_NEW_ROW = "NEW_ROW"
+
+        # The Rails nested-attributes wire name for one row field — the name
+        # accepts_nested_attributes_for expects. Defaults to the template
+        # placeholder; pass index: for a server-rendered row. Scope-aware: the
+        # `<association>_attributes` base goes through reactive_scope FIRST, so
+        # a `reactive_scope :order` component emits
+        # order[line_items_attributes][3][quantity] (never a nested-bracket
+        # corruption of the scope wrap).
+        def nested_field_name(association, field, index: NESTED_NEW_ROW)
+          nested_identifier!(:nested_field_name, :association, association)
+          nested_identifier!(:nested_field_name, :field, field)
+          unless index.to_s == NESTED_NEW_ROW || index.to_s.match?(/\A\d+\z/)
+            raise ArgumentError,
+              "nested_field_name index: must be an integer or the NEW_ROW placeholder, " \
+              "got #{index.inspect} — anything else corrupts the bracketed wire name"
+          end
+
+          "#{scoped_field_name(:"#{association}_attributes")}[#{index}][#{field}]"
+        end
+
+        # The container cloned rows land in — one per association, inside the
+        # root. Server-rendered rows (an edit form's persisted children) render
+        # inside it too.
+        #
+        # `as: :json` (issue #208) switches the SUBMIT wire from Rails'
+        # accepts_nested_attributes_for names to ONE hidden JSON field — for an
+        # app whose controller already parses a serialized JSON param
+        # (`JSON.parse(params[:order][:todos])`) instead of nested attributes.
+        # The container keeps its plain marker (nestedAdd/Remove still key on
+        # it), and gains data-reactive-nested-json plus a scope-aware selector
+        # naming the hidden field the client mirrors the rows into on every
+        # add/remove/input. The default (:attributes) is unchanged — the plain
+        # accepts_nested_attributes_for wire.
+        def reactive_nested_list(association, as: :attributes)
+          name = nested_identifier!(:reactive_nested_list, :association, association)
+          data = { reactive_nested_list: name }
+          return { data: } if as == :attributes
+
+          unless as == :json
+            raise ArgumentError,
+              "reactive_nested_list(as:) takes :attributes (the default, Rails nested-attribute names) " \
+              "or :json (serialize the rows into one hidden JSON field), got #{as.inspect}"
+          end
+
+          # JSON mode: mark the container and name the hidden field the client
+          # keeps in sync — a scope-aware [name="…"] selector, the same
+          # convention reactive_tags/reactive_filter use so the field resolves
+          # under reactive_scope too.
+          data[:reactive_nested_json] = name
+          data[:reactive_nested_json_field] = %([name="#{scoped_field_name(association)}"])
+          { data: }
+        end
+
+        # The <template> holding ONE row's markup (server-owned, inert until
+        # cloned). Field names inside use nested_field_name's placeholder form.
+        def reactive_nested_template(association)
+          { data: { reactive_nested_template: nested_identifier!(:reactive_nested_template, :association,
+            association) } }
+        end
+
+        # The row wrapper marker — what nestedRemove resolves from its trigger
+        # (closest). Spread on the template row's outermost element AND on
+        # server-rendered rows, so both remove the same way.
+        def reactive_nested_row
+          { data: { reactive_nested_row: true } }
+        end
+
+        # The add-a-row trigger — CLIENT-ONLY (no dispatch descriptor, no
+        # POST). Forced type="button": a bare button inside the surrounding
+        # real <form> would submit it.
+        def reactive_nested_add(association)
+          {
+            type: "button",
+            data: {
+              action: "click->reactive#nestedAdd",
+              reactive_association_param: nested_identifier!(:reactive_nested_add, :association, association)
+            }
+          }
+        end
+
+        # A row's remove trigger — client-only. Draft rows leave the DOM;
+        # persisted rows (a hidden [_destroy] input present) are marked and
+        # hidden instead, so Rails destroys them on save.
+        def reactive_nested_remove
+          { type: "button", data: { action: "click->reactive#nestedRemove" } }
+        end
+
         # CROSS-ROOT value-conditional visibility (issue #164) — the visibility
         # parallel to reactive_compute's `mirror:` (#159). A plain reactive_show
         # is root-scoped by design (#15), so it can't express "this control
@@ -757,6 +890,22 @@ module Phlex
         #
         #   reactive_show_targets(mode: { "#advanced-tab" => "advanced" },
         #                         kind: { "#premium-note" => %w[gold platinum] })
+        #
+        # MULTI-FIELD targets (issue #209): a "#id" KEY takes a full
+        # if:/if_any:/unless: conditions Hash — the SAME language reactive_show
+        # speaks, so a cross-root target can finally read a COMBINATION of
+        # owned fields (the last case forcing a bespoke JS listener):
+        #
+        #   reactive_show_targets("#trade-warning" => {
+        #     if: { type: "trade", price: ..0 }   # type == "trade" AND price <= 0
+        #   })
+        #
+        # Target-keyed and field-keyed entries mix in the ONE call (a "#" key is
+        # unambiguous — a field name may never start with "#"). The client folds
+        # the target's DNF payload with the same per-term field reads as an
+        # in-root reactive_show: every referenced field must be OWNED by this
+        # root (a missing owned field reads as blank, fail-closed); a target
+        # whose fields are ALL unowned is left alone, like the single-field skip.
         def reactive_show_targets(field, targets = nil)
           field_maps = targets.nil? ? field : { field => targets }
           unless field_maps.is_a?(Hash) && field_maps.any?
@@ -766,16 +915,12 @@ module Phlex
           end
 
           normalized = field_maps.to_h do |name, map|
-            # Catch the forgotten-field-name misuse — reactive_show_targets(
-            # "#id" => {…}) — before the per-target validation turns it into a
-            # baffling "predicate" error.
             if name.to_s.start_with?("#")
-              raise ArgumentError,
-                "reactive_show_targets: #{name.inspect} looks like a target selector, not a field " \
-                "name — call reactive_show_targets(:field, #{name.inspect} => { ... })"
+              # Target-keyed conditions (issue #209): "#id" => { if:/if_any:/unless: }.
+              [name.to_s, normalize_show_target_conditions(name.to_s, map)]
+            else
+              [name.to_s, normalize_show_target_map(name, map)]
             end
-
-            [name.to_s, normalize_show_target_map(name, map)]
           end
 
           { data: { reactive_show_targets: normalized.to_json } }
@@ -924,6 +1069,18 @@ module Phlex
           value
         end
 
+        # An association/field name for the nested-rows wire (issue #208),
+        # validated to a plain Ruby identifier at render — it becomes an
+        # attribute value, a CSS selector fragment, AND a bracketed param name,
+        # so anything else is a dead (or corrupting) binding.
+        def nested_identifier!(helper, kind, name)
+          value = name.to_s
+          return value if value.match?(/\A[a-z_][a-z0-9_]*\z/)
+
+          raise ArgumentError,
+            "#{helper} needs a plain #{kind} name (e.g. :line_items), got #{name.inspect}"
+        end
+
         # Issue #179: apply a confirm: gate to a trigger's data hash. A String is
         # the static #52/#55 form (data-reactive-confirm-param, unchanged). A Hash
         # is the CONDITIONAL form (data-reactive-confirm-when-param, JSON) — warn
@@ -1003,6 +1160,40 @@ module Phlex
           end
         end
 
+        # Normalize + validate ONE target-keyed entry (issue #209): the "#id"
+        # key is a single id selector (the same declare-time guard as
+        # field-keyed targets), the value a full if:/if_any:/unless: conditions
+        # Hash compiled by ShowConditions into the SAME { "any" => groups } DNF
+        # payload reactive_show emits. Anything else — a bare value, unknown
+        # keys, empty conditions — raises a guided error at render (a dead
+        # binding must never reach the browser).
+        def normalize_show_target_conditions(selector, conditions)
+          unless selector.match?(DSL::MIRROR_ID_SELECTOR)
+            raise ArgumentError,
+              "reactive_show_targets target #{selector.inspect} must be a single " \
+              "ID selector (\"#id\") — cross-root visibility is id-allowlisted, like mirror: (#159)"
+          end
+          unless conditions.is_a?(Hash) && conditions.any?
+            raise ArgumentError,
+              "reactive_show_targets: a target key takes a conditions Hash — " \
+              "reactive_show_targets(#{selector.inspect} => { if: { field: value, ... } }); " \
+              "to key by field instead: reactive_show_targets(:field, #{selector.inspect} => value). " \
+              "Got #{selector.inspect} => #{conditions.inspect}"
+          end
+          # Unknown keys are reported BEFORE the presence check so { bogus: 1 }
+          # names its offender instead of the generic shape message (specific
+          # beats generic). A non-empty hash surviving this subtraction holds
+          # only condition keys, so no separate presence check remains.
+          if (unknown = conditions.keys - SHOW_CONDITION_KEYS).any?
+            raise ArgumentError,
+              "reactive_show_targets #{selector.inspect}: unknown conditions key(s) " \
+              "#{unknown.map(&:inspect).join(", ")} — a target's conditions Hash takes only " \
+              "if:/if_any:/unless: (the reactive_show language)"
+          end
+
+          { "any" => Phlex::Reactive::ShowConditions.normalize(**conditions) }
+        end
+
         # Reject the removed 0.9.5 reactive_show surface (issue #180 clean break)
         # with a GUIDED error printing the if:/if_any:/unless: rewrite. A
         # positional field, a predicate kwarg (equals:/not:/in:/gte:/…), or a

data/lib/phlex/reactive/engine.rb

@@ -122,6 +122,12 @@ module Phlex
         # once per boot; the events fire for APMs regardless of this flag.
         Phlex::Reactive::LogSubscriber.attach_to(:phlex_reactive) if Phlex::Reactive.log_events
 
+        # Attach the turnkey APM adapter (issue #207) when an app set
+        # Phlex::Reactive.apm. Resolution is deferred to HERE — after initializers
+        # ran, so the vendor SDK (if any) is loaded — and no-ops with one warning
+        # when the named SDK is absent (the pgbus optionality invariant). Idempotent.
+        Phlex::Reactive::APM.attach! if Phlex::Reactive.apm
+
         # Freeze the param-type registry (issue #109): custom types register in
         # an initializer, which has run by now, so no further registration is
         # accepted. A schema referencing a type is validated at declaration; the

data/lib/phlex/reactive/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Reactive
-    VERSION = "0.11.4"
+    VERSION = "0.11.6"
   end
 end