phlex-reactive 0.13.0 → 0.13.2

data/lib/phlex/reactive/pending.rb

@@ -0,0 +1,337 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # The async-action lifecycle (issue #248): the machinery behind
+    # `reply.pending` — "mark these targets pending, let MY job settle them".
+    #
+    # ## Why this exists
+    #
+    # The endpoint runs an action inside a transaction and renders the reply
+    # THERE, while a 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 — next to a "Queued 177 transfers" 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 of
+    # identical bookkeeping per screen, and the page still never learned the
+    # outcome.
+    #
+    # ## The shape
+    #
+    # `reply.pending` does three things, in order:
+    #
+    #   1. mints ONE one-shot durable stream key for the whole call (see the
+    #      shared-key rule below) and builds a Handle describing the settle;
+    #   2. runs the caller's enqueue — a block, or the `job:`/`args:` sugar —
+    #      with that Handle in a thread-local, so EVERY ActiveJob enqueued
+    #      inside captures it through Phlex::Reactive::Settles#serialize;
+    #   3. records a Segment on the Response. The ENDPOINT turns it into wire
+    #      streams after the action's transaction committed (a rolled-back
+    #      action can never leak a directive).
+    #
+    # ## One key per call — a hard design rule
+    #
+    # A durable pgbus broadcast to a never-seen key calls `ensure_queue!` →
+    # `pgmq.create`, i.e. a REAL PGMQ table per key, reclaimed only by pgbus's
+    # hourly orphan sweep at a 24h threshold. A key per record would leave 177
+    # tables sitting for a day (and open 177 SSE connections). So all N settles
+    # of one `reply.pending` share ONE key and ONE subscription, anchored on the
+    # container component's id.
+    #
+    # Because the key is shared, a per-settle teardown would kill the
+    # subscription on the FIRST arrival. Teardown is therefore explicit — see
+    # Phlex::Reactive::Settle#finish? — and defaults to "finish when this call
+    # marked exactly one record pending".
+    #
+    # ## No pull fallback
+    #
+    # Unlike `reply.defer`, a settle has no `:fetch` lane: the client cannot
+    # poll "is the job done yet". So `reply.pending` needs the defer PUSH lane
+    # (Phlex::Reactive.settle_capable?). Without it, it DEGRADES rather than
+    # breaks: the enqueue still runs, no handle is installed (so
+    # `reactive_settle` no-ops exactly like a sweep-enqueued job), and NO
+    # pending markers are emitted — the UI shows the pre-job world, which is
+    # today's behavior, instead of a shimmer that could never resolve.
+    module Pending
+      # The settle handle: everything a job needs to reach the actor and rebuild
+      # the container off the request thread. It rides ActiveJob metadata, so it
+      # must round-trip through plain JSON.
+      Handle = Data.define(
+        :stream_key,        # the shared one-shot durable pgbus key
+        :container_class,   # the container component's class NAME
+        :container_payload, # its reactive_identity_payload, for from_identity
+        :anchor,            # the container's DOM id: subscription + teardown target
+        :collection,        # the declared reactive_collection name, or nil
+        :target_ids,        # the DOM ids THIS handle is responsible for un-pending
+        :peers,             # peer stream key parts, or nil (actor-only)
+        :connection_id      # the actor's connection id, so peers exclude the echo
+      ) do
+        # How many targets this handle owns — drives the `finish: :auto` default
+        # (a single-target settle tears the shared subscription down; a fan-out
+        # waits for an explicit finish).
+        def count = target_ids.size
+
+        def to_h_wire
+          {
+            "key" => stream_key, "c" => container_class, "p" => container_payload,
+            "anchor" => anchor, "coll" => collection&.to_s, "ids" => target_ids,
+            "peers" => peers, "cid" => connection_id
+          }
+        end
+
+        def self.from_wire(data)
+          return nil unless data.is_a?(Hash) && data["key"]
+
+          new(
+            stream_key: data["key"], container_class: data["c"], container_payload: data["p"],
+            anchor: data["anchor"], collection: data["coll"]&.to_sym,
+            target_ids: data["ids"] || [], peers: data["peers"], connection_id: data["cid"]
+          )
+        end
+      end
+
+      # One recorded pending segment: the handle plus the DOM ids that were
+      # marked pending (the endpoint emits one marker stream per id).
+      Segment = Data.define(:handle, :target_ids)
+
+      # The attribute apps style. Set alongside aria-busy on every pending
+      # target AND on the container, so one CSS rule covers both:
+      #
+      #   [data-reactive-pending] { opacity: .5; pointer-events: none; }
+      PENDING_ATTR = "data-reactive-pending"
+
+      # The thread/fiber-local cell holding the handle for the duration of the
+      # enqueue block. Mirrors Phlex::Reactive.with_connection_id exactly.
+      HANDLE_KEY = :phlex_reactive_settle_handle
+
+      class << self
+        def current_handle = Thread.current[HANDLE_KEY]
+
+        def with_handle(handle)
+          previous = Thread.current[HANDLE_KEY]
+          Thread.current[HANDLE_KEY] = handle
+          yield
+        ensure
+          Thread.current[HANDLE_KEY] = previous
+        end
+
+        # Build the Segment for one reply.pending call, running the caller's
+        # enqueue with the handle installed. Returns nil when the push lane is
+        # unavailable — the enqueue still ran, there is just nothing to settle.
+        def build_segment(container, records, collection:, peers:, job:, args:, enqueue:)
+          # Materialize ONCE. `records` may be a lazy Enumerator or a Relation,
+          # and the targets and the enqueue both need to walk it — enumerating
+          # twice either exhausts a one-shot source (jobs silently never enqueue)
+          # or re-queries, so a concurrent write could make the marked rows and
+          # the enqueued jobs disagree.
+          list = materialize(records)
+          targets = resolve_targets(container, list, collection)
+
+          unless Phlex::Reactive.settle_capable?
+            warn_no_lane
+            run_enqueue(list, job, args, enqueue, nil)
+            return nil
+          end
+
+          handle = build_handle(container, collection, targets, peers)
+          with_handle(handle) { run_enqueue(list, job, args, enqueue, targets) }
+          Segment.new(handle:, target_ids: targets)
+        end
+
+        # One record, or an enumerable of them, as an Array — never re-walked.
+        def materialize(records)
+          list = records.is_a?(Enumerable) && !records.is_a?(String) ? records.to_a : [records]
+          raise ::ArgumentError, "reply.pending needs at least one target" if list.empty?
+
+          list
+        end
+
+        # The wire streams for one segment, in apply order: the per-target
+        # pending markers FIRST (so the UI stops lying immediately), then the
+        # single subscription directive.
+        def streams_for(segment)
+          streams = segment.target_ids.map { marker_stream(it) }
+          streams << marker_stream(segment.handle.anchor)
+          streams << directive_stream(segment.handle)
+          streams
+        end
+
+        # The deterministic id of the shared <pgbus-stream-source>. The client
+        # mints it as reactive-defer-src-<anchor>; a settle removes it by this
+        # exact id to tear the subscription down.
+        def source_id(anchor) = "reactive-defer-src-#{anchor}"
+
+        # Resolve the DOM id a row component would render for `model`, WITHOUT
+        # rendering it (build is cheap — #id must be render-context-free, that
+        # is the Streamable#id contract).
+        def row_dom_id(definition, model)
+          return model if model.is_a?(String)
+
+          definition.item.send(:build, model, {}).id
+        end
+
+        private
+
+        # Each pending target, as a DOM id. With `in:` the rows resolve through
+        # the collection declaration; without it every entry must already be a
+        # Streamable component (its own #id is the target).
+        def resolve_targets(container, list, collection)
+          if collection
+            definition = Phlex::Reactive::Collections.definition!(container, collection)
+            return list.map { row_dom_id(definition, it) }
+          end
+
+          list.map do
+            unless it.is_a?(Phlex::Reactive::Streamable)
+              raise ::ArgumentError,
+                "reply.pending(#{it.class}) cannot resolve a DOM target — name the collection " \
+                "the record lives in (reply.pending(record, in: :collection_name)) or pass a " \
+                "Streamable component instance (its #id is the target)"
+            end
+
+            it.id
+          end
+        end
+
+        def build_handle(container, collection, targets, peers)
+          Handle.new(
+            stream_key: one_shot_stream_key,
+            container_class: container.class.name,
+            container_payload: container.send(:reactive_identity_payload),
+            anchor: container.id,
+            collection: collection&.to_sym,
+            target_ids: targets,
+            peers: resolve_peers(container, peers),
+            connection_id: Phlex::Reactive.current_connection_id
+          )
+        end
+
+        # `peers: true` means the container's own record stream (the natural
+        # "everyone looking at this batch"); an Array is that one key's parts,
+        # passed through to broadcast_to(*streamables) verbatim. The parts are
+        # GlobalID-serialized so they survive the trip into the job.
+        def resolve_peers(container, peers)
+          return nil unless peers
+
+          parts =
+            if peers == true
+              record = container.class.reactive_record_ivar &&
+                       container.instance_variable_get(container.class.reactive_record_ivar)
+              unless record
+                raise ::ArgumentError,
+                  "reply.pending(peers: true) needs a record-backed container (reactive_record) — " \
+                  "a state-backed one has no record stream, so pass the key parts explicitly: " \
+                  "peers: [list, :todos]"
+              end
+
+              [record]
+            else
+              Array(peers)
+            end
+
+          parts.map { it.respond_to?(:to_gid) ? { "gid" => it.to_gid.to_s } : it.to_s }
+        end
+
+        # Run the caller's enqueue: an explicit block wins; otherwise the
+        # job:/args: sugar. Neither is also fine — an action may have enqueued
+        # its work before calling reply.pending (the handle is then unused,
+        # which is a mistake we cannot detect, so it is documented, not guessed
+        # at).
+        #
+        # The sugar enqueues ONE job PER RECORD, so each job gets a handle
+        # NARROWED to that record's target id. That precision matters on the
+        # failure path: a job that raises (or settles with nothing but a flash)
+        # must clear ITS row's pending markers without un-dimming the other 176
+        # rows that are still legitimately working. The BLOCK form cannot be
+        # narrowed — the gem has no way to map an arbitrary enqueue back to a
+        # record — so it carries the whole target list, which is the right
+        # reading of "these jobs settle these targets as one unit".
+        def run_enqueue(list, job, args, enqueue, targets)
+          return enqueue.call if enqueue
+          return unless job
+
+          case args
+          when nil then each_with_narrowed_handle(list, targets) { job.perform_later(it) }
+          when ::Proc
+            each_with_narrowed_handle(list, targets) { job.perform_later(*Array(args.call(it))) }
+          else
+            if list.size > 1
+              raise ::ArgumentError,
+                "reply.pending(job:, args: [...]) is ambiguous for #{list.size} records — pass a " \
+                "Proc (args: ->(record) { [record.id] }) so each job gets its own arguments"
+            end
+
+            each_with_narrowed_handle(list, targets) { job.perform_later(*Array(args)) }
+          end
+        end
+
+        # Yield each record with the ambient handle narrowed to that record's own
+        # target id. `targets` is nil on the no-lane path (no handle is installed
+        # at all), in which case this is a plain each.
+        def each_with_narrowed_handle(list, targets)
+          return list.each { yield(it) } unless targets
+
+          handle = current_handle
+          list.each_with_index do |record, index|
+            id = targets[index]
+            narrowed = id ? handle.with(target_ids: [id]) : handle
+            with_handle(narrowed) { yield(record) }
+          end
+        end
+
+        # Mark ONE element pending: data-reactive-pending + aria-busy, via the
+        # existing reactive:js op lane (@root-scoped to the target), so this
+        # needs no client change at all.
+        def marker_stream(target_id)
+          ops = Phlex::Reactive::JS.new
+            .set_attr(:root, PENDING_ATTR, "true")
+            .set_attr(:root, "aria-busy", "true")
+          Phlex::Reactive::Stream.wrap(
+            Phlex::Reactive::Response.js_stream(ops, target: target_id),
+            action: "reactive:js", target: target_id, renders_root: false
+          )
+        end
+
+        # The subscription directive — the SAME reactive:defer wire the push
+        # lane already speaks, so the client needs nothing new. Deliberately NO
+        # data-reactive-defer-token: that attribute is the client's degrade-to-
+        # fetch path, and a settle has no fetch lane (POSTing it would render
+        # the pre-job component, re-creating the exact bug this fixes).
+        def directive_stream(handle)
+          src = signed_stream_src(handle.stream_key)
+          html = %(<turbo-stream action="#{Phlex::Reactive::Defer::DIRECTIVE_ACTION}" \
+target="#{ERB::Util.html_escape(handle.anchor)}" data-reactive-defer-via="stream" \
+data-reactive-defer-src="#{ERB::Util.html_escape(src)}" data-reactive-defer-since-id="0"></turbo-stream>)
+          Phlex::Reactive::Stream.wrap(
+            html.html_safe, action: Phlex::Reactive::Defer::DIRECTIVE_ACTION,
+            target: handle.anchor, renders_root: false
+          )
+        end
+
+        # The key + src minting are Defer's, verbatim — one implementation of
+        # the pgbus queue-name budget and the signed SSE src, so the two lanes
+        # can never disagree about either. (Private on Defer, reached the same
+        # way the rest of the identity internals are off-instance.)
+        def one_shot_stream_key = Phlex::Reactive::Defer.send(:one_shot_stream_key)
+        def signed_stream_src(key) = Phlex::Reactive::Defer.send(:signed_stream_src, key)
+
+        # No settle lane is a CONFIG fact, not a per-reply event — warn once per
+        # process (a pending reply can fire per click; per-reply spam would bury
+        # the signal), then degrade to a plain enqueue.
+        def warn_no_lane
+          return if @no_lane_warned
+
+          @no_lane_warned = true
+          return unless defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
+
+          ::Rails.logger.warn(
+            "[phlex-reactive] reply.pending needs the defer PUSH lane (pgbus reactive Streams + " \
+            "SignedName + ActiveJob, and defer_transport not forced to :fetch) — a settle has no " \
+            "pull fallback. Enqueuing without a settle handle; no pending markers were emitted."
+          )
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/reply.rb

