phlex-reactive 0.13.4 → 0.14.1

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

@@ -36,10 +36,11 @@ module Phlex
       # Actor-only ops: a js broadcast rejects a broadcast that carries one.
       # Focus ops steal focus in every subscriber's tab (issue #96); submit
       # (issue #226) would force-submit every subscriber's form; paste_into
-      # (issue #228) would read every subscriber's clipboard. They belong to
-      # the actor's own reply (reply.js) or gesture (on_client / a reducer's
-      # $ops), never a broadcast. Names mirror Phlex::Reactive::JS's verbs.
-      BROADCAST_REFUSED_OPS = %w[focus focus_first submit paste_into persist_state persist_clear].freeze
+      # (issue #228) would read every subscriber's clipboard; check_group
+      # (issue #342) would tick or clear every subscriber's selection. They
+      # belong to the actor's own reply (reply.js) or gesture (on_client / a
+      # reducer's $ops), never a broadcast. Names mirror Phlex::Reactive::JS's verbs.
+      BROADCAST_REFUSED_OPS = %w[focus focus_first submit paste_into persist_state persist_clear check_group].freeze
 
       # The broadcast_to verb kwargs (issue #185) → their Turbo stream action.
       # SELF-TARGETING verbs derive the target from the component's #id (require a
@@ -75,7 +76,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 +149,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
@@ -183,7 +192,8 @@ module Phlex
             raise ArgumentError,
               "broadcast_to(js:) refuses actor-only op(s) #{refused.join(", ")} — broadcasting focus " \
               "steals it in every subscriber's tab; broadcasting submit force-submits every " \
-              "subscriber's form; broadcasting paste_into reads every subscriber's clipboard. " \
+              "subscriber's form; broadcasting paste_into reads every subscriber's clipboard; " \
+              "broadcasting check_group ticks or clears every subscriber's selection. " \
               "These are actor concerns (reply.js / on_client / $ops)."
           end
 
@@ -313,6 +323,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

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

@@ -36,6 +36,30 @@ module Phlex
         # twin of wait_for_turbo watching the Turbo progress bar.
         ACTIVE_MARKER = "data-reactive-active"
 
+        # The <html> attribute the client keeps its per-kind request totals in
+        # (issue #279), as JSON ({"action":1,"defer":0}). Lockstep with
+        # reactive_controller.js REQUESTS_ATTR. Written only under the verbose
+        # gate (dev/test by default).
+        REQUESTS_ATTR = "data-reactive-requests"
+
+        # Parse the attribute value into { action:, defer: } Integers — zeros for
+        # an absent or garbled value. Shared by the helpers and
+        # ReactiveRequestsMatcher.
+        def self.parse_reactive_requests(raw)
+          parsed = raw.is_a?(::String) ? ::JSON.parse(raw) : {}
+          parsed = {} unless parsed.is_a?(::Hash)
+          { action: reactive_request_total(parsed["action"]), defer: reactive_request_total(parsed["defer"]) }
+        rescue ::JSON::ParserError
+          { action: 0, defer: 0 }
+        end
+
+        # One total as an Integer. Only a number or a numeric string counts; any
+        # other JSON value (array, object, boolean, null) is garbled, so zero.
+        def self.reactive_request_total(value)
+          value.is_a?(::Numeric) || value.is_a?(::String) ? value.to_i : 0
+        end
+        private_class_method :reactive_request_total
+
         # Block until the reactive layer is IDLE — every dispatch round trip and
         # deferred render has settled and the <html data-reactive-active> marker is
         # gone. The system-test twin of wait_for_turbo (which watches the Turbo
@@ -92,6 +116,42 @@ module Phlex
         def have_reactive_text(id, value, **)
           have_css("##{id}", text: value, **)
         end
