phlex-reactive 0.13.4 → 0.14.1

data/lib/phlex/reactive/fragment.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+require "base64"
+require "digest"
+require "json"
+
+module Phlex
+  module Reactive
+    # Privately cacheable lazy renders (issue #277): the signed id and URL of a
+    # `reactive_lazy cache: { max_age: }` component's GET fragment.
+    #
+    # The id is a DETERMINISTIC signature over the component's identity payload
+    # — no expiry, no actor binding, purpose-scoped — so the same component
+    # renders the same URL on every page view and the browser's private HTTP
+    # cache can reuse the response. It names NO viewer: who the render is for
+    # always comes from the session at the endpoint. (Like the identity token it
+    # does carry the signed state / record gid — signed, not encrypted.) The
+    # purpose makes it disjoint
+    # from the identity and defer tokens: a fragment id can't run an action or
+    # reach the defer endpoint, and neither of those tokens resolves here.
+    #
+    # Two unsigned query parameters only shape the browser's cache KEY — the
+    # render never reads them:
+    #   v — a digest of the component's reactive_cache_version (content changed)
+    #   u — a KEYED digest of its reactive_cache_viewer (who the render is
+    #       for). The endpoint recomputes it in the CURRENT session and makes
+    #       the reply cacheable only when it matches, so a URL can only ever
+    #       hold the render of the viewer it names. A blank viewer names nobody:
+    #       no `u`, and the reply falls back to `Vary: Cookie`.
+    module Fragment
+      # The purpose of the previous id format (still verified, see verify).
+      PURPOSE = "phlex-reactive/fragment"
+      # The purpose the current id's MAC is keyed under (issue #306).
+      ID_PURPOSE = "phlex-reactive/fragment-id"
+      # 128 bits of MAC: 22 base64url characters.
+      MAC_BYTES = 16
+      MAC_LENGTH = 22
+      BASE64URL = /\A[A-Za-z0-9_-]+\z/
+      VIEWER_PURPOSE = "phlex-reactive/fragment-viewer"
+      # A viewer is an identity — an id, or a few of them. These bound how far
+      # a collection is walked, so no value can make the shell render slow.
+      VIEWER_PART_LIMIT = 32
+      VIEWER_NODE_LIMIT = 64
+      # Components already warned about (by class name): once per component.
+      VIEWER_WARNED = Concurrent::Map.new
+
+      # A reactive_cache_viewer value that cannot name a viewer. Internal: it
+      # carries the reason from the walk to viewer_param, which logs it.
+      class UnusableViewer < StandardError; end
+
+      module_function
+
+      # The signed id of an identity payload (issue #306):
+      #
+      #   base64url(JSON payload) + base64url(128-bit MAC)
+      #
+      # The payload is encoded ONCE and the MAC is a fixed 22 characters, so the
+      # id is one URL path segment of base64url characters with no separator
+      # (a "." would read as a format suffix to the router). The MAC is keyed
+      # through the configured verifier — a digest of its signature over the
+      # encoded payload under its own purpose, the same construction as the
+      # viewer digest — so it works with any verifier the app configured and
+      # cannot be computed without the app's secret. Deterministic: the same
+      # identity always renders the same URL, which is what lets the browser's
+      # cache hit.
+      def sign(payload)
+        data = Base64.urlsafe_encode64(JSON.generate(payload.merge("v" => TOKEN_VERSION)), padding: false)
+        "#{data}#{compact_mac(data)}"
+      end
+
+      # The verified, version-upgraded payload, or nil — tampered, a token of
+      # another purpose, or no fragment id at all. The current format is tried
+      # first, then the previous one: a browser may still hold a page or a
+      # cached fragment URL minted before #306 (for up to
+      # fragment_cache_max_age_limit).
+      def verify(id)
+        id = id.to_s
+        payload = verify_compact(id) || verify_legacy(id)
+        payload && Phlex::Reactive.upgrade_token(payload)
+      end
+
+      # The MAC is checked BEFORE the data is decoded or parsed. Anything but
+      # base64url characters is not an id (and never reaches the verifier).
+      def verify_compact(id)
+        return nil unless id.length > MAC_LENGTH && id.match?(BASE64URL)
+
+        data = id[0...-MAC_LENGTH]
+        return nil unless ActiveSupport::SecurityUtils.secure_compare(compact_mac(data), id[-MAC_LENGTH..])
+
+        payload = JSON.parse(Base64.urlsafe_decode64(data))
+        payload.is_a?(::Hash) ? payload : nil
+      rescue ::ArgumentError, JSON::ParserError
+        nil
+      end
+
+      # The previous format: the verifier's token (Base64 + "--" + digest)
+      # wrapped in urlsafe Base64. Kept for one release (issue #306).
+      def verify_legacy(id)
+        Phlex::Reactive.verifier.verified(Base64.urlsafe_decode64(id), purpose: PURPOSE)
+      rescue ::ArgumentError
+        nil
+      end
+
+      # `data` is pinned to US-ASCII (it is base64url): the id is minted as a
+      # US-ASCII String but arrives as a UTF-8 param, and a Marshal-serializing
+      # verifier (load_defaults < 7.1) signs the encoding along with the bytes.
+      def compact_mac(data)
+        data = data.dup.force_encoding(Encoding::US_ASCII)
+        digest_param(Digest::SHA256.digest(Phlex::Reactive.verifier.generate(data, purpose: ID_PURPOSE)), MAC_BYTES)
+      end
+
+      # The fragment URL the shell renders into data-reactive-defer-src:
+      # <fragment_path>/<signed id>[?v=<version digest>][&u=<viewer digest>].
+      # `version` is the component's reactive_cache_version (nil → no `v`);
+      # `viewer` is its ALREADY-DIGESTED viewer_param (nil → no `u`).
+      def src(payload, version: nil, viewer: nil)
+        query = []
+        query << "v=#{version_param(version)}" unless version.nil?
+        query << "u=#{viewer}" if viewer
+        path = "#{Phlex::Reactive.fragment_path}/#{sign(payload)}"
+        query.empty? ? path : "#{path}?#{query.join("&")}"
+      end
+
+      # `v` only varies the browser's cache KEY — the endpoint never reads it —
+      # so it is digested: short, opaque, and safe for any value an app returns
+      # (a Time keeps its sub-second precision, a record its cache key). 64
+      # bits as 11 base64url characters: a cache-buster, not a secret.
+      def version_param(version)
+        key = version.respond_to?(:utc) ? version.utc.strftime("%Y%m%d%H%M%S%N") : version
+        digest_param(Digest::SHA256.digest(ActiveSupport::Cache.expand_cache_key(key)), 8)
+      end
+
+      def digest_param(digest, bytes)
+        Base64.urlsafe_encode64(digest.byteslice(0, bytes), padding: false)
+      end
+
+      # The `u` of a reactive_cache_viewer value, or nil when the value names
+      # NO viewer — nil, false, a blank String, or an Array with any blank part
+      # or Hash with any blank leaf (`[Current.user&.id, locale]` signed out),
+      # or a value whose cache key is empty. A blank viewer must never
+      # become a shared "anonymous" key: every signed-out or mis-resolved
+      # session would then store and read ONE url with no Vary. nil sends the
+      # component back to the default mode (`Vary: Cookie`) for that render.
+      #
+      # KEYED: the digest is taken over the verifier's signature of the value,
+      # so it can be neither reversed to the value (a user id is a small space)
+      # nor computed for someone else without the app's secret. 128 bits, as
+      # 22 base64url characters.
+      #
+      # NEVER RAISES and never takes long, whatever the hook returned: this runs
+      # inside the host page's render. A value that cannot be turned into a key
+      # (it raises, it is endless, it is huge) names nobody — the fail-closed
+      # default mode — and is logged once per component (`owner`, its class).
+      def viewer_param(viewer, owner: nil)
+        return nil unless viewer_named?(viewer)
+
+        signed = Phlex::Reactive.verifier.generate(ActiveSupport::Cache.expand_cache_key(viewer),
+          purpose: VIEWER_PURPOSE)
+        digest_param(Digest::SHA256.digest(signed), 16)
+      rescue UnusableViewer => e
+        warn_unusable_viewer(owner, e.message)
+      rescue StandardError => e
+        warn_unusable_viewer(owner, "#{e.class}: #{e.message}")
+      end
+
+      def viewer_named?(viewer)
+        named_within?(viewer, [VIEWER_NODE_LIMIT])
+      end
+
+      # Every LEAF must name something. A collection — anything
+      # expand_cache_key walks with to_a: an Array, a Hash (keys and values), a
+      # Set, a Struct, a sized Enumerator, nested — with one blank part is
+      # unnamed, and so is a value whose cache key expands to nothing (an
+      # object with a blank to_param). 0 is a viewer.
+      #
+      # Bounded: a Range is never walked, a collection of more than
+      # VIEWER_PART_LIMIT parts or a walk of more than VIEWER_NODE_LIMIT values
+      # (a self-referential Array, a to_a that returns itself) is unnamed.
+      # `budget` is a one-element counter shared by the whole walk.
+      def named_within?(value, budget)
+        return false if value.nil? || value == false
+        raise UnusableViewer, "a Range is not an identity" if value.is_a?(::Range)
+        raise UnusableViewer, "too deep or self-referential" if (budget[0] -= 1).negative?
+        return viewer_leaf?(value) unless value.respond_to?(:to_a) && !value.respond_to?(:cache_key)
+
+        size = value.respond_to?(:size) ? value.size : nil
+        raise UnusableViewer, "a collection of unknown or excessive size" unless viewer_size_ok?(size, value)
+
+        parts = value.to_a
+        raise UnusableViewer, "more than #{VIEWER_PART_LIMIT} parts" if parts.size > VIEWER_PART_LIMIT
+
+        parts.any? && parts.all? { named_within?(it, budget) }
+      end
+
+      def viewer_leaf?(value)
+        value.present? && ActiveSupport::Cache.expand_cache_key(value).present?
+      end
+
+      # An Enumerator must report a finite size; anything sized must be small.
+      def viewer_size_ok?(size, value)
+        return size <= VIEWER_PART_LIMIT if size.is_a?(::Integer)
+
+        !value.is_a?(::Enumerator) && size.nil?
+      end
+
+      # Logs why — once per COMPONENT, naming it, since the cause is that
+      # component's hook — and answers nil: "this value names nobody".
+      def warn_unusable_viewer(owner, reason)
+        name = owner.respond_to?(:name) ? owner.name.to_s : owner.to_s
+        return nil if VIEWER_WARNED.put_if_absent(name, true)
+        return nil unless defined?(::Rails) && ::Rails.respond_to?(:logger)
+
+        ::Rails.logger&.warn(
+          "[phlex-reactive] #{name.presence || "a component"}#reactive_cache_viewer returned a value that " \
+          "cannot name a viewer (#{reason}) — treated as no viewer (Vary: Cookie). Return an id, or a small " \
+          "Array of ids."
+        )
+        nil
+      end
+
+      # Test seam: let the once-per-component warnings fire again.
+      def reset_viewer_warning!
+        VIEWER_WARNED.clear
+      end
+
+      # The max-age (seconds) the endpoint answers with: the component's
+      # declared value, capped by Phlex::Reactive.fragment_cache_max_age_limit.
+      def max_age_for(component_class)
+        [component_class.reactive_lazy_cache.fetch(:max_age), Phlex::Reactive.fragment_cache_max_age_limit.to_i].min
+      end
+    end
+  end
+end

