phlex-reactive 0.4.8 → 0.9.0

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

@@ -27,27 +27,112 @@ module Phlex
       wrap_parameters false if respond_to?(:wrap_parameters)
 
       def create
+        # ONE action.phlex_reactive event per request (issue #107). The event
+        # payload carries the component/action NAMES + outcome ONLY (never the
+        # token, params, or state); we fill it as those become known and set
+        # :outcome on every exit path — the success tail and each rescue. The
+        # rescue bodies are unchanged (verbose diagnostics + reactive_error per
+        # #82/#87); we only ADD the outcome finalizer. `action` is safe to read
+        # up front (it comes from the request, not the verified token).
+        event = { component: nil, action: reactive_action_name.to_s, outcome: nil }
+        Phlex::Reactive.instrument("action", event) do
+          create_action(event)
+        end
+      end
+
+      private
+
+      # The action body, run inside the instrument block so its payload (`event`)
+      # can be finalized on every exit path. Kept separate so `create` stays a
+      # thin instrument wrapper.
+      def create_action(event)
         payload = verified_payload
         component_class = resolve_component(payload["c"])
+        event[:component] = component_class.name
         action_def = component_class.reactive_action(reactive_action_name)
 
-        return head(:forbidden) unless action_def # default-deny
+        # default-deny
+        unless action_def
+          event[:outcome] = :denied_undeclared
+          return reactive_error(:forbidden, undeclared_action_message(component_class), kind: :forbidden)
+        end
 
         component = component_class.from_identity(payload)
-        coerced = coerce_params(action_def.params)
+        coerced = coerce_params(action_def, component_class:, action_name: action_def.name)
 
         result = run_action(component, action_def, coerced)
 
+        event[:outcome] = :ok
         render turbo_stream: response_streams(result, component)
-      rescue Phlex::Reactive::InvalidToken
-        head :bad_request
+      rescue Phlex::Reactive::InvalidToken => e
+        # The component name here came from an UNVERIFIED token — do NOT report it
+        # as trusted. Leave event[:component] nil.
+        event[:outcome] = :invalid_token
+        reactive_error(:bad_request, e.message, kind: e.diagnostic || :tampered)
       rescue ActiveRecord::RecordNotFound
-        head :not_found
-      rescue *authorization_errors
-        head :forbidden
+        event[:outcome] = :not_found
+        reactive_error(:not_found, record_not_found_message(payload), kind: :not_found)
+      rescue *authorization_errors => e
+        event[:outcome] = :unauthorized
+        reactive_error(:forbidden, authorization_error_message(e, component_class, action_def), kind: :forbidden)
       end
 
