phlex-reactive 0.13.4 → 0.14.0

data/lib/phlex/reactive/inspector/report.rb

@@ -15,7 +15,13 @@ module Phlex
         # A plain-text table of every component × action, or a JSON array when
         # `format` is :json. One row per action: component, action, params,
         # file:line, authorization heuristic.
-        def actions(components, format: :text)
+        # `unverified_only:` keeps just the actions whose authorization_state is
+        # :none (the review queue) and drops components left with none.
+        def actions(components, format: :text, unverified_only: false)
+          if unverified_only
+            components = unverified(components)
+            return "no unverified actions" if components.empty? && format != :json
+          end
           return actions_json(components) if format == :json
 
           actions_text(components)
@@ -34,6 +40,13 @@ module Phlex
           lines.join("\n")
         end
 
+        def unverified(components)
+          components.filter_map do
+            actions = it.actions.select { it.authorization_state == :none }
+            it.with(actions:) if actions.any?
+          end
+        end
+
         # -- plain text -------------------------------------------------------
 
         def actions_text(components)
@@ -110,7 +123,9 @@ module Phlex
             name: action.name,
             params: action.params,
             source_location: location_str(action.source_location),
-            authorization_call_detected: action.authorization_call_detected?
+            authorization_call_detected: action.authorization_call_detected?,
+            authorization: action.authorization_state.to_s,
+            authorization_skip: action.authorization_skip&.to_s
           }
         end
 
@@ -131,8 +146,14 @@ module Phlex
         end
 
         # The authorization heuristic as a short label — advisory only.
+        # "authorized*" (call detected), "skipped" / "skipped (class)" (declared
+        # skip_verify_authorized), "unverified" (neither).
         def auth_str(action)
-          action.authorization_call_detected? ? "authorized*" : "unverified"
+          case action.authorization_state
+          when :detected then "authorized*"
+          when :skipped then action.authorization_skip == :class ? "skipped (class)" : "skipped"
+          else "unverified"
+          end
         end
       end
     end

data/lib/phlex/reactive/inspector.rb

@@ -31,7 +31,10 @@ module Phlex
       #                       of the definition finds a call to any configured
       #                       authorization method or mark_authorized!. A helper
       #                       may authorize indirectly, so this is advisory ONLY.
-      ActionInfo = Data.define(:name, :params, :source_location, :definition) do
+      #   * authorization_skip — :class (a bare skip_verify_authorized, own or
+      #                       inherited), :action (this action is named in one),
+      #                       or nil. The author's declared opt-out (issue #278).
+      ActionInfo = Data.define(:name, :params, :source_location, :definition, :authorization_skip) do
         # Was any authorization method (or mark_authorized!) called directly in
         # the method body? Heuristic — a Prism scan of `definition`. False when
         # the definition is unavailable.
@@ -40,6 +43,14 @@ module Phlex
 
           Inspector.authorization_call?(definition)
         end
+
+        # :detected (a call was found), :skipped (declared skip_verify_authorized)
+        # or :none (neither — the review queue). A detected call wins over a skip.
+        def authorization_state
+          return :detected if authorization_call_detected?
+
+          authorization_skip ? :skipped : :none
+        end
       end
 
       # One reactive component's introspection.
@@ -164,10 +175,20 @@ module Phlex
             name: action.name,
             params: action.params,
             source_location: location,
-            definition: (extract_definition(location) if location)
+            definition: (extract_definition(location) if location),
+            authorization_skip: authorization_skip(klass, action.name)
           )
         end
 
+        # How `name` opts out of verify_authorized: :class for a bare skip (own
+        # or inherited), :action when listed by name, else nil. Resolved through
+        # the same Registry readers the runtime guard uses.
+        def authorization_skip(klass, name)
+          return :class if klass.reactive_skip_all_authorization?
+
+          :action if klass.reactive_skip_authorization_actions.include?(name.to_sym)
+        end
+
         # The method's [file, line], or nil when the declared method is missing
         # (an undeclared/typo'd action — the endpoint would 500 on public_send).
         def method_location(klass, name)

data/lib/phlex/reactive/js.rb

@@ -196,9 +196,24 @@ module Phlex
       # "submit") interception. ACTOR-ONLY like focus: allowed from on_client /
       # reply.js / a reducer's $ops, refused in broadcast_to(js:) — a broadcast
       # submit would force-submit every subscriber's form.