@@ -129,6 +129,43 @@ module Phlex
         Response.build_streams(@component).defer(component, placeholder:, morph:)
       end
 
+      # Mark targets PENDING and let the app's own job settle them (issue #248).
+      # For an action that ENQUEUES the work rather than doing it: the endpoint
+      # renders the reply inside the transaction while the queue publishes on
+      # commit, so a `reply.morph` after an enqueue is guaranteed to draw the
+      # pre-job world. This replies truthfully instead.
+      #
+      #   def re_execute(transfer_id:)
+      #     transfer = @bulk_payment.transfers.re_executable.find(transfer_id)
+      #     reply.pending(transfer, in: :unreconcilable, job: ReExecuteJob, args: [transfer.id])
+      #   end
+      #
+      #   def restore_all                       # the enqueue lives in a service
+      #     count = 0
+      #     reply.pending(restorable, in: :declined) { count = BatchRestoreService.call(...) }
+      #       .flash(:notice, "Putting #{count} back…")
+      #   end
+      #
+      # `records` is one record, an enumerable of them, or Streamable component
+      # instances. `in:` names the reactive_collection they live in (required
+      # for records — it is how their row DOM ids and the count/empty-state
+      # bookkeeping are resolved). The enqueue is a BLOCK (anything ActiveJob
+      # enqueued inside it captures the settle handle — including from a service
+      # object) or the `job:`/`args:` sugar. `peers: true` also broadcasts each
+      # settle to the container's record stream, so a second operator watching
+      # the same batch sees it; the default is actor-only, matching reply.defer.
+      #
+      # The bound component is the CONTAINER: it owns the collection declaration,
+      # the size resolver, and the subscription anchor. Its token is refreshed
+      # but it is NOT re-rendered.
+      #
+      # See Phlex::Reactive::Settles for the job side.
+      def pending(records, peers: false, job: nil, args: nil, **opts, &enqueue)
+        Response.build_pending(
+          @component, records, collection: Response.pending_collection!(opts), peers:, job:, args:, enqueue:
+        )
+      end
+
       private
 
       # Sentinel distinguishing "keyword omitted" from an explicit nil value, so

