phlex-reactive 0.13.4 → 0.14.0

data/lib/phlex/reactive/doctor.rb

@@ -16,6 +16,8 @@ module Phlex
     # default-deny boundary; the worst it does is a throwaway sign→verify round
     # trip and (for the component checks) iterate the loaded Streamable registry.
     class Doctor
+      include FiberIsolation
+
       # The result of one check: a status (:ok/:fail/:unknown), a human message,
       # and (on anything but :ok) a fix line telling the adopter what to do. A
       # plain value object (not Data) so it takes positional status/message plus
@@ -70,14 +72,19 @@ module Phlex
         [
           route_check,
           defer_route_check,
+          fragment_route_check,
+          fragment_path_meta_check,
           stimulus_check,
           csrf_check,
           verifier_check,
           base_controller_check,
+          fiber_isolation_check,
           action_check(components),
           id_check(components),
-          authorization_check(components)
-        ]
+          authorization_check(components),
+          dormant_check(components),
+          *early_pin_check(components)
+        ].compact
       end
 
       # --- individual checks ------------------------------------------------
@@ -97,6 +104,45 @@ module Phlex
         path_check(Phlex::Reactive.defer_path, :defer_route, "Phlex::Reactive.defer_path")
       end
 
+      # The cacheable-fragment GET endpoint (issue #277): a host GET catch-all
+      # that shadows it makes every `reactive_lazy cache:` fetch load the host's
+      # fallback page instead of the fragment.
+      def fragment_route_check
+        path = "#{Phlex::Reactive.fragment_path}/:id"
+        if Phlex::Reactive.fragment_route_ok?
+          Check.new(:ok, "GET #{path} routes to phlex/reactive/fragments", name: :fragment_route)
+        else
+          Check.new(:fail, "GET #{path} does not resolve to phlex/reactive/fragments", name: :fragment_route,
+            fix: "A host catch-all route (get \"*path\", ...) likely shadows it. Exempt " \
+                 "#{Phlex::Reactive.fragment_path.delete_prefix("/")} from the catch-all, or set " \
+                 "Phlex::Reactive.fragment_path to an unshadowed path.")
+        end
+      end
+
+      # A custom fragment_path the client was never told about (issue #277): the
+      # client only fetches a fragment URL under the path it knows — the meta
+      # tag, else the default — so every `reactive_lazy cache:` shell would be
+      # refused (reactive:error, the shell never loads). Only checked when the
+      # path was changed; nil (no check) otherwise.
+      def fragment_path_meta_check
+        path = Phlex::Reactive.fragment_path
+        return if path == "/reactive/fragment"
+
+        # A file must name the meta AND supply this path — literally, or from
+        # the setting (`Phlex::Reactive.fragment_path`). A tag left behind with
+        # an old path is as broken as none. Whether it sits in <head> (the only
+        # place the client reads it) can't be told from source; the fix says so.
+        if layout_references?("phlex-reactive-fragment-path") { it.include?(path) || it.include?("fragment_path") }
+          Check.new(:ok, "phlex-reactive-fragment-path meta found for #{path} (it must be in <head>)",
+            name: :fragment_path_meta)
+        else
+          Check.new(:fail, "Phlex::Reactive.fragment_path is #{path} but no layout renders its meta tag with that path",
+            name: :fragment_path_meta,
+            fix: "Add <meta name=\"phlex-reactive-fragment-path\" content=\"#{path}\"> to your layout's " \
+                 "<head> — the client refuses a fragment URL outside the path it knows.")
+        end
+      end
+
       # Shared body for the two endpoint-route checks: both POST to the gem's
       # ActionsController, so action_route_ok? answers for either path.
       def path_check(path, name, setting)
@@ -212,6 +258,42 @@ module Phlex
                "`skip_verify_authorized`. See the Debugging & tooling docs page.")
       end
 
