phlex-reactive 0.13.3 → 0.14.0

data/lib/phlex/reactive/pending/markup.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module Pending
+      # The opt-in pending MARKUP hook (issue #249). The #248 markers dim a live
+      # row; some apps want the pending state to be honest markup instead — a
+      # real "Queued" badge, a button that is genuinely gone. A row component
+      # opts in by defining `pending_template` (private is fine), and
+      # reply.pending then ALSO replaces the row with that markup:
+      #
+      #   class TransferRow < ApplicationComponent
+      #     def view_template = li(id:, **reactive_attrs) { ...; button(**on(:retry)) { "Retry" } }
+      #
+      #     private
+      #
+      #     def pending_template = li(id:, **reactive_attrs) { ...; span(class: "badge") { "Queued" } }
+      #   end
+      #
+      # It is a TEMPLATE method, not a content method like `deferred_placeholder`
+      # (#165): there the gem owns the shell div and the component supplies what
+      # goes inside; here the row's own root is swapped, so the hook renders it.
+      #
+      # ## Why a subclass
+      #
+      # Phlex 2 compiles templates per class, so the swap cannot be a per-instance
+      # method. Each opted-in row class gets ONE memoized anonymous subclass whose
+      # view_template is the pending template. Two contracts make that safe:
+      #
+      #   * The variant's `.name` is the PARENT's. A row that includes Component
+      #     signs its class name into its token; an anonymous name cannot
+      #     constantize, so the row's next action would 400.
+      #   * The memo holds classes derived from reloadable ones, so the engine
+      #     resets it on Rails code reload (config.to_prepare), exactly like the
+      #     view-context and stream-builder memos.
+      #
+      # ## Un-pending is the settle's job
+      #
+      # The markers are attributes, so any settle can strip them. Swapped markup
+      # is not: only a settle that REPLACES or REMOVES the row puts it back. A
+      # flash-only settle, `finish: true` or a failed job clears the markers but
+      # leaves the pending markup in place.
+      module Markup
+        HOOK = :pending_template
+
+        # The root start tag of the rendered markup, walked quote-aware: Phlex
+        # double-quotes every attribute value and leaves `>` raw inside it
+        # (`data-action="click->reactive#dispatch"`), so the tag must not end at
+        # the first `>`.
+        ROOT_TAG = %r{\A\s*<[^\s>/]+(?:\s+[^\s=>/]+(?:="[^"]*")?)*}
+
+        # Keyed weakly on the row class, so a class Zeitwerk replaced is not
+        # pinned between resets. A WeakKeyMap, not a WeakMap: nothing else holds
+        # the variant, so a weak VALUE would let GC drop the memo.
+        @variants = ObjectSpace::WeakKeyMap.new
+        @mutex = Mutex.new
+
+        class << self
+          # The row's pending markup as HTML, or nil when the row has no hook
+          # (or the target is a bare DOM id String — there is no component to
+          # render). Rendered through the PARENT's render_component: the variant
+          # is never registered with Streamable, so this reuses the parent's
+          # memoized, reload-reset view context and its instrumentation name.
+          def render(row)
+            return nil unless row.is_a?(Phlex::Reactive::Streamable) && row.respond_to?(HOOK, true)
+
+            html = row.class.render_component(variant_instance(row))
+            assert_keeps_id!(row, html)
+            html
+          end
+
+          # The replace stream that swaps one row to its pending markup.
+          def stream(target_id, html)
+            Phlex::Reactive::Stream.wrap(
+              Phlex::Reactive.stream_builder.replace(target_id, html: html.html_safe),
+              action: "replace", target: target_id, renders_root: true
+            )
+          end
+
+          def variant_for(row_class)
+            @mutex.synchronize { @variants[row_class] ||= build_variant(row_class) }
+          end
+
+          # Called from the engine's config.to_prepare (Rails code reload).
+          def reset!
+            @mutex.synchronize { @variants = ObjectSpace::WeakKeyMap.new }
+          end
+
+          private
+
+          def build_variant(row_class)
+            Class.new(row_class) do
+              def self.name = superclass.name
+              def self.inspect = "#{superclass.name}(pending)"
+              def self.to_s = inspect
+
+              def view_template = pending_template
+            end
+          end
+
+          # A variant instance carrying the built row's state. allocate + copy
+          # rather than re-running initialize: the row may have been handed to
+          # reply.pending already built, with arguments the gem never saw.
+          def variant_instance(row)
+            variant = variant_for(row.class).allocate
+            row.instance_variables.each { variant.instance_variable_set(it, row.instance_variable_get(it)) }
+            variant
+          end
+
+          # A pending template that drops the row's id leaves the settle nothing
+          # to target: its replace/remove would miss and the row would say
+          # "Queued" forever. Fail at the action, before anything is enqueued.
+          # Only the ROOT start tag counts — the id on a data- attribute or a
+          # nested child is not a target the settle can swap (see ROOT_TAG).
+          def assert_keeps_id!(row, html)
+            root_tag = html[ROOT_TAG].to_s
+            return if root_tag.match?(/\sid="#{Regexp.escape(ERB::Util.html_escape(row.id))}"/)
+
+            raise Phlex::Reactive::Error,
+              "#{row.class.name}#pending_template must render the row's root with its id " \
+              "(id=\"#{row.id}\") — the settle targets that id to replace or remove the row. " \
+              "Render the root as in view_template, e.g. li(id:, **reactive_attrs) { ... }."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/pending.rb

@@ -92,8 +92,10 @@ module Phlex
       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)
+      # marked pending (the endpoint emits one marker stream per id), and — in
+      # step with target_ids — each row's pending markup (issue #249), nil for
+      # a row without the pending_template hook.
+      Segment = Data.define(:handle, :target_ids, :markup)
 
       # The attribute apps style. Set alongside aria-busy on every pending
       # target AND on the container, so one CSS rule covers both:
@@ -126,7 +128,8 @@ module Phlex
           # 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)
+          rows = resolve_rows(container, list, collection)
+          targets = rows.map { it.is_a?(String) ? it : it.id }
 
           unless Phlex::Reactive.settle_capable?
             warn_no_lane
@@ -134,9 +137,12 @@ module Phlex
             return nil
           end
 
+          # Rendered BEFORE the enqueue, so a broken pending_template fails the
+          # action (and rolls it back) before any job exists.
+          markup = rows.map { Markup.render(it) }
           handle = build_handle(container, collection, targets, peers)
           with_handle(handle) { run_enqueue(list, job, args, enqueue, targets) }
-          Segment.new(handle:, target_ids: targets)
+          Segment.new(handle:, target_ids: targets, markup:)
         end
 
         # One record, or an enumerable of them, as an Array — never re-walked.
@@ -149,9 +155,13 @@ module Phlex
 
         # 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.
+        # single subscription directive. A row with pending markup is replaced
+        # just before its marker, so the marker lands on the swapped node.
         def streams_for(segment)
-          streams = segment.target_ids.map { marker_stream(it) }
+          streams = segment.target_ids.each_with_index.flat_map do |id, index|
+            html = segment.markup[index]
+            html ? [Markup.stream(id, html), marker_stream(id)] : [marker_stream(id)]
+          end
           streams << marker_stream(segment.handle.anchor)
           streams << directive_stream(segment.handle)
           streams
@@ -162,24 +172,18 @@ module Phlex
         # 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)
+        # Each pending target, as a row component (its #id is the target, and
+        # it renders the pending markup when it has the hook) or a bare DOM id
+        # String. With `in:` the rows resolve through the collection declaration
+        # (build is cheap — #id must be render-context-free, the Streamable#id
+        # contract); without it every entry must already be a Streamable
+        # component.
+        def resolve_rows(container, list, collection)
           if collection
             definition = Phlex::Reactive::Collections.definition!(container, collection)
-            return list.map { row_dom_id(definition, it) }
+            return list.map { it.is_a?(String) ? it : definition.item.send(:build, it, {}) }
           end
 
           list.map do
@@ -190,7 +194,7 @@ module Phlex
                 "Streamable component instance (its #id is the target)"
             end
 
-            it.id
+            it
           end
         end
 

data/lib/phlex/reactive/show_conditions.rb

@@ -20,6 +20,9 @@ module Phlex
     #   { length: 6 }                -> len_eq 6 (issue #226 — the value's
     #   { length: 6.. } / (4..8)        CODEPOINT count; Integer Ranges reuse
     #                                   the threshold vocabulary as len_*)
+    #   { checked: 1.. } / { checked: 0 } -> checked_* (issue #319 — how many
+    #                                   owned boxes of a checkbox GROUP are
+    #                                   ticked; same Integer/Range shapes)
     # Under unless: each term is NEGATED (De Morgan):
     #   scalar -> not; Array -> ∉ (AND of nots); Range -> the complement
     #   predicate (¬gte→lt, ¬lte→gt, ¬lt→gte), and a BOUNDED range complements
@@ -38,6 +41,14 @@ module Phlex
       # — the shared fixture's emoji vector proves it.
       LENGTH_KEYS = %w[len_eq len_gte len_gt len_lte len_lt].freeze
 
+      # The checked-count wire keys (issue #319) — the client mirrors them in
+      # SHOW_CHECKED_KEYS. They count the TICKED boxes of a checkbox group (an
+      # Array value counts its entries; an Integer is the count itself).
+      CHECKED_KEYS = %w[checked_eq checked_gte checked_gt checked_lte checked_lt].freeze
+
+      # A Hash value's one key -> its wire-key prefix.
+      COUNT_PREFIXES = { "length" => "len", "checked" => "checked" }.freeze
+
       module_function
 
       # Compile if:/if_any:/unless: into DNF groups. Loud validation at render
@@ -136,7 +147,7 @@ module Phlex
         case value
         when Range then range_terms(name, value)
         when Array then [membership_term(name, value)]
-        when Hash then length_terms(name, value)
+        when Hash then count_terms(name, value)
         else [{ "field" => name, "equals" => equals_literal(value) }]
         end
       end
@@ -180,90 +191,95 @@ module Phlex
         end
       end
 
-      # --- the length predicate (issue #226) ----------------------------------
+      # --- the count predicates: length: (#226) and checked: (#319) ---------
 
-      # A Hash value names a STRUCTURAL predicate — today only length:. Exact
-      # Integer -> one len_eq term; an Integer Range -> len_gte/len_lte/len_lt
-      # terms exactly like range_terms. Length is a total function over the
-      # value's codepoints (blank/absent -> 0), so { length: 0 } legitimately
-      # matches a blank field.
-      def length_terms(name, hash)
-        value = length_value!(name, hash)
+      # A Hash value names a STRUCTURAL predicate over a COUNT — length: (the
+      # value's codepoints) or checked: (the ticked boxes of a checkbox group).
+      # Exact Integer -> one *_eq term; an Integer Range -> *_gte/*_lte/*_lt
+      # terms exactly like range_terms. A count is total (blank/absent -> 0),
+      # so { length: 0 } / { checked: 0 } legitimately match a blank field.
+      def count_terms(name, hash)
+        kind, value = count_value!(name, hash)
+        prefix = COUNT_PREFIXES.fetch(kind)
         case value
         when Integer
-          validate_length_literal!(name, value)
-          [{ "field" => name, "len_eq" => value }]
-        when Range then length_range_terms(name, value)
-        else raise_length_kind(name, value)
+          validate_count_literal!(name, kind, value)
+          [{ "field" => name, "#{prefix}_eq" => value }]
+        when Range then count_range_terms(name, kind, value)
+        else raise_count_kind(name, kind, value)
         end
       end
 
-      def length_range_terms(name, range)
+      def count_range_terms(name, kind, range)
+        prefix = COUNT_PREFIXES.fetch(kind)
         first = range.begin
         last = range.end
-        raise_length_kind(name, range) if first.nil? && last.nil?
-        [first, last].compact.each { validate_length_literal!(name, it) }
+        raise_count_kind(name, kind, range) if first.nil? && last.nil?
+        [first, last].compact.each { validate_count_literal!(name, kind, it) }
 
         terms = []
-        terms << { "field" => name, "len_gte" => first } unless first.nil?
+        terms << { "field" => name, "#{prefix}_gte" => first } unless first.nil?
         if last
-          terms << { "field" => name, (range.exclude_end? ? "len_lt" : "len_lte") => last }
+          terms << { "field" => name, "#{prefix}_#{range.exclude_end? ? "lt" : "lte"}" => last }
         end
         terms
       end
 
-      # The complement of a length predicate, under unless:. Exact length
-      # negates to the outside disjunction (len < n OR len > n) — two
+      # The complement of a count predicate, under unless:. An exact count
+      # negates to the outside disjunction (n < x OR n > x) — two
       # alternatives, like a bounded numeric range; ranges complement each leg
-      # (not-gte -> lt, not-lte -> gt, not-lt -> gte). Length is total, so
+      # (not-gte -> lt, not-lte -> gt, not-lt -> gte). A count is total, so
       # unlike the numeric complements there is no blank/NaN fail-closed
       # asymmetry — the complement is exact.
-      def length_complement(name, hash)
-        value = length_value!(name, hash)
+      def count_complement(name, hash)
+        kind, value = count_value!(name, hash)
+        prefix = COUNT_PREFIXES.fetch(kind)
         case value
         when Integer
-          validate_length_literal!(name, value)
-          [[{ "field" => name, "len_lt" => value }], [{ "field" => name, "len_gt" => value }]]
+          validate_count_literal!(name, kind, value)
+          [[{ "field" => name, "#{prefix}_lt" => value }], [{ "field" => name, "#{prefix}_gt" => value }]]
         when Range
           first = value.begin
           last = value.end
-          raise_length_kind(name, value) if first.nil? && last.nil?
-          [first, last].compact.each { validate_length_literal!(name, it) }
+          raise_count_kind(name, kind, value) if first.nil? && last.nil?
+          [first, last].compact.each { validate_count_literal!(name, kind, it) }
 
-          low = first.nil? ? nil : [{ "field" => name, "len_lt" => first }]
+          low = first.nil? ? nil : [{ "field" => name, "#{prefix}_lt" => first }]
           high =
             if last.nil? then nil
-            elsif value.exclude_end? then [{ "field" => name, "len_gte" => last }]
-            else [{ "field" => name, "len_gt" => last }]
+            elsif value.exclude_end? then [{ "field" => name, "#{prefix}_gte" => last }]
+            else [{ "field" => name, "#{prefix}_gt" => last }]
             end
           [low, high].compact
-        else raise_length_kind(name, value)
+        else raise_count_kind(name, kind, value)
         end
       end
 
-      # The one Hash key must be length: — anything else is a typo'd predicate
-      # that must fail at render, never silently in the browser.
-      def length_value!(name, hash)
-        unless hash.size == 1 && hash.keys.first.to_s == "length"
+      # The one Hash key must be length: or checked: — anything else is a
+      # typo'd predicate that must fail at render, never silently in the
+      # browser. Returns [kind, value].
+      def count_value!(name, hash)
+        kind = hash.keys.first.to_s if hash.size == 1
+        unless COUNT_PREFIXES.key?(kind)
           raise ArgumentError,
-            "reactive_show: #{name.inspect} Hash value supports only length: " \
+            "reactive_show: #{name.inspect} Hash value supports only length: or checked: " \
             "(got #{hash.keys.inspect})"
         end
 
-        hash.values.first
+        [kind, hash.values.first]
       end
 
-      def validate_length_literal!(name, value)
+      def validate_count_literal!(name, kind, value)
         return if value.is_a?(Integer) && value >= 0
 
         raise ArgumentError,
-          "reactive_show: #{name.inspect} length: takes a non-negative Integer " \
-          "(a codepoint count), got #{value.inspect}"
+          "reactive_show: #{name.inspect} #{kind}: takes a non-negative Integer " \
+          "(a #{kind == "length" ? "codepoint" : "ticked-box"} count), got #{value.inspect}"
       end
 
-      def raise_length_kind(name, value)
+      def raise_count_kind(name, kind, value)
         raise ArgumentError,
-          "reactive_show: #{name.inspect} length: takes a non-negative Integer " \
+          "reactive_show: #{name.inspect} #{kind}: takes a non-negative Integer " \
           "or an Integer Range, got #{value.inspect}"
       end
 
@@ -278,7 +294,7 @@ module Phlex
         name = field.to_s
         case value
         when Range then range_complement(name, value)
-        when Hash then length_complement(name, value)
+        when Hash then count_complement(name, value)
         when Array
           list = value.map(&:to_s)
           raise ArgumentError, "reactive_show: #{name.inspect} Array needs at least one value" if list.empty?
@@ -320,28 +336,40 @@ module Phlex
         if term.key?("equals") then value == term["equals"]
         elsif term.key?("not") then value != term["not"]
         elsif term.key?("in") then term["in"].include?(value)
-        elsif (key = LENGTH_KEYS.find { term.key?(it) }) then length_term_matches?(key, term[key], value)
+        elsif (key = LENGTH_KEYS.find { term.key?(it) }) then count_matches?(key, term[key], value.to_s.length)
+        elsif (key = CHECKED_KEYS.find { term.key?(it) }) then count_matches?(key, term[key], checked_count(value))
         else numeric_term_matches?(term, value)
         end
       end
 
-      # len_* — compare the value's CODEPOINT count (String#length) against the
-      # Integer literal. Length is total (blank/absent -> 0), so every value is
-      # decidable; a malformed non-Integer literal (a hand-built term) is
-      # fail-closed, mirroring the client's warn-skip.
-      def length_term_matches?(key, literal, value)
+      # len_* / checked_* — compare a count (the value's CODEPOINTS via
+      # String#length, or the group's ticked boxes) against the Integer literal.
+      # A count is total (blank/absent -> 0), so every value is decidable; a
+      # malformed non-Integer literal (a hand-built term) is fail-closed,
+      # mirroring the client's warn-skip.
+      def count_matches?(key, literal, count)
         return false unless literal.is_a?(Integer)
 
-        length = value.to_s.length
-        case key
-        when "len_eq" then length == literal
-        when "len_gte" then length >= literal
-        when "len_gt" then length > literal
-        when "len_lte" then length <= literal
-        when "len_lt" then length < literal
+        case key.delete_prefix("len_").delete_prefix("checked_")
+        when "eq" then count == literal
+        when "gte" then count >= literal
+        when "gt" then count > literal
+        when "lte" then count <= literal
+        when "lt" then count < literal
         end
       end
 
+      # How many boxes of a group are ticked, from the first-paint value: an
+      # Array (the checked values) counts its entries, an Integer (or its
+      # string) is the count, a lone checkbox's "true"/"false" is 1/0, and a
+      # blank/absent group is 0 — the client counts the owned ticked boxes.
+      def checked_count(value)
+        return value.size if value.is_a?(Array)
+        return 1 if value.to_s == "true"
+
+        Integer(value.to_s, exception: false) || 0
+      end
+
       # gte/gt/lte/lt — coerce the field value to a number; a blank/non-numeric
       # value is fail-closed (never matches). Mirrors the client's
       # numericPredicateMatches (blank/whitespace -> NaN -> false).

data/lib/phlex/reactive/streamable.rb

@@ -75,7 +75,7 @@ module Phlex
         broadcast_remove_to_each: "broadcast_to(each: keys, remove: model)"
       }.freeze
 
