style_capsule 1.4.0 → 2.0.0

data/lib/style_capsule/component.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "digest/sha1"
+require_relative "component_class_methods"
 # ActiveSupport string extensions are conditionally required in lib/style_capsule.rb
 
 module StyleCapsule
@@ -95,314 +96,7 @@ module StyleCapsule
     end
 
     module ClassMethods
-      # Class-level cache for scoped CSS per component class
-      def css_cache
-        @css_cache ||= {}
-      end
-
-      # Clear the CSS cache for this component class
-      #
-      # Useful for testing or when you want to force CSS reprocessing.
-      # In development, this is automatically called when classes are reloaded.
-      #
-      # @example
-      #   MyComponent.clear_css_cache
-      def clear_css_cache
-        @css_cache = {}
-      end
-
-      # Set or get a custom capsule ID for this component class (useful for testing)
-      #
-      # @param capsule_id [String, nil] The custom capsule ID to use (nil to get current value)
-      # @return [String, nil] The current capsule ID if no argument provided
-      # @example Setting a custom capsule ID
-      #   class MyComponent < ApplicationComponent
-      #     include StyleCapsule::Component
-      #     capsule_id "test-capsule-123"
-      #   end
-      # @example Getting the current capsule ID
-      #   MyComponent.capsule_id  # => "test-capsule-123" or nil
-      def capsule_id(capsule_id = nil)
-        if capsule_id.nil?
-          @custom_capsule_id if defined?(@custom_capsule_id)
-        else
-          @custom_capsule_id = capsule_id.to_s
-        end
-      end
-
-      # Configure stylesheet registry for head rendering
-      #
-      # Enables head rendering and configures namespace and cache strategy in a single call.
-      # All parameters are optional - calling without arguments enables head rendering with defaults.
-      #
-      # @param namespace [Symbol, String, nil] Namespace identifier (nil/blank uses default)
-      # @param cache_strategy [Symbol, String, Proc, nil] Cache strategy: :none (default), :time, :proc, :file
-      #   - Symbol or String: :none, :time, :proc, :file (or "none", "time", "proc", "file")
-      #   - Proc: Custom cache proc (automatically uses :proc strategy)
-      #     Proc receives: (css_content, capsule_id, namespace) and should return [cache_key, should_cache, expires_at]
-      # @param cache_ttl [Integer, ActiveSupport::Duration, nil] Time-to-live in seconds (for :time strategy). Supports ActiveSupport::Duration (e.g., 1.hour, 30.minutes)
-      # @param cache_proc [Proc, nil] Custom cache proc (for :proc strategy, ignored if cache_strategy is a Proc)
-      #   Proc receives: (css_content, capsule_id, namespace) and should return [cache_key, should_cache, expires_at]
-      # @return [void]
-      # @example Basic usage (enables head rendering with defaults)
-      #   class MyComponent < ApplicationComponent
-      #     include StyleCapsule::Component
-      #     stylesheet_registry
-      #   end
-      # @example With namespace
-      #   class AdminComponent < ApplicationComponent
-      #     include StyleCapsule::Component
-      #     stylesheet_registry namespace: :admin
-      #   end
-      # @example With time-based caching
-      #   class MyComponent < ApplicationComponent
-      #     include StyleCapsule::Component
-      #     stylesheet_registry cache_strategy: :time, cache_ttl: 1.hour
-      #   end
-      # @example With custom proc caching
-      #   class MyComponent < ApplicationComponent
-      #     include StyleCapsule::Component
-      #     stylesheet_registry cache_strategy: :proc, cache_proc: ->(css, capsule_id, ns) {
-      #       cache_key = "css_#{capsule_id}_#{ns}"
-      #       should_cache = css.length > 100
-      #       expires_at = Time.now + 1800
-      #       [cache_key, should_cache, expires_at]
-      #     }
-      #   end
-      # @example File-based caching (requires class method component_styles)
-      #   class MyComponent < ApplicationComponent
-      #     include StyleCapsule::Component
-      #     stylesheet_registry cache_strategy: :file
-      #
-      #     def self.component_styles  # Must be class method for file caching
-      #       <<~CSS
-      #         .section { color: red; }
-      #       CSS
-      #     end
-      #   end
-      # @example All options combined
-      #   class MyComponent < ApplicationComponent
-      #     include StyleCapsule::Component
-      #     stylesheet_registry namespace: :admin, cache_strategy: :time, cache_ttl: 1.hour
-      #   end
-      def stylesheet_registry(namespace: nil, cache_strategy: :none, cache_ttl: nil, cache_proc: nil)
-        @head_rendering = true
-        @stylesheet_namespace = namespace unless namespace.nil?
-
-        # Normalize cache_strategy: convert strings to symbols, handle Proc
-        normalized_strategy, normalized_proc = normalize_cache_strategy(cache_strategy, cache_proc)
-        @inline_cache_strategy = normalized_strategy
-        @inline_cache_ttl = cache_ttl
-        @inline_cache_proc = normalized_proc
-      end
-
-      private
-
-      # Normalize cache_strategy to handle Symbol, String, and Proc
-      #
-      # @param cache_strategy [Symbol, String, Proc, nil] Cache strategy
-      # @param cache_proc [Proc, nil] Optional cache proc (ignored if cache_strategy is a Proc)
-      # @return [Array<Symbol, Proc|nil>] Normalized strategy and proc
-      def normalize_cache_strategy(cache_strategy, cache_proc)
-        case cache_strategy
-        when Proc
-          # If cache_strategy is a Proc, use it as the proc and set strategy to :proc
-          [:proc, cache_strategy]
-        when String
-          # Convert string to symbol
-          normalized = cache_strategy.to_sym
-          unless [:none, :time, :proc, :file].include?(normalized)
-            raise ArgumentError, "cache_strategy must be :none, :time, :proc, or :file (got: #{cache_strategy.inspect})"
-          end
-          [normalized, cache_proc]
-        when Symbol
-          unless [:none, :time, :proc, :file].include?(cache_strategy)
-            raise ArgumentError, "cache_strategy must be :none, :time, :proc, or :file (got: #{cache_strategy.inspect})"
-          end
-          [cache_strategy, cache_proc]
-        when nil
-          [:none, nil]
-        else
-          raise ArgumentError, "cache_strategy must be a Symbol, String, or Proc (got: #{cache_strategy.class})"
-        end
-      end
-
-      # Check if component uses head rendering (checks instance variable, then parent class, defaults to false)
-      #
-      # @return [Boolean] Whether head rendering is enabled (default: false)
-      def head_rendering?
-        if defined?(@head_rendering)
-          @head_rendering
-        elsif superclass.respond_to?(:head_rendering?, true)
-          superclass.head_rendering?
-        else
-          false
-        end
-      end
-
-      public :head_rendering?
-
-      # Get the namespace for stylesheet registry (checks instance variable, then parent class, defaults to nil)
-      #
-      # @return [Symbol, String, nil] The namespace identifier (default: nil)
-      def stylesheet_namespace
-        if defined?(@stylesheet_namespace) && @stylesheet_namespace
-          @stylesheet_namespace
-        elsif superclass.respond_to?(:stylesheet_namespace, true)
-          superclass.stylesheet_namespace
-        end
-      end
-
-      # Configure StyleCapsule settings
-      #
-      # All settings support class inheritance - child classes inherit settings from parent classes
-      # and can override them by calling style_capsule again with different values.
-      #
-      # @param namespace [Symbol, String, nil] Default namespace for stylesheets
-      # @param cache_strategy [Symbol, String, Proc, nil] Cache strategy: :none (default), :time, :proc, :file
-      # @param cache_ttl [Integer, ActiveSupport::Duration, nil] Time-to-live in seconds (for :time strategy)
-      # @param cache_proc [Proc, nil] Custom cache proc (for :proc strategy)
-      # @param scoping_strategy [Symbol, nil] CSS scoping strategy: :selector_patching (default) or :nesting
-      # @param head_rendering [Boolean, nil] Enable head rendering (default: true if any option is set, false otherwise)
-      # @return [void]
-      # @example Basic usage with namespace
-      #   class AdminComponent < ApplicationComponent
-      #     include StyleCapsule::Component
-      #     style_capsule namespace: :admin
-      #
-      #     def view_template
-      #       register_stylesheet("stylesheets/admin/dashboard")  # Uses :admin namespace automatically
-      #       div { "Content" }
-      #     end
-      #   end
-      # @example With all options
-      #   class MyComponent < ApplicationComponent
-      #     include StyleCapsule::Component
-      #     style_capsule(
-      #       namespace: :user,
-      #       cache_strategy: :time,
-      #       cache_ttl: 1.hour,
-      #       scoping_strategy: :nesting
-      #     )
-      #   end
-      # @example Inheritance - child class inherits parent settings
-      #   class BaseComponent < ApplicationComponent
-      #     include StyleCapsule::Component
-      #     style_capsule namespace: :admin, cache_strategy: :time, cache_ttl: 1.hour
-      #   end
-      #
-      #   class ChildComponent < BaseComponent
-      #     # Inherits namespace: :admin, cache_strategy: :time, cache_ttl: 1.hour
-      #     # Can override specific settings:
-      #     style_capsule namespace: :user  # Overrides namespace, keeps cache settings
-      #   end
-      def style_capsule(namespace: nil, cache_strategy: nil, cache_ttl: nil, cache_proc: nil, scoping_strategy: nil, head_rendering: nil)
-        # Set namespace (stored in instance variable, but getter checks parent class for inheritance)
-        if namespace
-          @stylesheet_namespace = namespace
-        end
-
-        # Configure cache strategy if provided
-        if cache_strategy || cache_ttl || cache_proc
-          normalized_strategy, normalized_proc = normalize_cache_strategy(cache_strategy || :none, cache_proc)
-          @inline_cache_strategy = normalized_strategy
-          # Explicitly set cache_ttl (even if nil) to override parent's value when cache settings are changed
-          @inline_cache_ttl = cache_ttl
-          @inline_cache_proc = normalized_proc
-        end
-
-        # Configure CSS scoping strategy if provided
-        if scoping_strategy
-          unless [:selector_patching, :nesting].include?(scoping_strategy)
-            raise ArgumentError, "scoping_strategy must be :selector_patching or :nesting (got: #{scoping_strategy.inspect})"
-          end
-          @css_scoping_strategy = scoping_strategy
-        end
-
-        # Enable head rendering if explicitly set or if any option is provided (except scoping_strategy)
-        if head_rendering.nil?
-          @head_rendering = true if namespace || cache_strategy || cache_ttl || cache_proc
-        else
-          @head_rendering = head_rendering
-        end
-      end
-
-      # Get the custom scope ID if set (alias for capsule_id getter)
-      def custom_capsule_id
-        @custom_capsule_id if defined?(@custom_capsule_id)
-      end
-
-      # Get inline cache strategy (checks instance variable, then parent class, defaults to nil)
-      #
-      # @return [Symbol, nil] The cache strategy (default: nil)
-      def inline_cache_strategy
-        if defined?(@inline_cache_strategy) && @inline_cache_strategy
-          @inline_cache_strategy
-        elsif superclass.respond_to?(:inline_cache_strategy, true)
-          superclass.inline_cache_strategy
-        end
-      end
-
-      # Get inline cache TTL (checks instance variable, then parent class, defaults to nil)
-      #
-      # @return [Integer, ActiveSupport::Duration, nil] The cache TTL (default: nil)
-      def inline_cache_ttl
-        if defined?(@inline_cache_ttl)
-          @inline_cache_ttl
-        elsif superclass.respond_to?(:inline_cache_ttl, true)
-          superclass.inline_cache_ttl
-        end
-      end
-
-      # Get inline cache proc (checks instance variable, then parent class, defaults to nil)
-      #
-      # @return [Proc, nil] The cache proc (default: nil)
-      def inline_cache_proc
-        if defined?(@inline_cache_proc)
-          @inline_cache_proc
-        elsif superclass.respond_to?(:inline_cache_proc, true)
-          superclass.inline_cache_proc
-        end
-      end
-
-      public :head_rendering?, :stylesheet_namespace, :style_capsule, :custom_capsule_id, :inline_cache_strategy, :inline_cache_ttl, :inline_cache_proc
-
-      # Get CSS scoping strategy (checks instance variable, then parent class, defaults to :selector_patching)
-      #
-      # @return [Symbol] The current scoping strategy (default: :selector_patching)
-      def css_scoping_strategy
-        if defined?(@css_scoping_strategy) && @css_scoping_strategy
-          @css_scoping_strategy
-        elsif superclass.respond_to?(:css_scoping_strategy, true)
-          superclass.css_scoping_strategy
-        else
-          :selector_patching
-        end
-      end
-
-      public :css_scoping_strategy
-
-      # Set or get options for stylesheet_link_tag when using file-based caching
-      #
-      # @param options [Hash, nil] Options to pass to stylesheet_link_tag (e.g., "data-turbo-track": "reload", omit to get current value)
-      # @return [Hash, nil] The current stylesheet link options if no argument provided
-      # @example Setting stylesheet link options
-      #   class MyComponent < ApplicationComponent
-      #     include StyleCapsule::Component
-      #     stylesheet_registry cache_strategy: :file
-      #     stylesheet_link_options "data-turbo-track": "reload"
-      #   end
-      # @example Getting the current options
-      #   MyComponent.stylesheet_link_options  # => {"data-turbo-track" => "reload"} or nil
-      def stylesheet_link_options(options = nil)
-        if options.nil?
-          @stylesheet_link_options if defined?(@stylesheet_link_options)
-        else
-          @stylesheet_link_options = options
-        end
-      end
-
-      public :stylesheet_link_options
+      include StyleCapsule::ComponentClassMethods
     end
 
     # Module that wraps view_template to add scoped wrapper
