style_capsule 1.0.2

data/lib/style_capsule/css_file_writer.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "digest/sha1"
+
+module StyleCapsule
+  # Writes inline CSS to files for HTTP caching
+  #
+  # This allows inline CSS to be cached by browsers and CDNs, improving performance.
+  # Files are written to a configurable output directory and can be precompiled
+  # via Rails asset pipeline.
+  #
+  # @example Configuration
+  #   StyleCapsule::CssFileWriter.configure(
+  #     output_dir: Rails.root.join(StyleCapsule::CssFileWriter::DEFAULT_OUTPUT_DIR),
+  #     filename_pattern: ->(component_class, capsule_id) { "capsule-#{capsule_id}.css" }
+  #   )
+  #
+  # @example Usage
+  #   file_path = StyleCapsule::CssFileWriter.write_css(
+  #     css_content: ".section { color: red; }",
+  #     component_class: MyComponent,
+  #     capsule_id: "abc123"
+  #   )
+  #   # => "capsules/capsule-abc123"
+  class CssFileWriter
+    # Default output directory for CSS files (relative to Rails root)
+    DEFAULT_OUTPUT_DIR = "app/assets/builds/capsules"
+
+    class << self
+      attr_accessor :output_dir, :filename_pattern, :enabled
+
+      # Configure CSS file writer
+      #
+      # @param output_dir [String, Pathname] Directory to write CSS files (relative to Rails root or absolute)
+      #   Default: `StyleCapsule::CssFileWriter::DEFAULT_OUTPUT_DIR`
+      # @param filename_pattern [Proc, nil] Proc to generate filename
+      #   Receives: (component_class, capsule_id) and should return filename string
+      #   Default: `"capsule-#{capsule_id}.css"` (capsule_id is unique and deterministic)
+      # @param enabled [Boolean] Whether file writing is enabled (default: true)
+      # @example
+      #   StyleCapsule::CssFileWriter.configure(
+      #     output_dir: Rails.root.join(StyleCapsule::CssFileWriter::DEFAULT_OUTPUT_DIR),
+      #     filename_pattern: ->(klass, capsule) { "capsule-#{capsule}.css" }
+      #   )
+      # @example Custom pattern with component name
+      #   StyleCapsule::CssFileWriter.configure(
+      #     filename_pattern: ->(klass, capsule) { "#{klass.name.underscore}-#{capsule}.css" }
+      #   )
+      def configure(output_dir: nil, filename_pattern: nil, enabled: true)
+        @enabled = enabled
+
+        @output_dir = if output_dir
+          output_dir.is_a?(Pathname) ? output_dir : Pathname.new(output_dir.to_s)
+        elsif defined?(Rails) && Rails.root
+          Rails.root.join(DEFAULT_OUTPUT_DIR)
+        else
+          Pathname.new(DEFAULT_OUTPUT_DIR)
+        end
+
+        @filename_pattern = filename_pattern || default_filename_pattern
+      end
+
+      # Write CSS content to file
+      #
+      # @param css_content [String] CSS content to write
+      # @param component_class [Class] Component class that generated the CSS
+      # @param capsule_id [String] Capsule ID for the component
+      # @return [String, nil] Relative file path (for stylesheet_link_tag) or nil if disabled
+      def write_css(css_content:, component_class:, capsule_id:)
+        return nil unless enabled?
+
+        ensure_output_directory
+
+        filename = generate_filename(component_class, capsule_id)
+        file_path = output_directory.join(filename)
+
+        # Write CSS to file with explicit UTF-8 encoding
+        File.write(file_path, css_content, encoding: "UTF-8")
+
+        # Return relative path for stylesheet_link_tag
+        # Path should be relative to app/assets
+        # Handle case where output directory is not under rails_assets_root (e.g., in tests)
+        begin
+          file_path.relative_path_from(rails_assets_root).to_s.gsub(/\.css$/, "")
+        rescue ArgumentError
+          # If paths don't share a common prefix (e.g., in tests), return just the filename
+          filename.gsub(/\.css$/, "")
+        end
+      end
+
+      # Check if file exists for given component and capsule
+      #
+      # @param component_class [Class] Component class
+      # @param capsule_id [String] Capsule ID
+      # @return [Boolean]
+      def file_exists?(component_class:, capsule_id:)
+        return false unless enabled?
+
+        filename = generate_filename(component_class, capsule_id)
+        file_path = output_directory.join(filename)
+        File.exist?(file_path)
+      end
+
+      # Get file path for given component and capsule
+      #
+      # @param component_class [Class] Component class
+      # @param capsule_id [String] Capsule ID
+      # @return [String, nil] Relative file path or nil if disabled
+      def file_path_for(component_class:, capsule_id:)
+        return nil unless enabled?
+
+        filename = generate_filename(component_class, capsule_id)
+        file_path = output_directory.join(filename)
+
+        return nil unless File.exist?(file_path)
+
+        # Return relative path for stylesheet_link_tag
+        # Handle case where output directory is not under rails_assets_root (e.g., in tests)
+        begin
+          file_path.relative_path_from(rails_assets_root).to_s.gsub(/\.css$/, "")
+        rescue ArgumentError
+          # If paths don't share a common prefix (e.g., in tests), return just the filename
+          filename.gsub(/\.css$/, "")
+        end
+      end
+
+      # Ensure output directory exists
+      #
+      # @return [void]
+      def ensure_output_directory
+        return unless enabled?
+
+        dir = output_directory
+        FileUtils.mkdir_p(dir) unless Dir.exist?(dir)
+      end
+
+      # Clear all generated CSS files
+      #
+      # @return [void]
+      def clear_files
+        return unless enabled?
+
+        dir = output_directory
+        return unless Dir.exist?(dir)
+
+        Dir.glob(dir.join("*.css")).each { |file| File.delete(file) }
+      end
+
+      # Check if file writing is enabled
+      #
+      # @return [Boolean]
+      def enabled?
+        @enabled != false
+      end
+
+      private
+
+      # Get output directory (with default)
+      def output_directory
+        @output_dir ||= if defined?(Rails) && Rails.root
+          Rails.root.join(DEFAULT_OUTPUT_DIR)
+        else
+          Pathname.new(DEFAULT_OUTPUT_DIR)
+        end
+      end
+
+      # Generate filename using pattern
+      #
+      # @param component_class [Class] Component class
+      # @param capsule_id [String] Capsule ID
+      # @return [String] Validated filename
+      # @raise [SecurityError] If filename contains path traversal or invalid characters
+      def generate_filename(component_class, capsule_id)
+        pattern_result = filename_pattern.call(component_class, capsule_id)
+        # Ensure .css extension
+        filename = pattern_result.end_with?(".css") ? pattern_result : "#{pattern_result}.css"
+
+        # Validate filename to prevent path traversal attacks
+        validate_filename!(filename)
+
+        filename
+      end
+
+      # Default filename pattern
+      #
+      # Uses only the capsule_id since it's unique and deterministic.
+      # The capsule_id is generated from the component class name using SHA1,
+      # ensuring uniqueness while keeping filenames concise and not exposing
+      # internal component structure.
+      #
+      # @return [Proc] Proc that generates filename from (component_class, capsule_id)
+      def default_filename_pattern
+        ->(component_class, capsule_id) do
+          # Validate capsule_id is safe (alphanumeric, hyphens, underscores only)
+          # This ensures the filename is safe even if capsule_id generation changes
+          safe_capsule_id = capsule_id.to_s.gsub(/[^a-zA-Z0-9_-]/, "")
+
+          if safe_capsule_id.empty?
+            raise ArgumentError, "Invalid capsule_id: must contain at least one alphanumeric character"
+          end
+
+          "capsule-#{safe_capsule_id}.css"
+        end
+      end
+
+      # Get Rails assets root (app/assets)
+      def rails_assets_root
+        if defined?(Rails) && Rails.root
+          Rails.root.join("app/assets")
+        else
+          Pathname.new("app/assets")
+        end
+      end
+
+      # Validate filename to prevent path traversal and other security issues
+      #
+      # @param filename [String] Filename to validate
+      # @raise [SecurityError] If filename is invalid
+      def validate_filename!(filename)
+        # Reject path traversal attempts
+        if filename.include?("..") || filename.include?("/") || filename.include?("\\")
+          raise SecurityError, "Invalid filename: path traversal detected in '#{filename}'"
+        end
+
+        # Reject null bytes
+        if filename.include?("\0")
+          raise SecurityError, "Invalid filename: null byte detected"
+        end
+
+        # Ensure filename is reasonable length (filesystem limit is typically 255)
+        if filename.length > 255
+          raise SecurityError, "Invalid filename: too long (max 255 characters, got #{filename.length})"
+        end
+
+        # Ensure filename contains only safe characters (alphanumeric, dots, hyphens, underscores)
+        # Must end with .css extension
+        unless filename.match?(/\A[a-zA-Z0-9._-]+\.css\z/)
+          raise SecurityError, "Invalid filename: contains unsafe characters (only alphanumeric, dots, hyphens, underscores allowed, must end with .css)"
+        end
+      end
+    end
+  end
+end