data/lib/phlex/reactive/inspector/report.rb

@@ -15,7 +15,13 @@ module Phlex
         # A plain-text table of every component × action, or a JSON array when
         # `format` is :json. One row per action: component, action, params,
         # file:line, authorization heuristic.
-        def actions(components, format: :text)
+        # `unverified_only:` keeps just the actions whose authorization_state is
+        # :none (the review queue) and drops components left with none.
+        def actions(components, format: :text, unverified_only: false)
+          if unverified_only
+            components = unverified(components)
+            return "no unverified actions" if components.empty? && format != :json
+          end
           return actions_json(components) if format == :json
 
           actions_text(components)
@@ -34,6 +40,13 @@ module Phlex
           lines.join("\n")
         end
 
+        def unverified(components)
+          components.filter_map do
+            actions = it.actions.select { it.authorization_state == :none }
+            it.with(actions:) if actions.any?
+          end
+        end
+
         # -- plain text -------------------------------------------------------
 
         def actions_text(components)
@@ -110,7 +123,9 @@ module Phlex
             name: action.name,
             params: action.params,
             source_location: location_str(action.source_location),
-            authorization_call_detected: action.authorization_call_detected?
+            authorization_call_detected: action.authorization_call_detected?,
+            authorization: action.authorization_state.to_s,
+            authorization_skip: action.authorization_skip&.to_s
           }
         end
 