+      # Dormant roots (issue #274): how many components declare `reactive_dormant`
+      # and whether a Stimulus entrypoint imports phlex/reactive/early — the
+      # module that wakes them (without it a dormant root never mounts). No line
+      # at all when nothing is dormant. ADVISORY when the import isn't found: it
+      # may live in a file the doctor doesn't scan. A per-render
+      # reactive_root(dormant: true) is invisible here (it isn't a declaration).
+      def dormant_check(components, early: imports_early?)
+        dormant = dormant_components(components)
+        return if dormant.empty?
+
+        label = "#{dormant.size} dormant #{dormant.one? ? "component" : "components"} (#{dormant.map(&:name).join(", ")})"
+        return Check.new(:ok, "#{label}; phlex/reactive/early is imported#{early_location(early)}", name: :dormant) if early
+
+        Check.new(:unknown, "#{label}, but no import of phlex/reactive/early was found", name: :dormant,
+          fix: "A dormant root is woken by that module — without it the root never mounts. Add to " \
+               "your entrypoint, before any controller loads:\n  import \"phlex/reactive/early\"")
+      end
+
+      # Every import map the app registers must pin phlex/reactive/early when a
+      # dormant root exists (issue #307): a map without the pin cannot resolve
+      # the specifier, so the import fails on the pages that map serves. One
+      # advisory check per map lacking the pin; none when every map has it.
+      # Maps: Rails.application.importmap, or Phlex::Reactive.importmaps (a
+      # callable returning { name => Importmap::Map }) for an app with its own.
+      def early_pin_check(components)
+        return [] if dormant_components(components).empty?
+
+        import_maps.filter_map do |name, map|
+          next if map_pins_early?(map)
+
+          Check.new(:unknown, "import map \"#{name}\" does not pin phlex/reactive/early", name: :early_pin,
+            fix: "A dormant root rendered on a page served by this map cannot load the module. Add to " \
+                 "the map's file:\n  pin \"phlex/reactive/early\", to: \"phlex/reactive/early.min.js\", preload: true")
+        end
+      end
+
       # --- rendering --------------------------------------------------------
 
       # The full plain-text report: a line per check, plus an indented fix under
@@ -236,6 +318,27 @@ module Phlex
         "phlex/reactive/actions"
       end
 
