style_capsule 1.3.0 → 2.0.0

data/lib/style_capsule/standalone_helper.rb

@@ -2,6 +2,7 @@
 
 require "digest/sha1"
 require "cgi"
+require_relative "helper_scope_cache"
 
 module StyleCapsule
   # Standalone helper module for use without Rails
@@ -27,6 +28,8 @@ module StyleCapsule
   #     "<style>.section { color: red; }</style><div class='section'>Content</div>"
   #   end
   module StandaloneHelper
+    include HelperScopeCache
+
     # Maximum HTML content size (10MB) to prevent DoS attacks
     MAX_HTML_SIZE = 10_000_000
 
@@ -40,16 +43,7 @@ module StyleCapsule
 
     # Scope CSS content and return scoped CSS
     def scope_css(css_content, capsule_id)
-      # Use thread-local cache to avoid reprocessing
-      cache_key = "style_capsule_#{capsule_id}"
-
-      if Thread.current[cache_key]
-        return Thread.current[cache_key]
-      end
-
-      scoped_css = CssProcessor.scope_selectors(css_content, capsule_id)
-      Thread.current[cache_key] = scoped_css
-      scoped_css
+      scope_css_with_bounded_cache(css_content, capsule_id)
     end
 
     # Generate HTML tag without Rails helpers
@@ -59,6 +53,7 @@ module StyleCapsule
     # @param options [Hash] HTML attributes
     # @param block [Proc] Block for tag content
     # @return [String] HTML string
+    # rubocop:disable Metrics/AbcSize -- serializes flat and nested HTML attributes
     def content_tag(tag, content = nil, **options, &block)
       tag_name = tag.to_s
       content = capture(&block) if block_given? && content.nil?
@@ -76,6 +71,7 @@ module StyleCapsule
       attrs = " #{attrs}" unless attrs.empty?
       "<#{tag_name}#{attrs}>#{content}</#{tag_name}>"
     end
+    # rubocop:enable Metrics/AbcSize
 
     # Capture block content (simplified version without Rails)
     #
@@ -114,7 +110,8 @@ module StyleCapsule
     # @param capsule_id [String, nil] Optional capsule ID
     # @param content_block [Proc] Block containing HTML content
     # @return [String] HTML with scoped CSS and wrapped content
-    def style_capsule(css_content = nil, capsule_id: nil, &content_block)
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- standalone helper mirrors Rails helper flow
+    def style_capsule(css_content = nil, capsule_id: nil, tag: :div, &content_block)
       html_content = nil
 
       # If CSS content is provided as argument, use it
@@ -127,13 +124,8 @@ module StyleCapsule
           raise ArgumentError, "HTML content exceeds maximum size of #{MAX_HTML_SIZE} bytes (got #{full_content.bytesize} bytes)"
         end
 
-        # Extract <style> tags from content
-        style_match = full_content.match(/<style[^>]*>(.*?)<\/style>/m)
-        if style_match
-          css_content = style_match[1]
-          html_content = full_content.sub(/<style[^>]*>.*?<\/style>/m, "").strip
-        else
-          css_content = nil
+        html_content, css_content = extract_styles_from_markup(full_content)
+        if css_content.nil?
           html_content = full_content
         end
       elsif css_content && block_given?
@@ -156,10 +148,11 @@ module StyleCapsule
 
       # Render style tag and wrapped content
       style_tag = content_tag(:style, raw(scoped_css), type: "text/css")
-      wrapped_content = content_tag(:div, raw(html_content), data: {capsule: capsule_id})
+      wrapped_content = content_tag(tag, raw(html_content), data: {capsule: capsule_id})
 
       html_safe(style_tag + wrapped_content)
     end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
     # Register a stylesheet file for head rendering
     #
@@ -179,10 +172,6 @@ module StyleCapsule
       StyleCapsule::StylesheetRegistry.render_head_stylesheets(self, namespace: namespace)
     end
 
-    # @deprecated Use {#stylesheet_registry_tags} instead.
-    #   This method name will be removed in a future version.
-    alias_method :stylesheet_registrymap_tags, :stylesheet_registry_tags
-
     private
 
     # Escape HTML attribute value

