phlex-reactive 0.3.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7232501319d17c45c8907195117f5af59d8b7a4ff9c8d5efb2c0c8248350041e
-  data.tar.gz: 783cd0758a5a51cead67f6f1ea2c8bf23245f62e49a38ea0831328b68b9d0b2c
+  metadata.gz: 786d397de0be7e32424c73079906cdf8d32d0325727d06027025d888693754e6
+  data.tar.gz: b080f12ff8c8f4271066993548f9c951278fe2dacabf9b7d21c2113704f58da4
 SHA512:
-  metadata.gz: a673a7253c99e7b6fccb5228014a47d2918cda2995de79afdb6545adb89a8af8ab99812569455bc7f206c12d7c7efb710ff90d628d767da012ba5deb690e5ab7
-  data.tar.gz: cf68ac7ff60925c73aa0de543665b60d85d8254bada63a40c1786a6a3e7ee3bfceaad123c91daf2f7fec18de8aab04ab61d2ee165b5e0ad241b451ce60c24769
+  metadata.gz: 316b9b2094490dd5045d1362276a8f31ba4deee96df08e6614dc9db8f62a2ceb822f5a474d2204dcb65f7ed1bb27b3c99303f14a180a336c2d5bc3d21c3bf31a
+  data.tar.gz: f54ecfe74e977b3d4a399cd004071792a3a7245636d1c82f19441b0240fb2d24d32bb072a3ae863a9e04efcab5a31182560628237f72bf77ff73ac387592e4c4

data/CHANGELOG.md

