view_component 4.12.0 → 4.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2f1a7d34956fc9ae629c0f0e710f4a7335b33ebc99f1c3eccafc41d19713524
-  data.tar.gz: efd4bec7d2425da171f89f28fbc1bfaf9f2cba94fd0f2a9cbce674830281938e
+  metadata.gz: 9da4df780e2f53937b1593ef29fbbf9ce09662b48de7bc56ceae812c43880d2f
+  data.tar.gz: 94c6f23684dc139431a5c912a9e7fab5f70e2e794ba6bb72f5b66211c97f0e8c
 SHA512:
-  metadata.gz: 5d0f5024d419a56b5e178f0cce3d77ac4a1ae2d4d3efc0ac5334e7b55a4dcb6cc7460aa4d60a47bce63918b0a452b53c5425297ef03da2ce074793407acef570
-  data.tar.gz: be1d649efec64995de234eb70998001d42cd9b0197bdce00ec5011d68cb2a2784925abf283b3f51c3986a55a446db3ba0c17cedf406c919e31b178ece2be6b51
+  metadata.gz: 50b36d70558457271f43deb0b67473209af190979ca48c68ce1b3116b27abf06255b0d9312c53382600be23d75aa2304b58926d9e52f314923c4968182b10e53
+  data.tar.gz: c687e6eec0d97bd5ea53b3f5b51012e94ca75bd3d659bd1ac2ea03d3343e4d88e695aa5b822d5fe8f55a4a239163cd3df7048a33195b95132ac95e186a491b7b

data/app/controllers/view_components_system_test_controller.rb

@@ -11,6 +11,7 @@ class ViewComponentsSystemTestController < ActionController::Base # :nodoc:
     end
 
     rescue_from ViewComponent::SystemTestControllerNefariousPathError, with: :render_not_found
+    rescue_from Errno::ENOENT, with: :render_not_found
 
     def system_test_entrypoint
       render file: @path

data/docs/CHANGELOG.md

@@ -10,6 +10,92 @@ nav_order: 6
 
 ## main
 