@@ -412,8 +106,11 @@ module StyleCapsule
           # Render styles first
           render_capsule_styles
 
+          # Get wrapper tag
+          tag = self.class.wrapper_tag
+
           # Wrap content in scoped element
-          div(data_capsule: component_capsule) do
+          public_send(tag, data_capsule: component_capsule) do
             super
           end
         else
@@ -451,6 +148,7 @@ module StyleCapsule
     #
     # Supports both instance method (def component_styles) and class method (def self.component_styles).
     # File caching is only allowed for class method component_styles.
+    # rubocop:disable Metrics/AbcSize -- coordinates head vs body rendering, caching, and registry
     def render_capsule_styles
       css_content = component_styles_content
       return if css_content.nil? || css_content.to_s.strip.empty?
@@ -501,6 +199,7 @@ module StyleCapsule
         end
       end
     end
+    # rubocop:enable Metrics/AbcSize
 
     # Check if component should use head rendering
     #
@@ -512,11 +211,12 @@ module StyleCapsule
 
     # Scope CSS and return scoped CSS with attribute selectors
     def scope_css(css_content)
-      # Use class-level cache to avoid reprocessing same CSS
-      # Include capsule_id and scoping strategy in cache key
+      # Use class-level cache to avoid reprocessing same CSS. Include a fingerprint of the
+      # source CSS so instance methods that return different styles per render stay correct.
       capsule_id = component_capsule
       scoping_strategy = self.class.css_scoping_strategy