+
+        # How many reactive requests the page has made since the last
+        # reset_reactive_requests! (or since the page loaded), per kind (issue
+        # #279):
+        #
+        #   reactive_request_count # => { action: 1, defer: 0 }
+        #
+        # A snapshot, not a wait — barrier on wait_for_reactive (or use
+        # have_reactive_requests) before reading it after a gesture.
+        def reactive_request_count
+          System.parse_reactive_requests(
+            page.evaluate_script("document.documentElement.getAttribute(#{REQUESTS_ATTR.to_json})")
+          )
+        end
+
+        # Baseline the request totals to zero. The attribute IS the client's
+        # store, so writing zeros re-baselines it — including after a Turbo Drive
+        # visit, where the <html> element (and its totals) survives navigation.
+        def reset_reactive_requests!
+          zeros = { action: 0, defer: 0 }.to_json
+          page.execute_script("document.documentElement.setAttribute(#{REQUESTS_ATTR.to_json}, '#{zeros}')")
+          nil
+        end
+
+        # Assert (waiting) that exactly `count` reactive requests were made — of
+        # `kind` (:action or :defer), or of any kind — since the last reset, AND
+        # that nothing is still in flight. Fails at once if the count overshoots
+        # (totals only grow until a reset).
+        #
+        #   reset_reactive_requests!
+        #   find("#open-panel").click
+        #   expect(page).to have_reactive_requests(1)
+        #   expect(page).to have_reactive_requests(0, kind: :defer)
+        def have_reactive_requests(count, kind: nil, timeout: nil, wait: nil)
+          ReactiveRequestsMatcher.new(count, kind:, wait: timeout || wait)
+        end
         # rubocop:enable Naming/PredicatePrefix
 
         # A waiting matcher that asserts a field's live `.value` PROPERTY (issue
@@ -190,3 +250,5 @@ module Phlex
     end
   end
 end
+
+require "phlex/reactive/test_helpers/system/reactive_requests_matcher"

data/lib/phlex/reactive/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Reactive
-    VERSION = "0.13.4"
+    VERSION = "0.14.1"
   end
 end

data/lib/phlex/reactive.rb

@@ -133,6 +133,12 @@ module Phlex
       # ActionPolicy::Unauthorized, ...).
       attr_accessor :authorization_errors
 
+      # Import maps `phlex_reactive:doctor` checks for the `phlex/reactive/early`
+      # pin (issue #307): a callable returning `{ name => Importmap::Map }`, for
+      # an app with more than one map (one per entry point). nil (the default)
+      # checks `Rails.application.importmap` only.
+      attr_accessor :importmaps
+
       # The path the action endpoint is mounted at. Default "/reactive/actions".
       # Set before boot if it collides with an app route. The client runtime
       # reads it from a <meta name="phlex-reactive-action-path"> tag if present,
@@ -532,6 +538,29 @@ module Phlex
         instance.view_context
       end
 
+      # --- Early triggers (issue #273) -----------------------------------
+
+      # How long (ms) a trigger captured by phlex/reactive/early before the
+      # controller connected stays replayable. Older entries are dropped on
+      # connect (warned under data-reactive-verbose): a click from long ago must
+      # not fire a request out of nowhere. The client reads it from a meta tag
+      # in the host layout (the engine can't inject into it):
+      #   <meta name="phlex-reactive-early-ttl" content="<%= Phlex::Reactive.early_event_ttl_ms %>">
+      # Without the meta the client uses the same 10 s default. nil resets.
+      # Validated at assignment: the client reads a non-positive TTL as "use
+      # the default", so 0 can never mean "replay nothing" — fail here instead.
+      def early_event_ttl_ms=(value)
+        unless value.nil? || (value.is_a?(Integer) && value.positive?)
+          raise ArgumentError, "early_event_ttl_ms must be a positive Integer (milliseconds) or nil, got #{value.inspect}"
+        end
+
+        @early_event_ttl_ms = value
+      end
+
+      def early_event_ttl_ms
+        @early_event_ttl_ms ||= 10_000
+      end
+
       # --- Deferred reply segments (issue #165) --------------------------
 
       # Lifetime (seconds) of a defer token. It only needs to cover the
@@ -552,6 +581,44 @@ module Phlex
         @defer_path ||= "/reactive/defer"
       end
 
+      # The path prefix of the cacheable-fragment GET endpoint (issue #277):
+      # GET <fragment_path>/<signed id>. Default "/reactive/fragment"; set
+      # before boot if it collides. The shell renders the full URL, but the
+      # client only fetches one under the path it knows: when you change this,
+      # also render <meta name="phlex-reactive-fragment-path" content="…">.
+      attr_writer :fragment_path
+
+      def fragment_path
+        @fragment_path ||= "/reactive/fragment"
+      end
+
+      # The longest max-age (seconds) a `reactive_lazy cache:` component may
+      # ask the browser to keep its fragment for. A component declaring more
+      # is answered with this cap. Within max-age the browser reuses its copy
+      # WITHOUT asking the server — so this also bounds how long a revoked
+      # permission can keep showing a stale fragment. Default 1 hour; nil
+      # restores it; 0 makes every cached fragment revalidate on each use.
+      def fragment_cache_max_age_limit=(value)
+        seconds = value.is_a?(ActiveSupport::Duration) && value.to_i == value ? value.to_i : value
+        unless seconds.nil? || (seconds.is_a?(::Integer) && !seconds.negative?)
+          raise ArgumentError,
+            "Phlex::Reactive.fragment_cache_max_age_limit must be a whole, non-negative number of seconds " \
+            "(or nil for the default) — got #{value.inspect}"
+        end
+
+        @fragment_cache_max_age_limit = seconds
+      end
+
+      def fragment_cache_max_age_limit
+        @fragment_cache_max_age_limit ||= 3600
+      end
+
+      # The deterministic, no-expiry, purpose-scoped fragment id of an identity
+      # payload, and its verification (issue #277). See Phlex::Reactive::Fragment.
+      def sign_fragment(payload) = Fragment.sign(payload)
+
+      def verify_fragment(id) = Fragment.verify(id)
+
       # How deferred segments reach the actor: :auto (push iff capable, else
       # pull), :fetch (always pull), :stream (push; degrades to pull with a
       # warning when the capability is absent). Validated at assignment — a