data/lib/style_capsule/stylesheet_registry.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "instrumentation"
+require_relative "asset_path"
+
 module StyleCapsule
   # Helper to determine the parent class for StylesheetRegistry
   # ActiveSupport::CurrentAttributes is optional - if ActiveSupport is loaded,
@@ -13,10 +16,13 @@ module StyleCapsule
 
   # Hybrid registry for stylesheet files that need to be injected into <head>
   #
-  # Uses a process-wide manifest for static file paths (like Propshaft) and request-scoped
-  # storage for inline CSS. This approach:
-  # - Collects static file paths once per process (no rebuilding on each request)
-  # - Stores inline CSS per-request (since it's component-specific)
+  # Uses a process-wide manifest for eager registrations, request-scoped storage for
+  # render-time file paths and inline CSS, and optional Rack middleware to inject
+  # stylesheets registered during body rendering into +<head>+ on the same request.
+  #
+  # This approach:
+  # - Keeps eager file paths in a process-wide manifest (class load / boot time)
+  # - Stores render-time file paths and inline CSS per request
   # - Works correctly with both threaded and forked web servers (Puma, Unicorn, etc.)
   #
   # Supports namespaces for separation of stylesheets (e.g., "admin", "user", "public").
@@ -33,9 +39,12 @@ module StyleCapsule
   #     end
   #   end
   #
-  # @example Register a stylesheet file manually (default namespace)
+  # @example Register a stylesheet during rendering (request-scoped)
   #   StyleCapsule::StylesheetRegistry.register('stylesheets/my_component')
   #
+  # @example Register a stylesheet eagerly at boot or class load (process-wide manifest)
+  #   StyleCapsule::StylesheetRegistry.register_eager('stylesheets/my_component', namespace: :user)
+  #
   # @example Register a stylesheet with a namespace
   #   StyleCapsule::StylesheetRegistry.register('stylesheets/admin/dashboard', namespace: :admin)
   #
@@ -65,20 +74,21 @@ module StyleCapsule
     DEFAULT_NAMESPACE = :default
 
     # Process-wide manifest for static file paths (like Propshaft)
-    # Organized by namespace: { namespace => Set of {file_path, options} hashes }
-    @manifest = {} # rubocop:disable Style/ClassVars
+    # Organized by namespace: { namespace => { logical_path => { file_path:, options: } } }
+    @manifest = {} # rubocop:disable Style/ClassVars, ThreadSafety/MutableClassInstanceVariable
 
     # Process-wide cache for inline CSS (with expiration support)
     # Structure: { cache_key => { css_content: String, cached_at: Time, expires_at: Time } }
-    @inline_cache = {} # rubocop:disable Style/ClassVars
+    @inline_cache = {} # rubocop:disable Style/ClassVars, ThreadSafety/MutableClassInstanceVariable
 
     # Track last cleanup time for lazy cleanup (prevents excessive cleanup calls)
     @last_cleanup_time = nil # rubocop:disable Style/ClassVars
 
-    # Request-scoped storage for inline CSS only
+    # Request-scoped storage for inline CSS and render-time file registrations
     # Only define attribute if we're inheriting from CurrentAttributes
     if defined?(ActiveSupport::CurrentAttributes) && self < ActiveSupport::CurrentAttributes
       attribute :inline_stylesheets
+      attribute :request_file_stylesheets
     end
 
     class << self
@@ -125,19 +135,41 @@ module StyleCapsule
         end
       end
 
+      # Get request-scoped file stylesheets (thread-local fallback if not using CurrentAttributes)
+      def request_file_stylesheets
+        if using_current_attributes?
+          inst = instance
+          inst&.request_file_stylesheets || {}
+        else
+          Thread.current[:style_capsule_request_file_stylesheets] ||= {}
+        end
+      end
+
+      # Set request-scoped file stylesheets (thread-local fallback if not using CurrentAttributes)
+      def request_file_stylesheets=(value)
+        if using_current_attributes?
+          inst = instance
+          inst.request_file_stylesheets = value if inst
+        else
+          Thread.current[:style_capsule_request_file_stylesheets] = value
+        end
+      end
+
       # Get instance (for CurrentAttributes compatibility)
       def instance
         if using_current_attributes?
           # Call the CurrentAttributes instance method from parent class
           super
         else