@@ -8,6 +8,171 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **File / multipart params in a reactive action (#34).** An action can now accept
+  an uploaded file: declare `params: { file: :file }` (or `[:file]` for multiple).
+  When the reactive root holds a populated `<input type="file">`, the client sends
+  the action as multipart `FormData` instead of JSON — `token` + `act` + scalar
+  params as fields, the file(s) appended — and the endpoint coerces `:file` to the
+  `ActionDispatch::Http::UploadedFile`, passed through untouched. A non-file value
+  sent to a `:file` param is dropped (the keyword default applies), consistent with
+  the #16 coercion rules — and for a `[:file]` array, a non-file *element* (a
+  forged/mixed payload) is rejected from the array too, so the internal coercion
+  sentinel never leaks to the action. A `<input type="file" multiple>` keeps its
+  array shape (`params[name][]`) even when the user picks exactly one file, so a
+  `[:file]` schema still coerces it. Token threading and the re-render/morph are
+  identical; only the request encoding changes when a file is present — so
+  attaching a document/receipt/image stays a reactive action instead of dropping
+  out to a bespoke controller + upload Stimulus controller. Covered end-to-end:
+  server coercion (request specs), the FormData wire shape (bun unit tests), and a
+  real browser upload under Puma + Falcon (system spec).
+
+### Changed
+
+- **Linter: Standard → RuboCop.** The gem now lints with RuboCop (all new cops
+  enabled, `NewCops: enable`) instead of StandardRB, so the suite teaches and
+  enforces newer Ruby idioms that Standard leaves alone — chiefly the Ruby 3.4
+  `it` implicit single block parameter (`map { it.foo }`) via
+  `Style/ItBlockParameter: always`. The whole tree was autocorrected; the
+  lib/app changes were the `|x| x.foo` → `it.foo` rename plus hash-brace
+  spacing — behavior is unchanged and all specs are green. The gemspec and
+  Rakefile are excluded from `Style/ItBlockParameter` (their `do |spec| … end`
+  config blocks read better named); a nested Phlex content block and a scope
+  lambda carry inline disables where blanket `it` would collapse two parameters
+  or break a `where(room:)` kwarg shorthand; and blocks that fed a
+  keyword-argument shorthand (`Component.new(todo:)`) were rewritten to an
+  explicit `Component.new(todo: it)` so the `it` rename can't silently change
+  the keyword. Component-
+  aware relaxations (line length, `Lint/MissingSuper`, unused action params)
+  are scoped to `spec/dummy/app/components/**`. `bundle exec standardrb` is now
+  `bundle exec rubocop`; `rake`'s default runs `spec + rubocop`.
+- **Added `rubocop-capybara` and `rubocop-thread_safety`.** Capybara lints the
+  browser specs (clean today — the suite already uses waiting matchers).
+  thread_safety stays on as a tripwire for unsafe shared mutable state on the
+  request/broadcast path; its `ClassInstanceVariable` /
+  `ClassAndModuleAttributes` cops are scoped off only in the three files whose
+  flagged class-level state is deliberate and audited — module-level config
+  (`lib/phlex/reactive.rb`, set once at boot), class-definition-time DSL
+  registries (`component.rb`), and the per-thread view-context cache's integer
+  generation counter (`streamable.rb`). An adversarial audit confirmed none are
+  request-path hazards; the lazy `||=` config defaults are idempotent. (A
+  follow-up may warm `verifier`/`renderer` at boot to remove even the
+  benign-by-idempotency first-call race — out of scope for this lint change.)
+
+### Removed
+
+- **Dropped the `standard` development dependency** in favor of `rubocop`,
+  `rubocop-capybara`, `rubocop-performance`, `rubocop-rake`, `rubocop-rspec`,
+  and `rubocop-thread_safety`.
+
+### BREAKING
+
+- **Minimum Ruby is now 3.4** (was 3.2). Enabling the `it` block parameter
+  requires Ruby 3.4, so `required_ruby_version` is `>= 3.4.0` and the CI matrix
+  drops 3.2 and 3.3. Stay on phlex-reactive 0.3.x if you need Ruby 3.2/3.3.
+
+### Fixed
+
+- **0.4.0 regression: re-renders lost the `request`, crashing `form_authenticity_token`
+  and other request-dependent helpers (#42).** The 0.4.0 render-path perf rework
+  built the cached off-request view context from a bare
+  `ActionController::Base.new.view_context`, whose controller has `request == nil`.
+  Any reactive component whose `view_template` calls `form_authenticity_token`,
+  `protect_against_forgery?`, or a host-aware URL helper (all of which read
+  `request.env`) then raised `NoMethodError: undefined method 'env' for nil` on
+  **every** re-render — through the action endpoint AND on broadcasts — so any app
+  with a reactive component rendering a Rails CSRF form could not adopt 0.4.0. Fixed
+  by building the cached view context through a request-bound controller
+  (`Phlex::Reactive.request_bound_view_context`), replicating exactly what
+  `ActionController::Renderer#render` does to set up its mock request: an
+  `ActionDispatch::Request` whose host is derived from the routes'
+  `default_url_options`. The 0.4.0 `render_in` speedup is kept — the request is set
+  up once when the per-thread context is built (not per render), and steady-state
+  render throughput/allocations are unchanged (retained-per-render stays 0). Covered
+  at the request level (a reactive `save` re-rendering a CSRF form returns 200, not
+  500), the broadcast level (the form component broadcasts without crashing), and the
+  unit level (a request is present on the cached context; host-aware `*_url` helpers
+  resolve when the renderer carries routes).
+
+- **Multipart path silently dropped an explicit nested-hash / array param (#39).**
+  When an action declared a `:file` param alongside an explicit nested (hash/array)
+  param, the nested param was dropped on the multipart path while the JSON path
+  handled it correctly — the two encodings were asymmetric. The client's
+  `#buildFormData` `JSON.stringify`'d a non-scalar param into one
+  `params[key]='<json>'` field, which the server received as an un-decodable
+  `String` leaf and dropped (nested hash → `{}`, array → key removed). Fixed
+  client-side: `#buildFormData` now bracket-expands a nested object/array into
+  `params[key][sub]` / `params[key][index][...]` fields (arrays use numeric
+  indices) — the same Rails-form shape the server's `expand_bracket_keys` /
+  `array_values` already parse, so a JSON body and a multipart body now coerce
+  identically. The server is unchanged. One intentional divergence: an empty
+  array/object as a whole param can't be carried by `FormData`, so the multipart
+  path omits the key (the action's keyword default applies) rather than sending an
+  explicit-clear `[]`/`{}`. Covered end-to-end: the bracketed multipart shape
+  coerces correctly (request specs), a `:file` alongside a nested param both
+  survive (request spec), and the FormData wire shape (bun unit tests).
+
+- **`to_stream_token` emitted an EMPTY token, making non-self-rendering replies
+  add-once-only (cosmos#1939).** `Streamable#to_stream_token` guarded on
+  `respond_to?(:reactive_token)`, but `Component#reactive_token` is **private**, so
+  the guard was false for every component and the refresh stream carried
+  `data-reactive-token-value=""`. Any reply that opts out of the full-self replace
+  but relies on the token-only refresh — `reply.streams` (#30) and the new
+  `reply.append`/`reply.remove` (#35) — therefore rolled an empty token forward:
+  the first action worked, then the next dispatch from that root was rejected (the
+  stale/empty token fails verification) with no error. Fixed by checking private
+  methods (`respond_to?(:reactive_token, true)`); a bare Streamable (genuinely no
+  token) still skips correctly. The `reactive_collection` builders also now bind the
+  **container** as the `token_component`, so an add/remove rolls the list root's
+  token forward (the load-bearing part for repeated add/remove). Regression tests
+  assert the token is non-empty AND re-verifies, and that a second add using the
+  first reply's token succeeds.
+
+### Changed
+
+- **The browser suite now runs under two real servers — Puma and Falcon.** The
+  `system` CI job runs as a matrix (`CAPYBARA_SERVER=puma` and `=falcon`), and a
+  new `rake spec:system_servers` task runs both locally, so a reactive round trip
+  is proven transport-agnostic across a sync (Puma, thread-pool) and an async
+  (Falcon, fiber-per-request) server. `webrick` is **removed** as a test server
+  (it isn't a real server) — `falcon` (with `protocol-rack`) replaces it as the
+  alternative, registered via `Capybara.register_server(:falcon)`. No production
+  dependency change; this is test infrastructure only.
+
+- **CI now tests against Ruby 4.0** (added to the test matrix in `main.yml` and
+  the pre-release matrix in `release.yml`, alongside 3.2/3.3/3.4; the lint and
+  browser-system jobs also run on 4.0 now). Ruby 4.0 shipped December 2025 and is
+  the current stable line. The gem requires no code changes for 4.0 — its
+  dependencies and the patterns it uses (ObjectSpace::WeakMap, Data.define,
+  Thread-locals, the MessageVerifier path) are stable across 3.4 → 4.0, and it
+  directly requires none of the gems 4.0 moved from default to bundled.
+  `required_ruby_version` stays `>= 3.2.0` (no upper bound, already permits 4.0).
+  Verified empirically: the full unit/request/generator suite is green on Ruby
+  4.0.5 with zero deprecation or unbundled-gem warnings.
+
+### Added
+
+- **`reactive_collection` — add/remove-row lists in one declaration (issue #35).**
+  An add/remove-row list (line items, tags, comments, a notifications list) is one
+  of the most common reactive surfaces, and every one re-implements the same
+  orchestration by hand: append the row to the right container, remove it on
+  delete, keep a count badge in sync, and swap an empty-state in/out as the list
+  crosses 0↔1. `reactive_collection :items, item:, container:, count:, empty:,
+  size:` declares that contract **once** on the container component, so each action
+  is a single call: `reply.append(:items, model)` (row + count + empty-state
+  clear), `reply.prepend(:items, model)`, and `reply.remove(:items, model_or_id)`
+  (row + count + empty-state restore). The size badge and empty-state toggle are
+  driven by the declared `size:` resolver, **re-counted server-side after the
+  mutation** — so they're correct-by-construction (no off-by-one, no client-held
+  count, consistent between the first render and the deltas). `count:`/`empty:`/
+  `size:` are optional (omit them and only the row stream is emitted), and the new
+  builders compose with `.flash`/`.stream` like any other reply. Reply governs the
+  actor's HTTP response only; a cross-tab live list still broadcasts the row with
+  `broadcast_append_to(..., exclude: reactive_connection_id)`. New
+  `Phlex::Reactive::Component::CollectionDefinition`,
+  `reactive_collection`/`reactive_collection_def`/`reactive_collection?` macros,
+  and `Response.collection_append`/`collection_prepend`/`collection_remove` behind
+  the `reply.*` surface.
+
 - **`reply.streams` — partial update with a token-only refresh (issue #30).**
   `reply.streams(Totals.update(@item))` emits **exactly** the streams you pass —
   no forced full-self replace — so an action can re-render only part of a
@@ -100,6 +265,41 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   trip still goes through the per-component queue so token threading holds.
   Omitting `debounce:` keeps the immediate-dispatch default.
 
+### Performance
+
+- **Re-render is ~2× faster with ~half the allocations.** `render_component` now
+  renders through phlex-rails' lightweight `#render_in` against a memoized
+  off-request view context, instead of `ActionController.renderer.render` (which
+  dragged in ActionView's `TemplateRenderer`/`LookupContext`/log subscriber).
+  Measured same-machine before/after: `render_component` 6.99k→14.1k i/s (212→99
+  obj/call); `to_stream_replace` 4.60k→8.00k i/s (331→191 obj/call). HTML is
+  byte-identical and the full Rails helper set (`dom_id`/`url_for`/`t`/CSRF) still
+  works. The biggest win is on the **broadcast** path (N subscribers = N renders,
+  no HTTP to amortize against); at the full-request level the Rails stack + DB
+  dominate, so request throughput is roughly unchanged.
+
+- **View context, Turbo `TagBuilder`, and flash builder are memoized** per
+  component class (the comment used to claim this; now it's true). Keyed on the
+  configured renderer's identity so swapping `Phlex::Reactive.renderer` rebuilds,
+  and reset on Rails code reload (`config.to_prepare`) so a reloaded controller
+  is never served stale.
+
+- **Smaller per-render allocations on the token path.** `reactive_token`
+  precomputes its ivar symbols + state string-keys per class (14→11 obj/call,
+  state-backed), and `on(:action)` skips re-serializing an empty params hash
+  (6→5 obj/call). The bracket-key regex in param coercion is hoisted to a frozen
+  constant.
+
+- **Client: the page-stable action path is resolved once per controller** instead
+  of a `querySelector` per dispatch. CSRF token and pgbus connection id stay live
+  (they can rotate).
+
+- **Benchmark harness + CI report.** `rake bench` (micro: render/token/coerce) and
+  `rake bench:request` (end-to-end via derailed) measure the hot paths; a CI
+  `bench` job runs them on every PR and uploads the report as an artifact
+  (run-and-report, not a hard gate). See `docs/performance.md` and the `/perf`
+  command.
+
 ### Fixed
 
 - **Model-scoped form fields feed a nested param (issue #21).** A Rails

data/README.md

@@ -313,10 +313,52 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 | `reactive_input(:param, **attrs)` / `reactive_select(:param, **attrs)` | Render a control already bound to an action param (no magic `name:`). |
 | `reactive_field(:param, **attrs)` | The attribute hash behind the above — spread onto any control. |
 | `nested_update!(:assoc, attrs)` | Map a nested param onto `<assoc>_attributes` with id preservation; update the record. |
+| `reactive_collection :name, item:, container:, count:, empty:, size:` | Declare an add/remove-row list once; actions call `reply.append`/`prepend`/`remove`. See [Reactive collections](#reactive-collections-addremove-rows--count--empty-state). |
 | `reply.replace` / `.morph` / `.update` / `.remove` / `.redirect(url)` / `.with(*)` | Return from an action to control the reply (flash, remove, redirect, multi-stream). See [Controlling the action's reply](#reply--controlling-the-actions-reply). |
+| `reply.append(name, model)` / `.prepend(...)` / `.remove(name, model)` | Add/remove a row in a declared `reactive_collection` (row + count + empty-state in one reply). |
+
+Param types: `:string` (default), `:integer`, `:float`, `:boolean`, `:file`.
+Anything not in the schema is dropped before reaching your method.
+
+**File uploads (`:file`).** Declare `:file` (or `[:file]` for multiple) to accept
+an uploaded file in a reactive action — attach a document/receipt/image to the
+record without dropping out to a bespoke controller. When the reactive root holds
+a populated `<input type="file">`, the client sends the action as multipart
+`FormData` (instead of JSON) — `token` + `act` as fields, scalar params as fields,
+any nested/array params bracket-expanded into `params[key][sub]` /
+`params[key][index]` fields (the same Rails-form shape, so a JSON body and a
+multipart body coerce identically — #39), and the file(s) appended; the endpoint
+coerces `:file` to the `ActionDispatch::Http::UploadedFile`, passed through
+untouched. A non-file value sent to a `:file` param is dropped (the keyword
+default applies — never a fabricated file). Token threading and the
+re-render/morph are identical; only the request encoding changes when a file is
+present.
 
-Param types: `:string` (default), `:integer`, `:float`, `:boolean`. Anything not
-in the schema is dropped before reaching your method.
+```ruby
+reactive_record :document
+action :upload, params: { file: :file, caption: :string } # single (has_one_attached)
+action :upload_pages, params: { pages: [:file] }           # multiple (has_many_attached)
+
+def upload(file: nil, caption: nil)
+  @document.file.attach(file) if file
+  @document.update!(title: caption) if caption.present?
+end
+
+def view_template
+  form(**on(:upload, event: "submit")) do
+    input(type: "file", name: "file")
+    input(name: "caption")
+    button(type: "submit") { "Upload" }
+  end
+end
+```
+
+> **One multipart caveat:** `FormData` can't carry an *empty* array or hash, so on
+> the multipart (file-present) path an empty `[]`/`{}` param is **omitted** and the
+> action's keyword default applies — it does **not** arrive as an explicit empty
+> collection the way it does over JSON. If you rely on sending `tags: []` to clear
+> a collection, send that action *without* a file (the JSON path). A non-empty
+> nested/array param rides along fine next to a file.
 
 **Array & nested params.** Wrap a type in an array for an array param, or a hash
 schema in an array for Rails-style nested attributes — so one reactive action can
@@ -485,12 +527,77 @@ update only the targets you name) and refreshes the token via a tiny inert
 > (`Phlex::Reactive::Response.replace(self)`) and it still works, but `reply` is
 > the preferred surface; treat `Response` as an internal detail.
 > **`html:`/`content` escaping.** A plain string is **HTML-escaped** by Turbo, so
-> **`html:`/`content` escaping.** A plain string is **HTML-escaped** by Turbo, so
 > `html: @account.name` is safe even for user-supplied values. To emit intentional
 > markup, pass a **Phlex component** (`html: Heading.new(name: @record.name)`) —
 > rendered and auto-escaped through the renderer — or an `html_safe` string for
 > raw HTML you control.
 
+### Reactive collections (add/remove rows + count + empty-state)
+
+An add/remove-row list — line items, attachments, tags, comments, a
+notifications list — is one of the most common reactive surfaces, and every one
+re-implements the same orchestration by hand: append the row to the right
+container, remove it on delete, keep a **count badge** in sync, and swap an
+**empty-state** in/out as the list crosses 0↔1. `reactive_collection` declares
+that contract **once** on the container so each action is a single call.
+
+Declare the collection on the container component, then `reply.append` /
+`reply.prepend` / `reply.remove` in the actions:
+
+```ruby
+class NotificationsList < ApplicationComponent
+  include Phlex::Reactive::Streamable
+  include Phlex::Reactive::Component
+
+  reactive_collection :notifications,
+    item: NotificationRow,        # the per-row Streamable component
+    container: "notifications",    # the DOM id rows live in
+    count: "notifications-count",  # optional companion id (the size badge)
+    empty: NotificationsEmpty,     # optional empty-state component
+    size: -> { Todo.count }        # resolves the live size (re-counted, never client state)
+
+  action :add, params: {title: :string}
+  action :dismiss, params: {id: :integer}
+
+  def add(title:)
+    todo = Todo.create!(title:)
+    reply.append(:notifications, todo)   # append row + bump count + clear empty-state
+  end
+
+  def dismiss(id:)
+    Todo.find(id).destroy!
+    reply.remove(:notifications, id)     # remove row + bump count + restore empty-state at 0
+  end
+
+  # view_template renders the count, the container <ul>, and the empty-state on
+  # first paint — the same components the helper streams in/out on each delta.
+end
+```
+
+| Builder | Reply (one `Response`) |
+|---|---|
+| `reply.append(name, model)` | append the row into the container + update the count + remove the empty-state when the list crosses 0→1 |
+| `reply.prepend(name, model)` | as `append`, but the row goes to the top |
+| `reply.remove(name, model)` | remove the row by its `dom_id` + update the count + append the empty-state back when the list crosses →0 |
+
+- **`size:` is the source of truth** — it's *re-counted* server-side after the
+  mutation, so the badge and the empty-state are correct-by-construction (no
+  off-by-one, no client-held count). `count:`, `empty:`, and `size:` are all
+  optional: omit them and only the row stream is emitted.
+- **Repeated add/remove just works** — each reply rolls the **container's** signed
+  token forward (via the inert `reactive:token` refresh), so the second click from
+  the list root is accepted. Without this an add/remove list would be add-once-only
+  (correct on the first click, silently rejected after); the helper bakes the
+  refresh in so you never hit it.
+- **`remove` takes the record or its `dom_id` string** — a just-destroyed
+  ActiveRecord still answers `dom_id` correctly, so `reply.remove(:items, todo)`
+  works; pass the raw id only if your row `#id` matches `ActiveRecord::RecordIdentifier`.
+- **Reply governs the actor's HTTP response only.** For a *cross-tab* live list
+  (other viewers see the row appear) keep broadcasting the row with
+  `NotificationRow.broadcast_append_to(..., exclude: reactive_connection_id)` —
+  `reactive_collection` is the per-actor add/remove + count + empty-state wrapper,
+  not a replacement for the broadcast.
+
 ### Configuration (`config/initializers/phlex_reactive.rb`)
 
 ```ruby
@@ -661,6 +768,7 @@ See [docs/broadcasting.md](docs/broadcasting.md) and
 - [Broadcasting & live updates](docs/broadcasting.md)
 - [Transport: pgbus vs Action Cable](docs/transport-pgbus.md)
 - [Testing reactive components](docs/testing.md)
+- [Performance & benchmarking](docs/performance.md)
 - Examples: [counter](docs/examples/counter.md) ·
   [chat](docs/examples/chat.md) · [todo list](docs/examples/todo_list.md) ·
   [inline edit](docs/examples/inline_edit.md) ·

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

@@ -101,7 +101,7 @@ 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? { |s| s.include?("data-reactive-token-value") }
+        if result.render_self? && streams.none? { it.include?("data-reactive-token-value") }
           streams = [component.to_stream_replace, *streams]
         end
         streams
@@ -115,7 +115,7 @@ module Phlex
       # us into skipping this component's refresh.
       def carries_token_for?(streams, component)
         target = %(target="#{ERB::Util.html_escape(component.id)}")
-        streams.any? { |s| s.include?("data-reactive-token-value") && s.include?(target) }
+        streams.any? {  it.include?("data-reactive-token-value") && it.include?(target) }
       end
 
       # A 200 turbo-stream carrying a namespaced custom action the client turns
@@ -126,9 +126,9 @@ module Phlex
         %(<turbo-stream action="reactive:visit" data-url="#{ERB::Util.html_escape(url)}"></turbo-stream>)
       end
 
-      def transaction_wrapper(&block)
+      def transaction_wrapper(&)
         if defined?(::ActiveRecord::Base)
-          ::ActiveRecord::Base.transaction(&block)
+          ::ActiveRecord::Base.transaction(&)
         else
           yield
         end
@@ -163,29 +163,60 @@ module Phlex
 
       # 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)
-        if type.is_a?(Array)
+        case type
+        when Array
           coerce_array(value, type.first)
-        elsif type.is_a?(Hash)
+        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?
 
-        values.map { |element| coerce(element, element_type) }
+        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
@@ -219,9 +250,9 @@ module Phlex
       def array_values(value)
         return value.to_a if value.is_a?(Array)
 
-        if value.respond_to?(:to_unsafe_h) || value.is_a?(Hash)
-          to_param_hash(value).sort_by { |k, _| k.to_i }.map(&:last)
-        end
+        return unless value.respond_to?(:to_unsafe_h) || value.is_a?(Hash)
+
+        to_param_hash(value).sort_by { |k, _| k.to_i }.map(&:last)
       end
 
       # Unwrap ActionController::Parameters (or a plain Hash) to a string-keyed
@@ -258,13 +289,19 @@ module Phlex
         end
       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.
+      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?("[")
 
         head, rest = key.split("[", 2)
-        [head, *rest.scan(/[^\[\]]+/)]
+        [head, *rest.scan(BRACKET_SEGMENT)]
       end
 
       # Walk/create nested hashes along `path`, then merge `value` at the leaf so
@@ -294,7 +331,7 @@ module Phlex
       # already gates this; defense in depth against constant injection.
       def resolve_component(name)
         klass = name.to_s.safe_constantize
-        unless klass&.respond_to?(:reactive_action?) && klass.include?(Phlex::Reactive::Component)
+        unless klass.respond_to?(:reactive_action?) && klass.include?(Phlex::Reactive::Component)
           raise Phlex::Reactive::InvalidToken
         end