@@ -131,8 +146,14 @@ module Phlex
         end
 
         # The authorization heuristic as a short label — advisory only.
+        # "authorized*" (call detected), "skipped" / "skipped (class)" (declared
+        # skip_verify_authorized), "unverified" (neither).
         def auth_str(action)
-          action.authorization_call_detected? ? "authorized*" : "unverified"
+          case action.authorization_state
+          when :detected then "authorized*"
+          when :skipped then action.authorization_skip == :class ? "skipped (class)" : "skipped"
+          else "unverified"
+          end
         end
       end
     end

data/lib/phlex/reactive/inspector.rb

@@ -31,7 +31,10 @@ module Phlex
       #                       of the definition finds a call to any configured
       #                       authorization method or mark_authorized!. A helper
       #                       may authorize indirectly, so this is advisory ONLY.
-      ActionInfo = Data.define(:name, :params, :source_location, :definition) do
+      #   * authorization_skip — :class (a bare skip_verify_authorized, own or
+      #                       inherited), :action (this action is named in one),
+      #                       or nil. The author's declared opt-out (issue #278).
+      ActionInfo = Data.define(:name, :params, :source_location, :definition, :authorization_skip) do
         # Was any authorization method (or mark_authorized!) called directly in
         # the method body? Heuristic — a Prism scan of `definition`. False when
         # the definition is unavailable.
