phlex-reactive 0.13.0 → 0.13.1

data/lib/phlex/reactive/settle.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # The job-side reply builder (issue #248) — what `reactive_settle` yields.
+    #
+    #   reactive_settle do |s|
+    #     if result.success?
+    #       s.remove(transfer, from: :unreconcilable)
+    #     else
+    #       s.replace(transfer)
+    #       s.flash(:alert, result.error)
+    #     end
+    #   end
+    #
+    # The verbs mirror `reply.*` and, critically, route through the SAME
+    # Phlex::Reactive::Collections decisions — so a job-side append emits the
+    # row AND the count companion AND the 0<->1 empty-state toggle, instead of
+    # the bare row `broadcast_to(append:)` gives you. That shared bookkeeping is
+    # the whole point: it is what the app can no longer get subtly wrong.
+    #
+    # Unlike Response, Settle is a MUTABLE accumulator, not a value object: a
+    # settle block is imperative (branch on the work's result, add a flash) and
+    # every verb returns self so the calls can also be chained.
+    #
+    # It collects streams; Phlex::Reactive::Settles owns the delivery — one
+    # durable message to the actor's shared one-shot stream, plus the optional
+    # peers broadcast.
+    class Settle
+      attr_reader :streams
+
+      # The rebuilt container — Settles reads it for the peers broadcast (it
+      # carries the collection declaration and the size resolver).
+      attr_reader :container
+
+      # `container` is the rebuilt container component (from_identity, off the
+      # request thread); `handle` is the Pending::Handle the enqueue captured.
+      def initialize(container, handle)
+        @container = container
+        @handle = handle
+        @streams = []
+        @peer_ops = []
+      end
+
+      # Re-render ONE row in place. The work ran and the row is simply different
+      # now (a failed re-execution going back to actionable, say). No count or
+      # empty-state stream: a replace cannot change the size.
+      #
+      # Accepts a record (resolved through the collection's row component) or a
+      # built Streamable component (its own #id is the target).
+      def replace(model, morph: false, effect: nil, **row_kwargs)
+        if model.is_a?(Phlex::Reactive::Streamable)
+          @streams << model.to_stream_replace(morph:, effect:)
+          # A built component carries its own identity, so peers can be handed
+          # the same instance — no definition needed.
+          @peer_ops << [nil, :replace, model, {}] if @handle.peers
+          return self
+        end
+
+        definition = definition!(nil)
+        @streams.concat(Phlex::Reactive::Collections.replace_streams(definition, model, effect:, **row_kwargs))
+        # A replace is NOT a collection delta (it moves no boundary), but peers
+        # still need it: without this, a failed re-execution goes back to
+        # actionable for the actor while every other operator keeps the stale
+        # row. It rides the ordinary row broadcast, not broadcast_collection_to.
+        peer(definition, :replace, model, row_kwargs)
+        self
+      end
+
+      # Remove a row: the row + the count companion + the empty-state restore at
+      # the 1->0 boundary. `from:` defaults to the collection reply.pending
+      # named, so the common case reads `s.remove(transfer)`.
+      def remove(model, from: nil, effect: nil)
+        definition = definition!(from)
+        @streams.concat(Phlex::Reactive::Collections.remove_streams(definition, @container, model, effect:))
+        peer(definition, :remove, model, {})
+        self
+      end
+
+      # Add a row: the row + the count companion + the empty-state clear at the
+      # 0->1 boundary.
+      def append(model, to: nil, effect: nil, **row_kwargs)
+        add(:append, model, to, effect, row_kwargs)
+      end
+
+      def prepend(model, to: nil, effect: nil, **row_kwargs)
+        add(:prepend, model, to, effect, row_kwargs)
+      end
+
+      # The case that motivated the whole issue: the work moved a record between
+      # two lists. Ordered remove-then-append so the size resolvers run against
+      # the post-move world in the order a reader expects, and so a row can
+      # never be momentarily present in both containers.
+      def move(model, from:, to:, effect: nil, **row_kwargs)
+        remove(model, from:, effect:)
+        append(model, to:, effect:, **row_kwargs)
+      end
+
+      # Refresh ONLY the collection's count companion — for a settle that
+      # changed the size without adding or removing a visible row. `name`
+      # defaults to the collection reply.pending named.
+      def count(name = nil)
+        @streams.concat(Phlex::Reactive::Collections.count_streams(definition!(name), @container))
+        self
+      end
+
+      # Tell the operator what happened. The job is where the OUTCOME is known,
+      # so this is how the page stops saying "Queued" forever.
+      def flash(level, content, target: Phlex::Reactive.flash_target, dismiss_after: nil)
+        @streams << Phlex::Reactive::Response.send(:flash_stream, level, content, target:, dismiss_after:)
+        self
+      end
+
+      # Server-pushed client DOM ops, same vocabulary as reply.js. Defaults to
+      # the container's id so self-scoped ops just work.
+      def js(ops, target: :__default)
+        resolved = target == :__default ? @handle.anchor : target
+        @streams << Phlex::Reactive::Response.js_stream(ops, target: resolved)
+        self
+      end
+
+      # Escape hatch: raw <turbo-stream> strings, exactly like reply.streams.
+      def streams!(*more)
+        @streams.concat(more.flatten)
+        self
+      end
+
+      # The peer deltas recorded alongside the actor's streams (issue #248).
+      # Collected rather than broadcast inline so Settles can send them AFTER
+      # the actor's message — the actor paid for the click and should not wait
+      # behind a fan-out of channel calls.
+      attr_reader :peer_ops
+
+      private
+
+      def add(action, model, name, effect, row_kwargs)
+        definition = definition!(name)
+        @streams.concat(
+          Phlex::Reactive::Collections.add_streams(definition, @container, model, action, row_kwargs, effect:)
+        )
+        peer(definition, action, model, row_kwargs)
+        self
+      end
+
+      # Resolve the collection: the explicit keyword, else the one reply.pending
+      # named. A settle with neither is a call-site mistake — fail loudly rather
+      # than silently emit nothing.
+      def definition!(name)
+        resolved = name || @handle.collection
+        unless resolved
+          raise Phlex::Reactive::Error,
+            "this settle has no collection to work on — name it (s.remove(record, from: :items)) " \
+            "or pass in: to reply.pending so the settle inherits it"
+        end
+
+        Phlex::Reactive::Collections.definition!(@container, resolved)
+      end
+
+      # Record a peer delta (only when reply.pending asked for peers:). The row
+      # kwargs ride along: a peer whose row component has a required init kwarg
+      # would otherwise raise, and one with an optional kwarg would render
+      # different markup than the actor got.
+      def peer(definition, action, model, row_kwargs)
+        return unless @handle.peers
+
+        @peer_ops << [definition.name, action, model, row_kwargs]
+      end
+    end
+  end
+end

