phlex-reactive 0.4.7 → 0.9.0

data/lib/phlex/reactive/streamable.rb

@@ -33,6 +33,10 @@ module Phlex
       # up without ever sharing a mutable context across threads.
       ThreadViewContext = Struct.new(:view_context, :builder, :renderer, :generation)
 
+      # Focus ops are actor-only (they steal focus): broadcast_js_to rejects a
+      # broadcast that carries one. Names mirror Phlex::Reactive::JS's focus verbs.
+      BROADCAST_REFUSED_OPS = %w[focus focus_first].freeze
+
       # Every class that includes Streamable, so the engine can flush their
       # memoized view contexts on a Rails code reload (dev) in one pass. A
       # WeakMap used as a set (the class is the key) so a class reloaded by
@@ -55,6 +59,20 @@ module Phlex
         def register(klass)
           @registry_mutex.synchronize { @registry[klass] = true }
         end
+
+        # A point-in-time snapshot of every registered streamable class, taken
+        # under the registry lock (the doctor iterates it — issue #106). Returns
+        # a plain Array so callers never hold the live WeakMap or the lock while
+        # working; a class GC'd later simply won't appear next time. Call
+        # Rails.application.eager_load! FIRST if you need every app class loaded —
+        # the WeakMap only holds classes that have actually been loaded.
+        def registered_classes
+          @registry_mutex.synchronize do
+            classes = []
+            @registry.each_key { classes << it }
+            classes
+          end
+        end
       end
 
       included do
@@ -133,36 +151,71 @@ module Phlex
         # view context still carries the full Rails helper set, so
         # dom_id/url_for/t()/csrf keep working during a re-render or broadcast.
         def render_component(component)
-          component.render_in(turbo_view_context)
+          # render.phlex_reactive (issue #107): the pure render cost — the unit
+          # an APM most wants (broadcast fan-out renders once per stream key).
+          # Payload carries the component NAME + html bytesize ONLY. bytesize is
+          # known only after rendering, so we mutate the payload inside the block.
+          event = { component: name, bytesize: 0 }
+          Phlex::Reactive.instrument("render", event) do
+            html = component.render_in(turbo_view_context)
+            event[:bytesize] = html.bytesize
+            html
+          end
         end
 
         # `morph: true` emits `<turbo-stream action="replace" method="morph">` so
         # Turbo 8's bundled Idiomorph morphs the subtree in place — preserving a
         # focused <input> + caret — instead of an outerHTML swap (issue #28).
         # Default (morph: false) is the unchanged plain replace.
+        # Wrapped in a Phlex::Reactive::Stream (issue #114) so the endpoint reads
+        # action/target/token-ness structurally. renders_root: true — a replace
+        # re-renders the component's own root (carrying its fresh token); wire
+        # bytes are byte-identical.
         def replace(model = nil, morph: false, **options)
           component = build(model, options)
-          turbo_stream_builder.replace(component.id, html: render_component(component), **morph_method(morph))
+          Phlex::Reactive::Stream.wrap(
+            turbo_stream_builder.replace(component.id, html: render_component(component), **morph_method(morph)),
+            action: "replace", target: component.id, renders_root: true
+          )
         end
 
-        def update(model = nil, **options)
+        # `morph: true` emits `<turbo-stream action="update" method="morph">` so
+        # Turbo 8 morphs the inner HTML in place instead of replacing it (issue
+        # #113) — a cross-tab update no longer clobbers a peer's focus/caret.
+        # Default (morph: false) is the unchanged plain update.
+        def update(model = nil, morph: false, **options)
           component = build(model, options)
-          turbo_stream_builder.update(component.id, html: render_component(component))
+          Phlex::Reactive::Stream.wrap(
+            turbo_stream_builder.update(component.id, html: render_component(component), **morph_method(morph)),
+            action: "update", target: component.id, renders_root: true
+          )
         end
 