@@ -40,6 +43,14 @@ module Phlex
 
           Inspector.authorization_call?(definition)
         end
+
+        # :detected (a call was found), :skipped (declared skip_verify_authorized)
+        # or :none (neither — the review queue). A detected call wins over a skip.
+        def authorization_state
+          return :detected if authorization_call_detected?
+
+          authorization_skip ? :skipped : :none
+        end
       end
 
       # One reactive component's introspection.
@@ -164,10 +175,20 @@ module Phlex
             name: action.name,
             params: action.params,
             source_location: location,
-            definition: (extract_definition(location) if location)
+            definition: (extract_definition(location) if location),
+            authorization_skip: authorization_skip(klass, action.name)
           )
         end
 
+        # How `name` opts out of verify_authorized: :class for a bare skip (own
+        # or inherited), :action when listed by name, else nil. Resolved through
+        # the same Registry readers the runtime guard uses.
+        def authorization_skip(klass, name)
+          return :class if klass.reactive_skip_all_authorization?
+
+          :action if klass.reactive_skip_authorization_actions.include?(name.to_sym)
+        end
+
         # The method's [file, line], or nil when the declared method is missing
         # (an undeclared/typo'd action — the endpoint would 500 on public_send).
         def method_location(klass, name)

data/lib/phlex/reactive/js.rb

