phlex-reactive 0.13.3 → 0.14.0

data/lib/generators/phlex/reactive/install/templates/phlex_reactive.rb.erb

@@ -117,6 +117,24 @@
 #   <meta name="phlex-reactive-defer-path" content="<%%= Phlex::Reactive.defer_path %>">
 # Phlex::Reactive.defer_path = "/_r/defer"
 
+# Cacheable lazy fragments (reactive_lazy cache: { max_age: … }): the GET
+# endpoint's path prefix (default "/reactive/fragment") and the longest max-age
+# a component may be answered with (default 1 hour — within it the browser does
+# not ask the server, so it also bounds how long a revoked permission can keep
+# showing a cached fragment). If you change the path, expose it to the client
+# in the layout <head> (the client refuses fragment URLs outside the path it
+# knows; phlex_reactive:doctor checks for the tag):
+#   <meta name="phlex-reactive-fragment-path" content="<%%= Phlex::Reactive.fragment_path %>">
+# Phlex::Reactive.fragment_path = "/_r/fragment"
+# Phlex::Reactive.fragment_cache_max_age_limit = 10.minutes
+
+# Early triggers (issue #273): with `import "phlex/reactive/early"` in your
+# entry point, a trigger that fires before a lazily loaded controller connects
+# is replayed on connect — unless it is older than this (ms, default 10s).
+# Render it into your layout head for the client to read:
+#   <meta name="phlex-reactive-early-ttl" content="<%%= Phlex::Reactive.early_event_ttl_ms %>">
+# Phlex::Reactive.early_event_ttl_ms = 10_000
+
 # Client request timeout (default 30s). There is NO server-side setting — a hung
 # request aborts client-side after this window (reactive:error kind "timeout"),
 # so the per-component queue never wedges. Override in your layout head:

data/lib/phlex/reactive/claude/skills/phlex-reactive-debugging/SKILL.md

@@ -33,13 +33,15 @@ Run this FIRST — most "nothing happens" reports are a red ✗ here.
 ```bash
 bin/rails phlex_reactive:actions            # every component × action: params, file:line, auth
 bin/rails phlex_reactive:actions FORMAT=json
+bin/rails phlex_reactive:actions UNVERIFIED=1   # only the unverified rows (the review queue)
 bin/rails "phlex_reactive:find[counter]"    # fuzzy-find one; prints each action's method source
 ```
 
 Answers "what reactive actions exist, where are they defined, and is each
-authorized?" without grepping. The `auth` column is a heuristic (`authorized*` =
-an authorization call was detected in the body; `unverified` = none — a helper
-may still authorize indirectly).
+authorized?" without grepping. The `auth` column is a heuristic: `authorized*` =
+an authorization call was detected in the body; `skipped` / `skipped (class)` =
+the author opted out with `skip_verify_authorized` (for that action / for the
+whole class); `unverified` = neither — a helper may still authorize indirectly.
 
 ## 3. Scan the live page (browser inspector)
 

data/lib/phlex/reactive/component/dsl.rb

@@ -213,8 +213,29 @@ module Phlex
           # root's element for content that can't legally hold a <div> — a
           # `reactive_lazy tag: :tr` component rooting at <tr> inside <tbody>
           # ships a <tr> shell, not a <div> the HTML parser would hoist away.
-          def reactive_lazy(tag: :div)
-            Registry.write_scalar(self, :lazy, { tag: tag.to_sym })
+          #
+          # `on:` (issue #276) defers the REQUEST itself, not just server time:
+          #   reactive_lazy on: "panel:opened"        # a DOM event on (or bubbling into) the shell
+          #   reactive_lazy on: :visible              # the shell first scrolls into view
+          #   reactive_lazy on: { visible: "200px" }  # …with an IntersectionObserver rootMargin
+          # The shell then carries the identity token (no TTL) and materializes
+          # once through the action endpoint. See Component::Lazy.
+          #
+          # `cache:` (issue #277) makes the real render a privately cacheable GET:
+          #   reactive_lazy cache: { max_age: 10.minutes }   # combine with on:/tag: freely
+          # The shell carries a stable signed URL instead of a per-render token,
+          # and the endpoint answers `Cache-Control: private, max-age=…`, so the
+          # browser reuses the fragment across page views. Define
+          # `reactive_cache_version` to bust the URL when the content changes,
+          # and `reactive_cache_viewer` (e.g. Current.user&.id) to key the URL
+          # on the viewer instead of `Vary: Cookie` — needed for reuse ACROSS
+          # page views when the session cookie changes on every response
+          # (Rails' cookie store does).
+          def reactive_lazy(tag: :div, on: nil, cache: nil)
+            declaration = { tag: tag.to_sym }
+            declaration[:trigger] = Lazy.normalize_trigger(on) unless on.nil?
+            declaration[:cache] = Lazy.normalize_cache(cache) unless cache.nil?
+            Registry.write_scalar(self, :lazy, declaration)
           end
 
           # The RAW resolved lazy declaration ({ tag: } or nil) — the reader the