+        # renders_root: false — append inserts a CHILD into `target`; even when
+        # the appended component carries its OWN token, that must never count as
+        # the container's own refresh (issue #44).
         def append(target:, model: nil, **options)
           component = build(model, options)
-          turbo_stream_builder.append(target, html: render_component(component))
+          Phlex::Reactive::Stream.wrap(
+            turbo_stream_builder.append(target, html: render_component(component)),
+            action: "append", target: target, renders_root: false
+          )
         end
 
         def prepend(target:, model: nil, **options)
           component = build(model, options)
-          turbo_stream_builder.prepend(target, html: render_component(component))
+          Phlex::Reactive::Stream.wrap(
+            turbo_stream_builder.prepend(target, html: render_component(component)),
+            action: "prepend", target: target, renders_root: false
+          )
         end
 
         def remove(model = nil, **options)
           component = build(model, options)
-          turbo_stream_builder.remove(component.id)
+          Phlex::Reactive::Stream.wrap(
+            turbo_stream_builder.remove(component.id),
+            action: "remove", target: component.id, renders_root: false
+          )
         end
 
         # --- Broadcasts (server -> client over the stream transport) ---
@@ -183,48 +236,211 @@ module Phlex
         # so a peer tab keeps its focus/caret on the morphed row. The broadcast
         # path takes EXTRA <turbo-stream> attributes via `attributes:` (not the
         # TagBuilder's `method:` kwarg), so the morph flag rides there.
+        # Each broadcast_*_to wraps its body in a broadcast.phlex_reactive event
+        # (issue #107) via instrument_broadcast — the stream action + streamables
+        # COUNT + component name, never the model/state. The event fires on BOTH
+        # transports (Action Cable AND pgbus): it wraps this class-method body,
+        # which is the same on either, so pgbus optionality is preserved.
         def broadcast_replace_to(*streamables, model: nil, exclude: nil, visible_to: nil, morph: false, **options)
-          component = build(model, options)
-          ::Turbo::StreamsChannel.broadcast_replace_to(
-            *streamables, target: component.id, html: render_component(component),
-            **morph_attributes(morph), **broadcast_transport_opts(exclude:, visible_to:)
-          )
+          instrument_broadcast("replace", streamables) do
+            component = build(model, options)
+            ::Turbo::StreamsChannel.broadcast_replace_to(
+              *streamables, target: component.id, html: render_component(component),
+              **morph_attributes(morph), **broadcast_transport_opts(exclude:, visible_to:)
+            )
+          end
         end
 
-        def broadcast_update_to(*streamables, model: nil, exclude: nil, visible_to: nil, **options)
-          component = build(model, options)
-          ::Turbo::StreamsChannel.broadcast_update_to(
-            *streamables, target: component.id, html: render_component(component),
-            **broadcast_transport_opts(exclude:, visible_to:)
-          )
+        # `morph: true` makes the live cross-tab update morph in place (issue
+        # #113), so a peer tab editing this component keeps its focus/caret
+        # instead of an inner-HTML clobber. Like broadcast_replace_to's morph
+        # flag, it rides through `attributes:` (the broadcast path has no
+        # `method:` kwarg) via morph_attributes.
+        def broadcast_update_to(*streamables, model: nil, exclude: nil, visible_to: nil, morph: false, **options)
+          instrument_broadcast("update", streamables) do
+            component = build(model, options)
+            ::Turbo::StreamsChannel.broadcast_update_to(
+              *streamables, target: component.id, html: render_component(component),
+              **morph_attributes(morph), **broadcast_transport_opts(exclude:, visible_to:)
+            )
+          end
         end
 
         def broadcast_append_to(*streamables, target:, model: nil, exclude: nil, visible_to: nil, **options)