+      #
+      # submitter: (issue #319) — a CSS selector for the submit control to
+      # submit THROUGH (form.requestSubmit(submitter)), so the request carries
+      # its name=value — the bulk-action "Delete" that posts action=delete. It
+      # resolves with the op's own scoping; one that isn't a submit control of
+      # that form warns in the browser and falls back to a plain submit.
+      #   js.submit("#bulk", submitter: "#delete-submit")
+
+      def submit(to = :root, global: false, submitter: nil)
+        args = target_args(to, global:)
+        return append("submit", args) if submitter.nil?
+
+        unless submitter.is_a?(String) && !submitter.empty?
+          raise ArgumentError,
+            "js.submit submitter: must be a CSS selector string naming a submit control, got #{submitter.inspect}"
+        end
 
-      def submit(to = :root, global: false)
-        append("submit", target_args(to, global:))
+        append("submit", args.merge("submitter" => submitter).freeze)
       end
 
       # --- Clipboard-source paste (issue #228) ---

data/lib/phlex/reactive/mcp/tools/actions_tool.rb

@@ -15,7 +15,9 @@ module Phlex
             action with its param schema, source file:line, and a heuristic
             authorization status (whether an authorization method or
             mark_authorized! call was detected in the body — advisory only, since a
-            helper may authorize indirectly). Pass `component:` to scope to one
+            helper may authorize indirectly), plus `authorization` — detected,
+            skipped (declared skip_verify_authorized; `authorization_skip` says
+            class or action) or none. Pass `component:` to scope to one
             component (exact name). Read-only — schemas and paths, never runtime
             values.
           DESC

data/lib/phlex/reactive/mcp/tools/find_tool.rb

@@ -15,7 +15,8 @@ module Phlex
             Fuzzy-find reactive components by name (exact > prefix > substring >
             subsequence, on both the demodulized and full name). Returns the ranked
             matches, each with its actions' param schema, source location,
-            authorization heuristic, and the full method-definition SOURCE
+            authorization (detected / skipped / none, plus the skip form), and the
+            full method-definition SOURCE
             (extracted with Prism). Read-only.
 
             NOTE: unlike the other tools (which report names/paths/schemas only),
@@ -53,6 +54,8 @@ module Phlex
               params: action.params,
               source_location: Phlex::Reactive::Inspector::Report.location_str(action.source_location),
               authorization_call_detected: action.authorization_call_detected?,
+              authorization: action.authorization_state.to_s,
+              authorization_skip: action.authorization_skip&.to_s,
               # The full method SOURCE — this is the one field that exposes an
               # action body verbatim (see the tool description). A secret hardcoded
               # in an action would surface here; keep secrets out of action bodies.

data/lib/phlex/reactive/param_schema.rb

@@ -334,36 +334,10 @@ module Phlex
         value.is_a?(Hash) || value.respond_to?(:to_unsafe_h)
       end
 
-      # Unwrap ActionController::Parameters (or a plain Hash) to a string-keyed
-      # Hash so coercion can index it uniformly, then expand bracket notation so
-      # a model-scoped Rails form's flat keys nest (issue #21).
-      def to_param_hash(value)
-        flat =
-          if value.respond_to?(:to_unsafe_h)
-            value.to_unsafe_h.stringify_keys
-          elsif value.is_a?(Hash)
-            value.stringify_keys
-          else
-            return {}
-          end
-
-        expand_bracket_keys(flat)
-      end
-
-      # The client's #collectFields keeps a form input's name verbatim, so a
-      # Rails Form(model: @invoice) posts FLAT bracketed keys like
-      # "invoice[date]". Coercion does exact-key matching, so without this a
-      # nested schema (params: { invoice: { date: … } }) never finds "invoice"
-      # and drops everything. Expand "invoice[date]" => "2026-01-02" into
-      # { "invoice" => { "date" => "2026-01-02" } } — and "items[0][qty]" into
-      # the Rails index-hash form coerce_array already understands — deep-merging
-      # so sibling keys (invoice[date], invoice[status]) coalesce. Keys WITHOUT
-      # brackets and already-nested values pass through untouched.
-      def expand_bracket_keys(flat)
-        flat.each_with_object({}) do |(key, value), out|
-          deep_assign(out, bracket_path(key), value)
-        end
-      end
+      # Each nested hash is unwrapped and expanded by the class-level expand
+      # below — the same expansion the endpoint runs before peeling a
+      # reactive_scope (issue #337), so both read one shape.
+      def to_param_hash(value) = self.class.expand(value)
 
       # Matches each bracket segment in "items_attributes][0][qty]" — the part
       # after the first "[". Hoisted to a frozen constant so coercing a bracketed