data/lib/phlex/reactive/settles.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # The job half of the async-action lifecycle (issue #248). Include it in a
+    # job that does work an action merely ENQUEUED, and settle the UI when the
+    # work is actually done:
+    #
+    #   class ReExecuteJob < ApplicationJob
+    #     include Phlex::Reactive::Settles
+    #
+    #     def perform(transfer_id)          # signature UNCHANGED
+    #       transfer = Transfer.find(transfer_id)
+    #       result   = Transfers::ReExecuteService.call(transfer:)
+    #
+    #       reactive_settle do |s|
+    #         if result.success?
+    #           s.remove(transfer, from: :unreconcilable)
+    #         else
+    #           s.replace(transfer)
+    #           s.flash(:alert, result.error)
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    # ## The handle rides ActiveJob metadata
+    #
+    # `reply.pending` installs a Pending::Handle in a thread-local and runs the
+    # caller's enqueue inside it; #serialize below copies it into the job's
+    # metadata, #deserialize restores it. So `perform`'s ARITY IS UNTOUCHED and
+    # every OTHER caller of the same job — a nightly sweep, a webhook — enqueues
+    # it with no handle, in which case `reactive_settle` is a NO-OP that returns
+    # nil. That is load-bearing: these jobs almost always have non-UI callers.
+    #
+    # (`perform_now` does not round-trip through serialize/deserialize, so it
+    # carries no handle either — which is the correct reading: a synchronous
+    # call has no pending UI waiting on it.)
+    #
+    # ## A rolled-back action
+    #
+    # The endpoint builds the pending markers and the subscription directive only
+    # AFTER the action's transaction committed, so a rolled-back action leaks
+    # neither. Whether the ENQUEUE survives the rollback is the queue adapter's
+    # business, exactly as it is for a bare `perform_later` in an action — and if
+    # such a job does run, its settle broadcasts to a key nobody ever subscribed
+    # to. That is inert: the one-shot queue is reclaimed by pgbus's orphan sweep.
+    #
+    # ## Failure is never silent, and never permanent
+    #
+    # If the block raises, the target's pending markers are still cleared (the
+    # shimmer must not lie) and the error is RE-RAISED so the retry policy sees
+    # it. The shared subscription is deliberately NOT torn down on failure — a
+    # retry must still be able to reach the actor.
+    module Settles
+      # ActiveJob metadata key. Prefixed and spelled out — job metadata is a
+      # shared namespace with every other gem in the app.
+      SETTLE_METADATA_KEY = "phlex_reactive_settle"
+
+      # Capture the in-flight settle handle at ENQUEUE time. This is the same
+      # seam pgbus's own ActiveJob::CurrentAttributes integration uses, and it
+      # is adapter-agnostic: it works under :async, :test and :inline as well as
+      # a real backend, which is what app specs need.
+      def serialize
+        handle = Phlex::Reactive::Pending.current_handle
+        return super unless handle
+
+        super.merge(SETTLE_METADATA_KEY => handle.to_h_wire)
+      end
+
+      def deserialize(job_data)
+        super
+        @reactive_settle_handle = Phlex::Reactive::Pending::Handle.from_wire(job_data[SETTLE_METADATA_KEY])
+      end
+
+      # Settle the UI this job's work was enqueued for. Yields a
+      # Phlex::Reactive::Settle bound to the container, rebuilt from the signed
+      # identity the enqueue captured. Returns nil (and never runs the block)
+      # when this job carries no handle.
+      #
+      # `finish:` controls teardown of the SHARED one-shot subscription. All N
+      # settles of one reply.pending share ONE stream key (a key per record
+      # would mean a PGMQ table and an SSE connection per record), so tearing
+      # down on the first arrival would cut off the other N-1. The default
+      # (:auto) therefore finishes only when reply.pending marked exactly one
+      # target; a fan-out passes `finish: true` from whatever knows it is last —
+      # a Pgbus::Batch on_finish callback, or the final job of a staggered
+      # sequence. Until then the subscription is superseded by the container's
+      # next pending call, or closed when the page unloads.
+      def reactive_settle(finish: :auto)
+        handle = @reactive_settle_handle
+        return nil unless handle
+
+        settle = build_settle(handle)
+        yield settle
+        deliver_settle(handle, settle, finish)
+        settle
+      rescue ::StandardError
+        # The shimmer must resolve even when the work blew up. Clear the pending
+        # markers, keep the subscription (a retry still needs it), then re-raise
+        # so ActiveJob's retry policy gets its chance. A failure to broadcast the
+        # cleanup itself propagates too — there is nothing deliverable, and the
+        # next attempt is the only remaining hope.
+        broadcast_settle_cleanup(@reactive_settle_handle) if @reactive_settle_handle
+        raise
+      end
+
+      private
+
+      def build_settle(handle)
+        container = handle.container_class.constantize.from_identity(handle.container_payload)
+        Phlex::Reactive::Settle.new(container, handle)
+      end
+
+      # ONE durable message to the actor, carrying every stream this settle
+      # produced. Bundling is deliberate: the row, the count companion and the
+      # empty-state toggle belong to the same instant, and one message per settle
+      # is also why the ACTOR path needs no coalescing — there is nothing extra
+      # to collapse. (Coalescing applies to the PEERS path, where the aggregates
+      # really are separate channel calls.)
+      def deliver_settle(handle, settle, finish)
+        payload = settle.streams.join
+        payload += finish_streams(handle) if finish_settle?(handle, finish)
+        broadcast_settle_payload(handle, payload) unless payload.empty?
+        deliver_peers(handle, settle)
+      end
+
+      def finish_settle?(handle, finish)
+        return finish unless finish == :auto
+
+        handle.count.to_i <= 1
+      end
+
+      # The teardown: clear the pending markers from EVERY target this handle
+      # owns as well as the container, then remove the client's
+      # <pgbus-stream-source> by its deterministic id — its disconnectedCallback
+      # closes the SSE, so the subscription tears itself down with the content it
+      # delivered.
+      #
+      # Clearing the targets (not just the anchor) is load-bearing: a settle that
+      # only flashes — "could not re-execute", say — emits no row stream at all,
+      # so nothing swaps that row's node and its markers would otherwise sit
+      # there forever. Clearing an id whose node WAS replaced or removed is a
+      # harmless no-op (the client op resolves to nothing).
+      def finish_streams(handle)
+        clear_pending_streams(handle.target_ids + [handle.anchor]) + source_teardown(handle.anchor)
+      end
+
+      # One reactive:js clear per id, concatenated. html_safe by construction —
+      # each piece is a SafeBuffer from js_stream.
+      def clear_pending_streams(ids)
+        ids.uniq.map { clear_pending_js(it).to_s }.join.html_safe
+      end
+
+      def source_teardown(anchor)
+        target = Phlex::Reactive::Pending.source_id(anchor)
+        %(<turbo-stream action="remove" target="#{ERB::Util.html_escape(target)}"></turbo-stream>).html_safe
+      end
+
+      # reactive:js ops that strip the pending vocabulary from ONE element.
+      def clear_pending_js(target)
+        ops = Phlex::Reactive::JS.new
+          .remove_attr(:root, Phlex::Reactive::Pending::PENDING_ATTR)
+          .remove_attr(:root, "aria-busy")
+          .remove_attr(:root, "data-reactive-defer-pending")
+        Phlex::Reactive::Response.js_stream(ops, target:)
+      end
+
+      # The failure path: clear the pending state so the UI stops lying, WITHOUT
+      # tearing the subscription down (a retry must still be able to reach the
+      # actor).
+      #
+      # ATTRIBUTION is the constraint. A handle that owns exactly ONE target —
+      # which is every job the `job:`/`args:` sugar enqueues, since it narrows
+      # the handle per record — unambiguously identifies the row that just
+      # failed, so both it and the container are cleared. A handle that owns
+      # MANY (the block form, where the gem cannot map an arbitrary enqueue back
+      # to a record) cannot: clearing all of them would un-dim 176 rows that are
+      # still legitimately working, and clearing the container alone would claim
+      # the whole batch is done. So that case clears nothing and says so — the
+      # fan-out's own `finish: true` is what sweeps it up.
+      def broadcast_settle_cleanup(handle)
+        unless handle.target_ids.one?
+          warn_unattributable_failure(handle)
+          return
+        end
+
+        broadcast_settle_payload(handle, clear_pending_streams(handle.target_ids + [handle.anchor]))
+      end
+
+      def warn_unattributable_failure(handle)
+        return unless defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
+
+        ::Rails.logger.warn(
+          "[phlex-reactive] a settle failed for a #{handle.count}-target reply.pending — the gem " \
+          "cannot tell WHICH target this job owned (the enqueue used the block form), so no " \
+          "pending marker was cleared. Those markers clear when a settle calls " \
+          "reactive_settle(finish: true)."
+        )
+      end
+
+      # Durable is load-bearing: pgbus's since-id replay only covers
+      # PGMQ-persisted messages, and that replay is what closes the
+      # broadcast-before-subscribe race (the actor may still be opening the SSE
+      # when a fast job finishes).
+      def broadcast_settle_payload(handle, payload)
+        ::Pgbus.stream(handle.stream_key, durable: true).broadcast(payload)
+      end
+
+      # The peers leg (issue #248): the same collection deltas, broadcast to the
+      # container's stream so a second operator watching the same batch sees
+      # them. Sent AFTER the actor's message — the actor paid for the click and
+      # should not wait behind a fan-out of channel calls. `exclude:` is the
+      # actor's connection id, so they never get the delta twice.
+      # Peer delivery is BEST EFFORT and never fails the job. The actor's durable
+      # message has already been sent by the time we get here; re-raising would
+      # hand the job to the retry policy, and the retry would re-run `perform`
+      # and send the ACTOR's settle a second time — duplicating the pieces that
+      # are not idempotent (a flash, an empty-state append). A peer who missed a
+      # cross-tab courtesy is a far smaller problem than an actor who sees the
+      # flash twice, and every other broadcast in the gem is best-effort too.
+      def deliver_peers(handle, settle)
+        return if handle.peers.nil? || settle.peer_ops.empty?
+
+        keys = handle.peers.map { it.is_a?(Hash) ? GlobalID::Locator.locate(it["gid"]) : it }
+        container = settle.container
+
+        settle.peer_ops.each { deliver_peer_op(container, keys, handle, it) }
+      rescue ::StandardError => e
+        log_peer_failure(e)
+      end
+
+      # ONE peer op. A collection delta (append/prepend/remove) goes through
+      # broadcast_collection_to so peers get the count companion and the
+      # empty-state toggle too; a REPLACE moves no boundary, so it rides the
+      # ordinary row broadcast. A nil name means the settle handed us a built
+      # component, which self-targets.
+      def deliver_peer_op(container, keys, handle, peer_op)
+        name, action, model, row_kwargs = peer_op
+        return broadcast_peer_component(keys, handle, model) if name.nil?
+
+        if action == :replace
+          definition = Phlex::Reactive::Collections.definition!(container, name)
+          return definition.item.broadcast_to(
+            *keys, replace: definition.item.send(:build, model, row_kwargs || {}),
+            exclude: handle.connection_id
+          )
+        end
+
+        container.class.broadcast_collection_to(
+          *keys, container:, in: name, action => model, row: row_kwargs || {},
+          exclude: handle.connection_id,
+          coalesce: Phlex::Reactive.settle_coalesce_window_ms
+        )
+      end
+
+      def broadcast_peer_component(keys, handle, component)
+        component.class.broadcast_to(*keys, replace: component, exclude: handle.connection_id)
+      end
+
+      def log_peer_failure(error)
+        return unless defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
+
+        ::Rails.logger.warn(
+          "[phlex-reactive] a settle's PEER broadcast failed (#{error.class}: #{error.message}) — " \
+          "the actor's settle already landed, so the job is NOT failed: retrying it would deliver " \
+          "the actor's settle (and its flash) a second time."
+        )
+      end
+    end
+  end
+end