-      # Every class that includes Streamable, so the engine can flush their
+      # Every class that includes Streamable or subclasses one, 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
       # Zeitwerk in dev is GC'd normally — a strong Array would pin every
@@ -148,7 +148,15 @@ module Phlex
               # different hosts — absolute URLs in broadcast-rendered components
               # keep the process defaults, so "host-relative URLs" stays the
               # broadcast contract. Off-request callers pay one nil-write pair.
-              html = verb == :js ? nil : Phlex::Reactive.with_url_options(nil) { render_broadcast_html(component) }
+              # Nor the actor's AWAKE dormant roots (issue #274): a subscriber may
+              # never have loaded the client, so its copy stays dormant (one
+              # fiber-local read off-request).
+              html =
+                if verb != :js
+                  Phlex::Reactive::Dormant.asleep do
+                    Phlex::Reactive.with_url_options(nil) { render_broadcast_html(component) }
+                  end
+                end
               ops_json = verb == :js ? broadcast_js_ops_json(payload) : nil
               keys.each { dispatch_broadcast(verb, it, resolved_target, html, ops_json, morph, effect) }
             end
@@ -313,6 +321,16 @@ module Phlex
       end
 
       class_methods do
+        # A subclass inherits Streamable rather than including it, so `included`
+        # never fires for it (issue #302). Register it here so the inventory
+        # (rake tasks, MCP tools), the doctor and the reload reset see it too.
+        # Anonymous subclasses register as well; readers filter to
+        # constant-resolvable classes, and the WeakMap lets them be GC'd.
+        def inherited(subclass)
+          super
+          Phlex::Reactive::Streamable.register(subclass)
+        end
+
         # The keyword the positional model maps to in `initialize`. For a
         # record-backed component (Component#reactive_record), this is the SAME
         # keyword the action endpoint uses in `from_identity` — so one