@@ -371,35 +345,75 @@ module Phlex
       BRACKET_SEGMENT = /[^\[\]]+/
       private_constant :BRACKET_SEGMENT
 
-      # "invoice[items_attributes][0][qty]" => ["invoice", "items_attributes",
-      # "0", "qty"]. A key with no brackets is a single-element path.
-      def bracket_path(key)
-        return [key] unless key.include?("[")
+      class << self
+        # Public so the endpoint can expand BEFORE it peels a reactive_scope
+        # (issue #337): a JSON body keeps "todo[title]" as one literal key, which
+        # only becomes { "todo" => { "title" => … } } here. Idempotent on input
+        # that is already nested (a multipart body Rails expanded itself).
+        #
+        # Unwraps ActionController::Parameters (or a plain Hash) to a string-keyed
+        # Hash so coercion can index it uniformly, then expands bracket notation so
+        # a model-scoped Rails form's flat keys nest (issue #21). Anything else is {}.
+        def expand(value)
+          flat =
+            if value.respond_to?(:to_unsafe_h)
+              value.to_unsafe_h.stringify_keys
+            elsif value.is_a?(Hash)
+              value.stringify_keys
+            else
+              return {}
+            end
 
-        head, rest = key.split("[", 2)
-        [head, *rest.scan(BRACKET_SEGMENT)]
-      end
+          expand_bracket_keys(flat)
+        end
 
-      # Walk/create nested hashes along `path`, then merge `value` at the leaf so
-      # a bracket key and a sibling pre-nested object coalesce regardless of which
-      # arrives first. #merge_value deep-merges hash/hash collisions and otherwise
-      # lets the later value win.
-      def deep_assign(hash, path, value)
-        *parents, leaf = path
-        node = parents.reduce(hash) do |acc, segment|
-          acc[segment] = {} unless acc[segment].is_a?(Hash)
-          acc[segment]
+        private
+
+        # The client's #collectFields keeps a form input's name verbatim, so a
+        # Rails Form(model: @invoice) posts FLAT bracketed keys like
+        # "invoice[date]". Coercion does exact-key matching, so without this a
+        # nested schema (params: { invoice: { date: … } }) never finds "invoice"
+        # and drops everything. Expand "invoice[date]" => "2026-01-02" into
+        # { "invoice" => { "date" => "2026-01-02" } } — and "items[0][qty]" into
+        # the Rails index-hash form coerce_array already understands — deep-merging
+        # so sibling keys (invoice[date], invoice[status]) coalesce. Keys WITHOUT
+        # brackets and already-nested values pass through untouched.
+        def expand_bracket_keys(flat)
+          flat.each_with_object({}) do |(key, value), out|
+            deep_assign(out, bracket_path(key), value)
+          end
         end
-        node[leaf] = merge_value(node[leaf], value)
-      end
 
-      # Combine an existing leaf value with a new one. Two hashes deep-merge (so
-      # bracket-expanded fields and a pre-nested object for the same key both
-      # survive); any other collision takes the new value.
-      def merge_value(existing, value)
-        return value unless existing.is_a?(Hash) && value.is_a?(Hash)
+        # "invoice[items_attributes][0][qty]" => ["invoice", "items_attributes",
+        # "0", "qty"]. A key with no brackets is a single-element path.
+        def bracket_path(key)
+          return [key] unless key.include?("[")
+
+          head, rest = key.split("[", 2)
+          [head, *rest.scan(BRACKET_SEGMENT)]
+        end
 
-        existing.merge(value.stringify_keys) { |_k, old, new| merge_value(old, new) }
+        # Walk/create nested hashes along `path`, then merge `value` at the leaf so
+        # a bracket key and a sibling pre-nested object coalesce regardless of which
+        # arrives first. #merge_value deep-merges hash/hash collisions and otherwise
+        # lets the later value win.
+        def deep_assign(hash, path, value)
+          *parents, leaf = path
+          node = parents.reduce(hash) do |acc, segment|
+            acc[segment] = {} unless acc[segment].is_a?(Hash)
+            acc[segment]
+          end
+          node[leaf] = merge_value(node[leaf], value)
+        end
+
+        # Combine an existing leaf value with a new one. Two hashes deep-merge (so
+        # bracket-expanded fields and a pre-nested object for the same key both
+        # survive); any other collision takes the new value.
+        def merge_value(existing, value)
+          return value unless existing.is_a?(Hash) && value.is_a?(Hash)
+
+          existing.merge(value.stringify_keys) { |_k, old, new| merge_value(old, new) }
+        end
       end
     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