data/lib/phlex/reactive/streamable.rb

@@ -50,6 +50,10 @@ module Phlex
         prepend: "prepend", remove: "remove", js: "reactive:js"
       }.freeze
       BROADCAST_SELF_TARGETING = %i[replace remove].freeze
+      # The broadcast_collection_to verbs (issue #248) — a collection DELTA, so
+      # only the three that change the size. (A `replace:` row is an ordinary
+      # broadcast_to: it moves no boundary and needs no count refresh.)
+      COLLECTION_VERBS = %i[append prepend remove].freeze
       BROADCAST_CONTAINER = %i[update append prepend].freeze
       BROADCAST_MORPHABLE = %i[replace update].freeze
 
@@ -118,7 +122,8 @@ module Phlex
         # thread-local path (so exclude:/visible_to: reach pgbus and Action Cable
         # no-ops). Self-targeting verbs derive the target from the component's #id
         # and REQUIRE a Streamable payload; container verbs need an explicit target.
-        def broadcast_component(owner, verb, payload, component, keys, morph:, target:, exclude:, visible_to:, effect: nil)
+        def broadcast_component(owner, verb, payload, component, keys, morph:, target:, exclude:, visible_to:,
+                                effect: nil, coalesce: nil)
           if verb == :js && !effect.nil?
             raise ArgumentError,
               "broadcast_to js: takes no effect: — effects animate element streams (replace/update/" \