data/lib/phlex/reactive/response.rb

@@ -119,87 +119,64 @@ module Phlex
         # `effect:` (issue #215) stamps the ROW stream only — the count
         # companion and the empty-state toggle are bookkeeping, not the thing
         # entering/leaving.
+        # Issue #248: the bookkeeping BODIES moved to Phlex::Reactive::Collections
+        # so the job-side settle and the peers broadcast run the SAME code. These
+        # builders keep their exact behaviour by delegating.
         def build_collection_append(component, name, model, effect: nil, **row_kwargs)
-          definition = collection_def!(component, name)
-          new(streams: collection_add_streams(definition, component, model, :append, row_kwargs, effect:),
-            render_self: false, token_component: component)
+          definition = Phlex::Reactive::Collections.definition!(component, name)
+          new(streams: Phlex::Reactive::Collections.add_streams(definition, component, model, :append, row_kwargs,
+            effect:), render_self: false, token_component: component)
         end
 
         def build_collection_prepend(component, name, model, effect: nil, **row_kwargs)
-          definition = collection_def!(component, name)
-          new(streams: collection_add_streams(definition, component, model, :prepend, row_kwargs, effect:),
-            render_self: false, token_component: component)
+          definition = Phlex::Reactive::Collections.definition!(component, name)
+          new(streams: Phlex::Reactive::Collections.add_streams(definition, component, model, :prepend, row_kwargs,
+            effect:), render_self: false, token_component: component)
         end
 
         def build_collection_remove(component, name, model, effect: nil)