-          component = build(model, options)
-          ::Turbo::StreamsChannel.broadcast_append_to(
-            *streamables, target:, html: render_component(component),
-            **broadcast_transport_opts(exclude:, visible_to:)
-          )
+          instrument_broadcast("append", streamables) do
+            component = build(model, options)
+            ::Turbo::StreamsChannel.broadcast_append_to(
+              *streamables, target:, html: render_component(component),
+              **broadcast_transport_opts(exclude:, visible_to:)
+            )
+          end
         end
 
         def broadcast_prepend_to(*streamables, target:, model: nil, exclude: nil, visible_to: nil, **options)
-          component = build(model, options)
-          ::Turbo::StreamsChannel.broadcast_prepend_to(
-            *streamables, target:, html: render_component(component),
-            **broadcast_transport_opts(exclude:, visible_to:)
-          )
+          instrument_broadcast("prepend", streamables) do
+            component = build(model, options)
+            ::Turbo::StreamsChannel.broadcast_prepend_to(
+              *streamables, target:, html: render_component(component),
+              **broadcast_transport_opts(exclude:, visible_to:)
+            )
+          end
         end
 
         def broadcast_remove_to(*streamables, model: nil, exclude: nil, visible_to: nil, **options)
-          component = build(model, options)
-          ::Turbo::StreamsChannel.broadcast_remove_to(
-            *streamables, target: component.id,
-            **broadcast_transport_opts(exclude:, visible_to:)
-          )
+          instrument_broadcast("remove", streamables) do
+            component = build(model, options)
+            ::Turbo::StreamsChannel.broadcast_remove_to(
+              *streamables, target: component.id,
+              **broadcast_transport_opts(exclude:, visible_to:)
+            )
+          end
+        end
+
+        # Push server-side client DOM ops to EVERY subscriber of a stream (issue
+        # #97) — the broadcast sibling of Response#js. Rides a `reactive:js`
+        # custom stream action over Turbo::StreamsChannel, so it works on Action
+        # Cable AND pgbus (transport opts pass through broadcast_transport_opts
+        # exactly like every other broadcast):
+        #
+        #   Notifications::Badge.broadcast_js_to(user, :alerts,
+        #     js.add_class("#bell", "has-unread"), exclude: reactive_connection_id)
+        #
+        # `ops` is a Phlex::Reactive::JS chain (or a raw [[op, args], ...] array);
+        # `target` (an element id) scopes op resolution on the client (nil →
+        # document-scoped). The ops JSON is HTML-escaped through the TagBuilder's
+        # attributes: path (data-reactive-ops), so a value can't break out of the
+        # attribute.
+        #
+        # The builder REJECTS focus-class ops (focus/focus_first) outright:
+        # broadcasting a focus steals focus in every subscriber's tab. Focus is an
+        # actor-reply concern only (Response#js), so it raises ArgumentError here
+        # rather than silently shipping a hostile-feeling broadcast.
+        def broadcast_js_to(*streamables, ops, exclude: nil, visible_to: nil, target: nil)
+          instrument_broadcast("reactive:js", streamables) do
+            json = broadcast_js_ops_json(ops)
+            ::Turbo::StreamsChannel.broadcast_action_to(
+              *streamables,
+              action: "reactive:js",
+              target: target,
+              attributes: { data: { reactive_ops: json } },
+              render: false,
+              **broadcast_transport_opts(exclude:, visible_to:)
+            )
+          end
+        end
+
+        # --- Multi-key fan-out (issue #119) ---------------------------------
+        # Broadcast ONE component to K DIFFERENT stream keys — a per-tenant loop
+        # ("the list page stream AND the dashboard stream"). The classic
+        # broadcast_*_to concatenates *streamables into ONE key, so fanning out
+        # to K keys the hand way is K× build + K× render + K× identity HMAC for
+        # BYTE-IDENTICAL HTML. These render the component ONCE and loop only the
+        # cheap channel call:
+        #
+        #   Counter.broadcast_replace_to_each(
+        #     accounts.map { [it, :counters] }, model: counter, exclude: reactive_connection_id)
+        #
+        # `stream_keys` is an enumerable of keys; each key is passed to the
+        # transport as its raw parts (a [record, :symbol] pair, or a bare string
+        # — `Array(key)` handles both). Transport opts (exclude:/visible_to:) and
+        # morph: forward PER key exactly as the single-key verbs do, so
+        # pgbus-present suppresses the actor's echo on every stream and
+        # pgbus-absent is unchanged (the no-opts call passes no unknown keyword).
+        #
+        # Irreducible exception: per-VIEWER content (visible_to: rendering
+        # DIFFERENT HTML per viewer) still renders per call — that's a
+        # render-per-viewer by definition and can't be shared. This fan-out is
+        # for the same payload to many keys.
+        def broadcast_replace_to_each(stream_keys, model: nil, exclude: nil, visible_to: nil, morph: false, **options)
+          instrument_broadcast("replace", stream_keys) do
+            component = build(model, options)
+            html = render_component(component)
+            transport = broadcast_transport_opts(exclude:, visible_to:)
+            stream_keys.each do
+              ::Turbo::StreamsChannel.broadcast_replace_to(
+                *Array(it), target: component.id, html:, **morph_attributes(morph), **transport
+              )
+            end
+          end
+        end
+
+        def broadcast_update_to_each(stream_keys, model: nil, exclude: nil, visible_to: nil, morph: false, **options)
+          instrument_broadcast("update", stream_keys) do
+            component = build(model, options)
+            html = render_component(component)
+            transport = broadcast_transport_opts(exclude:, visible_to:)
+            stream_keys.each do
+              ::Turbo::StreamsChannel.broadcast_update_to(
+                *Array(it), target: component.id, html:, **morph_attributes(morph), **transport
+              )
+            end
+          end
+        end
+
+        def broadcast_append_to_each(stream_keys, target:, model: nil, exclude: nil, visible_to: nil, **options)
+          instrument_broadcast("append", stream_keys) do
+            component = build(model, options)
+            html = render_component(component)
+            transport = broadcast_transport_opts(exclude:, visible_to:)
+            stream_keys.each do
+              ::Turbo::StreamsChannel.broadcast_append_to(*Array(it), target:, html:, **transport)
+            end
+          end
+        end
+
+        def broadcast_prepend_to_each(stream_keys, target:, model: nil, exclude: nil, visible_to: nil, **options)
+          instrument_broadcast("prepend", stream_keys) do
+            component = build(model, options)
+            html = render_component(component)
+            transport = broadcast_transport_opts(exclude:, visible_to:)
+            stream_keys.each do
+              ::Turbo::StreamsChannel.broadcast_prepend_to(*Array(it), target:, html:, **transport)
+            end
+          end
+        end
+
+        # remove has no body — nothing to render. It still builds ONCE to read
+        # the component's #id (the target), then loops the cheap channel call.
+        def broadcast_remove_to_each(stream_keys, model: nil, exclude: nil, visible_to: nil, **options)
+          instrument_broadcast("remove", stream_keys) do
+            component = build(model, options)
+            transport = broadcast_transport_opts(exclude:, visible_to:)
+            stream_keys.each do
+              ::Turbo::StreamsChannel.broadcast_remove_to(*Array(it), target: component.id, **transport)
+            end
+          end
         end
 
         private
 