data/lib/style_capsule/css_processor.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module StyleCapsule
+  # Shared CSS processing logic for scoping selectors with attribute selectors
+  #
+  # Supports two scoping strategies:
+  # 1. Selector patching (default): Adds [data-capsule="..."] prefix to each selector
+  #    - Better browser support (all modern browsers)
+  #    - Requires CSS parsing and transformation
+  # 2. CSS nesting (optional): Wraps entire CSS in [data-capsule="..."] { ... }
+  #    - More performant (no parsing needed)
+  #    - Requires CSS nesting support (Chrome 112+, Firefox 117+, Safari 16.5+)
+  module CssProcessor
+    # Maximum CSS content size (1MB) to prevent DoS attacks
+    MAX_CSS_SIZE = 1_000_000
+
+    # Rewrite CSS selectors to include attribute-based scoping
+    #
+    # Transforms:
+    #   .section { color: red; }
+    #   .heading:hover { opacity: 0.8; }
+    #
+    # Into:
+    #   [data-capsule="a1b2c3d4"] .section { color: red; }
+    #   [data-capsule="a1b2c3d4"] .heading:hover { opacity: 0.8; }
+    #
+    # This approach uses attribute selectors (similar to Angular's Emulated View Encapsulation)
+    # instead of renaming classes, ensuring styles only apply within scoped components.
+    #
+    # Simple approach:
+    # - Strips CSS comments first to avoid interference
+    # - Finds selectors before opening braces and prefixes them
+    # - Handles @media queries (preserves them, scopes inner selectors)
+    # - Handles :host and :host-context (component-scoped selectors)
+    #
+    # @param css_string [String] Original CSS content
+    # @param capsule_id [String] The capsule ID to use in attribute selector
+    # @return [String] CSS with scoped selectors
+    # @raise [ArgumentError] If CSS content exceeds maximum size or capsule_id is invalid
+    def self.scope_selectors(css_string, capsule_id)
+      return css_string if css_string.nil? || css_string.strip.empty?
+
+      # Validate CSS size to prevent DoS attacks
+      if css_string.bytesize > MAX_CSS_SIZE
+        raise ArgumentError, "CSS content exceeds maximum size of #{MAX_CSS_SIZE} bytes (got #{css_string.bytesize} bytes)"
+      end
+
+      # Validate capsule_id
+      validate_capsule_id!(capsule_id)
+
+      css = css_string.dup
+      capsule_attr = %([data-capsule="#{capsule_id}"])
+
+      # Strip CSS comments to avoid interference with selector matching
+      # Simple approach: remove /* ... */ comments (including multi-line)
+      css_without_comments = strip_comments(css)
+
+      # Process CSS rule by rule
+      # Match: selector(s) { ... }
+      # Pattern: (start or closing brace) + (whitespace) + (selector text) + (opening brace)
+      # Note: Uses non-greedy quantifier ([^{}@]+?) to minimize backtracking
+      # MAX_CSS_SIZE limit (1MB) mitigates ReDoS risk from malicious input
+      css_without_comments.gsub!(/(^|\})(\s*)([^{}@]+?)(\{)/m) do |_|
+        prefix = Regexp.last_match(1)  # Previous closing brace or start
+        whitespace = Regexp.last_match(2)  # Whitespace between rules
+        selectors_raw = Regexp.last_match(3)  # The selector group
+        selectors = selectors_raw.strip  # Stripped for processing
+        opening_brace = Regexp.last_match(4)  # The opening brace
+
+        # Skip at-rules (@media, @keyframes, etc.) - they should not be scoped at top level
+        next "#{prefix}#{whitespace}#{selectors_raw}#{opening_brace}" if selectors.start_with?("@")
+
+        # Skip if already scoped (avoid double-scoping)
+        next "#{prefix}#{whitespace}#{selectors_raw}#{opening_brace}" if selectors_raw.include?("[data-capsule=")
+
+        # Skip empty selectors
+        next "#{prefix}#{whitespace}#{selectors_raw}#{opening_brace}" if selectors.empty?
+
+        # Split selectors by comma and scope each one
+        scoped_selectors = selectors.split(",").map do |selector|
+          selector = selector.strip
+          next selector if selector.empty?
+
+          # Handle special component-scoped selectors (:host, :host-context)
+          if selector.start_with?(":host")
+            selector = selector
+              .gsub(/^:host-context\(([^)]+)\)/, "#{capsule_attr} \\1")
+              .gsub(/^:host\(([^)]+)\)/, "#{capsule_attr}\\1")
+              .gsub(/^:host\b/, capsule_attr)
+            selector
+          else
+            # Add capsule attribute with space before selector for descendant matching
+            # This ensures styles apply to elements inside the scoped wrapper
+            "#{capsule_attr} #{selector}"
+          end
+        end.compact.join(", ")
+
+        "#{prefix}#{whitespace}#{scoped_selectors}#{opening_brace}"
+      end
+
+      # Restore comments in their original positions
+      # Since we stripped comments, we need to put them back
+      # For simplicity, we'll just return the processed CSS without comments
+      # (comments are typically removed in production CSS anyway)
+      css_without_comments
+    end
+
+    # Scope CSS using CSS nesting (wraps entire CSS in [data-capsule] { ... })
+    #
+    # This approach is more performant as it requires no CSS parsing or transformation.
+    # However, it requires CSS nesting support in browsers (Chrome 112+, Firefox 117+, Safari 16.5+).
+    #
+    # Transforms:
+    #   .section { color: red; }
+    #   .heading:hover { opacity: 0.8; }
+    #
+    # Into:
+    #   [data-capsule="a1b2c3d4"] {
+    #     .section { color: red; }
+    #     .heading:hover { opacity: 0.8; }
+    #   }
+    #
+    # @param css_string [String] Original CSS content
+    # @param capsule_id [String] The capsule ID to use in attribute selector
+    # @return [String] CSS wrapped in nesting selector
+    # @raise [ArgumentError] If CSS content exceeds maximum size or capsule_id is invalid
+    def self.scope_with_nesting(css_string, capsule_id)
+      return css_string if css_string.nil? || css_string.strip.empty?
+
+      # Validate CSS size to prevent DoS attacks
+      if css_string.bytesize > MAX_CSS_SIZE
+        raise ArgumentError, "CSS content exceeds maximum size of #{MAX_CSS_SIZE} bytes (got #{css_string.bytesize} bytes)"
+      end
+
+      # Validate capsule_id
+      validate_capsule_id!(capsule_id)
+
+      # Simply wrap the entire CSS in the capsule attribute selector
+      # No parsing or transformation needed - much more performant
+      capsule_attr = %([data-capsule="#{capsule_id}"])
+      "#{capsule_attr} {\n#{css_string}\n}"
+    end
+
+    # Strip CSS comments (/* ... */) from the string
+    #
+    # @param css [String] CSS content with comments
+    # @return [String] CSS content without comments
+    def self.strip_comments(css)
+      # Remove /* ... */ comments (including multi-line)
+      # Use non-greedy match to handle multiple comments
+      css.gsub(/\/\*.*?\*\//m, "")
+    end
+
+    # Validate capsule ID to prevent injection attacks
+    #
+    # @param capsule_id [String] Capsule ID to validate
+    # @raise [ArgumentError] If capsule_id is invalid
+    def self.validate_capsule_id!(capsule_id)
+      unless capsule_id.is_a?(String)
+        raise ArgumentError, "capsule_id must be a String (got #{capsule_id.class})"
+      end
+
+      # Must not be empty (check first for clearer error message)
+      if capsule_id.empty?
+        raise ArgumentError, "capsule_id cannot be empty"
+      end
+
+      # Capsule ID should only contain alphanumeric characters, hyphens, and underscores
+      # This prevents injection into HTML attributes
+      unless capsule_id.match?(/\A[a-zA-Z0-9_-]+\z/)
+        raise ArgumentError, "Invalid capsule_id: must contain only alphanumeric characters, hyphens, and underscores (got: #{capsule_id.inspect})"
+      end
+
+      # Reasonable length limit
+      if capsule_id.length > 100
+        raise ArgumentError, "Invalid capsule_id: too long (max 100 characters, got #{capsule_id.length})"
+      end
+    end
+
+    private_class_method :strip_comments, :validate_capsule_id!
+  end
+end

data/lib/style_capsule/helper.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "digest/sha1"
+require "active_support/core_ext/string"
+
+module StyleCapsule
+  # ERB Helper module for use in Rails views
+  #
+  # This module is automatically included in ActionView::Base via Railtie.
+  # No manual inclusion is required - helpers are available in all ERB templates.
+  #
+  # Usage in ERB templates:
+  #
+  #   <%= style_capsule do %>
+  #     <style>
+  #       .section { color: red; }
+  #       .heading:hover { opacity: 0.8; }
+  #     </style>
+  #     <div class="section">
+  #       <h2 class="heading">Hello</h2>
+  #     </div>
+  #   <% end %>
+  #
+  # The CSS will be automatically scoped and content wrapped in a scoped div.
+  # The <style> tag will be extracted and processed separately.
+  module Helper
+    # Maximum HTML content size (10MB) to prevent DoS attacks
+    MAX_HTML_SIZE = 10_000_000
+    # Generate capsule ID based on caller location for uniqueness
+    def generate_capsule_id(css_content)
+      # Use caller location + CSS content for uniqueness
+      caller_info = caller_locations(1, 1).first
+      capsule_key = "#{caller_info.path}:#{caller_info.lineno}:#{css_content}"
+      "a#{Digest::SHA1.hexdigest(capsule_key)}"[0, 8]
+    end
+
+    # 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
+    end
+
+    # ERB helper: automatically wraps content in scoped div and processes CSS
+    #
+    # Extracts <style> tags from content, processes them, and wraps everything
+    # in a scoped div. CSS can be in <style> tags or as a separate block.
+    #
+    # Usage:
+    #   <%= style_capsule do %>
+    #     <style>
+    #       .section { color: red; }
+    #       .heading:hover { opacity: 0.8; }
+    #     </style>
+    #     <div class="section">
+    #       <h2 class="heading">Hello</h2>
+    #     </div>
+    #   <% end %>
+    #
+    # Or with CSS as separate content:
+    #   <% css_content = capture do %>
+    #     .section { color: red; }
+    #   <% end %>
+    #   <%= style_capsule(css_content) do %>
+    #     <div class="section">Content</div>
+    #   <% end %>
+    #
+    # Or with manual capsule ID (for testing/exact naming):
+    #   <%= style_capsule(capsule_id: "test-123") do %>
+    #     <style>.section { color: red; }</style>
+    #     <div class="section">Content</div>
+    #   <% end %>
+    #
+    # Or with both CSS content and manual capsule ID:
+    #   <% css_content = ".section { color: red; }" %>
+    #   <%= style_capsule(css_content, capsule_id: "test-123") do %>
+    #     <div class="section">Content</div>
+    #   <% end %>
+    def style_capsule(css_content = nil, capsule_id: nil, &content_block)
+      html_content = nil
+
+      # If CSS content is provided as argument, use it
+      # Otherwise, extract from content block
+      if css_content.nil? && block_given?
+        full_content = capture(&content_block)
+
+        # Validate HTML content size to prevent DoS attacks
+        if full_content.bytesize > MAX_HTML_SIZE
+          raise ArgumentError, "HTML content exceeds maximum size of #{MAX_HTML_SIZE} bytes (got #{full_content.bytesize} bytes)"
+        end
+
+        # Extract <style> tags from content
+        # Note: Pattern uses non-greedy matching (.*?) to minimize backtracking
+        # Size limit (MAX_HTML_SIZE) mitigates ReDoS risk from malicious input
+        style_match = full_content.match(/<style[^>]*>(.*?)<\/style>/m)
+        if style_match
+          css_content = style_match[1]
+          # Use sub instead of gsub to only remove first occurrence (reduces backtracking)
+          html_content = full_content.sub(/<style[^>]*>.*?<\/style>/m, "").strip
+        else
+          # No style tag found, treat entire content as HTML
+          css_content = nil
+          html_content = full_content
+        end
+      elsif css_content && block_given?
+        html_content = capture(&content_block)
+      elsif css_content && !block_given?
+        # CSS provided but no content block - just return scoped CSS
+        capsule_id ||= generate_capsule_id(css_content)
+        scoped_css = scope_css(css_content, capsule_id)
+        return content_tag(:style, raw(scoped_css), type: "text/css").html_safe
+      else
+        return ""
+      end
+
+      # If no CSS, just return content
+      return html_content.html_safe if css_content.nil? || css_content.to_s.strip.empty?
+
+      # Use provided capsule_id or generate one
+      capsule_id ||= generate_capsule_id(css_content)
+      scoped_css = scope_css(css_content, capsule_id)
+
+      # 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})
+
+      (style_tag + wrapped_content).html_safe
+    end
+
+    # Register a stylesheet file for head rendering
+    #
+    # Usage in ERB:
+    #   <% register_stylesheet("stylesheets/user/my_component", "data-turbo-track": "reload") %>
+    #   <% register_stylesheet("stylesheets/admin/dashboard", namespace: :admin) %>
+    #
+    # @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 register_stylesheet(file_path, namespace: nil, **options)
+      StyleCapsule::StylesheetRegistry.register(file_path, namespace: namespace, **options)
+    end
+
+    # Render StyleCapsule registered stylesheets (similar to javascript_importmap_tags)
+    #
+    # Usage in ERB:
+    #   <%= stylesheet_registrymap_tags %>
+    #   <%= stylesheet_registrymap_tags(namespace: :admin) %>
+    #
+    # @param namespace [Symbol, String, nil] Optional namespace to render (nil/blank renders all)
+    # @return [String] HTML-safe string with stylesheet tags
+    def stylesheet_registrymap_tags(namespace: nil)
+      StyleCapsule::StylesheetRegistry.render_head_stylesheets(self, namespace: namespace)
+    end
+  end
+end

data/lib/style_capsule/phlex_helper.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module StyleCapsule
+  # Phlex helper module for StyleCapsule stylesheet registry
+  #
+  # Include this in your base Phlex component class (e.g., ApplicationComponent):
+  #   class ApplicationComponent < Phlex::HTML
+  #     include StyleCapsule::PhlexHelper
+  #   end
+  #
+  # Usage in Phlex layouts:
+  #   head do
+  #     stylesheet_registrymap_tags
+  #   end
+  #
+  # Usage in Phlex components:
+  #   def view_template
+  #     register_stylesheet("stylesheets/user/my_component")
+  #     div { "Content" }
+  #   end
+  module PhlexHelper
+    # Register a stylesheet file for head rendering
+    #
+    # Usage in Phlex components:
+    #   def view_template
+    #     register_stylesheet("stylesheets/user/my_component", "data-turbo-track": "reload")
+    #     register_stylesheet("stylesheets/admin/dashboard", namespace: :admin)
+    #     div { "Content" }
+    #   end
+    #
+    # @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 register_stylesheet(file_path, namespace: nil, **options)
+      StyleCapsule::StylesheetRegistry.register(file_path, namespace: namespace, **options)
+    end
+
+    # Render StyleCapsule registered stylesheets (similar to javascript_importmap_tags)
+    #
+    # Usage in Phlex layouts:
+    #   head do
+    #     stylesheet_registrymap_tags
+    #     stylesheet_registrymap_tags(namespace: :admin)
+    #   end
+    #
+    # @param namespace [Symbol, String, nil] Optional namespace to render (nil/blank renders all)
+    # @return [void] Renders stylesheet tags via raw
+    def stylesheet_registrymap_tags(namespace: nil)
+      output = StyleCapsule::StylesheetRegistry.render_head_stylesheets(view_context, namespace: namespace)
+      # Phlex's raw() requires the object to be marked as safe
+      # Use Phlex's safe() if available, otherwise fall back to html_safe for test doubles
+      # The output from render_head_stylesheets is already html_safe (SafeBuffer)
+      output_string = output.to_s
+
+      if respond_to?(:safe)
+        # Real Phlex component - use raw() for rendering
+        safe_content = safe(output_string)
+        raw(safe_content)
+      end
+
+      # Always return the output string for testing/compatibility
+      output_string
+    end
+  end
+end