@@ -238,6 +259,22 @@ module Phlex
             value.is_a?(::Hash) ? value.fetch(:tag, :div) : :div
           end
 
+          # The normalized `on:` trigger of a lazy component — `{ event: "x" }`
+          # or `{ visible: "<rootMargin>" }` — or nil (plain reactive_lazy, or
+          # not lazy at all). The endpoint's `__materialize` gate reads it.
+          def reactive_lazy_trigger
+            value = reactive_lazy_declaration
+            value[:trigger] if value.is_a?(::Hash)
+          end
+
+          # The normalized `cache:` of a lazy component — `{ max_age: <seconds> }`
+          # — or nil. The fragment endpoint's opt-in gate reads it: only a
+          # component that declared `cache:` is reachable over GET.
+          def reactive_lazy_cache
+            value = reactive_lazy_declaration
+            value[:cache] if value.is_a?(::Hash)
+          end
+
           # Declare a client-invokable action with an optional param schema.
           #   action :increment
           #   action :rename, params: { title: :string }
@@ -258,6 +295,13 @@ module Phlex
           # ({ "0" => ..., "1" => ... }), so a fields_for collection works either way.
           def action(name, params: {})
             require_server_actions!(:action)
+            # Issue #276: the endpoint routes `__materialize` to the lazy render
+            # before the action registry is consulted — a declared one would be
+            # dead code that looks invokable.
+            if name.to_sym == Lazy::MATERIALIZE_ACTION
+              raise ArgumentError, "action #{name.inspect} is reserved for reactive_lazy(on:)"
+            end
+
             # Issue #184: params: :symbol resolves a registered named schema.
             params = Phlex::Reactive.param_schema(params) if params.is_a?(Symbol)
             # If a scope is already declared, reject a schema nested under the scope
@@ -293,6 +337,34 @@ module Phlex
               "use reactive_actions.key?(#{name.inspect})"
           end
 
+          # Dormant root (issue #274): every root of this component renders
+          # data-reactive-dormant="reactive" instead of data-controller=
+          # "reactive", so the client is neither mounted nor (when loaded
+          # lazily) fetched until one of the root's triggers fires — for a root
+          # that only matters after a gesture (a closed dialog, a menu that
+          # loads on open). The app must import "phlex/reactive/early", which
+          # wakes the root. Inherited; `reactive_dormant false` turns it off
+          # again in a subclass, and reactive_root(dormant:) overrides per
+          # render. See Phlex::Reactive::Dormant.
+          #
+          # Not with reactive_lazy(on: :visible): that shell has no trigger to
+          # wake on (refused here, or at render for the other declaration order).
+          # A plain reactive_lazy shell ignores it: it fetches on connect, so it
+          # always mounts. reactive_lazy(on: "event") shells do go dormant.
+          def reactive_dormant(dormant = true) # rubocop:disable Style/OptionalBooleanParameter
+            unless [true, false].include?(dormant)
+              raise ArgumentError, "#{self}: reactive_dormant takes true or false, got #{dormant.inspect}"
+            end
+
+            Phlex::Reactive::Dormant.reject_visible_lazy!(self) if dormant
+
+            Registry.write_scalar(self, :dormant, dormant)
+          end
+
+          def reactive_dormant?
+            Registry.resolve_scalar(self, :dormant, :reactive_dormant?) == true
+          end
+
           # Opt out of the default-ON verify_authorized guard (issue #168).
           # Bare skips the WHOLE component (a public counter, a client-only
           # filter); with names skips just those actions:

data/lib/phlex/reactive/component/helpers.rb

@@ -12,6 +12,7 @@ module Phlex
       # no signing (those live in DSL and Identity).
       module Helpers
         extend ActiveSupport::Concern
+        include Selection
 
         # The acting client's SSE connection id during the current action (nil
         # outside an action, or when the client isn't subscribed to a stream).
@@ -72,8 +73,22 @@ module Phlex
         # Root-element attributes: marks the element reactive and carries the
         # signed identity token. Spread onto the root:
         #   div(id:, **reactive_attrs) { ... }
-        def reactive_attrs
-          data = { controller: "reactive" }
+        #
+        # `dormant: true` (issue #274; default: the class's reactive_dormant)
+        # renders data-reactive-dormant="reactive" IN PLACE of the controller
+        # attribute: nothing mounts until a trigger fires and phlex/reactive/early
+        # wakes the root. The actor's own reply renders awake (Dormant.awake).
+        def reactive_attrs(dormant: nil)
+          dormant = self.class.reactive_dormant? if dormant.nil? && self.class.respond_to?(:reactive_dormant?)
+          data =
+            if dormant && !Phlex::Reactive::Dormant.awake?
+              # The lazy SHELL (not the real render) of an on: :visible component
+              # can never wake — refuse it rather than ship a dead placeholder.
+              Phlex::Reactive::Dormant.reject_visible_lazy!(self.class) unless Phlex::Reactive::Defer.real_render?
+              { reactive_dormant: "reactive" }
+            else
+              { controller: "reactive" }
+            end
           # A CLIENT-ONLY component (Phlex::Reactive::ClientBindings, issue #180)
           # has no Identity, so no token — the root is tokenless (show/filter/
           # compute need no signed round trip). reactive_token is private, so the
@@ -137,7 +152,12 @@ module Phlex
         # fields, and — for warn_unsaved: true — the navigate-away marker (STRING
         # "true", since a boolean-true attr renders valueless → "" → falsy client-
         # side). The removed track_dirty:/warn_unsaved: kwargs raise a guided error.
-        def reactive_root(**overrides)
+        #
+        # `dormant: true` (issue #274) is handed to reactive_attrs: the root mounts
+        # on its first trigger instead of on page load. On a reactive_lazy
+        # component declare `reactive_dormant` on the class instead: the lazy
+        # SHELL is rendered by the framework and reads only the class declaration.
+        def reactive_root(dormant: nil, **overrides)
           # A CLIENT-ONLY component (ClientBindings, issue #180) needs no #id —
           # there's no token to self-match by id. Use an explicit override, else
           # #id when the component defines one, else nothing (no id attr).
@@ -151,7 +171,7 @@ module Phlex
           # Issue #184: dirty tracking is a class-level reactive_dirty declaration.
           dirty = self.class.reactive_dirty_config if self.class.respond_to?(:reactive_dirty_config)
 
-          attrs = mix({ **reactive_attrs }, overrides)
+          attrs = mix({ **reactive_attrs(dormant:) }, overrides)
           attrs = mix(attrs, { id: root_id }) unless root_id.nil?
           # Root-level delegation tracks the whole subtree UNLESS only: scoped it to
           # named fields (those carry their own descriptor via reactive_field).
@@ -225,6 +245,16 @@ module Phlex
           "keydown.esc->reactive#listnavClose"
         ].freeze
 
+        # Roving-focus mode (issue #271): Enter/Space are the focused item's
+        # native activation and Escape is the caller's own on_client binding,
+        # so only the movement keys are bound.
+        LISTNAV_FOCUS_ACTIONS = [
+          "keydown.down->reactive#listnavNext",
+          "keydown.up->reactive#listnavPrev",
+          "keydown.home->reactive#listnavFirst",
+          "keydown.end->reactive#listnavLast"
+        ].freeze
+
         # Event modifiers (issue #80) — window:, once:, outside:, throttle: are
         # RESERVED keyword names on on() (no longer usable as free action params):
         #