+        # Wrap a broadcast_*_to body in a broadcast.phlex_reactive event (issue
+        # #107). Payload: the component NAME, the Turbo stream action, and the
+        # streamables COUNT — never the model/state. Fires on both transports
+        # because it wraps the shared class-method body. Returns the block's value
+        # (the broadcast result) so callers are unaffected.
+        def instrument_broadcast(stream_action, streamables, &)
+          Phlex::Reactive.instrument(
+            "broadcast",
+            { component: name, stream_action: stream_action, streamables: streamables.size },
+            &
+          )
+        end
+
+        # Validate + serialize broadcast ops: reject focus-class ops (they steal
+        # focus in every tab) and an empty chain (a dead broadcast), then return
+        # the JSON wire form. Works on a JS chain (inspect .ops) and a raw array.
+        def broadcast_js_ops_json(ops)
+          pairs = ops.is_a?(Phlex::Reactive::JS) ? ops.ops : Array(ops)
+          refused = pairs.map { |name, _| name.to_s } & Phlex::Reactive::Streamable::BROADCAST_REFUSED_OPS
+          unless refused.empty?
+            raise ArgumentError,
+              "broadcast_js_to refuses focus op(s) #{refused.join(", ")} — broadcasting focus " \
+              "steals it in every subscriber's tab. Focus is an actor-reply concern (reply.js)."
+          end
+
+          Phlex::Reactive::Response.js_ops_json(ops)
+        end
+
         def build(model, options)
           new(**(model ? component_args(model, options) : options))
         end