-      private
+      # Reply to an endpoint failure. The status NEVER changes with any flag —
+      # only the body. Precedence for the body (issue #100):
+      #   1. error_flash set → a turbo-stream flash the user actually SEES (the
+      #      client renders non-OK turbo-stream bodies). It wins over the verbose
+      #      diagnostic (both can't be the body); the diagnostic still logs below.
+      #   2. else verbose_errors → the plain-text diagnostic (client console.errors it).
+      #   3. else a bare head.
+      # The warn log fires in EVERY environment first, so a misbehaving client is
+      # debuggable from the server log alone regardless of which body path runs.
+      def reactive_error(status, message, kind: nil)
+        ::Rails.logger&.warn("[phlex-reactive] #{message}") if defined?(::Rails) && ::Rails.respond_to?(:logger)
+
+        flash = error_flash_stream(kind)
+        if flash
+          render turbo_stream: flash, status: status
+        elsif Phlex::Reactive.verbose_errors
+          render plain: message, status: status
+        else
+          head status
+        end
+      end
+
+      # Build the error flash turbo-stream when Phlex::Reactive.error_flash is
+      # configured, else nil (the non-flash body paths run). Degrades gracefully:
+      # a lambda that raises returns nil so the endpoint falls back to the bare/
+      # diagnostic body and NEVER turns one failure into a 500.
+      def error_flash_stream(kind)
+        callable = Phlex::Reactive.error_flash
+        return unless callable
+
+        message = callable.call(kind)
+        Phlex::Reactive::Response.flash_stream(:error, message, target: Phlex::Reactive.flash_target)
+      rescue => e # rubocop:disable Style/RescueStandardError
+        ::Rails.logger&.warn("[phlex-reactive] error_flash raised: #{e.message}") if defined?(::Rails) &&
+                                                                                     ::Rails.respond_to?(:logger)
+        nil
+      end
+
+      def undeclared_action_message(component_class)
+        declared = component_class.reactive_actions.keys.join(", ")
+        "action :#{reactive_action_name} is not declared on #{component_class.name} — " \
+          "declared actions: #{declared}"
+      end
+
+      def record_not_found_message(payload)
+        gid = payload.is_a?(Hash) && payload["gid"]
+        return "record not found" unless gid
+
+        "record #{gid} not found — deleted while a page still showed it?"
+      end
+
+      def authorization_error_message(error, component_class, action_def)
+        where = [component_class&.name, action_def&.name].compact.join("#")
+        "#{error.class.name} raised in #{where} — the signature proves identity, not permission; " \
+          "authorize in the action"
+      end
 
       # Run the action inside a transaction so transactional broadcasts (pgbus
       # broadcasts_to ... durable:) defer to after_commit and never fire for a
@@ -57,18 +142,60 @@ module Phlex
       # for the duration of the action via Phlex::Reactive.current_connection_id,
       # so a broadcast in the action can pass exclude: reactive_connection_id
       # and skip the actor's own echo.
+      #
+      # The component-aware around_action stack (issue #112) folds in HERE —
+      # INSIDE with_connection_id (so a wrapper's own broadcast can exclude the
+      # actor) but OUTSIDE transaction_wrapper (so a rate-limit rejection never
+      # opens a transaction, and an audit wrapper observes commit/rollback). The
+      # fold returns the continuation's value unchanged, so the action's
+      # Phlex::Reactive::Response survives to response_streams.
       def run_action(component, action_def, coerced)
         Phlex::Reactive.with_connection_id(request.headers["X-Pgbus-Connection"]) do
-          transaction_wrapper do
-            if coerced.any?
-              component.public_send(action_def.name, **coerced)
-            else
-              component.public_send(action_def.name)
+          with_around_actions(component, action_def, coerced) do
+            transaction_wrapper do
+              if coerced.any?
+                component.public_send(action_def.name, **coerced)
+              else
+                component.public_send(action_def.name)
+              end
             end
           end
         end
       end
 
+      # Fold the registered around_action wrappers around `block`, innermost being
+      # the transactioned action. The empty-stack fast path is a bare `yield` —
+      # the default request gains only one Array#empty? check. Each wrapper is
+      # called with the frozen ActionContext and the continuation as its block, so
+      # a well-behaved wrapper returns action.call's value and the action's
+      # Response propagates out unchanged (issue #112).
+      #
+      # Fold: seed the accumulator with the innermost action, then walk the stack
+      # oldest → newest wrapping each wrapper AROUND the accumulated continuation.
+      # The FIRST-registered wrapper wraps the action, and each later wrapper wraps
+      # that — so the LAST-registered runs OUTERMOST (LIFO nesting).
+      def with_around_actions(component, action_def, coerced, &block)
+        stack = Phlex::Reactive.around_actions
+        return yield if stack.empty?
+
+        # A frozen DUP of the coerced params, not the live hash: the same hash is
+        # splatted into the action below, so sharing it would let a wrapper mutate
+        # ctx.params and alter the action's actual inputs — breaking both the
+        # observe-only context contract and the schema-coercion guarantee. The
+        # dup+freeze runs only when a wrapper is registered (never the empty-stack
+        # hot path).
+        ctx = Phlex::Reactive::ActionContext.new(
+          component: component,
+          action_name: action_def.name,
+          params: coerced.dup.freeze,
+          request: request
+        )
+
+        stack.reduce(block) do |inner, wrapper|
+          -> { wrapper.call(ctx, &inner) }
+        end.call
+      end
+
       # Turn the action's return value into the turbo-stream(s) to render for
       # the actor. A Phlex::Reactive::Response is honored explicitly; any other
       # value (the legacy contract — return value ignored) falls back to the