+## 4.15.0
+
+* Add experimental caching support, opt-in per component via `include ViewComponent::ExperimentallyCacheable`.
+
+    Components have never participated in Rails' template digests, so a `<% cache %>` block wrapping `render MyComponent.new` was never invalidated when the component changed ([#234](https://github.com/ViewComponent/view_component/issues/234), open since 2020).
+
+    Including the module registers the component with Rails' own `ActionView::Digestor`, so fragment caches are invalidated when the component's template, Ruby class, sidecar files, superclasses, child components, or rendered partials change. This includes components and partials rendered from inline templates and `#call` methods. Adding `cache_on` caches the component's own rendered output, optionally guarded by `if:`/`unless:`, and `.cache_digest` exposes the digest for use outside a request.
+
+    ```ruby
+    class MessageComponent < ViewComponent::Base
+      include ViewComponent::ExperimentallyCacheable
+
+      cache_on :message, unless: -> { message.draft? }
+
+      def initialize(message:)
+        @message = message
+      end
+    end
+    ```
+
+    **This API is experimental and may change or be removed in a non-major release.** It's shipping opt-in and per-component precisely so we can iterate on it in response to real-world use. **Please try it and tell us what breaks, what's missing, and what feels wrong in [#234](https://github.com/ViewComponent/view_component/issues/234).** We're especially interested in feedback on: whether `cache_on` is the right shape for declaring cache keys, how the feature behaves with slots and content blocks, and whether the `# Template Dependency:` escape hatch is sufficient for dynamic renders. See [the caching guide](https://viewcomponent.org/guide/caching.html) for details and known caveats.
+
+    This work builds directly on prior art from the community. The `cache_on` API and the case for component-local caching come from [#2126](https://github.com/ViewComponent/view_component/pull/2126) by *Reegan Viljoen*. The approach of integrating with Rails' digest tree rather than reimplementing it comes from [`view_component-cache_digest`](https://github.com/tildeio/view_component-cache_digest) by *Godfrey Chan*. The invalidation cases it's tested against were contributed by *JWShuff* and *timburgan*, drawing on [`view_component-fragment_caching`](https://github.com/patrickarnett/view_component-fragment_caching) by *Patrick Arnett*. The issue was opened and researched by *ozzyaaron*, *pinzonjulian*, and *Derek Kniffin*, and the digest workaround that surfaced the superclass gap came from *cannikin* and *rnestler*. Cache-key correctness issues (formats sharing an entry, positional `nil` collisions, conditional caching, and ignored `cache_on` blocks) were found and reported by *Reegan Viljoen*.
+
+    *Reegan Viljoen*, *Godfrey Chan*, *JWShuff*, *timburgan*, *Patrick Arnett*, *ozzyaaron*, *pinzonjulian*, *Derek Kniffin*, *cannikin*, *rnestler*, *Joel Hawksley*
+
+## 4.14.0
+
+* Freeze `ReusedInstanceError::MESSAGE` and update `test_renders_component_with_asset_url` to build a fresh `AssetComponent` per render, fixing CI regressions introduced by the GHSA-8qw7-6phv-7q6p remediation.
+
+    *Joel Hawksley*
+
+* [Security] Fix incomplete remediation for CVE-2026-54497 (GHSA-8qw7-6phv-7q6p): reused ViewComponent instances could still leak `with_content` and `renders_one`/`renders_many` slot content from an earlier render into a later render because slot state and content set via `with_content` are populated by the caller before `render_in` runs and were not cleared by the previous per-render reset. Reinstate the `ViewComponent::ReusedInstanceError` guard that raises when a component instance is rendered more than once. Rebuild collection child components per render and dup collection spacer components before each render so that legitimate re-rendering of `Collection`/spacer objects continues to work.
+
+    *Yazan Balawneh, Cystack.ps*
+
+* Update GitHub Actions workflows to use `actions/checkout` v7.
+
+    *Richard Macklin*
+
+## 4.13.0
+
+* Add support for Turbo-streaming ViewComponents.
+
+    *Ben Sheldon*, *Joel Hawksley*
+
+* Reduce allocations and avoid redundant compiler work when rendering components and collections.
+
+    *Joel Hawksley*
+
+* Stabilize rendering allocation tests with explicit warmups and exact expectations by Rails and Ruby.
+
+    *Joel Hawksley*
+
+* Replace the custom memory allocation test helper with `minitest-memory`, preserving Ruby-version-specific allocation thresholds while improving failure diagnostics.
+
+    *Joel Hawksley*
+
+* Add zizmor security analysis for GitHub Actions workflows to CI.
+
+    *Joel Hawksley*
+
+* Remove the `$PROGRAM_NAME` version-printing line from `version.rb` so the file no longer reads a global variable (unshareable across Ractors). The version is still available via `ViewComponent::VERSION::STRING`.
+
+    *Joel Hawksley*
+
+* Fix intermittent template compilation failures where line-number offsets and annotation stripping were decided when a template object was created instead of when it was compiled, so later changes to coverage or annotation settings produced off-by-one backtraces or blank output.
+
+    *Joel Hawksley*
+
+* Freeze `ViewComponent::VERSION::STRING` so the version constant is immutable and Ractor-shareable.
+
+    *Joel Hawksley*
+
+* Add [audition](https://github.com/yaroslav/audition) Ractor-readiness checks to CI. Applied safe `.freeze` auto-fixes to string constants in `ViewComponent::Errors` and baselined existing findings so the gate fails only on new Ractor-isolation violations.
+
+    *Joel Hawksley*
+
+* Update link to GOV.UK Components library in resources list to govuk-components.x-govuk.org
+
+    *Peter Yates*
+
+* Fix `NoMethodError: undefined method 'template_handler_extensions'` when gathering sidecar templates on Rails main. Action View removed the `ActionView::Template.template_handler_extensions` method in newer versions; the compiler now reads the registered extensions through `ActionView::Template::Handlers.extensions`, which is the supported read-path API across all supported Rails versions (7.1+).
+
+    *Luiz Kowalski*
+
 ## 4.12.0
 
 * Fix stale render context on reused component instances. A `ViewComponent::Base` instance memoized its controller, helpers, request, view context, lookup context, view flow, and requested format details on first render via `||=`. Rendering the same instance a second time (intentionally or via aliasing) reused that stale context, which could leak data across requests, sessions, or users. `#render_in` now resets these ivars on every call so each render derives its context from the current view.

data/lib/view_component/active_job_serializer.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "active_job/serializers"
+
+module ViewComponent
+  class ActiveJobSerializer < ActiveJob::Serializers::ObjectSerializer
+    def klass
+      ViewComponent::Serializable::Proxy
+    end
+
+    def serialize?(argument)
+      argument.is_a?(ViewComponent::Serializable::Proxy)
+    end
+
+    def serialize(proxy)
+      super(proxy.serialize)
+    end
+
+    def deserialize(hash)
+      ViewComponent::Serializable::Proxy.deserialize(hash)
+    end
+  end
+end

data/lib/view_component/base.rb

@@ -103,9 +103,10 @@ module ViewComponent
     # Returns HTML that has been escaped by the respective template handler.
     #
     # @return [String]
-    def render_in(view_context, **_, &block)
-      self.class.__vc_compile(raise_errors: true)
+    def render_in(view_context, **, &block)
+      self.class.__vc_compile(raise_errors: true) unless self.class.__vc_compiled?
 
+      __vc_check_reused_instance!
       __vc_reset_render_state!
 
       @view_context = view_context
@@ -180,6 +181,7 @@ module ViewComponent
     ensure
       view_context.instance_variable_set(:@virtual_path, @old_virtual_path)
       @current_template = old_current_template
+      @__vc_rendered = true
     end
 
     # Subclass components that call `super` inside their template code will cause a
@@ -468,17 +470,32 @@ module ViewComponent
     # state from a previous render. Slot state (`@__vc_set_slots`,
     # `@__vc_content_set_by_with_content`) is intentionally preserved because it
     # is populated by callers _before_ `render_in` runs (e.g. via `with_*`
-    # slot setters or `with_content`).
+    # slot setters or `with_content`); reuse of an instance that has slot or
+    # `with_content` state is guarded against separately by
+    # `__vc_check_reused_instance!`.
+    RENDER_STATE_IVARS = %i[
+      @__vc_controller
+      @__vc_helpers
+      @__vc_request
+    ].freeze
+
     def __vc_reset_render_state!
-      %i[
-        @__vc_controller
-        @__vc_helpers
-        @__vc_request
-      ].each do |ivar|
+      RENDER_STATE_IVARS.each do |ivar|
         remove_instance_variable(ivar) if instance_variable_defined?(ivar)
       end
     end
 
+    # Raises when a component instance is rendered more than once.
+    # Reusing a component instance across renders can leak request-scoped state
+    # (controller, helpers, request, view_flow, slot content, `with_content`)
+    # from an earlier render into a later one. See
+    # `ViewComponent::ReusedInstanceError` and GHSA-8qw7-6phv-7q6p.
+    def __vc_check_reused_instance!
+      return unless defined?(@__vc_rendered) && @__vc_rendered
+
+      raise ReusedInstanceError.new(self.class.name)
+    end
+
     # Configuration for generators.
     #
     # All options under this namespace default to `false` unless otherwise

data/lib/view_component/cache_digest/dependency_tracking.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "action_view/dependency_tracker"
+
+module ViewComponent
+  module CacheDigest
+    # Teaches `ActionView::DependencyTracker` to see components.
+    #
+    # Prepended to the tracker's singleton class rather than to a specific
+    # tracker implementation (`ERBTracker`, `RubyTracker`, or the trackers
+    # registered by the Haml and Slim gems). `find_dependencies` is the single
+    # seam every tracker flows through, so hooking it here works regardless of
+    # which handler a template uses and doesn't depend on tracker internals.
+    #
+    # @private
+    module DependencyTracking
+      def find_dependencies(name, template, view_paths = nil)
+        dependencies = super
+        source = template.source
+
+        # `# Template Dependency: SomeComponent` names a class, which Rails
+        # would resolve as a template path and never find. Swap it for the path
+        # the component is digested under, so the declaration resolves instead
+        # of becoming a missing node.
+        CacheDigest.explicit_component_dependencies(source).each do |declared, virtual_path|
+          dependencies = dependencies - [declared] + [virtual_path]
+        end
+
+        dependencies + CacheDigest.dependencies_in(template)
+      rescue
+        # A broken digest is preferable to a broken render. Falling back to the
+        # dependencies Rails found on its own means the component simply isn't
+        # tracked, which is the pre-existing behavior.
+        super
+      end
+
+      # @private
+      def self.install!
+        tracker = ActionView::DependencyTracker.singleton_class
+        return if tracker.include?(self)
+
+        tracker.prepend(self)
+      end
+    end
+  end
+end

data/lib/view_component/cache_digest/resolver.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module ViewComponent
+  module CacheDigest
+    # Synthesizes the templates Rails' `ActionView::Digestor` digests components from.
+    #
+    # Once `DependencyTracking` reports `view_component/cache_digest/foo_component`
+    # as a dependency, the Digestor tries to find a template at that path. No such
+    # file exists: a component's rendered output depends on its template *and* its
+    # Ruby class, its sidecar files, and its superclasses.
+    #
+    # This resolver answers with a synthetic template whose source encodes all of
+    # those inputs. The template is never compiled or rendered; the Digestor only
+    # reads `#source` to hash it and to scan it for further dependencies.
+    #
+    # @private
+    class Resolver < ActionView::Resolver
+      # Extensions whose contents are hashed into the synthetic source.
+      SIDECAR_EXTENSIONS = %w[yml yaml].freeze
+
+      class << self
+        def instance
+          INSTANCE
+        end
+      end
+
+      def find_templates(name, prefix, partial, details, locals = [])
+        virtual_path = [prefix.presence, name].compact.join("/")
+        component = CacheDigest.component_for(virtual_path)
+        return [] unless component
+
+        [build_template(component, virtual_path, details)]
+      rescue
+        # Never let digest resolution break rendering. Returning no template
+        # makes the Digestor treat this as a missing node, which degrades to
+        # the behavior components have without this feature.
+        []
+      end
+
+      def to_s
+        "ViewComponent::CacheDigest::Resolver"
+      end
+      alias_method :to_path, :to_s
+
+      def eql?(other)
+        self.class.equal?(other.class)
+      end
+      alias_method :==, :eql?
+
+      private
+
+      def build_template(component, virtual_path, details)
+        ActionView::Template.new(
+          source_for(component),
+          "view_component cache digest for #{component.name}",
+          ActionView::Template.handler_for_extension(:erb),
+          locals: [],
+          format: Array(details[:formats]).first || :html,
+          virtual_path: virtual_path
+        )
+      end
+
+      # The synthetic source. Every section exists to change this string when
+      # something the component renders from changes.
+      def source_for(component)
+        parts = []
+
+        # Safety net: this template should never be rendered, only digested.
+        parts << "<% raise ViewComponent::CacheDigestTemplateError.new(#{component.name.inspect}) %>"
+
+        # Content hashes of the Ruby files and sidecar files backing the
+        # component and its component superclasses. Hashing rather than
+        # inlining keeps the source small and avoids embedding Ruby that a
+        # tracker might misread as a render call.
+        source_files(component).each do |path|
+          parts << "<%# Resolved Dependency: #{path} #{file_digest(path)} %>"
+        end
+
+        # Everything the component renders from Ruby rather than from a
+        # template: `# Template Dependency:` declarations, components rendered
+        # from `#call` methods, and partials referenced by string path.
+        # Re-emitted so the Digestor resolves them as tree nodes.
+        ruby_dependencies(component).each do |dependency|
+          parts << "<%# Template Dependency: #{dependency} %>"
+        end
+
+        # Template sources verbatim, so trackers can discover the partials and
+        # components they render.
+        template_sources(component).each do |source|
+          parts << source
+        end
+
+        parts.join("\n")
+      end
+
+      # The component and any component superclasses, nearest first. Including
+      # ancestors means editing `ApplicationComponent` invalidates every
+      # component that inherits from it.
+      def component_ancestors(component)
+        component.ancestors.select do |ancestor|
+          ancestor.is_a?(Class) &&
+            ancestor <= ViewComponent::Base &&
+            ancestor != ViewComponent::Base
+        end
+      end
+
+      def source_files(component)
+        component_ancestors(component).flat_map { |ancestor|
+          [ancestor.identifier, *ancestor.sidecar_files(SIDECAR_EXTENSIONS)]
+        }.compact.uniq.select { |path| ::File.exist?(path) }
+      end
+
+      def template_files(component)
+        component_ancestors(component)
+          .flat_map { |ancestor| ancestor.sidecar_files(ActionView::Template::Handlers.extensions) }
+          .uniq
+          .select { |path| ::File.exist?(path) }
+      end
+
+      # Sidecar template files plus inline templates, which live in the Ruby
+      # file and so are invisible to Action View's trackers.
+      def template_sources(component)
+        sources = template_files(component).map { |path| ::File.read(path) }
+
+        component_ancestors(component).each do |ancestor|
+          inline_template = ancestor.__vc_inline_template
+          sources << inline_template.source if inline_template
+        end
+
+        sources.uniq
+      end
+
+      def explicit_dependencies(component)
+        ruby_sources(component).flat_map { |source|
+          declared = source.scan(CacheDigest::EXPLICIT_DEPENDENCY).flatten
+
+          # Component class names are translated to the path they're digested
+          # under; anything else is a template path already.
+          CacheDigest.explicit_component_dependencies(source).each do |name, virtual_path|
+            declared = declared - [name] + [virtual_path]
+          end
+
+          declared
+        }.uniq
+      end
+
+      # Everything a component renders from Ruby code rather than from a
+      # template. Action View's trackers only read templates, so a `#call`
+      # method that renders another component or a partial would otherwise go
+      # unnoticed.
+      def ruby_dependencies(component)
+        virtual_path = CacheDigest.virtual_path_for(component)
+
+        explicit_dependencies(component) |
+          ruby_sources(component).flat_map { |source|
+            CacheDigest.component_paths_in(source) |
+              CacheDigest.partial_paths_in(source, virtual_path)
+          }.uniq
+      end
+
+      def ruby_sources(component)
+        component_ancestors(component).filter_map { |ancestor|
+          path = ancestor.identifier
+          ::File.read(path) if path && ::File.exist?(path)
+        }
+      end
+
+      def file_digest(path)
+        ActiveSupport::Digest.hexdigest(::File.read(path))
+      end
+
+      # Built once at load time rather than memoized, so no class-level state
+      # is written after boot. The resolver is stateless: it reads from disk on
+      # every call so it can't go stale when a component changes.
+      INSTANCE = new
+    end
+  end
+end

data/lib/view_component/cache_digest.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require "active_support/dependencies/autoload"
+require "action_view/digestor"
+require "action_view/render_parser"
+
+module ViewComponent
+  # Integrates ViewComponents into Rails' template digest tree.
+  #
+  # Rails computes a digest for every template from its source and the templates
+  # it renders. That digest is mixed into the key of every `<% cache %>` block in
+  # the template, so editing a partial busts the caches of everything that
+  # renders it.
+  #
+  # Components are invisible to that mechanism for two reasons:
+  #
+  # 1. **Discovery** — `ActionView::DependencyTracker` doesn't recognize
+  #    `render SomeComponent.new(...)` as a dependency.
+  # 2. **Resolution** — component templates live outside the view paths, and a
+  #    component's rendered output depends on its Ruby class and sidecar files,
+  #    not just its template.
+  #
+  # This module fixes both, reusing Rails' own `ActionView::Digestor` rather than
+  # reimplementing static analysis. Components opt in individually by including
+  # `ViewComponent::ExperimentallyCacheable`; until at least one component does,
+  # every hook here short-circuits.
+  #
+  # @private
+  module CacheDigest
+    extend ActiveSupport::Autoload
+
+    autoload :DependencyTracking
+    autoload :Resolver
+
+    # Prefix for the synthetic virtual paths components are digested under.
+    #
+    # Namespaced under `view_component/` so it can't collide with an
+    # application partial.
+    VIRTUAL_PATH_PREFIX = "view_component/cache_digest"
+
+    # Matches `render FooComponent`, `render(Foo::BarComponent.new(...))`,
+    # `render FooComponent.with_collection(...)`, etc.
+    #
+    # Deliberately a plain source scan rather than a tracker-specific hook: it
+    # behaves identically for the ERB tracker, the Prism-based Ruby tracker, and
+    # third-party Haml/Slim trackers.
+    RENDER_CALL = /
+      \brender(?:_to_string)?\b   # render or render_to_string
+      \s*\(?\s*                   # optional opening paren
+      (?<const>
+        (?:::)?[A-Z]\w*           # a constant
+        (?:::[A-Z]\w*)*           # optionally namespaced
+      )
+    /x
+
+    # Rails' escape hatch for dependencies static analysis can't see.
+    EXPLICIT_DEPENDENCY = /#\s*Template Dependency:\s*(\S+)/
+    class << self
+      # Virtual paths of components that have opted into caching, mapped to
+      # their class names.
+      #
+      # Class *names* rather than class objects so the registry survives
+      # autoloader reloads without pinning stale constants in memory.
+      #
+      # @return [Hash{String => String}]
+      def registry
+        @registry ||= {}
+      end
+
+      # @return [Boolean] whether any component has opted in.
+      def enabled?
+        !registry.empty?
+      end
+
+      # @private
+      def register(component)
+        return unless component.virtual_path && component.name
+
+        registry[component.virtual_path] = component.name
+      end
+
+      # The synthetic virtual path a component is digested under.
+      #
+      # @return [String, nil]
+      def virtual_path_for(component)
+        return unless component.respond_to?(:virtual_path) && component.virtual_path
+
+        "#{VIRTUAL_PATH_PREFIX}/#{component.virtual_path}"
+      end
+
+      # Resolve a synthetic virtual path back to the component that owns it.
+      #
+      # @return [Class, nil]
+      def component_for(virtual_path)
+        return unless virtual_path.start_with?("#{VIRTUAL_PATH_PREFIX}/")
+
+        name = registry[virtual_path.delete_prefix("#{VIRTUAL_PATH_PREFIX}/")]
+        return unless name
+
+        constantize_component(name)
+      end
+
+      # Scan a template's source for renders of cacheable components.
+      #
+      # Called for every template Rails digests, so it exits early when the
+      # feature is unused.
+      #
+      # @return [Array<String>] synthetic virtual paths
+      def dependencies_in(template)
+        return [] unless enabled?
+
+        component_paths_in(template.source)
+      end
+
+      # Scan arbitrary source (a template or a component's Ruby file) for
+      # renders of cacheable components.
+      #
+      # @return [Array<String>] synthetic virtual paths
+      def component_paths_in(source)
+        return [] unless source.is_a?(String) && source.include?("render")
+
+        source.scan(RENDER_CALL).flatten.uniq.filter_map do |constant_name|
+          component = constantize_component(constant_name)
+          virtual_path_for(component) if component
+        end
+      end
+
+      # Scan a component's Ruby source for partials referenced by string path,
+      # such as `render "posts/byline"` inside a `#call` method.
+      #
+      # Uses Rails' own render parser — the same one `RubyTracker` runs over
+      # compiled templates — rather than a second implementation of the same
+      # analysis. Its results are then narrowed to paths that appear verbatim in
+      # the source, which keeps string literals and discards the speculative
+      # `things/_thing` entries the parser infers from dynamic renders like
+      # `render @thing` or `render FooComponent.new`. Those would resolve to
+      # nothing and only add log noise; components rendered from Ruby are
+      # already found precisely by `component_paths_in`.
+      #
+      # @param source [String] Ruby source
+      # @param name [String] virtual path the source is being digested under
+      # @return [Array<String>] partial virtual paths
+      def partial_paths_in(source, name)
+        return [] unless source.is_a?(String) && source.include?("render")
+
+        RENDER_PARSER.new(name, source).render_calls.uniq.select do |path|
+          source.include?(path) || source.include?(path.sub(%r{(\A|/)_}, '\1'))
+        end
+      rescue
+        # Never let digest computation break rendering.
+        []
+      end
+
+      # Action View has shipped its render parser as a class (Rails 7.1, and
+      # again on main) and as a module holding a `Default` implementation
+      # chosen from Prism or Ripper (Rails 7.2 through 8.1).
+      #
+      # @param parser [Class, Module] `ActionView::RenderParser`
+      # @return [Class]
+      def resolve_render_parser(parser)
+        parser.is_a?(Class) ? parser : parser::Default
+      end
+
+      # Resolve `# Template Dependency: SomeComponent` declarations.
+      #
+      # Rails' escape hatch takes a template path, but the path a component is
+      # digested under is an internal detail. Naming the class instead keeps
+      # that detail out of application code, so `SomeComponent` is translated
+      # to the path the Digestor can resolve.
+      #
+      # @return [Array<Array(String, String)>] pairs of declared name and
+      #   synthetic virtual path
+      def explicit_component_dependencies(source)
+        return [] unless source.is_a?(String) && source.include?("Template Dependency:")
+
+        source.scan(EXPLICIT_DEPENDENCY).flatten.uniq.filter_map do |declared|
+          next unless /\A(?:::)?[A-Z]/.match?(declared)
+
+          component = constantize_component(declared)
+          [declared, virtual_path_for(component)] if component
+        end
+      end
+
+      # Compute the digest of a component using Rails' digest tree.
+      #
+      # @param component [Class] a component that includes `ExperimentallyCacheable`
+      # @param finder [ActionView::LookupContext]
+      # @param format [Symbol]
+      # @return [String]
+      def digest(component, finder: default_finder, format: :html)
+        virtual_path = virtual_path_for(component)
+        return "" unless virtual_path
+
+        ActionView::Digestor.digest(name: virtual_path, format: format, finder: finder)
+      end
+
+      # A lookup context for digesting components outside a request, where no
+      # view context (and therefore no finder) exists.
+      #
+      # @return [ActionView::LookupContext]
+      def default_finder
+        # Not memoized across reloads: view paths change when the app reloads.
+        ActionView::LookupContext.new(ActionController::Base.view_paths)
+      end
+
+      # Wire the tracker and resolver into Action View.
+      #
+      # Called each time a component includes `ExperimentallyCacheable`. Both
+      # steps below are individually idempotent, so no "already installed" flag
+      # is kept. Both hooks short-circuit while the registry is empty, so
+      # applications that never opt in are unaffected.
+      #
+      # @private
+      def install!
+        DependencyTracking.install!
+
+        ActiveSupport.on_load(:action_controller_base) do
+          resolver = ViewComponent::CacheDigest::Resolver.instance
+
+          append_view_path(resolver) unless view_paths.include?(resolver)
+        end
+      end
+
+      private
+
+      # Resolve a constant name to a component that opted into caching.
+      #
+      # Returns nil for anything else, including constants that don't exist.
+      # Autoloading here is safe: the template is about to render this constant
+      # anyway.
+      def constantize_component(constant_name)
+        component = constant_name.safe_constantize
+        return unless component.is_a?(Class)
+        return unless component.respond_to?(:__vc_cacheable?) && component.__vc_cacheable?
+
+        component
+      rescue
+        # Never let digest computation break rendering.
+        nil
+      end
+    end
+
+    # Resolved once at load time rather than memoized, so no class-level state
+    # is written after boot.
+    RENDER_PARSER = resolve_render_parser(ActionView::RenderParser)
+  end
+end