data/lib/phlex/reactive/test_helpers/system/reactive_requests_matcher.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Phlex
+  module Reactive
+    module TestHelpers
+      module System
+        # The waiting matcher behind have_reactive_requests (issue #279). Reads the
+        # client's per-kind request totals (<html data-reactive-requests>, JSON)
+        # AND the in-flight marker in ONE evaluate_script per poll, and holds once
+        # the selected total equals `expected` with the layer idle, so a request
+        # still in flight is never counted early. It cannot see a request that has
+        # not STARTED yet (a debounced trigger, or the defer an action's reply is
+        # about to start): barrier on the UI outcome first for those.
+        #
+        # Totals only grow until reset_reactive_requests!, so a total ABOVE the
+        # expectation is terminal: the matcher fails at once instead of waiting out
+        # the budget. A plain class (no RSpec::Matchers.define), like
+        # ReactiveValueMatcher, so System stays loadable under Capybara alone.
+        class ReactiveRequestsMatcher
+          KINDS = %i[action defer].freeze
+
+          def initialize(expected, kind: nil, wait: nil)
+            unless kind.nil? || KINDS.include?(kind)
+              raise ArgumentError, "unknown reactive request kind #{kind.inspect} (expected one of #{KINDS.inspect} or nil)"
+            end
+
+            @expected = Integer(expected)
+            @kind = kind
+            @wait = wait
+          end
+
+          def matches?(page)
+            @page = page
+            poll_until do
+              read_state
+              break false if selected > @expected
+
+              selected == @expected && !@active
+            end
+          end
+
+          # RSpec's required negated-matcher protocol name, not a predicate we pick.
+          # rubocop:disable-next Naming/PredicatePrefix
+          def does_not_match?(page)
+            @page = page
+            poll_until do
+              read_state
+              selected != @expected && !@active
+            end
+          end
+
+          def failure_message
+            with_gate_hint(
+              "expected #{@expected} reactive #{noun} (#{scope}), got #{selected} — totals #{totals_str}"
+            )
+          end
+
+          def failure_message_when_negated
+            with_gate_hint(
+              "expected the reactive request count (#{scope}) NOT to be #{@expected}, but it was — totals #{totals_str}"
+            )
+          end
+
+          private
+
+          # A closed verbose gate is the usual cause of an unexpected zero: say so.
+          def with_gate_hint(message)
+            return message if @verbose
+
+            "#{message}. The verbose gate is closed, so the client is not counting: it writes " \
+              "<html #{REQUESTS_ATTR}> only under Phlex::Reactive.verbose_errors (on in dev/test " \
+              "by default) or data-reactive-verbose on <html>"
+          end
+
+          def read_state
+            raw = @page.evaluate_script(<<~JS)
+              (() => {
+                const html = document.documentElement
+                return {
+                  requests: html.getAttribute(#{REQUESTS_ATTR.to_json}),
+                  active: html.hasAttribute(#{ACTIVE_MARKER.to_json}),
+                  verbose: html.hasAttribute("data-reactive-verbose") ||
+                    !!document.querySelector('[data-reactive-verbose="true"]'),
+                }
+              })()
+            JS
+            raw = {} unless raw.is_a?(::Hash)
+            @verbose = raw["verbose"] == true
+            @totals = System.parse_reactive_requests(raw["requests"])
+            @active = raw["active"] == true
+          end
+
+          def selected = @kind ? @totals[@kind] : @totals.values.sum
+
+          def scope = @kind ? "kind: #{@kind.inspect}" : "any kind"
+
+          def noun = @expected == 1 ? "request" : "requests"
+
+          def totals_str = "{#{@totals.map { |k, v| "#{k}: #{v}" }.join(", ")}}"
+
+          # Same bounded, monotonic-clock poll as ReactiveValueMatcher. A `break
+          # false` inside the block ends the poll early (a terminal mismatch).
+          def poll_until
+            deadline = now + (@wait || ::Capybara.default_max_wait_time)
+            loop do
+              return true if yield
+              return false if now >= deadline
+
+              sleep 0.05
+            end
+          end
+
+          def now = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+        end
+      end
+    end
+  end
+end