@@ -101,49 +228,89 @@ module Phlex
         # replace when a hand-built `with(...)` stream omits it. Idempotent: a
         # Response.replace(self)/update(self) already carries the token, so we
         # don't double the self-render.
-        if result.render_self? && streams.none? { it.include?("data-reactive-token-value") }
+        #
+        # GUARD 2 (issue #114): GLOBAL, un-scoped — "does ANY stream carry a
+        # token?", NOT target-scoped. A Stream answers from its precomputed
+        # ground-truth flag (rx_carries_token?), a raw string from a substring
+        # scan. Deliberately NOT rx_refreshes_token_for? (target-scoped): scoping
+        # this guard would regress update/morph of self on an aliased id.
+        if result.render_self? && streams.none? { stream_carries_token?(it) }
           streams = [component.to_stream_replace, *streams]
         end
         streams
       end
 
+      # GUARD 2 predicate. A Stream with intact metadata answers structurally
+      # (O(1) flag read); a raw string / metadata-degraded object falls back to
+      # the substring scan the endpoint always used.
+      def stream_carries_token?(stream)
+        if stream.is_a?(Phlex::Reactive::Stream) && stream.rx_action
+          stream.rx_carries_token?
+        else
+          stream.include?(Phlex::Reactive::Stream::TOKEN_ATTR)
+        end
+      end
+
       # Actions that RE-RENDER the component's own root (so the root's fresh
       # data-reactive-token-value rolls the signed token forward). `append`/
       # `prepend` are deliberately excluded: they insert CHILDREN into the
       # component, and a reactive child carries its OWN token — that child token is
       # not the component's (issue #44). reactive:token is our inert token-only
       # refresh; replace/update re-render the root.
+      #
+      # Issue #114: a Phlex::Reactive::Stream now knows its own action structurally
+      # (Stream::SELF_RENDER_ACTIONS), so this allowlist survives ONLY for the
+      # LEGACY regex fallback below — the path raw strings (reply.with,
+      # interpolated/degraded streams) take. The primary path is structural.
       SELF_RENDER_ACTIONS = %w[replace update reactive:token].freeze
       private_constant :SELF_RENDER_ACTIONS
 
-      # True when one of `streams` already carries a fresh token by RE-RENDERING
-      # this component itself — i.e. the caller hand-built the actor's own
-      # token-bearing stream, so appending to_stream_token would double it.
+      # GUARD 1 (issue #114): true when one of `streams` already carries a fresh
+      # token by RE-RENDERING this component itself — so appending to_stream_token
+      # would double it. Target+root scoped (distinct from GUARD 2's global scan).
       #
-      # The match requires BOTH (a) the stream's action re-renders the component's
-      # ROOT (replace/update/reactive:token — never append/prepend, which insert
-      # children) AND (b) it targets the component's id AND (c) it actually carries
-      # a token. This is stricter than a same-string substring check on purpose:
-      #   * A sibling component's replace targets a DIFFERENT id → (b) fails, so we
+      # A Phlex::Reactive::Stream answers STRUCTURALLY (rx_refreshes_token_for? —
+      # the three-way test carries_token AND renders_root AND same target, no
+      # regex). A raw string / metadata-degraded object falls back to the legacy
+      # opening-tag regex, which encodes the same rule:
+      #   * A sibling component's replace targets a DIFFERENT id → no match, so we
       #     still refresh ours (issue #30).
       #   * A reactive child row appended/prepended INTO the component carries its