@@ -276,10 +492,32 @@ module Phlex
         end
       end
 
-      # Required: the stable DOM id used as the Turbo Stream target. It MUST
-      # match the id set on the component's root element in `view_template`.
+      # The stable DOM id used as the Turbo Stream target. It MUST match the id
+      # set on the component's root element in `view_template`.
+      #
+      # Record-backed components (Component's `reactive_record :x`) get a
+      # default for free: dom_id(record) — the id virtually every such
+      # component wrote by hand (issue #81). An explicit `def id` always wins
+      # via normal method lookup. Everything else (state-backed, a bare
+      # Streamable) still raises: a class-name default would silently collide
+      # the moment two instances render on one page. Two DIFFERENT component
+      # classes rendering the SAME record on one page also collide on the
+      # default — give one a prefixed id: `def id = dom_id(@todo, "rich")`.
+      #
+      # Called on every render/stream build, so the default stays lean: a
+      # respond_to? (reactive_record_key is Component API — a bare Streamable
+      # keeps raising) plus ivar reads via the memoized reactive_record_ivar.
       def id
-        raise NotImplementedError, "#{self.class} must implement #id for Turbo Stream targeting"
+        klass = self.class
+        if klass.respond_to?(:reactive_record_key) && (record_ivar = klass.reactive_record_ivar) &&
+           (record = instance_variable_get(record_ivar))
+          return dom_id(record)
+        end
+
+        raise NotImplementedError,
+          "#{klass} must implement #id (the stable DOM id Turbo Streams target) — add e.g. " \
+          "`def id = \"my-thing\"`. Record-backed components (reactive_record :x) get " \
+          "`dom_id(record)` as the default automatically."
       end
 
       # Render-context-free dom_id, safe to use inside `#id`. The streamable
@@ -292,9 +530,15 @@ module Phlex
       end
 
       # Render THIS already-built instance as a replace stream (used by the
-      # reactive action endpoint after an action mutated state).
+      # reactive action endpoint after an action mutated state). Wrapped in a
+      # Phlex::Reactive::Stream (issue #114) so the endpoint reads the action /
+      # target / token-ness structurally instead of regexing the markup; the wire
+      # bytes are byte-identical.
       def to_stream_replace
-        self.class.turbo_stream_builder.replace(id, html: self.class.render_component(self))
+        Phlex::Reactive::Stream.wrap(
+          self.class.turbo_stream_builder.replace(id, html: self.class.render_component(self)),
+          action: "replace", target: id, renders_root: true
+        )
       end
 
       # Render THIS instance as a MORPHING replace (issue #28):
@@ -304,11 +548,23 @@ module Phlex
       # data-reactive-token-value (so the signed token refreshes). Used by
       # Response.morph / Response.replace(self, morph: true).
       def to_stream_morph
-        self.class.turbo_stream_builder.replace(id, html: self.class.render_component(self), method: :morph)
+        Phlex::Reactive::Stream.wrap(
+          self.class.turbo_stream_builder.replace(id, html: self.class.render_component(self), method: :morph),
+          action: "replace", target: id, renders_root: true
+        )
       end
 
