phlex-reactive 0.13.0 → 0.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6181c7ab8900e42562ecb8b82e8c52a30af5b643eadd89b045c60d1b48c7e87
-  data.tar.gz: cfa42f5aa9230785cb451cfcefc0c280d5d51d0c648d5bf797911807a59291b4
+  metadata.gz: '049bef601e70264a857668de2ad7766f9b4edae020ded0844d2f5efacdc0607d'
+  data.tar.gz: 1293bfd5f14ef03fa1889444c662846d4f1129155e1b9ea458b48529a7644b3b
 SHA512:
-  metadata.gz: 01744edf54e1a720c5365413ad4f70334b88d5351685d7476ec1a782f146e9c0e97cdbe66d536d36da6fcf52e31b8dee0e9320019fca5313282dea3ce0a01cc7
-  data.tar.gz: dbaf5238767322e2ce1f0ca4bd44d93f3712f56189050984bcc3f612fa4f650d994b5813afd52fd163973543f346a47d6eca75627e73d77008a0ce83cfe9d3f4
+  metadata.gz: d3fe07e736d776bdcdc594ef9d4cb3e91aea4c0cf81d6bf9c0f703d5de744e2d60394b79c4bad02c32b98ac04fc99d3b1a6746c88ff8e377e94e259765ddbfec
+  data.tar.gz: eb3c04c9cea640d1c6662e602a77b1b49e4e5e7204cb6c587916440c5695064a84219348127b7282ee83b9dd6e6fa57dced2ca9dd79fd7eba1cb1e33e56d6419

data/CHANGELOG.md