-      #     own token at the component's target, but the action is append/prepend →
-      #     (a) fails, so we still refresh the CONTAINER's token (issue #44). Before
-      #     this, the child's token at the container target suppressed the
-      #     container's refresh and the list was add-once-only.
+      #     own token at the component's target, but append/prepend do NOT
+      #     re-render the root → no match, so we still refresh the CONTAINER's
+      #     token (issue #44). Before this, the child's token at the container
+      #     target suppressed the container's refresh and the list was
+      #     add-once-only.
       def carries_token_for?(streams, component)
-        target = %(target="#{ERB::Util.html_escape(component.id)}")
-        streams.any? do
-          it.include?("data-reactive-token-value") &&
-            it.include?(target) &&
-            self_render_stream_for?(it, target)
+        streams.any? { stream_refreshes_token_for?(it, component.id) }
+      end
+
+      # Per-stream GUARD 1 predicate: a Stream with intact metadata answers
+      # structurally (rx_refreshes_token_for?); a raw string / metadata-degraded
+      # object falls back to the legacy opening-tag regex.
+      def stream_refreshes_token_for?(stream, component_id)
+        if stream.is_a?(Phlex::Reactive::Stream) && stream.rx_action
+          stream.rx_refreshes_token_for?(component_id)
+        else
+          legacy_self_render_token?(stream, component_id)
         end
       end
 
+      # LEGACY fallback for raw strings (reply.with) and metadata-degraded
+      # streams: the pre-#114 substring + opening-tag regex, kept verbatim as the
+      # floor beneath the structural path.
+      def legacy_self_render_token?(stream, component_id)
+        target = %(target="#{ERB::Util.html_escape(component_id)}")
+        stream.include?("data-reactive-token-value") &&
+          stream.include?(target) &&
+          self_render_stream_for?(stream, target)
+      end
+
       # Does this turbo-stream's OPENING tag re-render `target` itself? Matches a
       # `<turbo-stream action="<self-render>" ... target="<id>">` opening tag — the
       # action and target on the SAME tag — so a child row's token embedded in an
       # append/prepend `<template>` can never count as the container's own refresh.
+      # LEGACY: only the raw-string fallback reaches this now.
       def self_render_stream_for?(stream, target)
         open_tag = stream[/<turbo-stream\b[^>]*>/]
         return false unless open_tag&.include?(target)
@@ -170,7 +337,11 @@ module Phlex
 
       def verified_payload
         token = params.require(:token)
-        Phlex::Reactive.verify(token) || raise(Phlex::Reactive::InvalidToken)
+        Phlex::Reactive.verify(token) || raise(Phlex::Reactive::InvalidToken.new(
+          "token signature invalid — stale token from before a deploy? secret_key_base mismatch? " \
+          "a reply.with(...) stream that skipped the token refresh?",
+          diagnostic: :tampered
+        ))
       end
 
       # NB: must NOT be named `action_name` — that's reserved by
@@ -179,158 +350,88 @@ module Phlex
         params.require(:act).to_sym
       end
 
-      # Coerce client params against the action's declared schema. Anything not
+      # Coerce client params against the action's compiled schema (issue #109 —
+      # the coerce family now lives in Phlex::Reactive::ParamSchema). Anything not
       # in the schema is dropped — no raw mass assignment reaches the component.