-          # Return a simple object that responds to inline_stylesheets
+          # Return a simple object that responds to request-scoped attributes
           # This is mainly for compatibility with code that might call instance.inline_stylesheets
           registry_class = self
           @_standalone_instance ||= begin
             obj = Object.new
             obj.define_singleton_method(:inline_stylesheets) { registry_class.inline_stylesheets }
             obj.define_singleton_method(:inline_stylesheets=) { |v| registry_class.inline_stylesheets = v }
+            obj.define_singleton_method(:request_file_stylesheets) { registry_class.request_file_stylesheets }
+            obj.define_singleton_method(:request_file_stylesheets=) { |v| registry_class.request_file_stylesheets = v }
             obj
           end
         end
@@ -155,33 +187,65 @@ module StyleCapsule
       namespace.to_sym
     end
 
-    # Register a stylesheet file path for head rendering
+    # Register a stylesheet file path during rendering (request-scoped).
     #
-    # Static file paths are stored in process-wide manifest (collected once per process).
-    # This is similar to Propshaft's manifest approach - files are static, so we can
-    # collect them process-wide without rebuilding on each request.
+    # Render-time registrations are stored per request and emitted by
+    # +render_head_stylesheets+ when the layout head runs before the body, or by
+    # +HeadInjectionMiddleware+ when components register stylesheets later in the response.
     #
     # Files registered here are served through Rails asset pipeline (via stylesheet_link_tag).
-    # This includes both:
-    # - Pre-built files from assets:precompile (already in asset pipeline)
-    # - Dynamically written files (written during runtime, also served through asset pipeline)
-    #
-    # The Set automatically deduplicates entries, so registering the same file multiple times
-    # (e.g., when the same component renders multiple times) is safe and efficient.
     #
     # @param file_path [String] Path to stylesheet (relative to app/assets/stylesheets)
     # @param namespace [Symbol, String, nil] Optional namespace for separation (nil/blank uses default)
     # @param options [Hash] Options for stylesheet_link_tag
     # @return [void]
     def self.register(file_path, namespace: nil, **options)
+      register_request_file(file_path, namespace: namespace, **options)
+    end
+
+    # Register a stylesheet file path eagerly (process-wide manifest).
+    #
+    # Use at class load or boot time when the stylesheet should always be available in
+    # +render_head_stylesheets+ without waiting for a component render.
+    #
+    # @param file_path [String] Path to stylesheet (relative to app/assets/stylesheets)
+    # @param namespace [Symbol, String, nil] Optional namespace for separation (nil/blank uses default)
+    # @param options [Hash] Options for stylesheet_link_tag
+    # @return [void]
+    def self.register_eager(file_path, namespace: nil, **options)
       ns = normalize_namespace(namespace)
-      @manifest[ns] ||= Set.new
-      # Use a hash with file_path and options as the key to avoid duplicates
-      # Set will automatically deduplicate based on hash equality
-      entry = {file_path: file_path, options: options}
-      @manifest[ns] << entry
+      path = AssetPath.validate_logical_path!(file_path)
+
+      Instrumentation.instrument_registration(
+        namespace: ns,
+        file_path: path,
+        inline_size: nil,
+        cache_strategy: :none
+      ) do
+        @manifest[ns] ||= {}
+        @manifest[ns][path] = {file_path: path, options: options}
+      end
     end
 
+    # @api private
+    def self.register_request_file(file_path, namespace: nil, **options)
+      ns = normalize_namespace(namespace)
+      path = AssetPath.validate_logical_path!(file_path)
+
+      Instrumentation.instrument_registration(
+        namespace: ns,
+        file_path: path,
+        inline_size: nil,
+        cache_strategy: :none
+      ) do
+        registry = request_file_stylesheets
+        registry[ns] ||= {}
+        registry[ns][path] = {file_path: path, options: options}
+        self.request_file_stylesheets = registry
+      end
+    end
+    private_class_method :register_request_file
+
     # Register inline CSS for head rendering
     #
     # Inline CSS can be cached based on cache configuration. Supports:
@@ -201,6 +265,7 @@ module StyleCapsule
     # @param component_class [Class, nil] Component class (for :file strategy)
     # @param stylesheet_link_options [Hash, nil] Options for stylesheet_link_tag (for :file strategy)
     # @return [void]
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- coordinates file, inline, and cache registration
     def self.register_inline(css_content, namespace: nil, capsule_id: nil, cache_key: nil, cache_strategy: :none, cache_ttl: nil, cache_proc: nil, component_class: nil, stylesheet_link_options: nil)
       ns = normalize_namespace(namespace)
 