@@ -136,7 +141,7 @@ module Phlex
           Phlex::Reactive.instrument(
             "broadcast", { component: component_name, stream_action: BROADCAST_VERBS[verb], streamables: keys.size }
           ) do
-            with_pgbus_broadcast_opts(exclude:, visible_to:) do
+            with_pgbus_broadcast_opts(exclude:, visible_to:, coalesce:) do
               # A broadcast render NEVER inherits the actor's url_options (issue
               # #232): this call may run inside an action request (where the
               # endpoint threaded the actor's host), but subscribers can be on
@@ -150,6 +155,21 @@ module Phlex
           end
         end
 
+        # Broadcast ALREADY-RENDERED html (issue #248) — no component to build or
+        # render. The count companion is a plain number, not a component, so it
+        # has no render leg; everything else (instrumentation, the pgbus
+        # thread-locals, the per-key dispatch) is identical to
+        # broadcast_component.
+        def broadcast_raw(owner, verb, target, html, keys, exclude: nil, visible_to: nil, coalesce: nil)
+          Phlex::Reactive.instrument(
+            "broadcast", { component: owner.name, stream_action: BROADCAST_VERBS[verb], streamables: keys.size }
+          ) do
+            with_pgbus_broadcast_opts(exclude:, visible_to:, coalesce:) do
+              keys.each { dispatch_broadcast(verb, it, target, html, nil, false, nil) }
+            end
+          end
+        end
+
         # Validate + serialize broadcast ops: reject actor-only ops (focus steals
         # focus in every tab; submit force-submits every subscriber's form;
         # paste_into reads every subscriber's clipboard) and an empty chain (a