-          definition = collection_def!(component, name)
-          new(streams: collection_remove_streams(definition, component, model, effect:),
+          definition = Phlex::Reactive::Collections.definition!(component, name)
+          new(streams: Phlex::Reactive::Collections.remove_streams(definition, component, model, effect:),
             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_collections[name.to_sym] ||
-            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, row_kwargs = {}, effect: nil)
-          # row_kwargs (issue #186) thread to the row component's init via the class
-          # stream builder's **options passthrough (ItemRow.new(model:, **row_kwargs)).
-          streams = [definition.item.public_send(action, target: definition.container, model:, effect:, **row_kwargs)]
-          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, effect: nil)
-          streams = [collection_row_remove(definition, model, effect)]
-          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)
+        # --- Async-action lifecycle (issue #248) ---
+        # Mark targets pending and hand the fulfilment to the app's own job. The
+        # reply deliberately does NOT re-render the container: re-rendering it
+        # here would draw the PRE-JOB world (the endpoint renders inside the
+        # transaction; the queue publishes on commit) — the exact bug this verb
+        # exists to fix. render_self is therefore false, with the container as
+        # token_component so the signed token still rolls forward (cosmos#1939 —
+        # without it the list is act-once-only).
+        #
+        # The Response only RECORDS the segment; the ENDPOINT turns it into the
+        # marker + directive streams after the transaction committed.
+        # Pull `in:` out of reply.pending's **opts and REFUSE anything left over.
+        # `in` is a Ruby keyword, so it cannot be a named parameter — which means
+        # every other keyword lands in **opts and would otherwise be silently
+        # dropped. A typo (`jbo:` for `job:`) would then mark the rows pending
+        # and enqueue NOTHING: a permanently shimmering row, the exact failure
+        # this feature exists to prevent. So it fails at the call site instead.
+        def pending_collection!(opts)
+          collection = opts.delete(:in)
+          unless opts.empty?
+            raise ArgumentError,
+              "reply.pending got unknown keyword(s) #{opts.keys.map(&:inspect).join(", ")} — " \
+              "it takes in:, job:, args:, peers: and a block. A dropped keyword would mark the " \
+              "targets pending with nothing to settle them."
           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, 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