@@ -215,7 +280,7 @@ module StyleCapsule
 
         if existing_path
           # File exists (pre-built or previously written), register it as a file path
-          # The Set in @manifest will deduplicate if the same file is registered multiple times
+          # The manifest deduplicates by logical path if the same file is registered multiple times
           # This file will be served through Rails asset pipeline (stylesheet_link_tag)
           link_options = stylesheet_link_options || {}
           register(existing_path, namespace: namespace, **link_options)
@@ -248,21 +313,28 @@ module StyleCapsule
       # Use cached CSS if available, otherwise use provided CSS
       final_css = cached_css || css_content
 
-      # Store in request-scoped registry
-      registry = inline_stylesheets
-      registry[ns] ||= []
-      registry[ns] << {
-        type: :inline,
-        css_content: final_css,
-        capsule_id: capsule_id
-      }
-      self.inline_stylesheets = registry
+      Instrumentation.instrument_registration(
+        namespace: ns,
+        file_path: nil,
+        inline_size: final_css.bytesize,
+        cache_strategy: cache_strategy
+      ) do
+        registry = inline_stylesheets
+        registry[ns] ||= []
+        registry[ns] << {
+          type: :inline,
+          css_content: final_css,
+          capsule_id: capsule_id
+        }
+        self.inline_stylesheets = registry
+      end
 
       # Cache the CSS if strategy is enabled and not already cached
       if cache_strategy != :none && cache_key && !cached_css && cache_strategy != :file
         cache_inline_css(cache_key, css_content, cache_strategy: cache_strategy, cache_ttl: cache_ttl, cache_proc: cache_proc, capsule_id: capsule_id, namespace: ns)
       end
     end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
     # Get cached inline CSS if available and not expired
     #
@@ -291,7 +363,9 @@ module StyleCapsule
         return nil if cache_ttl && cached_entry[:expires_at] && current_time > cached_entry[:expires_at]
       when :proc
         return nil unless cache_proc
-        # Proc should validate cache entry
+        # Re-validation: the proc is invoked on every read with the *current* request's CSS.
+        # Return [_, true, _] from the proc to keep using the cached entry; false invalidates it.
+        # (This is closer to a conditional cache than a blind key/value store.)
         _key, should_use, _expires = cache_proc.call(css_content, capsule_id, namespace)
         return nil unless should_use
       end
@@ -401,9 +475,9 @@ module StyleCapsule
 
     # Get all registered file paths from process-wide manifest (organized by namespace)
     #
-    # @return [Hash<Symbol, Set<Hash>>] Hash of namespace => set of file registrations
+    # @return [Hash<Symbol, Array<Hash>>] Hash of namespace => array of file registrations
     def self.manifest_files
-      @manifest.dup
+      @manifest.transform_values { |h| h.values }
     end
 
     # Get all registered inline stylesheets for current request (organized by namespace)
@@ -413,38 +487,51 @@ module StyleCapsule
       inline_stylesheets
     end
 
+    # Get all request-scoped file stylesheets for the current request (organized by namespace)
+    #
+    # @return [Hash<Symbol, Hash<String, Hash>>] Hash of namespace => logical path => registration
+    def self.request_stylesheet_files
+      request_file_stylesheets
+    end
+
     # Get all stylesheets (files + inline) for a specific namespace
     #
     # @param namespace [Symbol, String, nil] Namespace identifier (nil/blank uses default)
     # @return [Array<Hash>] Array of stylesheet registrations for the namespace
     def self.stylesheets_for(namespace: nil)
       ns = normalize_namespace(namespace)
-      result = []
-
-      # Add process-wide file paths
-      if @manifest[ns]
-        result.concat(@manifest[ns].to_a)
-      end
+      result = merged_file_registrations_for_namespace(ns)
 
-      # Add request-scoped inline CSS
       inline = request_inline_stylesheets[ns] || []
       result.concat(inline)
 
       result
     end
 