@@ -189,18 +209,27 @@ module Phlex
         # instrument_broadcast uses (issue #185/#187). Duplicated at module level so
         # the shared broadcast_component owns its transport threading. On Action
         # Cable / old pgbus this is a pure `yield`.
-        def with_pgbus_broadcast_opts(exclude:, visible_to:)
+        # `coalesce:` (issue #248) rides the SAME thread-local convention. Unlike
+        # a kwarg, an unknown thread-local is silently IGNORED by a pgbus that
+        # does not forward it (pre-zoolutions/pgbus#465) — so setting it is
+        # always safe: an old pgbus just does not coalesce (more messages, same
+        # correctness), a new one does. That is why there is no capability gate
+        # here beyond the existing pgbus_streams? one.
+        def with_pgbus_broadcast_opts(exclude:, visible_to:, coalesce: nil)
           return yield unless Phlex::Reactive.pgbus_streams?
 
           prev_exclude = Thread.current[:pgbus_broadcast_exclude]
           prev_visible = Thread.current[:pgbus_broadcast_visible_to]
+          prev_coalesce = Thread.current[:pgbus_broadcast_coalesce]
           Thread.current[:pgbus_broadcast_exclude] = exclude
           Thread.current[:pgbus_broadcast_visible_to] = visible_to