-      cache_key = "#{self.class.name}:#{capsule_id}:#{scoping_strategy}"
+      css_fingerprint = Digest::SHA1.hexdigest(css_content.to_s)
+      cache_key = "#{self.class.name}:#{capsule_id}:#{scoping_strategy}:#{css_fingerprint}"
 
       if self.class.css_cache.key?(cache_key)
         return self.class.css_cache[cache_key]
@@ -530,10 +230,7 @@ module StyleCapsule
         CssProcessor.scope_selectors(css_content, capsule_id, component_class: self.class)
       end
 
-      # Cache at class level (one style block per component type/scope/strategy combination)
-      self.class.css_cache[cache_key] = scoped_css
-
-      scoped_css
+      self.class.store_css_cache(cache_key, scoped_css)
     end
 
     # Generate a unique scope ID based on component class name (per-component-type)

data/lib/style_capsule/component_builder.rb

@@ -85,6 +85,7 @@ module StyleCapsule
       # @param component_class [Class] Component class to build
       # @param output_proc [Proc, nil] Optional proc to call with output messages
       # @return [String, nil] Generated file path or nil if skipped
+      # rubocop:disable Metrics/AbcSize -- file build path with instrumentation and error handling
       def build_component(component_class, output_proc: nil)
         return nil unless component_class.inline_cache_strategy == :file
         # Check for class method component_styles (required for file caching)