-      def to_stream_update
-        self.class.turbo_stream_builder.update(id, html: self.class.render_component(self))
+      # `morph: true` emits `<turbo-stream action="update" method="morph">`
+      # (issue #113) so Turbo 8 morphs the inner HTML in place, preserving a
+      # focused <input> + caret across a per-field update. Default (morph:
+      # false) is the unchanged plain update. Passing `method: :morph` inline
+      # (as #to_stream_morph does) keeps the plain call's wire byte-identical.
+      # Used by Response.update.
+      def to_stream_update(morph: false)
+        builder = self.class.turbo_stream_builder
+        html = self.class.render_component(self)
+        rendered = morph ? builder.update(id, html:, method: :morph) : builder.update(id, html:)
+        Phlex::Reactive::Stream.wrap(rendered, action: "update", target: id, renders_root: true)
       end
 
       # Render a TOKEN-ONLY refresh stream (issue #30): a tiny
@@ -334,14 +590,22 @@ module Phlex
       # has no reactive_token method at all, so it still returns false correctly.
       def to_stream_token
         token = respond_to?(:reactive_token, true) ? reactive_token : nil
-        %(<turbo-stream action="reactive:token" target="#{ERB::Util.html_escape(id)}" data-reactive-token-value="#{ERB::Util.html_escape(token)}"></turbo-stream>)
+        html = %(<turbo-stream action="reactive:token" target="#{ERB::Util.html_escape(id)}" data-reactive-token-value="#{ERB::Util.html_escape(token)}"></turbo-stream>)
+        # Both interpolations are ERB::Util.html_escape'd, so .html_safe is a
+        # byte-identical relabel. renders_root: true — reactive:token IS a
+        # self-render for token purposes (it's in SELF_RENDER_ACTIONS) — unifies
+        # the actor's own token stream onto the structural path (issue #114).
+        Phlex::Reactive::Stream.wrap(html.html_safe, action: "reactive:token", target: id, renders_root: true)
       end
 
       # Render THIS instance as a remove stream. The component already knows its
       # own #id, so no record/class reconstruction is needed (works for record-
       # and state-backed components alike). Used by Response.remove.
       def to_stream_remove
-        self.class.turbo_stream_builder.remove(id)
+        Phlex::Reactive::Stream.wrap(
+          self.class.turbo_stream_builder.remove(id),
+          action: "remove", target: id, renders_root: false
+        )
       end
     end
   end