@@ -196,9 +196,24 @@ module Phlex
       # "submit") interception. ACTOR-ONLY like focus: allowed from on_client /
       # reply.js / a reducer's $ops, refused in broadcast_to(js:) — a broadcast
       # submit would force-submit every subscriber's form.
+      #
+      # submitter: (issue #319) — a CSS selector for the submit control to
+      # submit THROUGH (form.requestSubmit(submitter)), so the request carries
+      # its name=value — the bulk-action "Delete" that posts action=delete. It
+      # resolves with the op's own scoping; one that isn't a submit control of
+      # that form warns in the browser and falls back to a plain submit.
+      #   js.submit("#bulk", submitter: "#delete-submit")
+
+      def submit(to = :root, global: false, submitter: nil)
+        args = target_args(to, global:)
+        return append("submit", args) if submitter.nil?
+
+        unless submitter.is_a?(String) && !submitter.empty?
+          raise ArgumentError,
+            "js.submit submitter: must be a CSS selector string naming a submit control, got #{submitter.inspect}"
+        end
 
-      def submit(to = :root, global: false)
-        append("submit", target_args(to, global:))
+        append("submit", args.merge("submitter" => submitter).freeze)
       end
 
       # --- Clipboard-source paste (issue #228) ---
@@ -244,6 +259,36 @@ module Phlex
         append("text", args.freeze)
       end
 
+      # --- Tick or untick a checkbox group (issue #342) ---
+      #
+      # check_group(group, checked = true) — set every OWNED box of the group
+      # (the #15 rule: a nested root's boxes are its own) the way a
+      # reactive_select_all header does: every box first, then `input` +
+      # `change` on each one it flipped, then ONE re-sync of the header, count,
+      # show and enable bindings. The group is a checkbox name resolved like
+      # reactive_select_all's: a bare name takes reactive_scope, a bracketed one
+      # ("ids[]") is used verbatim. `global: true` is for a trigger outside the
+      # root that owns the group: EVERY connected reactive root on the page flips the
+      # boxes of that name it owns (nested roots included). ACTOR-ONLY like focus/submit: a broadcast that cleared
+      # every subscriber's selection would be hostile (BROADCAST_REFUSED_OPS).
+      #   button(**on_client(:click, js.check_group("ids[]", false))) { "✕" }
+
+      # Positional `checked` on purpose: js.check_group("ids[]", false) reads as
+      # the op it is (the issue #342 API).
+      def check_group(group, checked = true, global: false) # rubocop:disable Style/OptionalBooleanParameter
+        name = -group.to_s
+        if name.strip.empty?
+          raise ArgumentError, "check_group needs a checkbox group name (e.g. \"ids[]\"), got #{group.inspect}"
+        end
+        unless [true, false].include?(checked)
+          raise ArgumentError, "check_group(#{name.inspect}) takes true or false, got #{checked.inspect}"
+        end
+
+        args = { "to" => ROOT_SENTINEL, "group" => name, "checked" => checked }
+        args["global"] = true if global
+        append("check_group", args.freeze)
+      end
+
       # --- Dispatch a bubbling CustomEvent (issue #96) ---
       #
       # dispatch(name, to: nil, detail: {}) — emit a bubbling CustomEvent so other

data/lib/phlex/reactive/mcp/tools/actions_tool.rb

@@ -15,7 +15,9 @@ module Phlex
             action with its param schema, source file:line, and a heuristic
             authorization status (whether an authorization method or
             mark_authorized! call was detected in the body — advisory only, since a
-            helper may authorize indirectly). Pass `component:` to scope to one
+            helper may authorize indirectly), plus `authorization` — detected,
+            skipped (declared skip_verify_authorized; `authorization_skip` says
+            class or action) or none. Pass `component:` to scope to one
             component (exact name). Read-only — schemas and paths, never runtime
             values.
           DESC