+      STIMULUS_ENTRYPOINTS = %w[
+        app/javascript/controllers/index.js
+        app/javascript/controllers/application.js
+        app/javascript/application.js
+      ].freeze
+      EARLY_IMPORT = %r{import\s+["']phlex/reactive/early["']}
+      # Closed comments, which may span lines: HTML, JS block and ERB.
+      BLOCK_COMMENT = %r{<!--.*?-->|/\*.*?\*/|<%#.*?%>}m
+      # What precedes the import on its line when it is commented out: a //
+      # (not the one in a URL), an unclosed /*, or a block-comment's leading *.
+      COMMENT_BEFORE = %r{(?<!:)//|/\*|\A\s*\*}
+
+      # Is there an `import "phlex/reactive/early"` in `source` that actually
+      # runs? Closed comments are dropped first, then each line is read, so a
+      # commented-out import doesn't count.
+      def self.imports_early_source?(source)
+        source.gsub(BLOCK_COMMENT, "").each_line.any? do
+          (match = EARLY_IMPORT.match(it)) && !match.pre_match.match?(COMMENT_BEFORE)
+        end
+      end
+
       private
 
       # A one-line tally: how many passed, failed, and are advisory/unknown.
@@ -340,11 +443,7 @@ module Phlex
       # small/importmap app often registers inline in <head> rather than in a
       # dedicated entrypoint file. Only existing files are returned.
       def stimulus_registration_files
-        candidates = %w[
-          app/javascript/controllers/index.js
-          app/javascript/controllers/application.js
-          app/javascript/application.js
-        ].map { app_path(it) }
+        candidates = STIMULUS_ENTRYPOINTS.map { app_path(it) }
         candidates += ::Dir.glob(app_path("app/views/layouts/**/*.erb"))
         candidates.select { File.exist?(it) }
       end
@@ -355,6 +454,58 @@ module Phlex
         false
       end
 
+      # The relative path of the first file that imports phlex/reactive/early,
+      # or false. The Stimulus registration files go first, then every other app
+      # JavaScript entry (vendor excluded) and inline module scripts in views and
+      # components (issue #307).
+      def imports_early?
+        (stimulus_registration_files | early_import_candidates).each do
+          return relative(it) if Doctor.imports_early_source?(early_source(it))
+        rescue StandardError
+          next
+        end
+        false
+      end
+
+      # A Ruby file's `# …` comment lines are not code (a layout that mentions
+      # the import in a comment must not pass the check).
+      def early_source(path)
+        source = File.read(path)
+        path.end_with?(".rb") ? source.lines.grep_v(/\A\s*#/).join : source
+      end
+
+      def early_import_candidates
+        globs = %w[app/javascript/**/*.js app/views/**/*.{rb,erb} app/components/**/*.{rb,erb}].map { app_path(it) }
+        ::Dir.glob(globs).reject { it.include?("/vendor/") }.sort
+      end
+
+      # " (path)" when the import sits outside the JavaScript entrypoints the
+      # doctor always scanned (those keep their original output).
+      def early_location(early)
+        return "" unless early.is_a?(String)
+        return "" if STIMULUS_ENTRYPOINTS.include?(early)
+
+        " (#{early})"
+      end
+
+      def dormant_components(components)
+        components.select { it.respond_to?(:reactive_dormant?) && it.reactive_dormant? }
+      end
+
+      def import_maps
+        default = ::Rails.application.respond_to?(:importmap) ? ::Rails.application.importmap : nil
+        maps = default ? { "application" => default } : {}
+        maps.merge(Phlex::Reactive.importmaps&.call || {})
+      rescue StandardError
+        maps || {}
+      end
+
+      def map_pins_early?(map)
+        map.packages.key?("phlex/reactive/early")
+      rescue StandardError
+        true
+      end
+
       # Only meaningful when importmap is in use. True when importmap is present
       # but the reactive_controller pin is absent (the engine pins it, so this is
       # really "someone overrode importmap.rb and dropped the pin").
@@ -371,6 +522,12 @@ module Phlex
 
       # Grep ERB layouts AND Phlex layout files for a csrf_meta_tags reference.
       def csrf_meta_referenced?
+        layout_references?("csrf_meta_tags")
+      end
+
+      # Does any ERB view / Phlex view or component mention `needle` (and, with
+      # a block, satisfy it for that file's source)?
+      def layout_references?(needle)
         globs = %w[
           app/views/**/*.erb
           app/views/**/*.rb
@@ -379,7 +536,8 @@ module Phlex
         ].map { app_path(it) }
 
         ::Dir.glob(globs).any? do
-          File.read(it).include?("csrf_meta_tags")
+          source = File.read(it)
+          source.include?(needle) && (!block_given? || yield(source))
         rescue StandardError
           false
         end

data/lib/phlex/reactive/dormant.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # Dormant roots (issue #274). A root declared dormant — `reactive_dormant`
+    # on the class, or `reactive_root(dormant: true)` — renders
+    # data-reactive-dormant="reactive" INSTEAD of data-controller="reactive":
+    # the reactive controller is not mounted (and, when the app loads it lazily,
+    # not even fetched) until one of the root's triggers fires. The client's
+    # phlex/reactive/early module then moves the identifier into data-controller
+    # and the trigger is replayed on connect.
+    #
+    # A render made for the ACTOR's own reply is AWAKE: the reply only exists
+    # because that page's controller is loaded and connected, so a dormant
+    # replacement would save nothing and cost one more wake. The endpoint runs
+    # the action and its reply (and the defer render) inside Dormant.awake;
+    # every other render — the page, a stream built outside a reactive request,
+    # and a BROADCAST even when fired inside an action (Dormant.asleep) — stays
+    # dormant, because its receivers may never have loaded the client.
+    module Dormant
+      AWAKE_KEY = :phlex_reactive_dormant_awake
+
+      class << self
+        def awake?
+          Thread.current[AWAKE_KEY] ? true : false
+        end
+
+        # Render dormant roots awake inside the block (fiber-local, restored on
+        # exit — a raise included).
+        def awake
+          previous = Thread.current[AWAKE_KEY]
+          Thread.current[AWAKE_KEY] = true
+          yield
+        ensure
+          Thread.current[AWAKE_KEY] = previous
+        end
+
+        # A reactive_lazy(on: :visible) shell (issue #276) has no trigger
+        # descriptor — the CONTROLLER's IntersectionObserver materializes it —
+        # so a dormant one could never wake. Refused where it is declared, and
+        # (for the other declaration order) where the shell renders.
+        def reject_visible_lazy!(klass)
+          return unless klass.respond_to?(:reactive_lazy_trigger) && klass.reactive_lazy_trigger&.key?(:visible)
+
+          raise ArgumentError,
+            "#{klass}: reactive_dormant cannot be combined with reactive_lazy(on: :visible) — a dormant " \
+            "root wakes on a trigger event, and a visibility shell has none (the controller's " \
+            "IntersectionObserver loads it). Use reactive_lazy(on: \"an:event\"), or drop reactive_dormant."
+        end
+
+        # The inverse, for a render fired INSIDE an awake block that leaves the
+        # actor's page — a broadcast. A plain yield when nothing is awake.
+        def asleep
+          return yield unless Thread.current[AWAKE_KEY]
+
+          begin
+            Thread.current[AWAKE_KEY] = nil
+            yield
+          ensure
+            Thread.current[AWAKE_KEY] = true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/engine.rb

@@ -11,20 +11,39 @@ module Phlex
     class Engine < ::Rails::Engine
       isolate_namespace Phlex::Reactive
 
+      # The client's feature modules (issue #275), each its own file at the
+      # bare specifier phlex/reactive/features/<name>. The DEFAULT client
+      # (phlex/reactive/reactive_controller) is one file with all of them
+      # bundled in and never fetches these. The opt-in phlex/reactive/core
+      # imports one only when a root on the page uses it. Listed here once; the
+      # precompile list and the importmap pins below are built from it. The
+      # build script (scripts/build_client.js), the core's own table and the
+      # default entry name the same features —
+      # spec/phlex/engine_client_pin_spec.rb fails when they disagree.
+      CLIENT_FEATURES = %w[persist defer form bindings compute effects hints devtools].freeze
+      # (Gzipped, bun zlib level 9: the default file 26.1 KB; the core 12.4 KB;
+      # persist 3.2, defer 2.8, form 1.0, bindings 5.4, compute 2.1, effects
+      # 1.7, hints 1.0, devtools 1.6 KB. spec/javascript/bundle_budget.test.js
+      # is the source of truth and holds a ratchet on each.)
+
       # Mount POST /reactive/actions -> Phlex::Reactive::ActionsController#create
       # and POST /reactive/defer -> #deferred (the pull-lane defer endpoint,
-      # issue #165). Apps can change the paths with Phlex::Reactive.action_path /
-      # .defer_path before boot.
+      # issue #165), and GET /reactive/fragment/:id -> FragmentsController#show
+      # (the privately cacheable lazy render, issue #277). Apps can change the
+      # paths with Phlex::Reactive.action_path / .defer_path / .fragment_path
+      # before boot.
       initializer "phlex_reactive.routes" do
         it.routes.append do
           post Phlex::Reactive.action_path, to: "phlex/reactive/actions#create", as: :phlex_reactive_action
           post Phlex::Reactive.defer_path, to: "phlex/reactive/actions#deferred", as: :phlex_reactive_defer
+          get "#{Phlex::Reactive.fragment_path}/:id", to: "phlex/reactive/fragments#show",
+            as: :phlex_reactive_fragment
         end
       end
 
       # Make the MINIFIED client build available to Propshaft/Sprockets so it can
       # be fingerprinted, served, and pinned in importmap. The browser ships the
-      # minified twin (108 KB -> 22 KB for the controller; `rake build:js`), not
+      # minified twin (about a fifth of the source; `rake build:js`), not
       # the comment-dense source. The .min.js.map is precompiled too so devtools
       # resolves the linked sourcemap back to the readable source on demand.
       initializer "phlex_reactive.assets" do
@@ -37,6 +56,10 @@ module Phlex
           it.config.assets.precompile += %w[
             phlex/reactive/reactive_controller.min.js
             phlex/reactive/reactive_controller.min.js.map
+            phlex/reactive/core.min.js
+            phlex/reactive/core.min.js.map
+            phlex/reactive/early.min.js
+            phlex/reactive/early.min.js.map
             phlex/reactive/confirm.min.js
             phlex/reactive/confirm.min.js.map
             phlex/reactive/confirm_predicate.min.js
@@ -47,6 +70,9 @@ module Phlex
             phlex/reactive/inspect.min.js.map
             phlex/reactive/effects.css
           ]
+          it.config.assets.precompile += CLIENT_FEATURES.flat_map do
+            ["phlex/reactive/features/#{it}.min.js", "phlex/reactive/features/#{it}.min.js.map"]
+          end
         end
       end
 
@@ -55,11 +81,32 @@ module Phlex
       # asset pipeline instead (see README).
       initializer "phlex_reactive.importmap", after: "importmap" do
         if defined?(::Importmap::Map) && it.respond_to?(:importmap)
+          # The DEFAULT client: one file, the core and every feature bundled.
           it.importmap.pin(
             "phlex/reactive/reactive_controller",
             to: "phlex/reactive/reactive_controller.min.js",
             preload: true
           )
+          # The OPT-IN client (issue #275): the controller without its
+          # features, which it imports on demand (the feature pins below). An
+          # app imports this INSTEAD of reactive_controller, never both. Not
+          # preloaded: an app that does not opt in must not fetch it. One that
+          # does re-pins it with preload: true, like any entry it imports
+          # eagerly.
+          it.importmap.pin(
+            "phlex/reactive/core",
+            to: "phlex/reactive/core.min.js",
+            preload: false
+          )
+          # The early-trigger capture (issue #273): a ~1 KB module the app
+          # imports EAGERLY (`import "phlex/reactive/early"`) so a trigger that
+          # fires before a lazily loaded controller connects is replayed on
+          # connect instead of lost. Preloaded: it must run before the triggers.
+          it.importmap.pin(
+            "phlex/reactive/early",
+            to: "phlex/reactive/early.min.js",
+            preload: true
+          )
           # The overridable confirm resolver (issue #55). reactive_controller.js
           # imports it by this BARE specifier — `import { confirmResolver } from
           # "phlex/reactive/confirm"` — NOT a relative "./confirm.js" (issue #57:
@@ -102,6 +149,19 @@ module Phlex
             to: "phlex/reactive/inspect.min.js",
             preload: false
           )
+          # Feature modules (issue #275), for the opt-in phlex/reactive/core.
+          # NOT preloaded: the core imports one only when a root on the page
+          # uses it, so a page without such a root never fetches it — and the
+          # default client never does. An app on the core that knows it needs
+          # one on every page re-pins it with preload: true.
+          importmap = it.importmap
+          CLIENT_FEATURES.each do
+            importmap.pin(
+              "phlex/reactive/features/#{it}",
+              to: "phlex/reactive/features/#{it}.min.js",
+              preload: false
+            )
+          end
         end
       end
 

data/lib/phlex/reactive/fragment.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+require "base64"
+require "digest"
+require "json"
+
+module Phlex
+  module Reactive
+    # Privately cacheable lazy renders (issue #277): the signed id and URL of a
+    # `reactive_lazy cache: { max_age: }` component's GET fragment.
+    #
+    # The id is a DETERMINISTIC signature over the component's identity payload
+    # — no expiry, no actor binding, purpose-scoped — so the same component
+    # renders the same URL on every page view and the browser's private HTTP
+    # cache can reuse the response. It names NO viewer: who the render is for
+    # always comes from the session at the endpoint. (Like the identity token it
+    # does carry the signed state / record gid — signed, not encrypted.) The
+    # purpose makes it disjoint
+    # from the identity and defer tokens: a fragment id can't run an action or
+    # reach the defer endpoint, and neither of those tokens resolves here.
+    #
+    # Two unsigned query parameters only shape the browser's cache KEY — the
+    # render never reads them:
+    #   v — a digest of the component's reactive_cache_version (content changed)
+    #   u — a KEYED digest of its reactive_cache_viewer (who the render is
+    #       for). The endpoint recomputes it in the CURRENT session and makes
+    #       the reply cacheable only when it matches, so a URL can only ever
+    #       hold the render of the viewer it names. A blank viewer names nobody:
+    #       no `u`, and the reply falls back to `Vary: Cookie`.
+    module Fragment
+      # The purpose of the previous id format (still verified, see verify).
+      PURPOSE = "phlex-reactive/fragment"
+      # The purpose the current id's MAC is keyed under (issue #306).
+      ID_PURPOSE = "phlex-reactive/fragment-id"
+      # 128 bits of MAC: 22 base64url characters.
+      MAC_BYTES = 16
+      MAC_LENGTH = 22
+      BASE64URL = /\A[A-Za-z0-9_-]+\z/
+      VIEWER_PURPOSE = "phlex-reactive/fragment-viewer"
+      # A viewer is an identity — an id, or a few of them. These bound how far
+      # a collection is walked, so no value can make the shell render slow.
+      VIEWER_PART_LIMIT = 32
+      VIEWER_NODE_LIMIT = 64
+      # Components already warned about (by class name): once per component.
+      VIEWER_WARNED = Concurrent::Map.new
+
+      # A reactive_cache_viewer value that cannot name a viewer. Internal: it
+      # carries the reason from the walk to viewer_param, which logs it.
+      class UnusableViewer < StandardError; end
+
+      module_function
+
+      # The signed id of an identity payload (issue #306):
+      #
+      #   base64url(JSON payload) + base64url(128-bit MAC)
+      #
+      # The payload is encoded ONCE and the MAC is a fixed 22 characters, so the
+      # id is one URL path segment of base64url characters with no separator
+      # (a "." would read as a format suffix to the router). The MAC is keyed
+      # through the configured verifier — a digest of its signature over the
+      # encoded payload under its own purpose, the same construction as the
+      # viewer digest — so it works with any verifier the app configured and
+      # cannot be computed without the app's secret. Deterministic: the same
+      # identity always renders the same URL, which is what lets the browser's
+      # cache hit.
+      def sign(payload)
+        data = Base64.urlsafe_encode64(JSON.generate(payload.merge("v" => TOKEN_VERSION)), padding: false)
+        "#{data}#{compact_mac(data)}"
+      end
+
+      # The verified, version-upgraded payload, or nil — tampered, a token of
+      # another purpose, or no fragment id at all. The current format is tried
+      # first, then the previous one: a browser may still hold a page or a
+      # cached fragment URL minted before #306 (for up to
+      # fragment_cache_max_age_limit).
+      def verify(id)
+        id = id.to_s
+        payload = verify_compact(id) || verify_legacy(id)
+        payload && Phlex::Reactive.upgrade_token(payload)
+      end
+
+      # The MAC is checked BEFORE the data is decoded or parsed. Anything but
+      # base64url characters is not an id (and never reaches the verifier).
+      def verify_compact(id)
+        return nil unless id.length > MAC_LENGTH && id.match?(BASE64URL)
+
+        data = id[0...-MAC_LENGTH]
+        return nil unless ActiveSupport::SecurityUtils.secure_compare(compact_mac(data), id[-MAC_LENGTH..])
+
+        payload = JSON.parse(Base64.urlsafe_decode64(data))
+        payload.is_a?(::Hash) ? payload : nil
+      rescue ::ArgumentError, JSON::ParserError
+        nil
+      end
+
+      # The previous format: the verifier's token (Base64 + "--" + digest)
+      # wrapped in urlsafe Base64. Kept for one release (issue #306).
+      def verify_legacy(id)
+        Phlex::Reactive.verifier.verified(Base64.urlsafe_decode64(id), purpose: PURPOSE)
+      rescue ::ArgumentError
+        nil
+      end
+
+      # `data` is pinned to US-ASCII (it is base64url): the id is minted as a
+      # US-ASCII String but arrives as a UTF-8 param, and a Marshal-serializing
+      # verifier (load_defaults < 7.1) signs the encoding along with the bytes.
+      def compact_mac(data)
+        data = data.dup.force_encoding(Encoding::US_ASCII)
+        digest_param(Digest::SHA256.digest(Phlex::Reactive.verifier.generate(data, purpose: ID_PURPOSE)), MAC_BYTES)
+      end
+
+      # The fragment URL the shell renders into data-reactive-defer-src:
+      # <fragment_path>/<signed id>[?v=<version digest>][&u=<viewer digest>].
+      # `version` is the component's reactive_cache_version (nil → no `v`);
+      # `viewer` is its ALREADY-DIGESTED viewer_param (nil → no `u`).
+      def src(payload, version: nil, viewer: nil)
+        query = []
+        query << "v=#{version_param(version)}" unless version.nil?
+        query << "u=#{viewer}" if viewer
+        path = "#{Phlex::Reactive.fragment_path}/#{sign(payload)}"
+        query.empty? ? path : "#{path}?#{query.join("&")}"
+      end
+
+      # `v` only varies the browser's cache KEY — the endpoint never reads it —
+      # so it is digested: short, opaque, and safe for any value an app returns
+      # (a Time keeps its sub-second precision, a record its cache key). 64
+      # bits as 11 base64url characters: a cache-buster, not a secret.
+      def version_param(version)
+        key = version.respond_to?(:utc) ? version.utc.strftime("%Y%m%d%H%M%S%N") : version
+        digest_param(Digest::SHA256.digest(ActiveSupport::Cache.expand_cache_key(key)), 8)
+      end
+
+      def digest_param(digest, bytes)
+        Base64.urlsafe_encode64(digest.byteslice(0, bytes), padding: false)
+      end
+
+      # The `u` of a reactive_cache_viewer value, or nil when the value names
+      # NO viewer — nil, false, a blank String, or an Array with any blank part
+      # or Hash with any blank leaf (`[Current.user&.id, locale]` signed out),
+      # or a value whose cache key is empty. A blank viewer must never
+      # become a shared "anonymous" key: every signed-out or mis-resolved
+      # session would then store and read ONE url with no Vary. nil sends the
+      # component back to the default mode (`Vary: Cookie`) for that render.
+      #
+      # KEYED: the digest is taken over the verifier's signature of the value,
+      # so it can be neither reversed to the value (a user id is a small space)
+      # nor computed for someone else without the app's secret. 128 bits, as
+      # 22 base64url characters.
+      #
+      # NEVER RAISES and never takes long, whatever the hook returned: this runs
+      # inside the host page's render. A value that cannot be turned into a key
+      # (it raises, it is endless, it is huge) names nobody — the fail-closed
+      # default mode — and is logged once per component (`owner`, its class).
+      def viewer_param(viewer, owner: nil)
+        return nil unless viewer_named?(viewer)
+
+        signed = Phlex::Reactive.verifier.generate(ActiveSupport::Cache.expand_cache_key(viewer),
+          purpose: VIEWER_PURPOSE)
+        digest_param(Digest::SHA256.digest(signed), 16)
+      rescue UnusableViewer => e
+        warn_unusable_viewer(owner, e.message)
+      rescue StandardError => e
+        warn_unusable_viewer(owner, "#{e.class}: #{e.message}")
+      end
+
+      def viewer_named?(viewer)
+        named_within?(viewer, [VIEWER_NODE_LIMIT])
+      end
+
+      # Every LEAF must name something. A collection — anything
+      # expand_cache_key walks with to_a: an Array, a Hash (keys and values), a
+      # Set, a Struct, a sized Enumerator, nested — with one blank part is
+      # unnamed, and so is a value whose cache key expands to nothing (an
+      # object with a blank to_param). 0 is a viewer.
+      #
+      # Bounded: a Range is never walked, a collection of more than
+      # VIEWER_PART_LIMIT parts or a walk of more than VIEWER_NODE_LIMIT values
+      # (a self-referential Array, a to_a that returns itself) is unnamed.
+      # `budget` is a one-element counter shared by the whole walk.
+      def named_within?(value, budget)
+        return false if value.nil? || value == false
+        raise UnusableViewer, "a Range is not an identity" if value.is_a?(::Range)
+        raise UnusableViewer, "too deep or self-referential" if (budget[0] -= 1).negative?
+        return viewer_leaf?(value) unless value.respond_to?(:to_a) && !value.respond_to?(:cache_key)
+
+        size = value.respond_to?(:size) ? value.size : nil
+        raise UnusableViewer, "a collection of unknown or excessive size" unless viewer_size_ok?(size, value)
+
+        parts = value.to_a
+        raise UnusableViewer, "more than #{VIEWER_PART_LIMIT} parts" if parts.size > VIEWER_PART_LIMIT
+
+        parts.any? && parts.all? { named_within?(it, budget) }
+      end
+
+      def viewer_leaf?(value)
+        value.present? && ActiveSupport::Cache.expand_cache_key(value).present?
+      end
+
+      # An Enumerator must report a finite size; anything sized must be small.
+      def viewer_size_ok?(size, value)
+        return size <= VIEWER_PART_LIMIT if size.is_a?(::Integer)
+
+        !value.is_a?(::Enumerator) && size.nil?
+      end
+
+      # Logs why — once per COMPONENT, naming it, since the cause is that
+      # component's hook — and answers nil: "this value names nobody".
+      def warn_unusable_viewer(owner, reason)
+        name = owner.respond_to?(:name) ? owner.name.to_s : owner.to_s
+        return nil if VIEWER_WARNED.put_if_absent(name, true)
+        return nil unless defined?(::Rails) && ::Rails.respond_to?(:logger)
+
+        ::Rails.logger&.warn(
+          "[phlex-reactive] #{name.presence || "a component"}#reactive_cache_viewer returned a value that " \
+          "cannot name a viewer (#{reason}) — treated as no viewer (Vary: Cookie). Return an id, or a small " \
+          "Array of ids."
+        )
+        nil
+      end
+
+      # Test seam: let the once-per-component warnings fire again.
+      def reset_viewer_warning!
+        VIEWER_WARNED.clear
+      end
+
+      # The max-age (seconds) the endpoint answers with: the component's
+      # declared value, capped by Phlex::Reactive.fragment_cache_max_age_limit.
+      def max_age_for(component_class)
+        [component_class.reactive_lazy_cache.fetch(:max_age), Phlex::Reactive.fragment_cache_max_age_limit.to_i].min
+      end
+    end
+  end
+end