@@ -111,11 +112,13 @@ module StyleCapsule
           output_proc&.call("Generated: #{file_path}") if file_path
           file_path
         rescue ArgumentError, NoMethodError => e
-          # Component requires arguments or has dependencies - skip it
+          # Component requires arguments or has dependencies - skip it (common for ViewComponent with required kwargs)
+          warn "[style_capsule] Skipped #{component_class.name} in style_capsule:build — #{e.class}: #{e.message}"
           output_proc&.call("Skipped #{component_class.name}: #{e.message}")
           nil
         end
       end
+      # rubocop:enable Metrics/AbcSize
 
       # Build CSS files for all components
       #

data/lib/style_capsule/component_class_methods.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+module StyleCapsule
+  # Shared class-level DSL for {StyleCapsule::Component} and {StyleCapsule::ViewComponent}.
+  #
+  # @api private
+  module ComponentClassMethods
+    MAX_CSS_CACHE_ENTRIES = 256
+
+    # Class-level cache for scoped CSS per component class
+    def css_cache
+      @css_cache ||= {}
+    end
+
+    # Store scoped CSS in the bounded class-level cache
+    #
+    # @param cache_key [String]
+    # @param scoped_css [String]
+    # @return [String] +scoped_css+
+    def store_css_cache(cache_key, scoped_css)
+      cache = css_cache
+      order = css_cache_order
+      evict_css_cache_if_full!(cache, order)
+      cache[cache_key] = scoped_css
+      order << cache_key
+      scoped_css
+    end
+
+    # Clear the CSS cache for this component class
+    #
+    # Useful for testing or when you want to force CSS reprocessing.
+    # In development, this is automatically called when classes are reloaded.
+    #
+    # @example
+    #   MyComponent.clear_css_cache
+    def clear_css_cache
+      @css_cache = {}
+      @css_cache_order = []
+    end
+
+    private
+
+    def css_cache_order
+      @css_cache_order ||= []
+    end
+
+    def evict_css_cache_if_full!(cache, order)
+      while order.size >= MAX_CSS_CACHE_ENTRIES
+        old = order.shift
+        cache.delete(old)
+      end
+    end
+
+    public
+
+    # Set or get a custom capsule ID for this component class (useful for testing)
+    #
+    # @param capsule_id [String, nil] The custom capsule ID to use (nil to get current value)
+    # @return [String, nil] The current capsule ID if no argument provided
+    # @example Setting a custom capsule ID
+    #   class MyComponent < ApplicationComponent
+    #     include StyleCapsule::Component
+    #     capsule_id "test-capsule-123"
+    #   end
+    # @example Getting the current capsule ID
+    #   MyComponent.capsule_id  # => "test-capsule-123" or nil
+    def capsule_id(capsule_id = nil)
+      if capsule_id.nil?
+        @custom_capsule_id if defined?(@custom_capsule_id)
+      else
+        @custom_capsule_id = capsule_id.to_s
+      end
+    end
+
+    # Configure stylesheet registry for head rendering
+    #
+    # Enables head rendering and configures namespace and cache strategy in a single call.
+    # All parameters are optional - calling without arguments enables head rendering with defaults.
+    #
+    # @deprecated Prefer {#style_capsule}, which configures namespace, cache, scoping, and head
+    #   rendering in one place. This method remains for backward compatibility.
+    #
+    # @param namespace [Symbol, String, nil] Namespace identifier (nil/blank uses default)
+    # @param cache_strategy [Symbol, String, Proc, nil] Cache strategy: :none (default), :time, :proc, :file
+    #   - Symbol or String: :none, :time, :proc, :file (or "none", "time", "proc", "file")
+    #   - Proc: Custom cache proc (automatically uses :proc strategy)
+    #     Proc receives: (css_content, capsule_id, namespace) and should return [cache_key, should_cache, expires_at]
+    # @param cache_ttl [Integer, ActiveSupport::Duration, nil] Time-to-live in seconds (for :time strategy). Supports ActiveSupport::Duration (e.g., 1.hour, 30.minutes)
+    # @param cache_proc [Proc, nil] Custom cache proc (for :proc strategy, ignored if cache_strategy is a Proc)
+    #   Proc receives: (css_content, capsule_id, namespace) and should return [cache_key, should_cache, expires_at]
+    # @return [void]
+    def stylesheet_registry(namespace: nil, cache_strategy: :none, cache_ttl: nil, cache_proc: nil)
+      @head_rendering = true
+      @stylesheet_namespace = namespace unless namespace.nil?
+
+      # Normalize cache_strategy: convert strings to symbols, handle Proc
+      normalized_strategy, normalized_proc = normalize_cache_strategy(cache_strategy, cache_proc)
+      @inline_cache_strategy = normalized_strategy
+      @inline_cache_ttl = cache_ttl
+      @inline_cache_proc = normalized_proc
+    end
+
+    private
+
+    # Normalize cache_strategy to handle Symbol, String, and Proc
+    #
+    # @param cache_strategy [Symbol, String, Proc, nil] Cache strategy
+    # @param cache_proc [Proc, nil] Optional cache proc (ignored if cache_strategy is a Proc)
+    # @return [Array<Symbol, Proc|nil>] Normalized strategy and proc
+    def normalize_cache_strategy(cache_strategy, cache_proc)
+      case cache_strategy
+      when Proc
+        # If cache_strategy is a Proc, use it as the proc and set strategy to :proc
+        [:proc, cache_strategy]
+      when String
+        # Convert string to symbol
+        normalized = cache_strategy.to_sym
+        unless [:none, :time, :proc, :file].include?(normalized)
+          raise ArgumentError, "cache_strategy must be :none, :time, :proc, or :file (got: #{cache_strategy.inspect})"
+        end
+        [normalized, cache_proc]
+      when Symbol
+        unless [:none, :time, :proc, :file].include?(cache_strategy)
+          raise ArgumentError, "cache_strategy must be :none, :time, :proc, or :file (got: #{cache_strategy.inspect})"
+        end
+        [cache_strategy, cache_proc]
+      when nil
+        [:none, nil]
+      else
+        raise ArgumentError, "cache_strategy must be a Symbol, String, or Proc (got: #{cache_strategy.class})"
+      end
+    end
+
+    # Check if component uses head rendering (checks instance variable, then parent class, defaults to false)
+    #
+    # @return [Boolean] Whether head rendering is enabled (default: false)
+    def head_rendering?
+      if defined?(@head_rendering)
+        @head_rendering
+      elsif superclass.respond_to?(:head_rendering?, true)
+        superclass.head_rendering?
+      else
+        false
+      end
+    end
+
+    public :head_rendering?
+
+    # Get the namespace for stylesheet registry (checks instance variable, then parent class, defaults to nil)
+    #
+    # @return [Symbol, String, nil] The namespace identifier (default: nil)
+    def stylesheet_namespace
+      if defined?(@stylesheet_namespace) && @stylesheet_namespace
+        @stylesheet_namespace
+      elsif superclass.respond_to?(:stylesheet_namespace, true)
+        superclass.stylesheet_namespace
+      end
+    end
+
+    # Configure StyleCapsule settings
+    #
+    # All settings support class inheritance - child classes inherit settings from parent classes
+    # and can override them by calling style_capsule again with different values.
+    #
+    # @param namespace [Symbol, String, nil] Default namespace for stylesheets
+    # @param cache_strategy [Symbol, String, Proc, nil] Cache strategy: :none (default), :time, :proc, :file
+    # @param cache_ttl [Integer, ActiveSupport::Duration, nil] Time-to-live in seconds (for :time strategy)
+    # @param cache_proc [Proc, nil] Custom cache proc (for :proc strategy)
+    # @param scoping_strategy [Symbol, nil] CSS scoping strategy: :selector_patching (default) or :nesting
+    # @param head_rendering [Boolean, nil] Enable head rendering (default: true if any option is set, false otherwise)
+    # @param tag [Symbol, String, nil] HTML tag name for wrapper element (default: :div)
+    # @return [void]
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- DSL configures multiple optional class settings
+    def style_capsule(namespace: nil, cache_strategy: nil, cache_ttl: nil, cache_proc: nil, scoping_strategy: nil, head_rendering: nil, tag: nil)
+      # Set namespace (stored in instance variable, but getter checks parent class for inheritance)
+      if namespace
+        @stylesheet_namespace = namespace
+      end
+
+      # Configure cache strategy if provided
+      if cache_strategy || cache_ttl || cache_proc
+        normalized_strategy, normalized_proc = normalize_cache_strategy(cache_strategy || :none, cache_proc)
+        @inline_cache_strategy = normalized_strategy
+        # Explicitly set cache_ttl (even if nil) to override parent's value when cache settings are changed
+        @inline_cache_ttl = cache_ttl
+        @inline_cache_proc = normalized_proc
+      end
+
+      # Configure CSS scoping strategy if provided
+      if scoping_strategy
+        unless [:selector_patching, :nesting].include?(scoping_strategy)
+          raise ArgumentError, "scoping_strategy must be :selector_patching or :nesting (got: #{scoping_strategy.inspect})"
+        end
+        @css_scoping_strategy = scoping_strategy
+      end
+
+      # Configure wrapper tag if provided
+      if tag
+        @wrapper_tag = tag
+      end
+
+      # Enable head rendering if explicitly set or if any option is provided (except scoping_strategy)
+      if head_rendering.nil?
+        @head_rendering = true if namespace || cache_strategy || cache_ttl || cache_proc
+      else
+        @head_rendering = head_rendering
+      end
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+    # Get the custom scope ID if set (alias for capsule_id getter)
+    def custom_capsule_id
+      @custom_capsule_id if defined?(@custom_capsule_id)
+    end
+
+    # Get inline cache strategy (checks instance variable, then parent class, defaults to nil)
+    #
+    # @return [Symbol, nil] The cache strategy (default: nil)
+    def inline_cache_strategy
+      if defined?(@inline_cache_strategy) && @inline_cache_strategy
+        @inline_cache_strategy
+      elsif superclass.respond_to?(:inline_cache_strategy, true)
+        superclass.inline_cache_strategy
+      end
+    end
+
+    # Get inline cache TTL (checks instance variable, then parent class, defaults to nil)
+    #
+    # @return [Integer, ActiveSupport::Duration, nil] The cache TTL (default: nil)
+    def inline_cache_ttl
+      if defined?(@inline_cache_ttl)
+        @inline_cache_ttl
+      elsif superclass.respond_to?(:inline_cache_ttl, true)
+        superclass.inline_cache_ttl
+      end
+    end
+
+    # Get inline cache proc (checks instance variable, then parent class, defaults to nil)
+    #
+    # @return [Proc, nil] The cache proc (default: nil)
+    def inline_cache_proc
+      if defined?(@inline_cache_proc)
+        @inline_cache_proc
+      elsif superclass.respond_to?(:inline_cache_proc, true)
+        superclass.inline_cache_proc
+      end
+    end
+
+    public :head_rendering?, :stylesheet_namespace, :style_capsule, :custom_capsule_id, :inline_cache_strategy, :inline_cache_ttl, :inline_cache_proc
+
+    # Get CSS scoping strategy (checks instance variable, then parent class, defaults to :selector_patching)
+    #
+    # @return [Symbol] The current scoping strategy (default: :selector_patching)
+    def css_scoping_strategy
+      if defined?(@css_scoping_strategy) && @css_scoping_strategy
+        @css_scoping_strategy
+      elsif superclass.respond_to?(:css_scoping_strategy, true)
+        superclass.css_scoping_strategy
+      else
+        :selector_patching
+      end
+    end
+
+    public :css_scoping_strategy
+
+    # Get wrapper tag (checks instance variable, then parent class, defaults to :div)
+    #
+    # @return [Symbol, String] The wrapper tag (default: :div)
+    def wrapper_tag
+      if defined?(@wrapper_tag) && @wrapper_tag
+        @wrapper_tag
+      elsif superclass.respond_to?(:wrapper_tag, true)
+        superclass.wrapper_tag
+      else
+        :div
+      end
+    end
+
+    public :wrapper_tag
+
+    # Set or get options for stylesheet_link_tag when using file-based caching
+    #
+    # @param options [Hash, nil] Options to pass to stylesheet_link_tag (e.g., "data-turbo-track": "reload", omit to get current value)
+    # @return [Hash, nil] The current stylesheet link options if no argument provided
+    def stylesheet_link_options(options = nil)
+      if options.nil?
+        @stylesheet_link_options if defined?(@stylesheet_link_options)
+      else
+        @stylesheet_link_options = options
+      end
+    end
+
+    public :stylesheet_link_options
+  end
+end