phlex-reactive 0.3.0 → 0.4.1

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

@@ -8,9 +8,12 @@ import { Controller } from "@hotwired/stimulus"
 // (replace by default; method="morph" — Response.morph — preserves focus).
 //
 // Wire format (client -> server), POST <action path>, turbo-stream Accept:
-//   { token: "<signed identity>", act: "<action>", params: {...} }
+//   { token: "<signed identity>", act: "<action>", params: {...} }   (JSON)
 // (`act`, not `action`: `action` is a reserved Rails routing param.)
 // The token is a MessageVerifier-signed { component, gid } — NO state is sent.
+// When the root holds a chosen <input type="file">, the SAME payload is sent as
+// multipart FormData instead (token/act flat, params bracketed, files appended)
+// so an upload reaches the action (issue #34) — only the encoding differs.
 // The response is a <turbo-stream> that replaces the component by its id.
 //
 // Server -> client live updates use the SAME element id, pushed over the
@@ -119,6 +122,7 @@ export default class extends Controller {
 
   #tokenCache // freshest token, threaded synchronously across queued requests
   #debounceTimers = new Map() // trigger element -> { timer, flush } pending dispatch
+  #actionPathCache // page-stable action path, resolved once per controller
 
   // Mark that a reactive controller actually connected, so the registration
   // guard above knows the controller was registered (issue #26 part 2).
@@ -202,24 +206,34 @@ export default class extends Controller {
 
   async #perform(action, params) {
     // Auto-collect named field values inside this component so a button-
-    // triggered action still receives sibling inputs (Livewire-style).
-    // Explicit params (data-reactive-params-param) win over collected fields.
-    const fieldParams = this.#collectFields()
-
-    const body = JSON.stringify({
-      token: this.#currentToken,
-      act: action,
-      params: { ...fieldParams, ...this.#parseParams(params) },
-    })
+    // triggered action still receives sibling inputs (Livewire-style), plus any
+    // chosen file inputs in the SAME walk. Explicit params
+    // (data-reactive-params-param) win over collected fields.
+    const { fields, files } = this.#collectFields()
+    const allParams = { ...fields, ...this.#parseParams(params) }
+    const token = this.#currentToken
+
+    // File/multipart path (issue #34): if THIS root has a populated
+    // <input type="file">, the action can't be JSON (JSON.stringify drops the
+    // File). Send FormData instead — token + act + scalar params as fields, each
+    // chosen file appended. The morph/token machinery downstream is identical;
+    // only the request ENCODING differs when files are present.
+    const multipart = files.length > 0
+    const body = multipart
+      ? this.#buildFormData(token, action, allParams, files)
+      : JSON.stringify({ token, act: action, params: allParams })
 
     this.element.setAttribute("aria-busy", "true")
 
     try {
       const headers = {
-        "Content-Type": "application/json",
         Accept: "text/vnd.turbo-stream.html",
         "X-CSRF-Token": this.#csrfToken(),
       }
+      // For JSON we declare the content type; for multipart we must NOT — the
+      // browser sets `multipart/form-data; boundary=…` itself, and overriding it
+      // would strip the boundary and corrupt the body server-side.
+      if (!multipart) headers["Content-Type"] = "application/json"
       // Send the pgbus SSE connection id (if subscribed) so the server can
       // exclude this connection from its own broadcast echo — the actor
       // already gets the action's HTTP response. Harmless without pgbus.
@@ -287,12 +301,22 @@ export default class extends Controller {
     return el.closest('[data-controller~="reactive"]') === this.element
   }
 
+  // One walk over THIS root's named controls (not a nested reactive root's),
+  // returning both the scalar `fields` and any chosen `files`. A file input's
+  // `.value` is the useless "C:\fakepath\…" string, never a scalar — so its
+  // chosen files are collected separately (honoring `multiple`) and it adds no
+  // phantom blank value (issue #34). An empty `files` keeps the JSON path.
   #collectFields() {
     const fields = {}
-    // Standard form controls owned by THIS root (not a nested reactive root).
+    const files = []
     this.element.querySelectorAll("input[name], select[name], textarea[name]").forEach((field) => {
       if (!this.#ownsField(field)) return
-      if (field.type === "checkbox") {
+      if (field.type === "file") {
+        // Carry the input's `multiple` flag so #buildFormData keeps the array
+        // shape (params[name][]) even when the user picked exactly one file —
+        // otherwise a [:file] schema would see a lone scalar upload and drop it.
+        for (const file of field.files ?? []) files.push({ name: field.name, file, multiple: field.multiple })
+      } else if (field.type === "checkbox") {
         fields[field.name] = field.checked
       } else if (field.type === "radio") {
         if (field.checked) fields[field.name] = field.value
@@ -320,7 +344,71 @@ export default class extends Controller {
           fields[name] = el.value ?? el.textContent ?? el.innerHTML ?? ""
         }
       })
-    return fields
+    return { fields, files }
+  }
+
+  // Build the multipart body (issue #34). `token`/`act` are flat fields the
+  // endpoint reads from params[:token]/params[:act]; scalar params nest under
+  // params[<key>] (Rails parses the bracket into params[:params]); each file is
+  // appended under params[<name>] (single) — a second file with the same name
+  // (a `multiple` picker, several inputs sharing a name) is sent as
+  // params[<name>][] so Rails coerces it to an array for a [:file] schema.
+  #buildFormData(token, action, params, files) {
+    const fd = new FormData()
+    fd.append("token", token)
+    fd.append("act", action)
+    for (const [key, value] of Object.entries(params)) {
+      this.#appendField(fd, `params[${key}]`, value)
+    }
+    const multiNames = this.#multiFileNames(files)
+    for (const { name, file, multiple } of files) {
+      // params[name][] when the input is `multiple` (array shape even for one
+      // file) OR the name repeats across inputs; otherwise a lone scalar file.
+      const asArray = multiple || multiNames.has(name)
+      const key = asArray ? `params[${name}][]` : `params[${name}]`
+      fd.append(key, file, file.name)
+    }
+    return fd
+  }
+
+  // Append a param leaf to FormData under its bracketed key. FormData carries
+  // only strings, so a NON-scalar param (a nested object or an array) is
+  // bracket-EXPANDED into params[key][sub] / params[key][index][...] fields —
+  // the SAME Rails-form shape the server's expand_bracket_keys / array_values
+  // already parse, so a JSON body and a multipart body coerce identically
+  // (issue #39). Previously a non-scalar was JSON.stringify'd into one
+  // params[key]='<json>' field, which the server received as an un-decodable
+  // String leaf and DROPPED (nested hash -> {}, array -> key removed).
+  //
+  // Arrays use NUMERIC indices (params[key][0], params[key][1]) — required for
+  // an array-of-hash so each element's sub-keys stay grouped and the server's
+  // index-hash sort rebuilds order; params[key][] would collapse them. A scalar
+  // (string/number/boolean) is one string field, mirroring the JSON wire shape
+  // (the server's :boolean/:integer casts read "true"/"42"). null/undefined is
+  // an empty field. An EMPTY array/object emits NOTHING — FormData can't carry
+  // []/{}, so the key is omitted and the action's keyword default applies (this
+  // differs from the JSON path, where an explicit [] coerces to an empty array).
+  #appendField(fd, key, value) {
+    if (value == null) {
+      fd.append(key, "")
+    } else if (Array.isArray(value)) {
+      value.forEach((element, index) => this.#appendField(fd, `${key}[${index}]`, element))
+    } else if (typeof value === "object") {
+      for (const [subKey, subValue] of Object.entries(value)) {
+        this.#appendField(fd, `${key}[${subKey}]`, subValue)
+      }
+    } else {
+      fd.append(key, String(value))
+    }
+  }
+
+  // Names that appear more than once across the chosen files (a `multiple`
+  // picker, or several file inputs sharing a name) — those go to params[name][]
+  // so the server sees an array; a lone file stays params[name].
+  #multiFileNames(files) {
+    const counts = new Map()
+    for (const { name } of files) counts.set(name, (counts.get(name) ?? 0) + 1)
+    return new Set([...counts].filter(([, n]) => n > 1).map(([name]) => name))
   }
 
   #parseParams(raw) {
@@ -332,13 +420,21 @@ export default class extends Controller {
     }
   }
 
+  // The action path comes from a <meta> tag that is fixed for the page's life,
+  // so resolve it once per controller and cache it — avoids a querySelector on
+  // every dispatch (this runs on the request hot path, once per click/keystroke
+  // round trip). Cached on the instance, so a fresh connect() (after a Turbo
+  // navigation swaps the element) re-reads it.
   #actionPath() {
-    return (
+    return (this.#actionPathCache ??=
       document.querySelector('meta[name="phlex-reactive-action-path"]')?.content ||
-      "/reactive/actions"
-    )
+      "/reactive/actions")
   }
 
+  // CSRF token and connection id are read LIVE (not cached) on purpose: Rails
+  // can rotate the CSRF token, and the pgbus connection id changes on an SSE
+  // reconnect — caching either would send a stale value. A single querySelector
+  // per request is cheap next to the round trip itself.
   #csrfToken() {
     return document.querySelector('meta[name="csrf-token"]')?.content ?? ""
   }

data/lib/generators/phlex/reactive/install/install_generator.rb

@@ -29,8 +29,8 @@ module Phlex
           index = stimulus_index_path
 
           unless index
-            say_status :skip, "no Stimulus controllers entrypoint found — register manually:\n" \
-                              "    #{IMPORT_LINE}\n    #{REGISTER_LINE}", :yellow
+            say_status :skip, "no Stimulus controllers entrypoint found — register manually:\n    " \
+                              "#{IMPORT_LINE}\n    #{REGISTER_LINE}", :yellow
             return
           end
 
@@ -44,9 +44,9 @@ module Phlex
           end
 
           # Fallback: if the standard import line wasn't found, append both lines.
-          unless File.read(index).include?(REGISTER_LINE)
-            append_to_file index, "\n#{IMPORT_LINE}\n#{REGISTER_LINE}\n"
-          end
+          return if File.read(index).include?(REGISTER_LINE)
+
+          append_to_file index, "\n#{IMPORT_LINE}\n#{REGISTER_LINE}\n"
         end
 
         def show_post_install
@@ -69,7 +69,7 @@ module Phlex
           %w[
             app/javascript/controllers/index.js
             app/javascript/controllers/application.js
-          ].map { |p| File.join(destination_root, p) }.find { |p| File.exist?(p) }
+          ].map { File.join(destination_root, it) }.find { File.exist?(it) }
         end
 
         def relative(path)

data/lib/phlex/reactive/component.rb

@@ -62,12 +62,31 @@ module Phlex
       # A declared, client-invokable action and its param schema.
       Action = Data.define(:name, :params)
 
+      # A declared add/remove-row collection (issue #35): the list contract tied
+      # into one unit — the per-row item component, the container DOM id rows
+      # live in, an optional companion count id, an optional empty-state
+      # component, and a size resolver (a proc evaluated against the container
+      # instance) used to re-render the count and toggle the empty-state at the
+      # 0<->1 boundary. count/empty/size are nil when not declared, and the
+      # corresponding stream is simply omitted — so a list with just rows still
+      # works.
+      CollectionDefinition = Data.define(:name, :item, :container, :count, :empty, :size) do
+        # The collection's current size, evaluated against the bound container
+        # instance (instance_exec so the proc reads the component's ivars /
+        # association). nil when no resolver was declared — callers skip the
+        # count/empty streams that need a number.
+        def size_for(component)
+          size && component.instance_exec(&size)
+        end
+      end
+
       class_methods do
         # Declare the ActiveRecord (GlobalID-able) record this component is
         # rebuilt from. The signed token carries its GlobalID; the server
         # re-finds it on each action. State lives in the DB.
         def reactive_record(name)
           @reactive_record_key = name.to_sym
+          remove_instance_variable(:@reactive_record_ivar) if defined?(@reactive_record_ivar)
         end
 
         def reactive_record_key
@@ -80,6 +99,7 @@ module Phlex
         #   reactive_state :count, :open
         def reactive_state(*names)
           reactive_state_keys.concat(names.map(&:to_sym))
+          @reactive_state_ivars = nil # rebuild the cached [key, ivar] pairs
         end
 
         def reactive_state_keys
@@ -120,6 +140,59 @@ module Phlex
           reactive_actions.key?(name.to_sym)
         end
 
+        # Declare an add/remove-row collection (issue #35) — the list contract
+        # in one place, so actions append/prepend/remove a row WITHOUT
+        # re-deriving the container id, count, and empty-state in every action:
+        #
+        #   reactive_collection :items,
+        #     item: ItemRowComponent,    # the per-row Streamable component
+        #     container: "items-list",   # the DOM id rows live in
+        #     count: "items-count",      # optional companion id (the size badge)
+        #     empty: ItemsEmptyComponent, # optional empty-state component
+        #     size: -> { @record.items.size } # resolves the live size
+        #
+        # An action then governs the reply with one call:
+        #   reply.append(:items, item)   # row append + count + clear empty-state
+        #   reply.remove(:items, id)     # row remove + count + restore empty-state
+        #
+        # count/empty/size are optional: a list with just rows omits them and the
+        # corresponding stream isn't emitted. See Phlex::Reactive::Reply and the
+        # README "Reactive collections" section.
+        def reactive_collection(name, item:, container:, count: nil, empty: nil, size: nil)
+          reactive_collections[name.to_sym] =
+            CollectionDefinition.new(name: name.to_sym, item:, container:, count:, empty:, size:)
+        end
+
+        def reactive_collections
+          @reactive_collections ||= superclass.respond_to?(:reactive_collections) ? superclass.reactive_collections.dup : {}
+        end
+
+        def reactive_collection_def(name)
+          reactive_collections[name.to_sym]
+        end
+
+        def reactive_collection?(name)
+          reactive_collections.key?(name.to_sym)
+        end
+
+        # The record's instance-variable symbol (e.g. :@todo), computed once.
+        # reactive_token reads it on every render; interpolating :"@#{key}" each
+        # time would allocate a symbol per render. Nil when record-less. Memoized
+        # per class; reset alongside reactive_record so it can't go stale.
+        def reactive_record_ivar
+          return @reactive_record_ivar if defined?(@reactive_record_ivar)
+
+          @reactive_record_ivar = reactive_record_key ? :"@#{reactive_record_key}" : nil
+        end
+
+        # [string_key, ivar_symbol] pairs for the signed state, computed once.
+        # reactive_token walks these every render; precomputing the "count"/:@count
+        # forms avoids a String + Symbol allocation per key per render. Memoized
+        # per class; reset when reactive_state adds a key.
+        def reactive_state_ivars
+          @reactive_state_ivars ||= reactive_state_keys.map { [it.to_s, :"@#{it}"] }
+        end
+
         # Rebuild a component instance from a verified identity payload. Called
         # by the action endpoint after the token signature is verified.
         #
@@ -139,14 +212,14 @@ module Phlex
 
           if reactive_state_keys.any?
             state = payload.fetch("s", {})
-            reactive_state_keys.each do |key|
+            reactive_state_keys.each do
               # Use key presence, not the value: a signed `nil` (nullable state)
               # must round-trip distinctly. Only a genuinely absent key falls
               # back to the component's initialize default; `false` and `nil`
               # both survive.
-              next unless state.key?(key.to_s)
+              next unless state.key?(it.to_s)
 
-              kwargs[key] = state[key.to_s]
+              kwargs[it] = state[it.to_s]
             end
           end
 
@@ -211,12 +284,18 @@ module Phlex
       # live-update-as-you-type doesn't POST per keystroke. A blur flushes a
       # pending dispatch so the last edit is never dropped. Omit it for the
       # immediate-dispatch default.
+      # The verbatim JSON for an empty explicit-params payload. The common
+      # trigger (on(:increment), no params) hits this on EVERY render — skipping
+      # params.to_json (which re-serializes {} to the same "{}" each time) avoids
+      # a per-render allocation while keeping the wire format byte-identical.
+      EMPTY_PARAMS_JSON = "{}"
+
       def on(action_name, event: "click", debounce: nil, **params)
         attrs = {
           data: {
             action: "#{event}->reactive#dispatch",
             reactive_action_param: action_name.to_s,
-            reactive_params_param: params.to_json
+            reactive_params_param: params.empty? ? EMPTY_PARAMS_JSON : params.to_json
           }
         }
         attrs[:data][:reactive_debounce_param] = debounce if debounce
@@ -234,7 +313,7 @@ module Phlex
       # hatch). The trigger (on(:save)) stays on the button, not the field — so
       # focusing the input doesn't dispatch and collapse edit mode.
       def reactive_field(param, **attrs)
-        {name: param.to_s, **attrs}
+        { name: param.to_s, **attrs }
       end
 
       # Render an <input> already bound to an action param (issue #23). Sugar for
@@ -248,8 +327,8 @@ module Phlex
       # is the element's content, so the awkward FormBuilder positional split
       # (where name: lands after the options/html-options args) goes away:
       #   reactive_select(:status) { @statuses.each { |s| option(value: s, selected: s == @record.status) { s } } }
-      def reactive_select(param, **attrs, &block)
-        select(**reactive_field(param, **attrs), &block)
+      def reactive_select(param, **attrs, &)
+        select(**reactive_field(param, **attrs), &)
       end
 
       # Map a declared nested param onto Rails' <assoc>_attributes, carrying the
@@ -265,7 +344,7 @@ module Phlex
         existing = reactive_record_for_nested.public_send(association)
         merged[:id] = existing.id if existing
 
-        {"#{association}_attributes": merged}
+        { "#{association}_attributes": merged }
       end
 
       # Map a nested param onto <assoc>_attributes (with id preservation) AND
@@ -283,9 +362,7 @@ module Phlex
       # record-backed component).
       def reactive_record_for_nested
         key = self.class.reactive_record_key
-        unless key
-          raise Error, "#{self.class} must declare `reactive_record` to use nested_update!/nested_attributes"
-        end
+        raise Error, "#{self.class} must declare `reactive_record` to use nested_update!/nested_attributes" unless key
 
         instance_variable_get(:"@#{key}")
       end
@@ -297,17 +374,18 @@ module Phlex
       # record. Record-only ({c, gid}) and state-only ({c, s}) shapes are
       # unchanged.
       def reactive_token
-        payload = {"c" => self.class.name}
+        klass = self.class
+        payload = { "c" => klass.name }
 
-        if self.class.reactive_record_key
-          record = instance_variable_get(:"@#{self.class.reactive_record_key}")
-          payload["gid"] = record.to_gid.to_s
+        if (record_ivar = klass.reactive_record_ivar)
+          payload["gid"] = instance_variable_get(record_ivar).to_gid.to_s
         end
 
-        if self.class.reactive_state_keys.any?
-          payload["s"] = self.class.reactive_state_keys.to_h do |k|
-            [k.to_s, instance_variable_get(:"@#{k}").as_json]
-          end
+        state_ivars = klass.reactive_state_ivars
+        unless state_ivars.empty?
+          state = {}
+          state_ivars.each { |key, ivar| state[key] = instance_variable_get(ivar).as_json }
+          payload["s"] = state
         end
 
         Phlex::Reactive.sign(payload)

data/lib/phlex/reactive/engine.rb

@@ -13,27 +13,27 @@ module Phlex
 
       # Mount POST /reactive/actions -> Phlex::Reactive::ActionsController#create.
       # Apps can change the path with Phlex::Reactive.action_path before boot.
-      initializer "phlex_reactive.routes" do |app|
-        app.routes.append do
+      initializer "phlex_reactive.routes" do
+        it.routes.append do
           post Phlex::Reactive.action_path, to: "phlex/reactive/actions#create", as: :phlex_reactive_action
         end
       end
 
       # Make reactive_controller.js available to Propshaft/Sprockets so it can
       # be included via the asset pipeline or pinned in importmap.
-      initializer "phlex_reactive.assets" do |app|
-        if app.config.respond_to?(:assets)
-          app.config.assets.paths << root.join("app/javascript").to_s
-          app.config.assets.precompile += %w[phlex/reactive/reactive_controller.js]
+      initializer "phlex_reactive.assets" do
+        if it.config.respond_to?(:assets)
+          it.config.assets.paths << root.join("app/javascript").to_s
+          it.config.assets.precompile += %w[phlex/reactive/reactive_controller.js]
         end
       end
 
       # Auto-pin the client controller for importmap apps so it loads without
       # manual configuration. Apps that don't use importmap include it via the
       # asset pipeline instead (see README).
-      initializer "phlex_reactive.importmap", after: "importmap" do |app|
-        if defined?(::Importmap::Map) && app.respond_to?(:importmap)
-          app.importmap.pin(
+      initializer "phlex_reactive.importmap", after: "importmap" do
+        if defined?(::Importmap::Map) && it.respond_to?(:importmap)
+          it.importmap.pin(
             "phlex/reactive/reactive_controller",
             to: "phlex/reactive/reactive_controller.js",
             preload: true
@@ -41,6 +41,15 @@ module Phlex
         end
       end
 
+      # Flush memoized off-request view contexts on every code reload (dev) so a
+      # reloaded renderer controller class is never served from a stale memo. In
+      # production to_prepare runs once (eager load), so the cache simply builds
+      # fresh after boot. See Streamable.reset_all_view_contexts!.
+      config.to_prepare do
+        Phlex::Reactive::Streamable.reset_all_view_contexts!
+        Phlex::Reactive.reset_flash_builder!
+      end
+
       # Boot-time guard (issue #26): warn if the action path doesn't resolve to
       # the gem controller. Runs after_initialize so the host's full route set
       # (including a bottom-of-file catch-all that would shadow our appended

data/lib/phlex/reactive/reply.rb

@@ -25,6 +25,12 @@ module Phlex
     # Response remains the public value object (it's what the endpoint reads); it
     # is simply an internal detail you rarely name directly now.
     class Reply
+      # Distinguishes `reply.remove` (no args — remove the bound component
+      # itself) from `reply.remove(:items, model)` (remove a collection row).
+      # A sentinel, not nil, so `reply.remove(:items, nil)` stays unambiguous.
+      UNSET = Object.new
+      private_constant :UNSET
+
       def initialize(component)
         @component = component
       end
@@ -47,9 +53,30 @@ module Phlex
         Response.update(@component)
       end
 
-      # Remove the component's element from the DOM (render_self false).
-      def remove
-        Response.remove(@component)
+      # Reactive collections (issue #35) — add/remove a row in a declared
+      # reactive_collection, emitting the row stream + the count companion +
+      # the empty-state toggle as ONE Response. The bound component is the
+      # container (it carries the declaration + size resolver).
+      #
+      #   def add_item(...)    = (item = @list.items.create!(...); reply.append(:items, item))
+      #   def remove_item(id:) = (@list.items.find(id).destroy!;   reply.remove(:items, id))
+      #
+      # `model` is the row's record; remove also accepts the row's dom-id string.
+      def append(name, model)
+        Response.collection_append(@component, name, model)
+      end
+
+      def prepend(name, model)
+        Response.collection_prepend(@component, name, model)
+      end
+
+      # Two forms:
+      #   reply.remove               # remove the bound component's own element
+      #   reply.remove(:items, model) # remove a collection row + count + empty
+      def remove(name = UNSET, model = UNSET)
+        return Response.remove(@component) if name.equal?(UNSET)
+
+        Response.collection_remove(@component, name, model)
       end
 
       # Subject-free builders — pass straight through so they read naturally.

data/lib/phlex/reactive/response.rb

@@ -51,6 +51,104 @@ module Phlex
         # Escape hatch / multi-stream root: zero or more raw turbo-stream strings.
         def with(*strings) = new(streams: strings.flatten)
 
+        # --- Reactive collections (issue #35) ---
+        # Add/remove a row in a declared reactive_collection, emitting the row
+        # stream + the count companion update + the empty-state toggle as ONE
+        # Response. `component` is the bound CONTAINER (it carries the
+        # declaration and the size resolver); `model` is the row's record (or, for
+        # remove, a model OR a dom-id string). count/empty/size are optional — a
+        # stream is emitted only for the pieces declared.
+        #
+        # render_self is false: the row append/prepend/remove IS the update, so
+        # we must NOT also replace the whole container (that would re-render every
+        # row and clobber the just-streamed delta).
+        #
+        # token_component is the CONTAINER (cosmos#1939): a reply that does NOT
+        # re-render self must STILL refresh self's signed token, or the list is
+        # add-once-only — correct on the first click, then every subsequent dispatch
+        # from the list root is rejected (its token went stale) with no error. The
+        # container owns the add/remove trigger, so the endpoint appends its inert
+        # `reactive:token` stream (the same #30 machinery reply.streams uses) to roll
+        # the token forward without re-rendering the rows.
+        def collection_append(component, name, model)
+          definition = collection_def!(component, name)
+          new(streams: collection_add_streams(definition, component, model, :append),
+            render_self: false, token_component: component)
+        end
+
+        def collection_prepend(component, name, model)
+          definition = collection_def!(component, name)
+          new(streams: collection_add_streams(definition, component, model, :prepend),
+            render_self: false, token_component: component)
+        end
+
+        def collection_remove(component, name, model)
+          definition = collection_def!(component, name)
+          new(streams: collection_remove_streams(definition, component, model),
+            render_self: false, token_component: component)
+        end
+
+        private
+
+        # Resolve the declaration off the container's class, raising a clear error
+        # for an undeclared name (a typo'd collection should fail loudly, not
+        # silently emit an empty Response).
+        def collection_def!(component, name)
+          component.class.reactive_collection_def(name) ||
+            raise(Phlex::Reactive::Error, "undeclared reactive_collection :#{name} on #{component.class}")
+        end
+
+        # Row add (append/prepend) + count + empty-state clear. The empty-state is
+        # removed only when the list just crossed 0->1 (size == 1) — appending to
+        # an already-populated list leaves it untouched.
+        def collection_add_streams(definition, component, model, action)
+          streams = [definition.item.public_send(action, target: definition.container, model:)]
+          append_count_stream(streams, definition, component)
+
+          size = definition.size_for(component)
+          streams << definition.empty.new.to_stream_remove if definition.empty && size == 1
+          streams
+        end
+
+        # Row remove + count + empty-state restore. The empty-state is appended
+        # back into the container only when the list just emptied (size == 0).
+        def collection_remove_streams(definition, component, model)
+          streams = [collection_row_remove(definition, model)]
+          append_count_stream(streams, definition, component)
+
+          size = definition.size_for(component)
+          if definition.empty && size&.zero?
+            # Render the empty-state and append it INTO the container (not its
+            # own id) — restoring "No items yet" when the last row was removed.
+            # model: nil builds it argument-free (an empty-state is a static view).
+            streams << definition.empty.append(target: definition.container, model: nil)
+          end
+          streams
+        end
+
+        # Remove the row by its DOM id. Accepts the record (so dom_id is derived)
+        # or an already-built dom-id string (e.g. the value the row used as #id).
+        def collection_row_remove(definition, model)
+          if model.is_a?(String)
+            Phlex::Reactive.flash_builder.remove(model)
+          else
+            definition.item.remove(model)
+          end
+        end
+
+        # Append the count companion's update stream when a count id + a size
+        # resolver are both declared. The size is a number, HTML-escaped by Turbo.
+        def append_count_stream(streams, definition, component)
+          return unless definition.count
+
+          size = definition.size_for(component)
+          return if size.nil?
+
+          streams << update_stream(definition.count, size.to_s)
+        end
+
+        public
+
         # Partial / per-field update with a TOKEN-ONLY refresh (issue #30). Emits
         # EXACTLY the given streams — no forced full-self replace — but binds
         # `component` so the endpoint appends its tiny `to_stream_token` stream.