data/lib/phlex/reactive/mcp/tools/find_tool.rb

@@ -15,7 +15,8 @@ module Phlex
             Fuzzy-find reactive components by name (exact > prefix > substring >
             subsequence, on both the demodulized and full name). Returns the ranked
             matches, each with its actions' param schema, source location,
-            authorization heuristic, and the full method-definition SOURCE
+            authorization (detected / skipped / none, plus the skip form), and the
+            full method-definition SOURCE
             (extracted with Prism). Read-only.
 
             NOTE: unlike the other tools (which report names/paths/schemas only),
@@ -53,6 +54,8 @@ module Phlex
               params: action.params,
               source_location: Phlex::Reactive::Inspector::Report.location_str(action.source_location),
               authorization_call_detected: action.authorization_call_detected?,
+              authorization: action.authorization_state.to_s,
+              authorization_skip: action.authorization_skip&.to_s,
               # The full method SOURCE — this is the one field that exposes an
               # action body verbatim (see the tool description). A secret hardcoded
               # in an action would surface here; keep secrets out of action bodies.

data/lib/phlex/reactive/param_schema.rb

@@ -334,36 +334,10 @@ module Phlex
         value.is_a?(Hash) || value.respond_to?(:to_unsafe_h)
       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
-
-        expand_bracket_keys(flat)
-      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.
-      def expand_bracket_keys(flat)
-        flat.each_with_object({}) do |(key, value), out|
-          deep_assign(out, bracket_path(key), value)
-        end
-      end
+      # Each nested hash is unwrapped and expanded by the class-level expand
+      # below — the same expansion the endpoint runs before peeling a
+      # reactive_scope (issue #337), so both read one shape.
+      def to_param_hash(value) = self.class.expand(value)
 
       # Matches each bracket segment in "items_attributes][0][qty]" — the part
       # after the first "[". Hoisted to a frozen constant so coercing a bracketed
@@ -371,35 +345,75 @@ module Phlex
       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.
-      def bracket_path(key)
-        return [key] unless key.include?("[")
+      class << self
+        # Public so the endpoint can expand BEFORE it peels a reactive_scope
+        # (issue #337): a JSON body keeps "todo[title]" as one literal key, which
+        # only becomes { "todo" => { "title" => … } } here. Idempotent on input
+        # that is already nested (a multipart body Rails expanded itself).
+        #
+        # Unwraps ActionController::Parameters (or a plain Hash) to a string-keyed
+        # Hash so coercion can index it uniformly, then expands bracket notation so
+        # a model-scoped Rails form's flat keys nest (issue #21). Anything else is {}.
+        def expand(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
 
-        head, rest = key.split("[", 2)
-        [head, *rest.scan(BRACKET_SEGMENT)]
-      end
+          expand_bracket_keys(flat)
+        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. #merge_value deep-merges hash/hash collisions and otherwise
-      # lets the later value win.
-      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]
+        private
+
+        # 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.
+        def expand_bracket_keys(flat)
+          flat.each_with_object({}) do |(key, value), out|
+            deep_assign(out, bracket_path(key), value)
+          end
         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)
+        # "invoice[items_attributes][0][qty]" => ["invoice", "items_attributes",
+        # "0", "qty"]. A key with no brackets is a single-element path.
+        def bracket_path(key)
+          return [key] unless key.include?("[")
+
+          head, rest = key.split("[", 2)
+          [head, *rest.scan(BRACKET_SEGMENT)]
+        end
 
-        existing.merge(value.stringify_keys) { |_k, old, new| merge_value(old, new) }
+        # 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. #merge_value deep-merges hash/hash collisions and otherwise
+        # lets the later value win.
+        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
     end
   end