+          Thread.current[:pgbus_broadcast_coalesce] = coalesce
           yield
         ensure
           if Phlex::Reactive.pgbus_streams?
             Thread.current[:pgbus_broadcast_exclude] = prev_exclude
             Thread.current[:pgbus_broadcast_visible_to] = prev_visible
+            Thread.current[:pgbus_broadcast_coalesce] = prev_coalesce
           end
         end
 
@@ -494,6 +523,49 @@ module Phlex
           )
         end
 
+        # Broadcast a collection DELTA — the row PLUS the count companion PLUS
+        # the 0<->1 empty-state toggle (issue #248), the broadcast-side
+        # counterpart of reply.append / reply.remove.
+        #
+        #   Container.broadcast_collection_to(@list, :todos,
+        #     container: @list_component, append: todo, in: :todos,
+        #     exclude: reactive_connection_id)
+        #
+        # broadcast_to(append:) deliberately emits the BARE row: it has no
+        # container instance, so it cannot resolve the declaration or run the
+        # size resolver. This verb takes that instance as `container:` and runs
+        # the SAME Phlex::Reactive::Collections decisions the reply path runs,
+        # so a peer's list stays as correct as the actor's.
+        #
+        # `in:` names the declared reactive_collection; the verb is `append:`,
+        # `prepend:` or `remove:` (exactly one). `exclude:`/`visible_to:` thread
+        # to pgbus as everywhere else.
+        #
+        # `row:` is the row component's extra init kwargs (issue #186's row_kwargs
+        # on the reply side) — pass the SAME ones the actor got, or a peer whose
+        # row component has a required kwarg raises instead of rendering.
+        #
+        # `coalesce:` (a window in ms, or true) applies to the AGGREGATE streams
+        # only — the count companion and the empty-state toggle are idempotent
+        # replaces of stable targets, so a 177-row fan-out collapses to a
+        # handful of count refreshes. The ROW stream is NEVER coalesced: an
+        # append is not idempotent and each row is a distinct target. Needs
+        # pgbus with zoolutions/pgbus#465; on anything older the thread-local is
+        # ignored and every aggregate stream simply goes out (correct, chattier).
+        # (`in:` is a Ruby keyword, so it cannot be a named parameter — it is
+        # pulled out of **opts, which then holds exactly the verb kwarg.)
+        def broadcast_collection_to(*streamables, container:, exclude: nil, visible_to: nil,
+                                    coalesce: nil, effect: nil, row: {}, **opts)
+          name = opts.delete(:in) ||
+                 raise(ArgumentError, "broadcast_collection_to needs in: :collection_name")
+          action, model = extract_collection_verb(opts)
+          definition = Phlex::Reactive::Collections.definition!(container, name)
+          keys = [streamables]
+
+          broadcast_collection_row(definition, action, model, keys, exclude:, visible_to:, effect:, row:)
+          broadcast_collection_aggregates(definition, container, action, keys, exclude:, visible_to:, coalesce:)
+        end
+
         # Define the guided-error stub for each removed broadcast method (issue
         # #185). `verb` is referenced in define_method AND the message, so the outer
         # block param must be named — `it` is illegal here.