@@ -1056,6 +1123,7 @@ module Phlex
       # The controller a correctly-mounted action path resolves to. Used by the
       # route guard below.
       ACTIONS_CONTROLLER = "phlex/reactive/actions"
+      FRAGMENTS_CONTROLLER = "phlex/reactive/fragments"
 
       # True when a POST to `path` resolves to the gem's ActionsController. A host
       # catch-all route (match "*path", ...) appended above the engine's route
@@ -1076,6 +1144,20 @@ module Phlex
         false
       end
 
+      # Does GET <fragment_path>/<id> resolve to the gem's FragmentsController
+      # (issue #277)? A host GET catch-all shadows it otherwise, and every
+      # `reactive_lazy cache:` fetch then gets the host's fallback page. The
+      # doctor reports it, like the defer route.
+      def fragment_route_ok?(path = fragment_path)
+        return false unless defined?(::Rails) && ::Rails.application
+
+        ensure_routes_loaded
+        recognized = ::Rails.application.routes.recognize_path("#{path}/probe", method: :get)
+        recognized[:controller] == FRAGMENTS_CONTROLLER
+      rescue ActionController::RoutingError, ActiveRecord::RecordNotFound
+        false
+      end
+
       # Log a clear warning (once, at boot) when the action path doesn't resolve
       # to the gem controller — pointing at the catch-all shadow rather than
       # leaving an adopter to guess. Called from the engine's after_initialize.
@@ -1184,6 +1266,8 @@ loader.ignore("#{lib}/phlex/reactive/test_helpers/matchers.rb")
 # only when Capybara is present, so the loader must ignore it (otherwise an
 # eager-load in production would define browser helpers with no Capybara).
 loader.ignore("#{lib}/phlex/reactive/test_helpers/system.rb")
+# ...and its matcher subdirectory (issue #279), required by system.rb itself.
+loader.ignore("#{lib}/phlex/reactive/test_helpers/system")
 # The MCP diagnostic tool tree (issue #168) subclasses the OPTIONAL `mcp` gem's
 # constants (MCP::Tool) at class-definition time, so the whole mcp/ subdirectory
 # must stay out of the autoloader — Phlex::Reactive::MCP.load! requires it in

data/lib/tasks/phlex_reactive.rake

@@ -12,14 +12,18 @@ namespace :phlex_reactive do
     abort unless Phlex::Reactive::Doctor.run
   end
 
-  desc "List every declared reactive action (component | action | params | file:line | auth); FORMAT=json for tooling"
+  desc "List every declared reactive action (component | action | params | file:line | auth); " \
+       "FORMAT=json for tooling, UNVERIFIED=1 for only the unverified rows"
   task actions: :environment do
     # eager_load! so every app component is in the Streamable registry the
     # Inspector reads. Plain text by default (no ANSI, like the doctor);
     # FORMAT=json emits a parseable array for tooling. Names/paths/schemas only.
+    # UNVERIFIED=1 keeps only actions with neither a detected authorization call
+    # nor a skip_verify_authorized — the review queue (issue #278).
     Rails.application.eager_load!
     format = ENV["FORMAT"].to_s.downcase == "json" ? :json : :text
-    puts Phlex::Reactive::Inspector::Report.actions(Phlex::Reactive::Inspector.components, format:)
+    unverified_only = %w[1 true yes].include?(ENV["UNVERIFIED"].to_s.downcase)
+    puts Phlex::Reactive::Inspector::Report.actions(Phlex::Reactive::Inspector.components, format:, unverified_only:)
   end
 
   desc "Fuzzy-find a reactive component and print its actions with method-definition source — phlex_reactive:find[query]"