+          collection
         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)
+        def build_pending(component, records, collection:, peers:, job:, args:, enqueue:)
+          segment = Phlex::Reactive::Pending.build_segment(
+            component, records, collection:, peers:, job:, args:, enqueue:
+          )
+          new(streams: [], render_self: false, token_component: component,
+            pending_segments: segment ? [segment] : NO_SEGMENTS)
         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.
@@ -376,13 +353,14 @@ data-reactive-ops="#{ERB::Util.html_escape(json)}"></turbo-stream>).html_safe
       NO_SEGMENTS = [].freeze
 
       def initialize(streams: [], redirect_url: nil, render_self: true, token_component: nil,
-                     subject_component: nil, deferred_segments: NO_SEGMENTS)
+                     subject_component: nil, deferred_segments: NO_SEGMENTS, pending_segments: NO_SEGMENTS)
         @streams = streams.freeze
         @redirect_url = redirect_url
         @render_self = render_self
         @token_component = token_component
         @subject_component = subject_component
         @deferred_segments = deferred_segments.freeze
+        @pending_segments = pending_segments.freeze
         freeze
       end
 
@@ -394,6 +372,13 @@ data-reactive-ops="#{ERB::Util.html_escape(json)}"></turbo-stream>).html_safe
 
       def deferred? = !@deferred_segments.empty?
 