-      # The top-level params arrive as an ActionController::Parameters; coerce
-      # them against the action's hash schema (same recursion as nested hashes).
-      def coerce_params(schema)
-        return {} if schema.blank?
-
-        coerce_hash(params.fetch(:params, {}), schema)
-      end
-
-      # Sentinel: a declared key whose value can't be coerced to its type is
-      # DROPPED (not assigned), so the method's keyword default applies — exactly
-      # as if the client had omitted the key. Distinct from a coerced nil/[].
-      DROP = Object.new
-      private_constant :DROP
-
-      # Coerce a value against a declared type. A type is one of:
-      #   * a scalar symbol            (:string/:integer/:float/:boolean)
-      #   * :file                      — a multipart upload (issue #34)
-      #   * a Hash schema              ({ id: :integer, ... })   — nested object
-      #   * a one-element Array        ([:integer] / [{ ... }])  — array of that
-      # Arrays accept both a real JSON array and a Rails-style index hash
-      # ({ "0" => ..., "1" => ... }), so a fields_for collection works either way.
-      def coerce(value, type)
-        case type
-        when Array
-          coerce_array(value, type.first)
-        when Hash
-          coerce_hash(value, type)
-        when :file
-          coerce_file(value)
-        else
-          coerce_scalar(value, type)
-        end
-      end
-
-      # An uploaded file (issue #34) passes through UNTOUCHED — never .to_s'd,
-      # which would corrupt it into a string the action can't attach. Anything
-      # that isn't an uploaded file (a forged/malformed scalar, an empty input)
-      # returns DROP, so the method's keyword default applies — consistent with
-      # the #16 rule that a value that can't be coerced to its type is dropped,
-      # not fabricated. Duck-types on UploadedFile's interface (original_filename
-      # + a readable IO) rather than naming a class, so a Rack::Test upload, an
-      # ActionDispatch upload, and a Falcon multipart body all qualify.
-      def coerce_file(value)
-        uploaded_file?(value) ? value : DROP
-      end
-
-      def uploaded_file?(value)
-        value.respond_to?(:original_filename) && value.respond_to?(:read)
-      end
-
-      # A real array (or Rails index hash) coerces element-wise. A malformed
-      # present-but-non-array value returns DROP rather than [] — coercing a stray
-      # scalar to an empty array would let a bad payload read as an explicit
-      # "clear everything" on update!(declared_array:).
       #
-      # An ELEMENT that coerces to DROP (e.g. a non-file in a [:file] array, a
-      # forged/mixed payload) is rejected from the result — the same rule
-      # coerce_hash applies to a dropped value, so the internal DROP sentinel
-      # never leaks into the action. A genuinely empty input array stays [] (an
-      # explicit empty collection), but an array whose every element drops
-      # returns DROP, so the keyword default applies rather than handing the
-      # action a surprise [].
-      def coerce_array(value, element_type)
-        values = array_values(value)
-        return DROP if values.nil?
-        return [] if values.empty?
-
-        coerced = values.map { coerce(it, element_type) }
-        coerced.reject! { it.equal?(DROP) }
-        coerced.empty? ? DROP : coerced
-      end
-
-      # Keep declared keys only (drop undeclared — no mass assignment), recursing
-      # for nested hash/array element types. Symbolizes keys to splat as kwargs.
-      # A key whose value coerces to DROP is skipped (keyword default applies).
-      def coerce_hash(value, schema)
-        hash = to_param_hash(value)
-        schema.each_with_object({}) do |(key, type), out|
-          next unless hash.key?(key.to_s)
-
-          coerced = coerce(hash[key.to_s], type)
-          next if coerced.equal?(DROP)
-
-          out[key.to_sym] = coerced
-        end
+      # With verbose_errors on, ParamSchema fills a collector with every dropped
+      # key (full bracketed path + reason) and we warn-log it once per action.
+      # With the flag off the collector is nil and every diagnostic branch is
+      # skipped — zero extra work on the production path.
+      def coerce_params(action_def, component_class: nil, action_name: nil)
+        dropped = Phlex::Reactive.verbose_errors ? [] : nil
+        raw = params.fetch(:params, {})
+
+        coerced = action_def.schema.coerce(raw, dropped)
+        log_dropped_params(dropped, action_def.params, component_class, action_name)
+        coerced
       end
 