@@ -519,6 +591,77 @@ module Phlex
           verb.first
         end
 
+        # The collection verb split — append:/prepend:/remove:, exactly one.
+        def extract_collection_verb(verb)
+          unless verb.size == 1 && COLLECTION_VERBS.include?(verb.keys.first)
+            raise ArgumentError,
+              "broadcast_collection_to needs exactly ONE verb kwarg " \
+              "(#{COLLECTION_VERBS.join("/")}), got #{verb.keys.inspect}"
+          end
+
+          verb.first
+        end
+
+        # The ROW leg: routed through the ordinary broadcast_to so the row is
+        # built, rendered and instrumented exactly like every other broadcast.
+        # Never coalesced (distinct targets; an append is not idempotent).
+        #
+        # A STRING model is an already-built dom id, the same form
+        # reply.remove(id, from:) and Collections.row_remove_stream accept.
+        # Building a row component from it would hand the id to the component's
+        # initializer as if it were a record — so it short-circuits to a raw
+        # remove of that target instead.
+        def broadcast_collection_row(definition, action, model, keys, exclude:, visible_to:, effect:, row: {})
+          if action == :remove
+            if model.is_a?(::String)
+              return Phlex::Reactive::Streamable.broadcast_raw(
+                definition.item, :remove, model, nil, keys, exclude:, visible_to:
+              )
+            end
+
+            return Phlex::Reactive::Streamable.broadcast_component(
+              definition.item, :remove, model, definition.item.send(:build, model, row), keys,
+              morph: false, target: nil, exclude:, visible_to:, effect:
+            )
+          end
+
+          Phlex::Reactive::Streamable.broadcast_component(
+            definition.item, action, model, definition.item.send(:build, model, row), keys,
+            morph: false, target: definition.container, exclude:, visible_to:, effect:
+          )
+        end
+
+        # The AGGREGATE leg: the count companion and the empty-state toggle,
+        # both idempotent replaces of stable targets — so both carry `coalesce:`.
+        def broadcast_collection_aggregates(definition, container, action, keys, exclude:, visible_to:, coalesce:)
+          delta = action == :remove ? :remove : :add
+          # Resolve the size ONCE (it is usually a DB count) and hand the same
+          # value to both decisions — see Collections.size_of.
+          size = Phlex::Reactive::Collections.size_of(definition, container)
+
+          if (refresh = Phlex::Reactive::Collections.count_refresh(definition, container, size))
+            # NOT `target, size = refresh` — that would rebind `size` to the
+            # count's STRING form and hand a String to empty_toggle below.
+            count_target, count_html = refresh
+            Phlex::Reactive::Streamable.broadcast_raw(
+              self, :update, count_target, count_html, keys, exclude:, visible_to:, coalesce:
+            )
+          end
+
+          case Phlex::Reactive::Collections.empty_toggle(definition, container, delta, size)
+          when :clear
+            Phlex::Reactive::Streamable.broadcast_component(
+              definition.empty, :remove, nil, definition.empty.new, keys,
+              morph: false, target: nil, exclude:, visible_to:, coalesce:
+            )
+          when :restore
+            Phlex::Reactive::Streamable.broadcast_component(
+              definition.empty, :append, nil, definition.empty.new, keys,
+              morph: false, target: definition.container, exclude:, visible_to:, coalesce:
+            )
+          end
+        end
+
         # Coerce a verb payload into a built component: a Phlex component passes
         # through (issue #185 — built payloads); a Hash is init kwargs verbatim (no
         # **options collision); anything else is the record built via

data/lib/phlex/reactive/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Reactive
-    VERSION = "0.13.0"
+    VERSION = "0.13.1"
   end
 end