-    # Clear request-scoped inline stylesheets (does not clear process-wide manifest)
+    # Whether request-scoped stylesheets remain to inject into +<head>+
+    #
+    # @return [Boolean]
+    def self.pending_head_stylesheets?
+      !pending_request_stylesheets.empty?
+    end
+
+    # Clear request-scoped inline CSS and render-time file registrations (does not clear process-wide manifest)
     #
     # @param namespace [Symbol, String, nil] Optional namespace to clear (nil clears all)
     # @return [void]
     def self.clear(namespace: nil)
       if namespace.nil?
         self.inline_stylesheets = {}
+        self.request_file_stylesheets = {}
       else
         ns = normalize_namespace(namespace)
-        registry = inline_stylesheets
-        registry.delete(ns)
-        self.inline_stylesheets = registry
+        inline_registry = inline_stylesheets
+        inline_registry.delete(ns)
+        self.inline_stylesheets = inline_registry
+
+        file_registry = request_file_stylesheets
+        file_registry.delete(ns)
+        self.request_file_stylesheets = file_registry
       end
     end
 
@@ -464,8 +551,12 @@ module StyleCapsule
     # Render registered stylesheets as HTML
     #
     # This should be called in the layout's <head> section.
-    # Combines process-wide file manifest with request-scoped inline CSS.
-    # Automatically clears request-scoped inline CSS after rendering (manifest persists).
+    # Combines eager manifest files with request-scoped file paths and inline CSS
+    # registered before this call. Stylesheets registered later in the response are
+    # injected into +<head>+ by +HeadInjectionMiddleware+ when enabled.
+    #
+    # Automatically clears request-scoped inline CSS and file paths after rendering
+    # for the selected namespace(s). The eager manifest persists.
     #
     # @param view_context [ActionView::Base, nil] The view context (for helpers like content_tag, stylesheet_link_tag)
     #   In ERB: pass `self` (the view context)
@@ -473,22 +564,16 @@ module StyleCapsule
     #   If nil, falls back to basic HTML generation
     # @param namespace [Symbol, String, nil] Optional namespace to render (nil/blank renders all namespaces)
     # @return [String] HTML-safe string with stylesheet tags
+    # rubocop:disable Metrics/AbcSize, Metrics/PerceivedComplexity -- renders mixed inline and file registrations
     def self.render_head_stylesheets(view_context = nil, namespace: nil)
       if namespace.nil? || namespace.to_s.strip.empty?
-        # Render all namespaces
-        all_stylesheets = []
+        all_stylesheets = merged_file_registrations_all_namespaces
 
-        # Collect from process-wide manifest (all namespaces)
-        @manifest.each do |ns, files|
-          all_stylesheets.concat(files.to_a)
-        end
-
-        # Collect from request-scoped inline CSS (all namespaces)
         request_inline_stylesheets.each do |_ns, inline|
           all_stylesheets.concat(inline)
         end
 
-        clear # Clear request-scoped inline CSS only
+        clear # Clear request-scoped inline CSS and file paths only
         return safe_string("") if all_stylesheets.empty?
 
         all_stylesheets.map do |stylesheet|
@@ -503,7 +588,7 @@ module StyleCapsule
         # Render specific namespace
         ns = normalize_namespace(namespace)
         stylesheets = stylesheets_for(namespace: ns).dup
-        clear(namespace: ns) # Clear request-scoped inline CSS only
+        clear(namespace: ns) # Clear request-scoped inline CSS and file paths only
 
         return safe_string("") if stylesheets.empty?
 
@@ -517,28 +602,123 @@ module StyleCapsule
 
       end
     end
+    # rubocop:enable Metrics/AbcSize, Metrics/PerceivedComplexity
 
     # Check if there are any registered stylesheets
     #
     # @param namespace [Symbol, String, nil] Optional namespace to check (nil checks all)
     # @return [Boolean]
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- checks manifest and request-scoped registries
     def self.any?(namespace: nil)
       if namespace.nil?
         # Check process-wide manifest
         has_files = !@manifest.empty? && @manifest.values.any? { |files| !files.empty? }
+        # Check request-scoped file paths
+        request_files = request_file_stylesheets
+        has_request_files = !request_files.empty? && request_files.values.any? { |files| !files.empty? }
         # Check request-scoped inline CSS
         inline = request_inline_stylesheets
         has_inline = !inline.empty? && inline.values.any? { |stylesheets| !stylesheets.empty? }