-      def coerce_scalar(value, type)
-        case type
-        when :integer then value.to_i
-        when :float then value.to_f
-        when :boolean then ActiveModel::Type::Boolean.new.cast(value)
-        else value.to_s
-        end
+      # ---- verbose_errors dropped-param logging --------------------------
+      # ParamSchema collects the dropped entries; the controller formats the ONE
+      # warn line (with the #16/#21 shape hints). Everything below runs ONLY when
+      # the collector exists (flag on); the production path never reaches it.
+
+      # ONE warn line per action naming every dropped param with its reason —
+      # plus, for the #16/#21 confusion, a hint when a dropped name looks like
+      # the flat/bracketed twin of a declared key. `schema` is the RAW declared
+      # hash (action_def.params), read only for the shape hints.
+      def log_dropped_params(dropped, schema, component_class, action_name)
+        return if dropped.nil? || dropped.empty?
+        return unless defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
+
+        entries = dropped.map { |path, reason| "#{path} (#{dropped_reason(path, reason, schema)})" }
+        where = [component_class, action_name].compact.join("#")
+        where = "#{where} " unless where.empty?
+        ::Rails.logger.warn("[phlex-reactive] #{where}dropped params: #{entries.join(", ")}")
       end
 
-      # Normalize an array param: a real array passes through; a Rails index hash
-      # ({ "0" => ..., "1" => ... }) becomes its values in index order. Anything
-      # else (a stray scalar, nil) is malformed → nil, so the caller drops the
-      # param rather than fabricating an empty array.
-      def array_values(value)
-        return value.to_a if value.is_a?(Array)
+      def dropped_reason(path, reason, schema)
+        return reason.to_s unless reason == :undeclared
+        return "undeclared — the action declares no params" if schema.empty?
 
-        return unless value.respond_to?(:to_unsafe_h) || value.is_a?(Hash)
-
-        to_param_hash(value).sort_by { |k, _| k.to_i }.map(&:last)
+        hint = shape_hint(path, schema)
+        hint ? "undeclared — #{hint}" : "undeclared"
       end
 
-      # Unwrap ActionController::Parameters (or a plain Hash) to a string-keyed
-      # Hash so coercion can index it uniformly, then expand bracket notation so
-      # a model-scoped Rails form's flat keys nest (issue #21).
-      def to_param_hash(value)
-        flat =
-          if value.respond_to?(:to_unsafe_h)
-            value.to_unsafe_h.stringify_keys
-          elsif value.is_a?(Hash)
-            value.stringify_keys
-          else
-            return {}
-          end
+      # Fires only when a dropped segment matches a DECLARED key at a different
+      # nesting level — a bracketed name whose leaf the schema declares flat, or
+      # a flat name the schema declares one level down. Deliberately simple: it
+      # searches one nesting level (hash / array-of-hash), no deeper.
+      def shape_hint(path, schema)
+        segments = bracket_path(path)
+        if segments.length > 1
+          leaf = segments.last
+          return unless schema.key?(leaf.to_sym)
+
+          "schema declares :#{leaf} at top level; nested schemas look like " \
+            "{ #{segments.first}: { #{leaf}: :string } }"
+        else
+          parent = nested_declaration_of(segments.first, schema)
+          return unless parent
 
-        expand_bracket_keys(flat)
+          "schema declares :#{segments.first} nested under :#{parent}; " \
+            "post it as #{parent}[#{segments.first}]"
+        end
       end
 