@@ -376,6 +406,17 @@ module Phlex
         # Window-bound triggers are never preventDefault-ed by the client and skip
         # the forced type="button".
         #
+        # Issue #271: each call emits ONE self-describing binding record —
+        #   data-reactive-ops-param='{"on":"click","window":true,"outside":true,"ops":[…]}'
+        # carrying its own descriptor, flags and confirm, so several bindings on
+        # one element compose through mix: the data-action descriptors token-join,
+        # the records space-join (every literal space inside a record is written
+        # as \u0020, so the join is unambiguous), and the client runs only the
+        # record whose descriptor matches the firing event:
+        #   div(**mix(reactive_root,
+        #             on_client(:click, js.hide("#menu"), outside: true),
+        #             on_client("keydown.esc", js.hide("#menu"))))
+        #
         # Ops are EPHEMERAL UI: any server re-render of the component (an action
         # reply, a broadcast, a morph) rebuilds from server state and resets
         # whatever they toggled — by design (the LiveView JS-commands caveat). Use
@@ -402,29 +443,21 @@ module Phlex
               "(change/input), or gate it behind a reducer's $ops / reactive_on_complete."
           end
           window_bound = window || outside
+          record = client_binding_record(event, ops, window_bound:, outside:, once:, confirm:)
           attrs = {
             data: {
               action: "#{event}#{"@window" if window_bound}->reactive#runOps#{":once" if once}",
-              reactive_ops_param: ops.to_json
+              # Space-free (issue #271): compact JSON has no structural
+              # whitespace, so every space is inside a string, where \u0020
+              # parses to the same string — and mix's space-join stays splittable.
+              reactive_ops_param: record.to_json.gsub(" ", '\u0020')
             }
           }
-          # STRING "true", not boolean — same Phlex valueless-attribute trap as
-          # on()'s flags above.
-          attrs[:data][:reactive_outside_param] = "true" if outside
-          attrs[:data][:reactive_window_param] = "true" if window_bound
           # Issue #228: mark a clipboard-reading trigger so the client can gate
           # its visibility on availability — on connect the controller sets
           # hidden = !navigator.clipboard.readText. Render the trigger `hidden`
           # for reveal-when-available (a dead paste button never shows).
           attrs[:data][:reactive_clipboard] = "true" if ops.ops.any? { |name, _| name == "paste_into" }
-          # Issue #178: confirm: gates the client-op chain behind the SAME
-          # overridable confirmResolver on(:action, confirm:) uses (#52/#55). Emits
-          # the identical data-reactive-confirm-param; the client's runOps prompts
-          # via confirmResolver BEFORE applying the ops (a falsy resolve cancels
-          # the chain), so a destructive client op gets the themed dialog with no
-          # round trip. Issue #179: a Hash confirm: is CONDITIONAL — same shared
-          # apply_confirm! branches String vs Hash for both on and on_client.
-          apply_confirm!(attrs[:data], confirm) if confirm
           attrs[:type] = "button" if event == "click" && !window_bound
           attrs
         end
@@ -678,13 +711,23 @@ module Phlex
         # Enter picks the highlighted one by clicking its own reactive trigger
         # (selection stays a signed action), Escape clears. Combine with other
         # attrs via mix so a caller's data-action token-joins, not clobbers.
