phlex-reactive 0.11.3 → 0.11.5

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

@@ -640,6 +640,197 @@ module Phlex
           }
         end
 
+        # Tag-chip input (issue #203) — the composed combobox/tags primitive.
+        # Spread onto the ROOT (mix with reactive_root); it names the hidden
+        # field that stores the COMMA-JOINED value, and the generic controller
+        # maintains that field + the chip list entirely client-side. The value
+        # is FORM state (like text in an input), never component state — so
+        # add/remove round-trips nothing; the surrounding form submit carries
+        # the joined value and the server splits it (`tags.split(",")`).
+        #
+        #   div(**mix(reactive_root, reactive_tags(:tags), reactive_filter(:tag_query))) do
+        #     input(type: :hidden, **reactive_field(:tags), value: @tags.join(","))
+        #     div(data: { reactive_tags_list: true }) { }             # chips render here
+        #     template(data: { reactive_tags_template: true }) do     # the chip markup (server-owned)
+        #       span(class: "chip") do
+        #         span(data: { reactive_tag_text: true })             # the client writes the tag here (textContent)
+        #         button(**reactive_tags_remove) { "×" }              # the client fills the tag param per chip
+        #       end
+        #     end
+        #     input(name: "tag_query", **mix(reactive_listnav, reactive_tags_add))
+        #     button(**reactive_tags_option("Ruby")) { "Ruby" }       # preloaded options, filter narrows them
+        #   end
+        #
+        # The chip list is a CLIENT PROJECTION of the hidden field: every sync
+        # rebuilds the chips by cloning the <template> (textContent writes only
+        # — never innerHTML), so the hidden value is the single source of truth
+        # and a server re-render/morph re-seeds cleanly. An option whose tag is
+        # already selected is hidden and marked data-reactive-tags-selected
+        # (reactive_filter keeps it hidden through re-filters). Tags dedupe
+        # case-insensitively, keeping the first casing.
+        #
+        # Composes with reactive_filter (type to narrow — same driving input)
+        # and reactive_listnav (Arrow/Enter/Escape; Enter picks the highlighted
+        # option via its own tagsPick trigger, and reactive_tags_add only adds
+        # the TYPED text when nothing is highlighted — no double add).
+        def reactive_tags(field = nil)
+          if field.nil? || field.to_s.strip.empty?
+            raise ArgumentError, "reactive_tags needs a field name — reactive_tags(:tags)"
+          end
+
+          # Compile the field to a scoped [name="…"] selector, the reactive_filter
+          # convention — so the hidden field written via reactive_field(:tags)
+          # resolves under reactive_scope too.
+          { data: { reactive_tags_field: %([name="#{scoped_field_name(field)}"]) } }
+        end
+
+        # The Enter-to-add trigger for the tags query input (issue #203) — a
+        # CLIENT-ONLY keyboard action (no dispatch descriptor, no POST). Mix it
+        # AFTER reactive_listnav so Enter prefers the highlighted option
+        # (listnavPick preventDefaults; tagsAdd then skips), and free text adds
+        # only when nothing is highlighted:
+        #   input(name: "tag_query", **mix(reactive_listnav, reactive_tags_add))
+        # Enter never submits the enclosing form — the client preventDefaults.
+        def reactive_tags_add
+          { data: { action: "keydown.enter->reactive#tagsAdd" } }
+        end
+
+        # A preloaded option row that ADDS its tag on click (issue #203) — the
+        # tags sibling of the combobox's on(:select) option, but CLIENT-ONLY
+        # (form state, no POST). Emits the [role=option] convention (so
+        # reactive_filter/reactive_listnav see it), the forced type="button" (a
+        # bare button inside a <form> would submit it), and the tag value the
+        # client reads. Compose extra attrs (the filter haystack, a testid) via
+        # mix. The tag can't contain a comma — it would corrupt the joined value.
+        def reactive_tags_option(tag)
+          {
+            type: "button",
+            role: "option",
+            data: {
+              action: "click->reactive#tagsPick",
+              reactive_tag_param: tags_tag!(:reactive_tags_option, tag)
+            }
+          }
+        end
+
+        # A chip's remove button (issue #203) — client-only, no POST. Two forms:
+        # inside the <template data-reactive-tags-template> chip, call it with NO
+        # tag (the client fills data-reactive-tag-param per cloned chip); on a
+        # server-rendered initial chip, pass the tag explicitly:
+        #   button(**reactive_tags_remove(tag)) { "×" }
+        def reactive_tags_remove(tag = nil)
+          attrs = { type: "button", data: { action: "click->reactive#tagsRemove" } }
+          attrs[:data][:reactive_tag_param] = tags_tag!(:reactive_tags_remove, tag) unless tag.nil?
+          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.
+        def reactive_nested_list(association)
+          { data: { reactive_nested_list: nested_identifier!(:reactive_nested_list, :association, association) } }
+        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
@@ -825,6 +1016,33 @@ module Phlex
           selector
         end
 
+        # A declared tag value for reactive_tags_option/reactive_tags_remove
+        # (issue #203), validated non-blank and comma-free at render — the hidden
+        # field is comma-joined, so a declared tag containing a comma would
+        # corrupt the stored value (and a blank tag is a dead trigger).
+        def tags_tag!(helper, tag)
+          value = tag.to_s.strip
+          raise ArgumentError, "#{helper} needs a non-blank tag, got #{tag.inspect}" if value.empty?
+          if value.include?(",")
+            raise ArgumentError,
+              "#{helper}(#{tag.inspect}): a tag can't contain a comma — the hidden field is comma-joined"
+          end
+
+          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

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.3"
+    VERSION = "0.11.5"
   end
 end