-      # The client's #collectFields keeps a form input's name verbatim, so a
-      # Rails Form(model: @invoice) posts FLAT bracketed keys like
-      # "invoice[date]". Coercion does exact-key matching, so without this a
-      # nested schema (params: { invoice: { date: … } }) never finds "invoice"
-      # and drops everything. Expand "invoice[date]" => "2026-01-02" into
-      # { "invoice" => { "date" => "2026-01-02" } } — and "items[0][qty]" into
-      # the Rails index-hash form coerce_array already understands — deep-merging
-      # so sibling keys (invoice[date], invoice[status]) coalesce. Keys WITHOUT
-      # brackets and already-nested values pass through untouched, so a
-      # pre-nested object (issue #16) and plain scalars still work. Value types
-      # (a checkbox boolean, an explicit array) are preserved verbatim — unlike a
-      # round-trip through parse_nested_query, which only handles strings.
-      def expand_bracket_keys(flat)
-        flat.each_with_object({}) do |(key, value), out|
-          deep_assign(out, bracket_path(key), value)
-        end
+      # The first schema key whose nested hash (or array-of-hash element
+      # schema) declares `name` one level down.
+      def nested_declaration_of(name, schema)
+        schema.find do |_key, type|
+          inner = type.is_a?(Array) ? type.first : type
+          inner.is_a?(Hash) && inner.key?(name.to_sym)
+        end&.first
       end
 
       # Matches each bracket segment in "items_attributes][0][qty]" — the part
-      # after the first "[". Hoisted to a frozen constant so coercing a bracketed
-      # key doesn't recompile the pattern per key on every request.
+      # after the first "[". Hoisted to a frozen constant so the shape-hint path
+      # (verbose only) doesn't recompile the pattern per call.
       BRACKET_SEGMENT = /[^\[\]]+/
       private_constant :BRACKET_SEGMENT
 
-      # "invoice[items_attributes][0][qty]" => ["invoice", "items_attributes",
-      # "0", "qty"]. A key with no brackets is a single-element path.
+      # "invoice[date]" => ["invoice", "date"]. A key with no brackets is a
+      # single-element path. Used only to shape the dropped-param hint.
       def bracket_path(key)
         return [key] unless key.include?("[")
 
@@ -338,35 +439,26 @@ module Phlex
         [head, *rest.scan(BRACKET_SEGMENT)]
       end
 
-      # Walk/create nested hashes along `path`, then merge `value` at the leaf so
-      # a bracket key and a sibling pre-nested object coalesce regardless of which
-      # arrives first ({ "invoice[date]" => …, invoice: { status: … } } keeps
-      # both). #merge_value deep-merges hash/hash collisions and otherwise lets
-      # the later value win (a bracket key colliding with a flat scalar).
-      def deep_assign(hash, path, value)
-        *parents, leaf = path
-        node = parents.reduce(hash) do |acc, segment|
-          acc[segment] = {} unless acc[segment].is_a?(Hash)
-          acc[segment]
-        end
-        node[leaf] = merge_value(node[leaf], value)
-      end
-
-      # Combine an existing leaf value with a new one. Two hashes deep-merge (so
-      # bracket-expanded fields and a pre-nested object for the same key both
-      # survive); any other collision takes the new value.
-      def merge_value(existing, value)
-        return value unless existing.is_a?(Hash) && value.is_a?(Hash)
-
-        existing.merge(value.stringify_keys) { |_k, old, new| merge_value(old, new) }
-      end
+      # ---- end verbose_errors logging ------------------------------------
 
       # Only components that opt into Reactive may be resolved. The signature
-      # already gates this; defense in depth against constant injection.
+      # already gates this; defense in depth against constant injection. The
+      # two failure causes carry distinct diagnostics: a name that doesn't
+      # resolve at all vs a constant that resolved but isn't a reactive
+      # component.
       def resolve_component(name)
         klass = name.to_s.safe_constantize
+        unless klass
+          raise Phlex::Reactive::InvalidToken.new(
+            "token class #{name} does not resolve — component renamed/removed while a page was open?",
+            diagnostic: :unknown_class
+          )
+        end
         unless klass.respond_to?(:reactive_action?) && klass.include?(Phlex::Reactive::Component)
-          raise Phlex::Reactive::InvalidToken
+          raise Phlex::Reactive::InvalidToken.new(
+            "#{name} resolved but does not include Phlex::Reactive::Component",
+            diagnostic: :not_reactive_class
+          )
         end
 
         klass