-        def reactive_listnav(option_selector = "[role=option]")
-          {
-            data: {
-              action: LISTNAV_ACTIONS.join(" "),
-              reactive_listnav_option_param: filter_selector!(:selector, option_selector)
-            }
+        #
+        # `focus: true` (issue #271) is ROVING-FOCUS mode for a menu container:
+        # Arrow Down/Up move real focus among the items (wrapping), Home/End jump
+        # to the first/last; no highlight attr is written. The item selector
+        # defaults to [role=menuitem]. Enter/Space stay native activation and
+        # Escape is yours to bind (on_client("keydown.esc", ...) composes via mix):
+        #
+        #   ul(role: "menu", **mix(reactive_listnav(focus: true), data: { testid: "menu" }))
+        def reactive_listnav(option_selector = nil, focus: false)
+          option_selector ||= focus ? "[role=menuitem]" : "[role=option]"
+          data = {
+            action: (focus ? LISTNAV_FOCUS_ACTIONS : LISTNAV_ACTIONS).join(" "),
+            reactive_listnav_option_param: filter_selector!(:selector, option_selector)
           }
+          # STRING "true" — Phlex renders a boolean true as a valueless attribute.
+          data[:reactive_listnav_focus_param] = "true" if focus
+          { data: }
         end
 
         # Tag-chip input (issue #203) — the composed combobox/tags primitive.
@@ -1391,6 +1434,29 @@ module Phlex
         # Shared by on and on_client so both paths speak the same three forms. The
         # predicate is soft-validation UX, NOT authorization — a user can bypass it;
         # the action still hits the endpoint's real authorize/default-deny.
+        # One on_client binding record (issue #271). Flags and confirm live IN
+        # the record — never as element-wide params, which a sibling binding
+        # would inherit. Issue #178: confirm: gates the chain behind the SAME
+        # overridable confirmResolver on(:action, confirm:) uses (#52/#55); the
+        # client prompts BEFORE applying the ops. Issue #179: a Hash confirm: is
+        # CONDITIONAL, compiled by the shared compile_conditional_confirm.
+        def client_binding_record(event, ops, window_bound:, outside:, once:, confirm:)
+          record = { "on" => event }
+          record["window"] = true if window_bound
+          record["outside"] = true if outside
+          # A mix-ed regular sibling keeps calling runOps after Stimulus drops
+          # this binding's :once listener — the client skips a spent once record.
+          record["once"] = true if once
+          case confirm
+          when nil, false then nil
+          when String then record["confirm"] = confirm
+          when Hash then record["confirmWhen"] = compile_conditional_confirm(confirm)
+          else apply_confirm!({}, confirm) # raises the shared guided error
+          end
+          record["ops"] = ops.ops
+          record
+        end
+
         def apply_confirm!(data, confirm)
           case confirm
           when String
@@ -1529,14 +1595,22 @@ module Phlex
         def apply_first_paint_hidden(attrs, groups, values_override)
           return attrs if attrs.key?(:hidden)
 
+          visible = first_paint_match(groups, values_override)
+          visible.nil? ? attrs : attrs.merge(hidden: !visible)
+        end
+
+        # The server-side evaluation of a binding's conditions for first paint
+        # (reactive_show's hidden:, reactive_enable's disabled:): true/false
+        # when reactive_values (merged under values:) covers EVERY referenced
+        # field, else nil — the client seeds it at connect.
+        def first_paint_match(groups, values_override)
           provided = show_values(values_override)
-          return attrs if provided.nil?
+          return nil if provided.nil?
 
           referenced = Phlex::Reactive::ShowConditions.fields(groups)
-          return attrs unless referenced.all? { provided.key?(it) }
+          return nil unless referenced.all? { provided.key?(it) }
 
-          visible = Phlex::Reactive::ShowConditions.match?(groups, provided)
-          attrs.merge(hidden: !visible)
+          Phlex::Reactive::ShowConditions.match?(groups, provided)
         end
 
         # The { field => current-string-value } map the first-paint evaluator
@@ -1552,7 +1626,9 @@ module Phlex
           merged = {}
           merged.merge!(base) if base
           merged.merge!(values_override) if values_override
-          merged.to_h { |name, value| [name.to_s, show_value_string(value)] }
+          # An Array (a checkbox group's checked values, issue #319) stays an
+          # Array so a checked: term can count it.
+          merged.to_h { |name, value| [name.to_s, value.is_a?(Array) ? value.map(&:to_s) : show_value_string(value)] }
         end
 
         # Stringify a reactive_values entry the way the client's #showFieldValue

data/lib/phlex/reactive/component/lazy.rb

@@ -14,9 +14,66 @@ module Phlex
       # the defer endpoint/job, the class stream builders — runs inside
       # Defer.with_real_render, so it renders the REAL template. Anything else
       # would make an action on a lazy component cost two round trips.
+      #
+      # `reactive_lazy(on:)` (issue #276) defers the REQUEST, not just the
+      # server time: the shell carries the identity token (no TTL, unlike the
+      # defer token). An event shell binds a `__materialize` trigger `once` to
+      # its event; a visibility shell has no binding — the client's
+      # IntersectionObserver starts the same `__materialize` request itself.
+      # The action endpoint routes `__materialize` to the same real render the
+      # defer endpoint does. The real render never contains the shell or its
+      # trigger, so `once` cannot re-arm.
       module Lazy
         extend ActiveSupport::Concern
 
+        # The framework-owned act the on: shell dispatches. Reserved: `action`
+        # refuses it, and the endpoint answers it only for reactive_lazy(on:).
+        MATERIALIZE_ACTION = :__materialize
+        # A DOM event name usable in a Stimulus descriptor: no key filter (.),
+        # no target (@), no descriptor syntax (->, #) — `panel:opened` is fine.
+        EVENT_NAME = /\A[A-Za-z][\w:-]*\z/
+        # An IntersectionObserver rootMargin: one to four px/% lengths.
+        # Any CSS whitespace between lengths; normalized to single spaces.
+        ROOT_MARGIN = /\A\s*-?\d+(?:\.\d+)?(?:px|%)(?:\s+-?\d+(?:\.\d+)?(?:px|%)){0,3}\s*\z/
+
+        # `on:` → { event: "x" } | { visible: "<rootMargin>" }, or raise.
+        def self.normalize_trigger(on)
+          case on
+          when String
+            return { event: on } if on.match?(EVENT_NAME)
+          when :visible
+            return { visible: "0px" }
+          when ::Hash
+            margin = on[:visible]
+            if on.keys == [:visible] && margin.is_a?(String) && margin.match?(ROOT_MARGIN)
+              return { visible: margin.split.join(" ") }
+            end
+          end
+          raise ArgumentError,
+            "reactive_lazy on: expects a DOM event name (\"panel:opened\"), :visible, or " \
+            "{ visible: \"200px\" } (a px/% rootMargin) — got #{on.inspect}"
+        end
+
+        # `cache:` → { max_age: <seconds> }, or raise. Only a whole, positive
+        # number of seconds (an Integer or an ActiveSupport::Duration) is a
+        # lifetime; the endpoint caps it at fragment_cache_max_age_limit.
+        def self.normalize_cache(cache)
+          unless cache.is_a?(::Hash) && cache.keys == [:max_age]
+            raise ArgumentError,
+              "reactive_lazy cache: expects { max_age: <seconds> } (e.g. { max_age: 10.minutes }) — got #{cache.inspect}"
+          end
+
+          max_age = cache[:max_age]
+          # Duration#to_i truncates (1.5.seconds → 1): only an exact one converts.
+          seconds = max_age.is_a?(ActiveSupport::Duration) && max_age.to_i == max_age ? max_age.to_i : max_age
+          unless seconds.is_a?(::Integer) && seconds.positive?
+            raise ArgumentError,
+              "reactive_lazy cache: max_age must be a positive whole number of seconds — got #{max_age.inspect}"
+          end
+
+          { max_age: seconds }
+        end
+
         private
 
         # Phlex 2's render hook: the template runs inside the block. Overridden
@@ -26,18 +83,92 @@ module Phlex
         def around_template(&)
           klass = self.class
           if klass.respond_to?(:reactive_lazy?) && klass.reactive_lazy? && !Phlex::Reactive::Defer.real_render?
-            render_defer_shell
+            (trigger = klass.reactive_lazy_trigger) ? render_trigger_shell(trigger) : render_defer_shell
           else
             super
           end
         end
 
+        # The on: shell (issue #276): the same placeholder contract as the
+        # defer shell (id, class, aria-busy, deferred_placeholder), but mounted
+        # like a reactive root — reactive_attrs' identity token. No defer token
+        # and no pending marker: the client's lazy probe gates on the token, so
+        # it skips this shell, and nothing is in flight until the trigger fires.
+        #
+        # The marker tells the client which shell this is, on connect AND after
+        # a Turbo morph re-shows it on a connected root (no Stimulus lifecycle):
+        #   * data-reactive-lazy-on="<event>" — plus the once-bound Stimulus
+        #     descriptor for `__materialize`, so the first event takes the
+        #     ordinary action path. The client re-arms the event itself after a
+        #     morph, because a spent `once` binding never fires again.
+        #   * data-reactive-lazy-visible="<rootMargin>" — no descriptor at all;
+        #     the client's IntersectionObserver materializes directly.
+        #
+        # A `cache:` component (issue #277) adds its fragment URL: the client
+        # then loads with a cacheable GET instead of the __materialize POST.
+        # Such a shell carries NO identity token (issue #306): every load, and
+        # the fallback for a URL the client refuses (a GET under the fragment
+        # path it knows), goes through the URL — a second signature of the same
+        # identity would only make the shell heavier than what it defers.
+        def render_trigger_shell(trigger)
+          src = fragment_src
+          root = reactive_attrs
+          root[:data].delete(:reactive_token_value) if src
+          attrs = mix(
+            { id:, class: "reactive-defer-placeholder", aria: { busy: "true" } },
+            root,
+            { data: trigger_shell_data(trigger) }
+          )
+          # Mixed in only when present: a non-cached shell allocates nothing extra.
+          attrs = mix(attrs, { data: { reactive_defer_src: src } }) if src
+          public_send(self.class.reactive_lazy_tag, **attrs) { render_deferred_placeholder_content }
+        end
+
+        # The cacheable fragment URL (issue #277) for a `cache:` component, else
+        # nil (Phlex omits a nil attribute, so a non-cached shell is unchanged).
+        # Deterministic: the same identity (+ version) renders the same URL on
+        # every page view, which is what lets the browser's HTTP cache hit.
+        def fragment_src
+          return unless self.class.reactive_lazy_cache
+
+          version = respond_to?(:reactive_cache_version, true) ? send(:reactive_cache_version) : nil
+          Phlex::Reactive::Fragment.src(reactive_identity_payload, version:, viewer: fragment_viewer_param)
+        end
+
+        # The `u` of the fragment URL: the keyed digest of reactive_cache_viewer
+        # when the component declares who its render is for AND that value names
+        # someone, else nil (the default, `Vary: Cookie` mode). The shell renders
+        # it; the endpoint recomputes it in the requesting session and compares
+        # (see FragmentsController).
+        def fragment_viewer_param
+          return unless respond_to?(:reactive_cache_viewer, true)
+
+          Phlex::Reactive::Fragment.viewer_param(send(:reactive_cache_viewer), owner: self.class)
+        end
+
+        def trigger_shell_data(trigger)
+          return { reactive_lazy_visible: trigger[:visible] } if trigger[:visible]
+
+          event = trigger[:event]
+          {
+            action: "#{event}->reactive#dispatch:once",
+            reactive_action_param: MATERIALIZE_ACTION.to_s,
+            reactive_params_param: Helpers::EMPTY_PARAMS_JSON,
+            reactive_lazy_on: event
+          }
+        end
+
         # The shell: owns the component's id (the arrival replaces it by that
         # id), mounts the generic controller, and carries the defer token as a
         # ROOT attribute — the controller's connect() probes it and enters the
         # same module-level fetch path a reply directive uses. Pending markers
         # + the .reactive-defer-placeholder class are the CSS hooks.
+        #
+        # A `cache:` component (issue #277) carries its stable fragment URL in
+        # data-reactive-defer-src INSTEAD of the token: the client GETs it, and
+        # the browser's private cache can answer.
         def render_defer_shell
+          src = fragment_src
           public_send(
             self.class.reactive_lazy_tag,
             id:,
@@ -46,6 +177,10 @@ module Phlex
             data: {
               controller: "reactive",
               reactive_defer_pending: "true",
+              # The same verbose stamp reactive_attrs writes (nil is omitted):
+              # the shell may be the page's only reactive root when its mount
+              # fetch runs, and the client's verbose gate reads it (issue #279).
+              reactive_verbose: (Phlex::Reactive.verbose_errors ? "true" : nil),
               # UNBOUND (issue #165 security): a lazy shell renders during the
               # page render — on a fresh visit the session doesn't exist yet, so
               # the token can't be actor-bound (it would 400 at the endpoint,
@@ -53,7 +188,8 @@ module Phlex
               # small leak surface); the TTL + `authorize!` are its bound. Only
               # reply.defer tokens (in action responses that can transit proxies)
               # are actor-bound.
-              reactive_defer_token: Phlex::Reactive.sign_defer(reactive_identity_payload, unbound: true)
+              reactive_defer_token: (Phlex::Reactive.sign_defer(reactive_identity_payload, unbound: true) unless src),
+              reactive_defer_src: src
             }
           ) { render_deferred_placeholder_content }
         end

data/lib/phlex/reactive/component/registry.rb

@@ -59,6 +59,8 @@ module Phlex
           dirty: :@reactive_own_dirty,
           # Deferred reply segments — reactive_lazy (issue #165).
           lazy: :@reactive_own_lazy,
+          # Mount on first use — reactive_dormant (issue #274).
+          dormant: :@reactive_own_dormant,
           # Enter/exit/update effects — reactive_effects (issue #215).
           effects: :@reactive_own_effects,
           # verify_authorized opt-out (issue #168): a scalar bare flag (skip the

data/lib/phlex/reactive/component/selection.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module Component
+      # Bulk-selection bindings (issue #319): a list with a row checkbox per
+      # item, a "select all" header, a "Delete (n)" count, and actions that stay
+      # disabled until something is ticked — with no per-list JavaScript.
+      #
+      #   form(id: "bulk", action: "/posts/bulk", method: "post") do
+      #     input(type: "checkbox", **reactive_select_all("ids[]"))   # header
+      #     @posts.each { input(type: "checkbox", name: "ids[]", value: it.id) }
+      #     span(**reactive_count("ids[]")) { "0" }                    # ticked count
+      #     button(**reactive_enable(if: { "ids[]" => { checked: 1.. } })) { "Delete" }
+      #   end
+      #
+      # The group is a checkbox NAME, resolved like any reactive_show field
+      # (owned boxes only — a nested reactive root's boxes are its own, #15;
+      # a bare name takes reactive_scope, a bracketed one like "ids[]" is used
+      # verbatim). The client re-syncs the header, the count and every
+      # binding when a box changes and when boxes are added or removed (a
+      # stream append, a morph, a removal). All client-only: no token, no
+      # round trip.
+      module Selection
+        # The sibling of reactive_show: the same if:/if_any:/unless: conditions
+        # (including the { checked: n } count term), but it flips the
+        # element's OWN `disabled` — a button, a fieldset — instead of
+        # `hidden`. First paint is computed from reactive_values exactly like
+        # reactive_show's `hidden:` (an explicit `disabled:` wins; `values:`
+        # merges over reactive_values).
+        def reactive_enable(**options)
+          conditions = options.slice(*Helpers::SHOW_CONDITION_KEYS)
+          values_override = options.delete(:values)
+          attrs = options.except(*Helpers::SHOW_CONDITION_KEYS)
+
+          groups = Phlex::Reactive::ShowConditions.normalize(**conditions)
+          result = mix({ data: { reactive_enable: { "any" => groups }.to_json } }, attrs)
+          return result if result.key?(:disabled)
+
+          match = first_paint_match(groups, values_override)
+          match.nil? ? result : result.merge(disabled: !match)
+        end
+
+        # The header box of a checkbox group. Its `change` ticks or unticks
+        # every owned box of the group (dispatching `input` + `change` on each one it
+        # flips, so computes, shows and counts re-run); its own checked /
+        # indeterminate state follows the group. Give the header NO `name` —
+        # it would post, and count as a member.
+        def reactive_select_all(group, **attrs)
+          mix({ data: { reactive_select_all: selection_group!(:reactive_select_all, group) } }, attrs)
+        end
+
+        # A text binding that shows how many owned boxes of the group are
+        # ticked (written via textContent, change-guarded). Seed the first
+        # paint in the element's own content: span(**reactive_count("ids[]")) { "0" }.
+        def reactive_count(group, **attrs)
+          mix({ data: { reactive_count: selection_group!(:reactive_count, group) } }, attrs)
+        end
+
+        private
+
+        def selection_group!(helper, group)
+          name = group.to_s
+          return name unless name.strip.empty?
+
+          raise ArgumentError, "#{helper} needs a checkbox group name (e.g. \"ids[]\"), got #{group.inspect}"
+        end
+      end
+    end
+  end
+end