data/lib/phlex/reactive/test_helpers/matchers.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+# RSpec matchers for reactive action Results (issue #110). Loaded lazily by
+# Phlex::Reactive::TestHelpers only when RSpec is present, so the gem never hard
+# depends on RSpec — a Minitest app mixes in TestHelpers and simply asserts on
+# Result predicates (result.replace?, result.streams) directly.
+#
+#   expect(run_reactive(component, :toggle)).to have_reactive_replace(component)
+#   expect(run_reactive(component, :archive)).to have_reactive_remove(component)
+#   expect(run_reactive(component, :increment)).to have_reactive_token_for(component)
+#
+# Each matcher accepts a component INSTANCE or a bare DOM id String, and prints a
+# diff worth reading on failure (the stream actions/targets it actually saw).
+#
+# Style/ItBlockParameter is disabled FILE-WIDE on purpose: in RSpec::Matchers
+# .define, the `do |arg|` param is the EXPECTED value and `match do |actual|` the
+# MATCHED value — two distinct objects. Collapsing either to the implicit `it`
+# (as the cop's autocorrect does) conflates them and silently guts the matcher.
+# rubocop:disable Style/ItBlockParameter
+module Phlex
+  module Reactive
+    module TestHelpers
+      # The DOM id a matcher argument targets: a String is the id verbatim; a
+      # component instance answers #id.
+      def self.matcher_target_id(component_or_id)
+        component_or_id.is_a?(::String) ? component_or_id : component_or_id.id
+      end
+
+      # A compact listing of the turbo-stream action="..." target="..." pairs in
+      # `streams` — the readable core of every failure message.
+      def self.describe_streams(streams)
+        pairs = streams.map do |stream|
+          open_tag = stream[/<turbo-stream\b[^>]*>/] || stream
+          action = open_tag[/\baction="([^"]+)"/, 1] || "?"
+          target = open_tag[/\btarget="([^"]+)"/, 1]
+          target ? "#{action}->##{target}" : action
+        end
+        pairs.empty? ? "(no streams)" : pairs.join(", ")
+      end
+
+      # True when a turbo-stream's opening tag re-renders `id` with one of
+      # `actions` at that target. Shared by the replace/remove target checks.
+      def self.stream_action_targets?(stream, actions, id)
+        open_tag = stream[/<turbo-stream\b[^>]*>/] || ""
+        actions.include?(open_tag[/\baction="([^"]+)"/, 1]) &&
+          open_tag.include?(%(target="#{ERB::Util.html_escape(id)}"))
+      end
+    end
+  end
+end
+
+RSpec::Matchers.define :have_reactive_replace do |component_or_id|
+  match do |result|
+    @id = Phlex::Reactive::TestHelpers.matcher_target_id(component_or_id)
+    @streams = result.streams
+    result.replace? &&
+      @streams.any? { |stream| Phlex::Reactive::TestHelpers.stream_action_targets?(stream, %w[replace update], @id) }
+  end
+
+  failure_message do
+    "expected the reactive Result to replace ##{@id}, " \
+      "but it did not (streams: #{Phlex::Reactive::TestHelpers.describe_streams(@streams)})"
+  end
+
+  failure_message_when_negated do
+    "expected the reactive Result NOT to replace ##{@id}, but it did " \
+      "(streams: #{Phlex::Reactive::TestHelpers.describe_streams(@streams)})"
+  end
+end
+
+RSpec::Matchers.define :have_reactive_remove do |component_or_id|
+  match do |result|
+    @id = Phlex::Reactive::TestHelpers.matcher_target_id(component_or_id)
+    @streams = result.streams
+    result.remove? &&
+      @streams.any? { |stream| Phlex::Reactive::TestHelpers.stream_action_targets?(stream, %w[remove], @id) }
+  end
+
+  failure_message do
+    "expected the reactive Result to remove ##{@id}, " \
+      "but it did not (streams: #{Phlex::Reactive::TestHelpers.describe_streams(@streams)})"
+  end
+
+  failure_message_when_negated do
+    "expected the reactive Result NOT to remove ##{@id}, but it did " \
+      "(streams: #{Phlex::Reactive::TestHelpers.describe_streams(@streams)})"
+  end
+end
+
+# Pins the #44/#46 token-refresh regression class: a reply that fails to roll the
+# component's signed token forward makes the next action reject silently. This
+# matcher asserts a fresh data-reactive-token-value for the component IS present.
+RSpec::Matchers.define :have_reactive_token_for do |component_or_id|
+  match do |result|
+    @id = Phlex::Reactive::TestHelpers.matcher_target_id(component_or_id)
+    @streams = result.streams
+    target = %(target="#{ERB::Util.html_escape(@id)}")
+    @streams.any? { |stream| stream.include?("data-reactive-token-value") && stream.include?(target) }
+  end
+
+  failure_message do
+    "expected the reactive Result to carry a fresh signed token for ##{@id} " \
+      "(a data-reactive-token-value at its target), but none was present — the next action " \
+      "from ##{@id} would be rejected with a stale token (streams: " \
+      "#{Phlex::Reactive::TestHelpers.describe_streams(@streams)})"
+  end
+
+  failure_message_when_negated do
+    "expected the reactive Result NOT to carry a fresh token for ##{@id}, but it did"
+  end
+end
+# rubocop:enable Style/ItBlockParameter