@@ -6,16 +6,77 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
-### Fixed
-
-- **`rake release` re-locks the root `Gemfile.lock` too.** Since #246 the gem
-  root's lockfile is committed, and it pins `phlex-reactive` by local path — so
-  the version bump left it stale and the Release workflow's frozen
-  `bundle install` refused it (v0.13.0's first attempt). The release task now
-  re-locks and commits every tracked lockfile that pins the gem (root + docs).
 
 ### Added
 
+- **`bin/release` — the release front door, ported from pgbus.** Works out the
+  next version (`patch` by default, `minor`, `major`, or an explicit `X.Y.Z`
+  with an optional `v`), prints the commits since the last tag, and hands off
+  to `rake release[X.Y.Z]` after a y/N confirm. `list` and `--dry-run` are
+  read-only. It refuses to run off anything but a clean, up-to-date `main` —
+  the rake task pushes `origin main`, so starting anywhere else either fails
+  the push or ships whatever local commits happen to be sitting there — and
+  refuses an existing tag unless `--force` (which maps to `release[X.Y.Z,force]`).
+  It also warns when `version.rb` and the newest `v*` tag disagree.
+
+- **Async-action lifecycle: `reply.pending` + `reactive_settle` (#248).** An
+  action that *enqueues* work can now reply truthfully. The endpoint renders the
+  reply inside the action's transaction while the queue publishes on commit, so
+  any `reply.morph` after an enqueue is guaranteed to draw the pre-job world —
+  rows still present, buttons still live — beside the "Queued 177" flash the
+  same reply emitted. Apps worked around it with a `queued:` kwarg threaded into
+  every row component plus a second render branch; ~60 lines per screen, and the
+  page still never learned the outcome.
+
+  `reply.pending(records, in: :collection, job:, args:)` — or the block form,
+  `reply.pending(records, in: :collection) { MyService.call(...) }`, which every
+  ActiveJob enqueued inside captures — marks the targets with
+  `data-reactive-pending` + `aria-busy` (style it in one CSS rule), opens ONE
+  shared durable subscription anchored on the container, and hands the
+  fulfilment to your job. The job includes `Phlex::Reactive::Settles` and calls
+  `reactive_settle { |s| s.remove(record) }` (also `replace` / `append` /
+  `prepend` / `move(from:, to:)` / `count` / `flash` / `js` / `streams!`), which
+  emits the row **plus** the count companion **plus** the 0↔1 empty-state
+  toggle. `peers: true` broadcasts the same delta to the container's record
+  stream for a second operator watching the batch.
+
+  The handle rides **ActiveJob metadata**, so `perform`'s arity is untouched and
+  every other caller of the same job — a nightly sweep, a webhook — runs
+  unchanged with `reactive_settle` as a no-op. The `job:`/`args:` form narrows
+  each job's handle to its own record, so a job that raises clears exactly that
+  row's markers before re-raising for the retry policy. No client changes: the
+  markers ride the existing `reactive:js` op lane and the subscription is the
+  `reactive:defer` push-lane wire from #165.
+
+- **`Phlex::Reactive::Collections` — the collection bookkeeping is now a public
+  module (#248).** The count companion and the 0↔1 empty-state boundary used to
+  live in `Response`'s privates, reachable only from `reply.*`, so a job or a
+  broadcast had to re-derive them by hand and got the boundary subtly wrong.
+  `Response.build_collection_*` now delegates, and the settle and broadcast
+  paths read the same `count_refresh` / `empty_toggle` decisions — they cannot
+  drift. No behavior change for existing `reply.append` / `reply.remove` calls,
+  except that each delta now resolves the `size:` proc **once** instead of twice
+  (one fewer query per add/remove, and the count companion can no longer
+  disagree with the empty-state toggle it ships beside when a concurrent write
+  lands between the two reads).
+
+- **`Container.broadcast_collection_to(*keys, container:, in:, append:/prepend:/remove:)`
+  (#248).** The broadcast-side counterpart of `reply.append` / `reply.remove`:
+  the row **plus** the count companion **plus** the empty-state toggle, instead
+  of the bare row `broadcast_to(append:)` emits. `coalesce:` applies to the
+  aggregate streams only (idempotent replaces of stable targets), so a 177-row
+  fan-out collapses to a handful of count refreshes; the row stream is never
+  coalesced. Needs pgbus with zoolutions/pgbus#465 — a thread-local an older
+  pgbus simply ignores, so it degrades to "chattier, equally correct" rather
+  than breaking.
+
+- **`Phlex::Reactive.settle_coalesce_window_ms` (50) and `.settle_capable?`
+  (#248).** The window governs the aggregate (count / empty-state) streams on
+  the peers path. `settle_capable?` reports whether `reply.pending` has a lane
+  at all; without one it degrades to a plain enqueue (no markers, no lie) with a
+  one-time warning. There is deliberately no `settle_token_ttl` — a settle has
+  no pull lane for a token to govern.
+
 - **`reactive_persist` drafts rich editors (#241).** A named `lexxy-editor`,
   `trix-editor` or bare `[contenteditable]` inside a `reactive_persist` root is
   now drafted and restored through its **own** value surface — the editor's
@@ -380,6 +441,33 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixed
 
+- **`rake release` bumps the pin in every tracked lockfile (#247, #253).** Since
+  #246 the gem root's `Gemfile.lock` is committed alongside `docs/Gemfile.lock`,
+  and both pin `phlex-reactive` by local path — so a version bump that left them
+  alone shipped a stale lockfile, and the Release workflow's frozen
+  `bundle install` refused it (v0.13.0's first attempt).
+
+  The task now bumps that pin **with a text edit**, not `bundle lock`. #247's
+  first cut used `bundle lock --local`, which is a full re-resolve — and a
+  re-resolve trips over constraints that have nothing to do with this gem:
+  `docs/Gemfile.lock` declares Linux platforms for the Kamal deploy, and
+  resolving `thruster` for those against a Mac's installed gems fails ("Could
+  not find gems matching 'thruster' valid for all resolution platforms"), which
+  aborted v0.13.1's first attempt mid-release with `version.rb` already bumped.
+  A re-resolve also silently folds unrelated dependency drift into the release
+  commit the moment a Gemfile is out of sync with its lock. The only line a
+  version bump changes is the path-gem pin, so the task edits exactly that (the
+  `PATH` spec + the `CHECKSUMS` entry) in place — deterministic on any machine,
+  no network, no installed gems, the same 2-line diff bundler produced. A
+  lockfile that names no pin at all now **aborts** the release rather than
+  reporting itself already current — and that check runs in a PREFLIGHT, before
+  the task does anything destructive or irreversible: before the `force`
+  cleanup that deletes the GitHub release and its tag, and before `version.rb`
+  or any lockfile is written. So an abort leaves the release intact and the tree
+  clean, rather than a deleted release or a half-bumped tree the clean-tree
+  guard would then block on retry.
+  pgbus's release task made the same call after the same failure.
+
 - **`Component::Action` renamed `ActionDefinition` — it shadowed a host kit
   component named `Action` under dev autoloading (#233).** The mixin sits in
   every reactive component's ancestry, so its bare `Action` constant satisfied

data/README.md

@@ -406,6 +406,8 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 | `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(*)` / `.js(ops)` | Return from an action to control the reply (flash, remove, redirect, multi-stream, server-pushed client ops). 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). |
+| `reply.pending(records, in:, job:) { … }` + `include Phlex::Reactive::Settles` / `reactive_settle` | For an action that **enqueues** work: mark targets pending, let your job settle them (row + count + empty-state) when it finishes. See [Async actions](#async-actions-replypending--reactive_settle). |
+| `Container.broadcast_collection_to(*keys, container:, in:, append:/prepend:/remove:)` | The broadcast-side `reply.append`/`reply.remove`: the row **plus** the count companion **plus** the empty-state toggle, to peers. |
 
 Param types: `:string` (default), `:integer`, `:float`, `:boolean`, `:file`,
 `:date`, `:datetime`, `:decimal`. Anything not in the schema is dropped before
@@ -1884,6 +1886,7 @@ def update(quantity:, price:) = (@item.update!(quantity:, price:); reply.streams
 | `reply.streams(*streams)` | **partial update** — emit exactly these streams (no full-self replace) + a tiny token-only refresh, so live inputs survive; for per-field grid editing (issue #30) |
 | `.js(ops, target: …)` | also push **client DOM ops** (focus, dispatch, class/attr toggles) over a `reactive:js` stream, applied AFTER the render — `reply.morph.js(js.focus("[name=next]"))` focuses the morphed field (issue #97) |
 | `.defer(component, placeholder:, morph:)` | take an **expensive segment off the actor's critical path** (issue #165) — the reply returns immediately and the real render streams to the SAME actor when ready; see [Deferred segments](#deferred-segments-replydefer--reactive_lazy) |
+| `reply.pending(records, in:, job:, args:, peers:) { … }` | the action **enqueues** the work: mark the targets pending now and let **your own job** settle them when the work is actually done (issue #248); see [Async actions](#async-actions-replypending--reactive_settle) |
 | `reply.with(*streams)` / `#stream(*more)` | multi-stream (self re-render still injected for the token) |
 
 `.flash`/`.stream`/`.also` are additive on a self-replace, so the component's
@@ -2449,11 +2452,240 @@ end
 - **`remove` takes the record or its `dom_id` string** — a just-destroyed
   ActiveRecord still answers `dom_id` correctly, so `reply.remove(todo, from: :items)`
   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_to(..., append: model, exclude: reactive_connection_id)` —
-  `reactive_collection` is the per-actor add/remove + count + empty-state wrapper,
-  not a replacement for the broadcast.
+- **Reply governs the actor's HTTP response only.** For a *cross-tab* live list,
+  broadcast the delta with `NotificationsList.broadcast_collection_to(*keys,
+  container: self, in: :notifications, append: model, exclude: reactive_connection_id)`
+  — that emits the row **plus** the count companion **plus** the empty-state
+  toggle, through the same decisions the reply path uses. (Plain
+  `broadcast_to(append:)` still works and still emits the **bare row**: it has no
+  container instance, so it cannot resolve the declaration or run `size:`.)
+- **When the work is asynchronous**, an action that merely enqueues it cannot
+  reply with a delta at all — the reply renders before the job touches the
+  database. Use [`reply.pending`](#async-actions-replypending--reactive_settle)
+  and let the job settle the row.
+
+### Async actions (`reply.pending` + `reactive_settle`)
+
+An action that **does** the work can reply honestly. An action that
+**enqueues** the work cannot — and until issue #248 every app worked around it
+the same way.
+
+The endpoint runs your action inside a transaction and renders the reply
+*there*, while the queue adapter publishes on **commit**. So any `reply.morph`
+after an enqueue renders from a database the job has not touched yet, and is
+*guaranteed* to draw the pre-job world — rows still present, buttons still live,
+counts unchanged — sitting right beside the "Queued 177 transfers" flash the
+same reply emitted:
+
+```ruby
+def restore_all
+  count = BatchRestoreService.call(bulk_payment: @bulk_payment)   # fans out N jobs
+  reply.morph.flash(:notice, "Putting #{count} back…")            # renders the PRE-job world
+end
+```
+
+The usual fix is a `queued:` kwarg threaded into every row component with a
+second render branch, a `@queued_*` flag on the container, and the header
+button's count forced to `0` — ~60 lines of identical bookkeeping per screen.
+And it still never tells the operator the **outcome**: the page says "Queued"
+forever until someone reloads.
+
+`reply.pending` replaces all of it:
+
+```ruby
+class ReconcileQueue < ApplicationComponent
+  include Phlex::Reactive::Component
+
+  reactive_collection :unreconcilable,
+    item: TransferRow, container: "unreconcilable",
+    count: "unreconcilable-count", empty: NothingToReconcile,
+    size: -> { @bulk_payment.transfers.unreconcilable.count }
+
+  action :re_execute, params: {transfer_id: :integer}
+  action :restore_all
+
+  # ONE record — the job settles it, and the subscription tears itself down.
+  def re_execute(transfer_id:)
+    transfer = @bulk_payment.transfers.re_executable.find(transfer_id)
+    authorize! transfer, :update?
+    reply.pending(transfer, in: :unreconcilable, job: ReExecuteJob, args: [transfer.id])
+  end
+
+  # A FAN-OUT — the enqueue lives in the block, so the service object's own
+  # perform_later calls capture the settle handle too.
+  def restore_all
+    authorize! @bulk_payment, :update?
+    restorable = @bulk_payment.transfers.restorable.to_a
+    reply.pending(restorable, in: :declined, peers: true) do
+      BatchRestoreService.call(bulk_payment: @bulk_payment)
+    end.flash(:notice, "Putting #{restorable.size} back…")
+  end
+end
+```
+
+and the job settles it when the work is **actually** done:
+
+```ruby
+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)                     # row + count + empty-state
+      else
+        s.replace(transfer)                    # back to actionable
+        s.flash(:alert, result.error)          # the operator learns the outcome
+      end
+    end
+  end
+end
+```
+
+and the case that motivated the whole thing — work that moves a record between
+two lists — is one call:
+
+```ruby
+reactive_settle { |s| s.move(transfer, from: :declined, to: :unreconcilable) }
+```
+
+#### What the reply actually does
+
+`reply.pending` deliberately does **NOT** re-render the container (that is the
+bug). It emits:
+
+1. a `data-reactive-pending="true"` + `aria-busy="true"` marker on every target,
+   over the existing `reactive:js` op lane — style it in one CSS rule:
+
+   ```css
+   [data-reactive-pending] { opacity: .5; pointer-events: none; }
+   ```
+
+2. **one** subscription directive, anchored on the container, opening a
+   single durable one-shot stream that **all N settles share**;
+3. an inert `reactive:token` refresh, so the container's signed token rolls
+   forward and the list is not act-once-only.
+
+| `reply.pending(...)` | |
+|---|---|
+| `records` | one record, an enumerable of records, or built Streamable components |
+| `in: :name` | the `reactive_collection` the records live in — how their row DOM ids *and* the count/empty-state bookkeeping are resolved (required for records) |
+| a block | your enqueue. **Anything ActiveJob-enqueued inside it captures the settle handle**, including from a service object |
+| `job:` / `args:` | sugar for the common case. `args:` is an Array (one record) or a Proc called per record (`args: ->(r) { [r.id] }`); omitted means `perform_later(record)` |
+| `peers: true` | also broadcast each settle to the container's record stream, so a second operator watching the same batch sees it. **Default is actor-only**, matching `reply.defer` |
+
+| `reactive_settle` yields a settle builder | |
+|---|---|
+| `s.replace(record)` | re-render the row in place (no count churn — a replace moves no boundary) |
+| `s.remove(record, from: :name)` | row + count + empty-state restore. `from:` defaults to the collection `reply.pending` named |
+| `s.append(record, to: :name)` / `s.prepend` | row + count + empty-state clear |
+| `s.move(record, from:, to:)` | ordered remove-then-append between two collections |
+| `s.count(:name)` | refresh only the count companion |
+| `s.flash(level, content)` | tell the operator the outcome |
+| `s.js(ops)` / `s.streams!(*raw)` | the `reply.js` / `reply.streams` escape hatches |
+
+#### The rules that make it safe
+
+- **The handle rides ActiveJob metadata, not `perform`'s arity.** `reply.pending`
+  installs it in a thread-local and runs your enqueue inside it;
+  `Settles#serialize` copies it into the job's metadata. So **every other caller
+  of the same job — a nightly sweep, a webhook — keeps working unchanged**, and
+  `reactive_settle` is simply a no-op there. That is load-bearing: these jobs
+  almost always have non-UI callers.
+- **A job that raises still clears the pending state — when it can attribute
+  it.** The `job:`/`args:` form enqueues one job per record and narrows each
+  job's handle to *that record's* target, so a failure clears exactly its row
+  and the container, then re-raises for your retry policy. The **block** form
+  cannot be narrowed (the gem cannot map an arbitrary enqueue back to a record),
+  so a failure there clears nothing and logs why — un-dimming 176 rows that are
+  still working would be a worse lie. Those markers clear at `finish: true`.
+  The subscription is deliberately **not** torn down on failure — a retry must
+  still be able to reach the actor.
+- **Finishing clears every target, not just the container.** A settle that only
+  flashes emits no row stream, so nothing swaps that row's node — the finish
+  sweep is what removes its markers.
+- **ONE stream key per `reply.pending` call.** A durable broadcast to a
+  never-seen key creates a real PGMQ table (reclaimed by pgbus's hourly orphan
+  sweep at a 24h threshold), so a key per record would leave 177 tables sitting
+  for a day and open 177 SSE connections. All N settles share one key and one
+  subscription.
+- **Teardown is therefore explicit.** Because the key is shared, tearing down on
+  the *first* arrival would cut off the other N−1. `reactive_settle` finishes
+  automatically 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 `reply.pending` or
+  closed when the page unloads.
+- **`reply.pending` needs the defer PUSH lane**
+  (`Phlex::Reactive.settle_capable?` — pgbus reactive Streams + `SignedName` +
+  ActiveJob, and `defer_transport` not forced to `:fetch`). A settle has no pull
+  fallback: the client cannot poll "is the job done yet". **Without it,
+  `reply.pending` degrades rather than breaks** — your enqueue still runs, no
+  handle is installed, and **no pending markers are emitted**, so the UI shows
+  the pre-job world (today's behavior) instead of a shimmer that could never
+  resolve. A one-time warning says so.
+- **The pgbus CLIENT must be on the page too.** The server picks the push lane on
+  *server-side* capability alone. If the browser has no `<pgbus-stream-source>`
+  custom element registered, `reply.defer` degrades to its fetch token — but a
+  settle has no fetch lane, so the subscription never opens and the pending
+  markers would sit there. The client logs a loud console error naming the cause.
+  Load pgbus's client wherever you use `reply.pending`; it is the same
+  prerequisite the defer push lane already has.
+- **Authorization is still yours.** `reply.pending` signs the *container's*
+  identity so the job can rebuild it; that is not permission to act. `authorize!`
+  in the action, exactly as everywhere else.
+- **One `reply.pending` per container, per reply.** Every pending segment emits a
+  directive targeting the container's id, and the client keys subscriptions by
+  target — so a second call would supersede the first and orphan its jobs. The
+  second call raises. Mark every target in one call; the settle names its own
+  collection (`s.remove(record, from: :name)`).
+- **Peer delivery is best effort.** If a peer broadcast fails after the actor's
+  message already went out, the job is *not* failed — retrying it would re-run
+  `perform` and send the actor's settle (and its flash) a second time. The
+  failure is logged instead.
+
+#### Broadcasting a collection delta to peers
+
+`broadcast_to(append:)` emits the **bare row** — it has no container instance,
+so it cannot resolve the declaration or run the size resolver. Its collection
+counterpart does:
+
+```ruby
+ReconcileQueue.broadcast_collection_to(@bulk_payment, :transfers,
+  container: self, in: :unreconcilable, remove: transfer,
+  exclude: reactive_connection_id)
+```
+
+`row:` carries the row component's extra init kwargs — pass the same ones the
+actor got, or a peer whose row has a required kwarg raises instead of rendering.
+A `remove:` may be a record or an already-built dom-id string, matching
+`reply.remove(id, from:)`.
+
+Row **plus** count companion **plus** empty-state toggle, through the same
+`Phlex::Reactive::Collections` decisions the reply path uses — so the two can
+never drift. `coalesce:` (default `Phlex::Reactive.settle_coalesce_window_ms`,
+50 ms) applies to the **aggregate** streams only: the count and empty-state are
+idempotent replaces of stable targets, so a 177-row fan-out collapses to a
+handful of them. The **row** stream is never coalesced (an append is not
+idempotent). Coalescing needs pgbus with
+[zoolutions/pgbus#465](https://github.com/zoolutions/pgbus/issues/465); on
+anything older the window is ignored and every aggregate goes out — chattier,
+equally correct.
+
+#### Settle configuration
+
+| Setting | Default | Purpose |
+|---|---|---|
+| `Phlex::Reactive.settle_coalesce_window_ms` | `50` | Window for the aggregate (count / empty-state) streams on the peers path. |
+
+There is deliberately **no** `settle_token_ttl`. A settle has no pull lane for a
+token to govern — the client cannot poll "is the job done yet", and redeeming
+such a token at the defer endpoint would render the *pre-job* component, i.e.
+the exact bug `reply.pending` fixes. The settle's wait is bounded by the job,
+not by a TTL.
 
 ### Effects — animate enter/exit/update (opt-in)
 

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

@@ -403,7 +403,21 @@ module Phlex
             end
         end
 
-        append_deferred_streams(streams, result)
+        append_pending_streams(append_deferred_streams(streams, result), result)
+      end
+
+      # Pending segments (issue #248) ride LAST, alongside the deferred ones and
+      # for the same reason: this runs AFTER run_action returned, i.e. after the
+      # action's transaction COMMITTED — a rolled-back action takes the rescue
+      # paths, so no pending marker and no subscription directive can ever
+      # outlive a mutation that did not happen. (The ENQUEUE itself already ran
+      # inside the action, exactly like the app's own perform_later would have;
+      # its transactional behaviour is the queue adapter's, unchanged.) The
+      # common non-pending reply pays one empty? check.
+      def append_pending_streams(streams, result)
+        return streams unless result.pending?
+
+        [*streams, *result.pending_segments.flat_map { Phlex::Reactive::Pending.streams_for(it) }]
       end
 
       # Deferred segments (issue #165) ride LAST — after every render stream and

data/lib/phlex/reactive/collections.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # The reactive_collection bookkeeping (issue #35), extracted from Response's
+    # privates so MORE THAN ONE caller can run it (issue #248).
+    #
+    # A collection row is never just a row: adding one must also refresh the
+    # count companion and clear the empty-state at the 0->1 boundary; removing
+    # one must refresh the count and restore the empty-state at the 1->0
+    # boundary. That arithmetic used to live inside Response, reachable only
+    # from `reply.*` — so a JOB that finished background work had to re-derive
+    # it by hand and got the boundary subtly wrong.
+    #
+    # Three callers now share this module:
+    #
+    #   * Response.build_collection_{append,prepend,remove} — the actor's reply
+    #   * Phlex::Reactive::Settle — the job-side settle (issue #248)
+    #   * Streamable.broadcast_collection_to — the peers' broadcast (issue #248)
+    #
+    # The reply/settle paths build <turbo-stream> STRINGS; the broadcast path
+    # hands pieces to Turbo::StreamsChannel, which builds its own tags. They
+    # therefore cannot share the rendering — so what they share is the layer
+    # that actually drifts: the DECISIONS (#count_refresh and #empty_toggle,
+    # the 0<->1 boundary). Every renderer below reads those two.
+    #
+    # The module is stateless: every method takes the CollectionDefinition plus
+    # the bound container instance (the size resolver is `instance_exec`d
+    # against it, so it reads the container's ivars/association).
+    module Collections
+      class << self
+        # Resolve a declared collection off the container's class. A typo'd name
+        # must fail LOUDLY here, not silently emit an empty stream list.
+        def definition!(container, name)
+          container.class.reactive_collections[name.to_sym] ||
+            raise(Phlex::Reactive::Error,
+              "undeclared reactive_collection :#{name} on #{container.class}")
+        end
+
+        # --- The two shared DECISIONS -------------------------------------
+
+        # The collection's LIVE size, resolved ONCE per delta. Both decisions
+        # below read it, and both renderers pass the same value down — the
+        # resolver is usually a DB count, so evaluating it twice per delta is
+        # both an extra query AND a correctness hazard: a concurrent write
+        # landing between the two reads would emit a count companion that
+        # disagrees with the empty-state toggle it ships beside.
+        # `:__unresolved` is the "not computed yet" sentinel, distinct from a
+        # legitimately nil size (no size: declared).
+        def size_of(definition, container) = definition.size_for(container)
+
+        # [count_target, size_string] when a count companion AND a size resolver
+        # are both declared and the resolver returned a number; nil otherwise
+        # (the count stream is simply omitted — a list with just rows works).
+        # `size:` may be passed in by a caller that already resolved it.
+        def count_refresh(definition, container, size = :__unresolved)
+          return nil unless definition.count
+
+          size = size_of(definition, container) if size == :__unresolved
+          return nil if size.nil?
+
+          [definition.count, size.to_s]
+        end
+
+        # What the empty-state must do for this delta, or nil for "nothing":
+        #   :clear   — the list just crossed 0->1, remove the empty-state
+        #   :restore — the list just emptied, append the empty-state back
+        # Both are edge-triggered off the LIVE size (the resolver runs after the
+        # mutation), never off a client-side increment.
+        def empty_toggle(definition, container, delta, size = :__unresolved)
+          return nil unless definition.empty
+
+          size = size_of(definition, container) if size == :__unresolved
+          case delta
+          when :add then :clear if size == 1
+          else :restore if size&.zero?
+          end
+        end
+
+        # --- The reply/settle renderer (turbo-stream strings) --------------
+
+        # Row add (append/prepend) + count + empty-state clear.
+        #
+        # row_kwargs (issue #186) thread to the row component's init via the
+        # class stream builder's **options passthrough (ItemRow.new(model:,
+        # **row_kwargs)). `effect:` (issue #215) stamps the ROW stream only —
+        # the count companion and the empty-state toggle are bookkeeping, not
+        # the thing entering/leaving.
+        def add_streams(definition, container, model, action, row_kwargs = {}, effect: nil)
+          size = size_of(definition, container)
+          streams = [
+            definition.item.public_send(action, target: definition.container, model:, effect:, **row_kwargs)
+          ]
+          streams.concat(count_streams(definition, container, size))
+          streams << definition.empty.new.to_stream_remove if empty_toggle(definition, container, :add, size) == :clear
+          streams
+        end
+
+        # Row remove + count + empty-state restore. The empty-state is appended
+        # back INTO the container (not its own id) when the list just emptied —
+        # restoring "No items yet" after the last row went. model: nil builds it
+        # argument-free (an empty-state is a static view).
+        def remove_streams(definition, container, model, effect: nil)
+          size = size_of(definition, container)
+          streams = [row_remove_stream(definition, model, effect)]
+          streams.concat(count_streams(definition, container, size))
+          if empty_toggle(definition, container, :remove, size) == :restore
+            streams << definition.empty.append(target: definition.container, model: nil)
+          end
+          streams
+        end
+
+        # The count companion's update stream, or [] when there is nothing to
+        # refresh. Its own method (rather than an inline append) because the
+        # settle path refreshes the count WITHOUT a row delta — a job that
+        # neither added nor removed a row can still have changed the size.
+        def count_streams(definition, container, size = :__unresolved)
+          target, resolved = count_refresh(definition, container, size)
+          return [] unless target
+
+          [Phlex::Reactive::Response.update_stream(target, resolved)]
+        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 its #id).
+        def row_remove_stream(definition, model, effect = nil)
+          if model.is_a?(String)
+            Phlex::Reactive::Effects.annotate(Phlex::Reactive.stream_builder.remove(model), effect)
+          else
+            definition.item.remove(model, effect:)
+          end
+        end
+
+        # Re-render ONE row in place (a settle that neither added nor removed —
+        # the work ran and the row is simply different now). No count/empty
+        # streams: a replace cannot change the size.
+        def replace_streams(definition, model, effect: nil, **row_kwargs)
+          [definition.item.replace(model, effect:, **row_kwargs)]
+        end
+      end
+    end
+  end
+end