-        has_files || has_inline
+        has_files || has_request_files || has_inline
       else
         ns = normalize_namespace(namespace)
         # Check process-wide manifest
         has_files = @manifest[ns] && !@manifest[ns].empty?
+        # Check request-scoped file paths
+        has_request_files = request_file_stylesheets[ns] && !request_file_stylesheets[ns].empty?
         # Check request-scoped inline CSS
         has_inline = request_inline_stylesheets[ns] && !request_inline_stylesheets[ns].empty?
-        !!(has_files || has_inline)
+        !!(has_files || has_request_files || has_inline)
+      end
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+    # Inject pending request-scoped stylesheets into an HTML document before +</head>+.
+    #
+    # Used by +HeadInjectionMiddleware+ after the body has rendered and components have
+    # called +register_stylesheet+ or +register_inline+.
+    #
+    # @param html [String] Full HTML response body
+    # @param view_context [ActionView::Base, nil] View context for +stylesheet_link_tag+
+    # @return [String] HTML with pending stylesheet tags injected, or the original HTML
+    def self.inject_pending_head_stylesheets(html, view_context = nil)
+      pending_stylesheets = pending_request_stylesheets
+      return html if pending_stylesheets.empty?
+
+      closing_head_index = html.match(%r{</head>}i)&.begin(0)
+      return html unless closing_head_index
+
+      tags = render_stylesheet_tags(pending_stylesheets, view_context)
+      return html if tags.empty?
+
+      injected = html.dup
+      injected.insert(closing_head_index, "#{tags}\n")
+      clear
+      injected
+    end
+
+    # @api private
+    def self.merged_file_registrations_for_namespace(namespace)
+      merge_file_registrations(@manifest[namespace], request_file_stylesheets[namespace])
+    end
+
+    # @api private
+    def self.merged_file_registrations_all_namespaces
+      merged = {}
+
+      @manifest.each do |ns, files|
+        files.each_value do |entry|
+          merged[[ns, entry[:file_path]]] = entry
+        end
       end
+
+      request_file_stylesheets.each do |ns, files|
+        files.each_value do |entry|
+          merged[[ns, entry[:file_path]]] = entry
+        end
+      end
+
+      merged.values
+    end
+
+    # @api private
+    def self.merge_file_registrations(eager_files, request_files)
+      merged = {}
+      eager_files&.each_value { |entry| merged[entry[:file_path]] = entry }
+      request_files&.each_value { |entry| merged[entry[:file_path]] = entry }
+      merged.values
+    end
+
+    # @api private
+    def self.pending_request_stylesheets
+      stylesheets = []
+
+      request_file_stylesheets.each_value do |files|
+        stylesheets.concat(files.values)
+      end
+
+      request_inline_stylesheets.each_value do |inline_styles|
+        stylesheets.concat(inline_styles)
+      end
+
+      stylesheets
+    end
+
+    # @api private
+    def self.render_stylesheet_tags(stylesheets, view_context)
+      return safe_string("") if stylesheets.empty?
+
+      stylesheets.map do |stylesheet|
+        if stylesheet[:type] == :inline
+          render_inline_stylesheet(stylesheet, view_context)
+        else
+          render_file_stylesheet(stylesheet, view_context)
+        end
+      end.join("\n").then { |output| safe_string(output) }.to_s
     end
+    private_class_method :pending_request_stylesheets, :render_stylesheet_tags,
+      :merged_file_registrations_for_namespace, :merged_file_registrations_all_namespaces,
+      :merge_file_registrations
 
     # Render a file-based stylesheet
     def self.render_file_stylesheet(stylesheet, view_context)
@@ -548,7 +728,7 @@ module StyleCapsule
       if view_context&.respond_to?(:stylesheet_link_tag)
         view_context.stylesheet_link_tag(file_path, **options)
       else
-        # Fallback if no view context
+        # Fallback if no view context (logical path validated in .register)
         href = "/assets/#{file_path}.css"
         tag_options = options.map { |k, v| %(#{k}="#{v}") }.join(" ")
         safe_string(%(<link rel="stylesheet" href="#{href}"#{" #{tag_options}" unless tag_options.empty?}>))

data/lib/style_capsule/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StyleCapsule
-  VERSION = "1.3.0"
+  VERSION = "2.0.0"
 end