+      # The recorded reply.pending segments (issue #248), in call order. Same
+      # contract as deferred_segments: recorded here, turned into wire streams
+      # by the endpoint AFTER the transaction committed.
+      attr_reader :pending_segments
+
+      def pending? = !@pending_segments.empty?
+
       # Append extra turbo-stream strings (a sibling component, a flash).
       # Returns a NEW Response (immutable).
       def stream(*more)
@@ -403,7 +388,8 @@ data-reactive-ops="#{ERB::Util.html_escape(json)}"></turbo-stream>).html_safe
           render_self: @render_self,
           token_component: @token_component,
           subject_component: @subject_component,
-          deferred_segments: @deferred_segments
+          deferred_segments: @deferred_segments,
+          pending_segments: @pending_segments
         )
       end
 
@@ -434,7 +420,52 @@ data-reactive-ops="#{ERB::Util.html_escape(json)}"></turbo-stream>).html_safe
           token_component: @token_component,
           subject_component: @subject_component,
           deferred_segments: @deferred_segments +
-            [Phlex::Reactive::Defer::Segment.new(component:, placeholder:, morph:)]
+            [Phlex::Reactive::Defer::Segment.new(component:, placeholder:, morph:)],
+          pending_segments: @pending_segments
+        )
+      end
+
+      # Chain reply.pending onto an existing reply (issue #248), so an action can
+      # do one synchronous thing AND mark other targets pending:
+      #
+      #   reply.replace.pending(rows, in: :declined, job: RestoreJob)
+      #
+      # Dead on a redirect, exactly like #defer: the client is navigating away,
+      # so the settle could never land.
+      def pending(records, peers: false, job: nil, args: nil, **opts, &enqueue)
+        if redirect?
+          raise Phlex::Reactive::Error,
+            "reply.pending on a redirect reply is dead — the client is navigating away, " \
+            "so the settle could never land"
+        end
+
+        subject = pending_subject!
+        # ONE subscription per anchor. Every pending segment on the same
+        # container emits a directive targeting that container's id, and the
+        # client keys its in-flight subscriptions BY TARGET — so a second
+        # directive supersedes the first, silently orphaning the jobs the first
+        # call enqueued. Two pending calls on one container in one reply is a
+        # call-site mistake; make it a loud one.
+        if @pending_segments.any? { it.handle.anchor == subject.id }
+          raise Phlex::Reactive::Error,
+            "reply.pending was called twice for #{subject.class} (##{subject.id}) — the second " \
+            "subscription would supersede the first on the client, so the first call's jobs could " \
+            "never settle. Mark every target in ONE reply.pending call (the settle names its own " \
+            "collection: s.remove(record, from: :name))."
+        end
+
+        built = self.class.build_pending(
+          subject, records, collection: self.class.pending_collection!(opts),
+          peers:, job:, args:, enqueue:
+        )
+        self.class.new(
+          streams: @streams,
+          redirect_url: @redirect_url,
+          render_self: @render_self,
+          token_component: @token_component || built.token_component,
+          subject_component: @subject_component,
+          deferred_segments: @deferred_segments,
+          pending_segments: @pending_segments + built.pending_segments
         )
       end
 
@@ -537,6 +568,16 @@ data-reactive-ops="#{ERB::Util.html_escape(json)}"></turbo-stream>).html_safe
 
       private
 
+      # The container a chained .pending marks: the component this reply is
+      # already bound to. A subject-free reply (reply.with) has none — chaining
+      # .pending onto it is a call-site mistake, so it fails loudly.
+      def pending_subject!
+        (@subject_component || @token_component) ||
+          raise(Phlex::Reactive::Error,
+            "reply.pending needs a bound component (the container that owns the collection) — " \
+            "chain it off a component verb (reply.replace.pending(...)) or call reply.pending(...) directly")
+      end
+
       # The default `target` for #js: the bound component's id when this reply is
       # component-scoped (replace/morph/update set subject_component; .streams and
       # collections set token_component), else nil — a subject-free reply.with is