data/app/javascript/phlex/reactive/compute.js

@@ -20,17 +20,62 @@
 //     allowance, leasing, cash: total - allowance - leasing,
 //   }))
 //
-// The reducer receives a plain object of { inputName: Number } and returns a
-// plain object of { outputName: value } — only the outputs it names are written,
-// so it can leave the edited field (and its caret) untouched. Returning the SAME
-// value it read is a no-op write; the controller still fires `input` on any field
-// it sets so a chained summary repaints, matching the server's set_value +
-// dispatch("input") contract.
+// The reducer's signature is (values, meta):
+//
+//   values — a plain object of { inputName: value } over the declared inputs.
+//            Untyped inputs (the array form) AND :number-typed inputs arrive as
+//            Numbers (blank/NaN → 0); :string-typed inputs (the hash form,
+//            issue #104) arrive as the RAW string. `reactive_compute :x, inputs:
+//            { title: :string, qty: :number }` is what selects per-input types;
+//            `inputs: %i[a b]` stays all-numeric (backward compatible).
+//   meta   — { changed }: the name (string) of the declared input the
+//            triggering event edited, or null (a direct recompute() call, or a
+//            target this root doesn't own / didn't declare as an input).
+//
+// OUTPUTS may be a form FIELD or a TEXT NODE (issue #104). An output whose name
+// matches an owned control writes its .value (+ the change-guarded input
+// dispatch below). An output with NO matching field writes textContent to every
+// owned [data-reactive-text="<name>"] node (reactive_text(:name)) — XSS-safe by
+// construction, change-guarded, NO input dispatch (a text node has no listener
+// contract). A declared INPUT also mirrors into its own text node on every
+// input via an always-run pass — so reactive_text(:title) is a live field
+// preview with NO registered reducer at all.
+//
+// It returns a plain object of { outputName: value } — only the outputs it
+// names are written, so it can leave the edited field (and its caret)
+// untouched. A one-argument reducer keeps working unchanged (it just ignores
+// meta). `changed` is what makes a MULTI-WAY / MUTUAL rebalance expressible as
+// one reducer (issue #75) — branch on which field the user edited:
+//
+//   setComputeReducer("three_way_split", ({ field_a, field_b, field_c, total }, { changed }) => {
+//     if (changed === "field_c") return { field_a: total - field_c - field_b }
+//     return { field_c: total - field_a - field_b }
+//   })
+//
+// Output writes are CHANGE-GUARDED: the controller writes a field and
+// dispatches a bubbling `input` event on it ONLY when the new value differs
+// from the field's current value (real browsers never fire `input` on a
+// programmatic .value write, so the controller dispatches explicitly — that's
+// what drives a chained summary repaint, matching the server's set_value +
+// dispatch("input") contract). Returning the SAME value a field already holds
+// is skipped entirely — no write, no event — which is why a reducer with
+// overlapping inputs/outputs (like payment_split above) settles instead of
+// re-entering itself forever.
+//
+// CONVERGENCE REQUIREMENT: because an output write dispatches a REAL input
+// event (issue #76), recompute re-enters with changed = that OUTPUT field's
+// name (when it's also a declared input). A branching reducer must therefore
+// be convergent: the re-entrant pass must compute values EQUAL to what the
+// first pass already wrote to the DOM, so the change guard settles the chain.
+// The three_way_split above is: after `changed === "field_a"` writes field_c,
+// the re-entrant `changed === "field_c"` pass derives field_a back to the
+// value it already holds — no write, no event, settled in one bounce.
 
 const reducers = new Map()
 
 // Register (or replace) the reducer for `key`. `fn` is
-// (values: Record<string, number>) => Record<string, unknown>.
+// (values: Record<string, number>, meta: { changed: string | null })
+//   => Record<string, unknown>.
 export function setComputeReducer(key, fn) {
   reducers.set(key, fn)
 }