style_capsule 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1fcbe6c03f9675593d6dca7b3d7d70de2b7d471d2d938993b59877614332ff4
-  data.tar.gz: 6aa5feb7ff25ef755084e7754f328e4340a0d4dc620e1ea8298badbb0387f254
+  metadata.gz: 0dc57ce596c8aec7767199f8c57b82db16a8f96b33ac06cba599febd89afa86a
+  data.tar.gz: b4767a7eed2a864357027386452ea6a2da24577be3376388569c8ceb61bff937
 SHA512:
-  metadata.gz: f06af1e47282aa0220b5ff28e5e0a197a8d76eaa9f3c00639958ca1f9d672c7ad1dd4f672b9de83cc7c521af6a49b9c9f9c9bd0ce476575211b1fc7a7aeb1da2
-  data.tar.gz: 3844dd9da6608b1eff6e495e19b92e3f90d4b41df323118f5fa7c6216603d3b33620c80df8aeb13c2e2506e133e3ab6e424c3dfd76feb16dbbc68b37fac72636
+  metadata.gz: a666c80dc9ddc70179e9992bc4a1c0c9b58a295e21e0fc64441227529c4b401fdc7c7a703af5e87403ca407d0e482a5b97c73b1cc81d385a021cea2e1186c8d5
+  data.tar.gz: 0d8523c1659c5467b6e0a1aa6fc1268f999f669772a2ff22b66b386ec5c6ed19d85a9b9dc2b915f744d691ad2d9ccaa2dd7bc33f5c132a3c7d1fe1df073dcd41

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # CHANGELOG
 
+## 1.3.0 (2025-11-26)
+
+- Added comprehensive instrumentation via `StyleCapsule::Instrumentation` using ActiveSupport::Notifications
+- Instrumentation events for CSS processing (`style_capsule.css_processor.scope`) with duration and size metrics
+- Instrumentation events for CSS file writing (`style_capsule.css_file_writer.write`) with duration and size metrics
+- Added fallback directory support for CSS file writing when default location is read-only (e.g., Docker containers)
+- Automatic fallback to `/tmp/style_capsule` when primary output directory is not writable
+- Instrumentation events for fallback scenarios (`style_capsule.css_file_writer.fallback`, `style_capsule.css_file_writer.fallback_failure`)
+- Instrumentation events for write failures (`style_capsule.css_file_writer.write_failure`)
+- All instrumentation is zero-overhead when no subscribers are present (only calculates metrics when actively monitored)
+- Improved test coverage reporting and analysis tools
+- Added community guidelines and governance documents
+
 ## 1.2.0 (2025-11-24)
 
 - Added `StyleCapsule::ClassRegistry` for Rails-friendly class tracking without ObjectSpace iteration

data/README.md

@@ -1,6 +1,6 @@
 # style_capsule
 
-[![Gem Version](https://badge.fury.io/rb/style_capsule.svg?v=1.2.0)](https://badge.fury.io/rb/style_capsule) [![Test Status](https://github.com/amkisko/style_capsule.rb/actions/workflows/test.yml/badge.svg)](https://github.com/amkisko/style_capsule.rb/actions/workflows/test.yml) [![codecov](https://codecov.io/gh/amkisko/style_capsule.rb/graph/badge.svg?token=2U6NXJOVVM)](https://codecov.io/gh/amkisko/style_capsule.rb)
+[![Gem Version](https://badge.fury.io/rb/style_capsule.svg?v=1.3.0)](https://badge.fury.io/rb/style_capsule) [![Test Status](https://github.com/amkisko/style_capsule.rb/actions/workflows/test.yml/badge.svg)](https://github.com/amkisko/style_capsule.rb/actions/workflows/test.yml) [![codecov](https://codecov.io/gh/amkisko/style_capsule.rb/graph/badge.svg?token=2U6NXJOVVM)](https://codecov.io/gh/amkisko/style_capsule.rb)
 
 CSS scoping extension for Ruby components. Provides attribute-based style encapsulation for Phlex, ViewComponent, and ERB templates to prevent style leakage between components. Works with Rails and can be used standalone in other Ruby frameworks (Sinatra, Hanami, etc.) or plain Ruby scripts. Includes configurable caching strategies for optimal performance.
 
@@ -28,6 +28,8 @@ Then run `bundle install`.
 - **CSS Nesting support** (optional, more performant, requires modern browsers)
 - **Stylesheet registry** with thread-safe head rendering, namespace support, and compatibility with Propshaft and other asset bundlers
 - **Multiple cache strategies**: none, time-based, custom proc, and file-based (HTTP caching)
+- **Comprehensive instrumentation** via ActiveSupport::Notifications for monitoring and metrics
+- **Fallback directory support** for read-only filesystems (e.g., Docker containers)
 - **Security protections**: path traversal protection, input validation, size limits
 
 ## Usage
@@ -265,10 +267,13 @@ StyleCapsule::CssFileWriter.configure(
   output_dir: Rails.root.join("app/assets/builds/capsules"),
   filename_pattern: ->(component_class, capsule_id) {
     "capsule-#{capsule_id}.css"
-  }
+  },
+  fallback_dir: "/tmp/style_capsule"  # Optional, defaults to /tmp/style_capsule
 )
 ```
 
+**Fallback Directory:** In production environments where the app directory is read-only (e.g., Docker containers), StyleCapsule automatically falls back to writing files to `/tmp/style_capsule` when the default location is not writable. When using the fallback directory, the gem gracefully falls back to inline CSS rendering, keeping the UI fully functional.
+
 **Precompilation:**
 
 ```bash
@@ -280,6 +285,70 @@ Files are automatically built during `bin/rails assets:precompile`.
 
 **Compatibility:** The stylesheet registry works with Propshaft, Sprockets, and other Rails asset bundlers. Static file paths are collected in a process-wide manifest (similar to Propshaft's approach), while inline CSS is stored per-request.
 
+## Instrumentation
+
+StyleCapsule provides comprehensive instrumentation via `ActiveSupport::Notifications` for monitoring CSS processing and file writing operations. All instrumentation is zero-overhead when no subscribers are present.
+
+### Available Events
+
+- `style_capsule.css_processor.scope` - CSS scoping operations with duration and size metrics
+- `style_capsule.css_file_writer.write` - CSS file write operations with duration and size metrics
+- `style_capsule.css_file_writer.fallback` - When fallback directory is used (read-only filesystem)
+- `style_capsule.css_file_writer.fallback_failure` - When both primary and fallback directories fail
+- `style_capsule.css_file_writer.write_failure` - Other write errors
+
+### Example: Monitoring CSS Processing
+
+```ruby
+# config/initializers/style_capsule.rb
+ActiveSupport::Notifications.subscribe("style_capsule.css_processor.scope") do |name, start, finish, id, payload|
+  duration_ms = (finish - start) * 1000
+  Rails.logger.info "CSS scoped in #{duration_ms.round(2)}ms, input: #{payload[:input_size]} bytes, output: #{payload[:output_size]} bytes"
+end
+```
+
+### Example: Monitoring File Writes
+
+```ruby
+ActiveSupport::Notifications.subscribe("style_capsule.css_file_writer.write") do |name, start, finish, id, payload|
+  duration_ms = (finish - start) * 1000
+  StatsD.timing("style_capsule.write.duration", duration_ms)
+  StatsD.histogram("style_capsule.write.size", payload[:size])
+end
+```
+
+### Example: Monitoring Fallback Scenarios
+
+```ruby
+ActiveSupport::Notifications.subscribe("style_capsule.css_file_writer.fallback") do |name, start, finish, id, payload|
+  Rails.logger.warn "StyleCapsule fallback used: #{payload[:component_class]} -> #{payload[:fallback_path]}"
+  # Exception info available: payload[:exception] and payload[:exception_object]
+  StatsD.increment("style_capsule.css_file_writer.fallback", tags: [
+    "component:#{payload[:component_class]}",
+    "error:#{payload[:exception].first}"
+  ])
+end
+```
+
+### Example: Error Reporting
+
+```ruby
+ActiveSupport::Notifications.subscribe("style_capsule.css_file_writer.fallback_failure") do |name, start, finish, id, payload|
+  ActionReporter.notify(
+    "StyleCapsule: CSS write failure (both primary and fallback failed)",
+    context: {
+      component_class: payload[:component_class],
+      original_path: payload[:original_path],
+      fallback_path: payload[:fallback_path],
+      original_exception: payload[:original_exception],
+      fallback_exception: payload[:fallback_exception]
+    }
+  )
+end
+```
+
+For more details, see the [ActiveSupport::Notifications documentation](https://guides.rubyonrails.org/active_support_instrumentation.html).
+
 ## Advanced Usage
 
 ### Database-Stored CSS

data/SECURITY.md

@@ -1,55 +1,28 @@
 # SECURITY
 
-## Supported Versions
+## Reporting a Vulnerability
 
-| Version | Supported          |
-| ------- | ------------------ |
-| 1.0.x   | :white_check_mark: |
-| < 1.0   | :x:                |
+**Do NOT** open a public GitHub issue for security vulnerabilities.
 
-## Security Guidelines
+Email security details to: **security@kiskolabs.com**
 
-StyleCapsule provides minimal security protections to assist with automated CSS scoping. The gem does not validate, sanitize, or secure CSS content itself—this is the application's responsibility.
+Include: description, steps to reproduce, potential impact, and suggested fix (if available).
 
-### What StyleCapsule Protects
+### Response Timeline
 
-- **Path Traversal**: Filenames are validated when writing CSS files to prevent directory traversal attacks
-- **Input Size Limits**: CSS content is limited to 1MB per component to prevent resource exhaustion
-- **Scope ID Validation**: Capsule IDs are validated to prevent injection into HTML attributes
+- We will acknowledge receipt of your report
+- We will provide an initial assessment
+- We will keep you informed of our progress and resolution timeline
 
-### What StyleCapsule Does NOT Control
+### Disclosure Policy
 
-**Developer Responsibility:**
-- **CSS Content**: StyleCapsule does not validate or sanitize CSS content. Malicious CSS (e.g., data exfiltration via `@import`, CSS injection attacks) is not prevented by the gem
-- **User Input**: Applications must validate and sanitize user-provided CSS before passing it to StyleCapsule
-- **Developer Intent**: The gem trusts that developers provide safe CSS content from trusted sources
+- We will work with you to understand and resolve the issue
+- We will credit you for the discovery (unless you prefer to remain anonymous)
+- We will publish a security advisory after the vulnerability is patched
+- We will coordinate public disclosure with you
 
-**Rails Framework:**
-- HTML escaping is handled by Rails' built-in helpers (`content_tag`, etc.)
-- Content Security Policy (CSP) must be configured at the application level
-- File system permissions and access control are managed by the application
+## Automation Security
 
-### Security Best Practices
+* **Context Isolation:** It is strictly forbidden to include production credentials, API keys, or Personally Identifiable Information (PII) in prompts sent to third-party LLMs or automation services.
 
-1. **Validate User Input**: Never pass untrusted CSS content to StyleCapsule without validation
-2. **Use Content Security Policy**: Configure CSP headers to restrict inline styles and external resources
-3. **Sanitize User-Generated CSS**: If allowing user input, sanitize CSS before processing
-4. **Keep Dependencies Updated**: Use supported Ruby (>= 3.0) and Rails versions with security patches
-5. **Review Generated Files**: Periodically review files in `app/assets/builds/capsules/` if using file-based caching
-
-### Reporting a Vulnerability
-
-If you discover a security vulnerability, please **do not** open a public issue. Instead:
-
-1. **Email**: contact@kiskolabs.com
-2. **Subject**: `[SECURITY] style_capsule vulnerability report`
-3. **Include**: Description, steps to reproduce, potential impact, and suggested fix (if any)
-
-We will acknowledge receipt within 48 hours and provide an initial assessment within 7 days.
-
-### Security Updates
-
-Security updates are released as patch versions (e.g., 1.0.1, 1.0.2) and announced via:
-- GitHub Security Advisories
-- RubyGems release notes
-- CHANGELOG.md
+* **Supply Chain:** All automated dependencies must be verified.

data/lib/style_capsule/component.rb

@@ -463,9 +463,9 @@ module StyleCapsule
       # Use the configured scoping strategy
       scoped_css = case scoping_strategy
       when :nesting
-        CssProcessor.scope_with_nesting(css_content, capsule_id)
+        CssProcessor.scope_with_nesting(css_content, capsule_id, component_class: self.class)
       else # :selector_patching (default)
-        CssProcessor.scope_selectors(css_content, capsule_id)
+        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)

data/lib/style_capsule/css_file_writer.rb

@@ -2,6 +2,7 @@
 
 require "fileutils"
 require "digest/sha1"
+require_relative "instrumentation"
 
 module StyleCapsule
   # Writes inline CSS to files for HTTP caching
@@ -10,10 +11,28 @@ module StyleCapsule
   # Files are written to a configurable output directory and can be precompiled
   # via Rails asset pipeline.
   #
+  # In production environments where the app directory is read-only (e.g., Docker containers),
+  # this class automatically falls back to writing files to /tmp/style_capsule when the
+  # default location is not writable. When using the fallback directory, write_css returns
+  # nil, causing StylesheetRegistry to fall back to inline CSS (keeping the UI functional).
+  #
+  # All fallback scenarios are instrumented via ActiveSupport::Notifications following
+  # Rails conventions (https://guides.rubyonrails.org/active_support_instrumentation.html):
+  # - style_capsule.css_file_writer.fallback: When fallback directory is used successfully
+  # - style_capsule.css_file_writer.fallback_failure: When both primary and fallback fail
+  # - style_capsule.css_file_writer.write_failure: When other write errors occur
+  #
+  # All events include exception information in the standard Rails format:
+  # - :exception: Array of [class_name, message]
+  # - :exception_object: The exception object itself
+  #
+  # These events can be subscribed to for monitoring, metrics collection, and error reporting.
+  #
   # @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" }
+  #     filename_pattern: ->(component_class, capsule_id) { "capsule-#{capsule_id}.css" },
+  #     fallback_dir: "/tmp/style_capsule"  # Optional, defaults to /tmp/style_capsule
   #   )
   #
   # @example Usage
@@ -22,13 +41,43 @@ module StyleCapsule
   #     component_class: MyComponent,
   #     capsule_id: "abc123"
   #   )
-  #   # => "capsules/capsule-abc123"
+  #   # => "capsules/capsule-abc123" (or nil if fallback was used)
+  #
+  # @example Listening to instrumentation events for monitoring
+  #   ActiveSupport::Notifications.subscribe("style_capsule.css_file_writer.fallback") do |name, start, finish, id, payload|
+  #     Rails.logger.warn "StyleCapsule fallback: #{payload[:component_class]} -> #{payload[:fallback_path]}"
+  #     # Exception info available: payload[:exception] and payload[:exception_object]
+  #   end
+  #
+  # @example Subscribing for error reporting
+  #   ActiveSupport::Notifications.subscribe("style_capsule.css_file_writer.fallback_failure") do |name, start, finish, id, payload|
+  #     ActionReporter.notify(
+  #       "StyleCapsule: CSS write failure (both primary and fallback failed)",
+  #       context: {
+  #         component_class: payload[:component_class],
+  #         original_path: payload[:original_path],
+  #         fallback_path: payload[:fallback_path],
+  #         original_exception: payload[:original_exception],
+  #         fallback_exception: payload[:fallback_exception]
+  #       }
+  #     )
+  #   end
+  #
+  # @example Subscribing for metrics collection
+  #   ActiveSupport::Notifications.subscribe("style_capsule.css_file_writer.fallback") do |name, start, finish, id, payload|
+  #     StatsD.increment("style_capsule.css_file_writer.fallback", tags: [
+  #       "component:#{payload[:component_class]}",
+  #       "error:#{payload[:exception].first}"
+  #     ])
+  #   end
   class CssFileWriter
     # Default output directory for CSS files (relative to Rails root)
     DEFAULT_OUTPUT_DIR = "app/assets/builds/capsules"
+    # Fallback directory for when default location is read-only (absolute path)
+    FALLBACK_OUTPUT_DIR = "/tmp/style_capsule"
 
     class << self
-      attr_accessor :output_dir, :filename_pattern, :enabled
+      attr_accessor :output_dir, :filename_pattern, :enabled, :fallback_dir
 
       # Configure CSS file writer
       #
@@ -38,6 +87,8 @@ module StyleCapsule
       #   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)
+      # @param fallback_dir [String, Pathname, nil] Fallback directory when default location is read-only
+      #   Default: `StyleCapsule::CssFileWriter::FALLBACK_OUTPUT_DIR` (/tmp/style_capsule)
       # @example
       #   StyleCapsule::CssFileWriter.configure(
       #     output_dir: Rails.root.join(StyleCapsule::CssFileWriter::DEFAULT_OUTPUT_DIR),
@@ -47,7 +98,7 @@ module StyleCapsule
       #   StyleCapsule::CssFileWriter.configure(
       #     filename_pattern: ->(klass, capsule) { "#{klass.name.underscore}-#{capsule}.css" }
       #   )
-      def configure(output_dir: nil, filename_pattern: nil, enabled: true)
+      def configure(output_dir: nil, filename_pattern: nil, enabled: true, fallback_dir: nil)
         @enabled = enabled
 
         @output_dir = if output_dir
@@ -58,6 +109,12 @@ module StyleCapsule
           Pathname.new(DEFAULT_OUTPUT_DIR)
         end
 
+        @fallback_dir = if fallback_dir
+          fallback_dir.is_a?(Pathname) ? fallback_dir : Pathname.new(fallback_dir.to_s)
+        else
+          Pathname.new(FALLBACK_OUTPUT_DIR)
+        end
+
         @filename_pattern = filename_pattern || default_filename_pattern
       end
 
@@ -66,17 +123,73 @@ module StyleCapsule
       # @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
+      # @return [String, nil] Relative file path (for stylesheet_link_tag) or nil if disabled/failed
       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)
+        used_fallback = false
 
-        # Write CSS to file with explicit UTF-8 encoding
-        File.write(file_path, css_content, encoding: "UTF-8")
+        begin
+          ensure_output_directory
+          # Write CSS to file with explicit UTF-8 encoding
+          Instrumentation.instrument_file_write(
+            component_class: component_class,
+            capsule_id: capsule_id,
+            file_path: file_path.to_s,
+            size: css_content.bytesize
+          ) do
+            File.write(file_path, css_content, encoding: "UTF-8")
+          end
+        rescue Errno::EACCES, Errno::EROFS => e
+          # Permission denied or read-only filesystem - try fallback directory
+          fallback_path = fallback_directory.join(filename)
+
+          begin
+            ensure_fallback_directory
+            File.write(fallback_path, css_content, encoding: "UTF-8")
+            used_fallback = true
+            file_path = fallback_path
+
+            # Instrument the fallback for visibility
+            Instrumentation.instrument_fallback(
+              component_class: component_class,
+              capsule_id: capsule_id,
+              original_path: output_directory.join(filename).to_s,
+              fallback_path: fallback_path.to_s,
+              exception: [e.class.name, e.message],
+              exception_object: e
+            )
+          rescue => fallback_error
+            # Even fallback failed - instrument and return nil (will fall back to inline CSS)
+            Instrumentation.instrument_fallback_failure(
+              component_class: component_class,
+              capsule_id: capsule_id,
+              original_path: output_directory.join(filename).to_s,
+              fallback_path: fallback_path.to_s,
+              original_exception: [e.class.name, e.message],
+              original_exception_object: e,
+              fallback_exception: [fallback_error.class.name, fallback_error.message],
+              fallback_exception_object: fallback_error
+            )
+            return nil
+          end
+        rescue => e
+          # Other errors - instrument and return nil (will fall back to inline CSS)
+          Instrumentation.instrument_write_failure(
+            component_class: component_class,
+            capsule_id: capsule_id,
+            file_path: file_path.to_s,
+            exception: [e.class.name, e.message],
+            exception_object: e
+          )
+          return nil
+        end
+
+        # If we used fallback directory, return nil (can't serve via asset pipeline)
+        # This will cause StylesheetRegistry to fall back to inline CSS
+        return nil if used_fallback
 
         # Return relative path for stylesheet_link_tag
         # Path should be relative to app/assets
@@ -135,6 +248,16 @@ module StyleCapsule
         FileUtils.mkdir_p(dir) unless Dir.exist?(dir)
       end
 
+      # Ensure fallback directory exists
+      #
+      # @return [void]
+      def ensure_fallback_directory
+        return unless enabled?
+
+        dir = fallback_directory
+        FileUtils.mkdir_p(dir) unless Dir.exist?(dir)
+      end
+
       # Clear all generated CSS files
       #
       # @return [void]
@@ -171,6 +294,11 @@ module StyleCapsule
         end
       end
 
+      # Get fallback directory (with default)
+      def fallback_directory
+        @fallback_dir ||= Pathname.new(FALLBACK_OUTPUT_DIR)
+      end
+
       # Generate filename using pattern
       #
       # @param component_class [Class] Component class

data/lib/style_capsule/css_processor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "instrumentation"
+
 module StyleCapsule
   # Shared CSS processing logic for scoping selectors with attribute selectors
   #
@@ -35,9 +37,10 @@ module StyleCapsule
     #
     # @param css_string [String] Original CSS content
     # @param capsule_id [String] The capsule ID to use in attribute selector
+    # @param component_class [Class, String, nil] Optional component class for instrumentation
     # @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)
+    def self.scope_selectors(css_string, capsule_id, component_class: nil)
       return css_string if css_string.nil? || css_string.strip.empty?
 
       # Validate CSS size to prevent DoS attacks
@@ -48,61 +51,69 @@ module StyleCapsule
       # 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}"
+      # Instrument CSS processing with timing and size metrics
+      Instrumentation.instrument_css_processing(
+        strategy: :selector_patching,
+        component_class: component_class || "Unknown",
+        capsule_id: capsule_id,
+        css_content: css_string
+      ) do
+        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
-
-      # 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] { ... })
@@ -122,9 +133,10 @@ module StyleCapsule
     #
     # @param css_string [String] Original CSS content
     # @param capsule_id [String] The capsule ID to use in attribute selector
+    # @param component_class [Class, String, nil] Optional component class for instrumentation
     # @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)
+    def self.scope_with_nesting(css_string, capsule_id, component_class: nil)
       return css_string if css_string.nil? || css_string.strip.empty?
 
       # Validate CSS size to prevent DoS attacks
@@ -135,10 +147,18 @@ module StyleCapsule
       # 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}"
+      # Instrument CSS processing with timing and size metrics
+      Instrumentation.instrument_css_processing(
+        strategy: :nesting,
+        component_class: component_class || "Unknown",
+        capsule_id: capsule_id,
+        css_content: css_string
+      ) do
+        # 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
     end
 
     # Strip CSS comments (/* ... */) from the string

data/lib/style_capsule/instrumentation.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+module StyleCapsule
+  # Centralized instrumentation module for StyleCapsule
+  #
+  # Provides efficient, non-blocking instrumentation using ActiveSupport::Notifications.
+  # Metrics (time, size) are only calculated when subscribers are present, ensuring
+  # zero performance impact when instrumentation is not being used.
+  #
+  # All events follow Rails naming convention: style_capsule.{module}.{event}
+  #
+  # @example Subscribing to CSS processing events
+  #   ActiveSupport::Notifications.subscribe("style_capsule.css_processor.scope") do |name, start, finish, id, payload|
+  #     duration_ms = (finish - start) * 1000
+  #     input_size = payload[:input_size]
+  #     Rails.logger.info "CSS scoped in #{duration_ms}ms, input: #{input_size} bytes"
+  #   end
+  #
+  # @example Using Event object for more details
+  #   ActiveSupport::Notifications.subscribe("style_capsule.css_processor.scope") do |event|
+  #     Rails.logger.info "CSS scoped in #{event.duration}ms, input: #{event.payload[:input_size]} bytes"
+  #   end
+  #
+  # @example Subscribing to file write events
+  #   ActiveSupport::Notifications.subscribe("style_capsule.css_file_writer.write") do |name, start, finish, id, payload|
+  #     StatsD.timing("style_capsule.write.duration", (finish - start) * 1000)
+  #     StatsD.histogram("style_capsule.write.size", payload[:size])
+  #   end
+  module Instrumentation
+    # Check if ActiveSupport::Notifications is available
+    #
+    # @return [Boolean]
+    def self.available?
+      defined?(ActiveSupport::Notifications)
+    end
+
+    # Instrument an operation with automatic timing and size metrics
+    #
+    # This method is highly efficient:
+    # - Only measures time if subscribers exist (ActiveSupport::Notifications is optimized for this)
+    # - Only calculates sizes if subscribers exist (lazy evaluation)
+    # - Uses monotonic time for accurate measurements
+    #
+    # @param event_name [String] Event name following Rails convention (e.g., "style_capsule.css_processor.scope")
+    # @param payload [Hash] Additional payload data
+    # @yield The operation to instrument
+    # @yieldreturn [Object] Result of the operation (used for output size calculation if needed)
+    # @return [Object] Return value of the block
+    # @example Instrumenting CSS processing
+    #   result = Instrumentation.instrument(
+    #     "style_capsule.css_processor.scope",
+    #     component_class: component_class.name,
+    #     capsule_id: capsule_id,
+    #     strategy: :selector_patching,
+    #     input_size: css_content.bytesize
+    #   ) do
+    #     CssProcessor.scope_selectors(css_content, capsule_id)
+    #   end
+    def self.instrument(event_name, payload = {}, &block)
+      return yield unless available?
+
+      # Check if there are any subscribers (ActiveSupport optimizes this check)
+      # If no subscribers, just execute the block without any overhead
+      unless ActiveSupport::Notifications.notifier.listening?(event_name)
+        return yield
+      end
+
+      # Calculate input size if not provided but css_content/input is in payload
+      unless payload[:input_size]
+        if payload[:css_content]
+          payload[:input_size] = payload[:css_content].bytesize
+        elsif payload[:input]
+          payload[:input_size] = payload[:input].bytesize
+        end
+      end
+
+      # Use ActiveSupport::Notifications.instrument which automatically:
+      # - Measures duration using monotonic time (available in event.duration)
+      # - Only does work if subscribers exist (zero overhead if no subscribers)
+      # Note: output_size is not included in payload (subscribers can calculate from result if needed)
+      result = nil
+      ActiveSupport::Notifications.instrument(event_name, payload) do
+        result = yield
+        result
+      end
+
+      result
+    end
+
+    # Instrument an event without a block (for events that don't have duration)
+    #
+    # @param event_name [String] Event name
+    # @param payload [Hash] Payload data
+    # @return [void]
+    # @example Instrumenting a fallback event
+    #   Instrumentation.notify(
+    #     "style_capsule.css_file_writer.fallback",
+    #     component_class: component_class.name,
+    #     original_path: original_path,
+    #     fallback_path: fallback_path,
+    #     exception: [e.class.name, e.message],
+    #     exception_object: e
+    #   )
+    def self.notify(event_name, payload = {})
+      return unless available?
+
+      # Only notify if subscribers exist
+      return unless ActiveSupport::Notifications.notifier.listening?(event_name)
+
+      ActiveSupport::Notifications.instrument(event_name, payload)
+    end
+
+    # Instrument CSS processing operations
+    #
+    # @param strategy [Symbol] Scoping strategy (:selector_patching or :nesting)
+    # @param component_class [Class, String] Component class
+    # @param capsule_id [String] Capsule ID
+    # @param css_content [String] CSS content (for size calculation)
+    # @yield The CSS processing operation
+    # @return [String] Processed CSS
+    def self.instrument_css_processing(strategy:, component_class:, capsule_id:, css_content:, &block)
+      component_name = component_class.is_a?(Class) ? component_class.name : component_class.to_s
+      input_size = css_content.bytesize
+
+      instrument(
+        "style_capsule.css_processor.scope",
+        strategy: strategy,
+        component_class: component_name,
+        capsule_id: capsule_id,
+        input_size: input_size
+      ) do
+        result = yield
+        # Output size will be calculated by subscribers if needed
+        # They can access it via: result.bytesize
+        result
+      end
+    end
+
+    # Instrument CSS file write operations
+    #
+    # @param component_class [Class] Component class
+    # @param capsule_id [String] Capsule ID
+    # @param file_path [String] File path
+    # @param size [Integer] CSS content size in bytes
+    # @yield The file write operation
+    # @return [Object] Return value of the block
+    def self.instrument_file_write(component_class:, capsule_id:, file_path:, size:, &block)
+      instrument(
+        "style_capsule.css_file_writer.write",
+        component_class: component_class.name,
+        capsule_id: capsule_id,
+        file_path: file_path,
+        size: size
+      ) do
+        yield
+      end
+    end
+
+    # Instrument fallback to temporary directory
+    #
+    # @param component_class [Class] Component class
+    # @param capsule_id [String] Capsule ID
+    # @param original_path [String] Original file path that failed
+    # @param fallback_path [String] Fallback file path used
+    # @param exception [Array<String>] Exception [class_name, message]
+    # @param exception_object [Exception] The exception object
+    # @return [void]
+    def self.instrument_fallback(component_class:, capsule_id:, original_path:, fallback_path:, exception:, exception_object:)
+      notify(
+        "style_capsule.css_file_writer.fallback",
+        component_class: component_class.name,
+        capsule_id: capsule_id,
+        original_path: original_path,
+        fallback_path: fallback_path,
+        exception: exception,
+        exception_object: exception_object
+      )
+    end
+
+    # Instrument fallback failure (both original and fallback failed)
+    #
+    # @param component_class [Class] Component class
+    # @param capsule_id [String] Capsule ID
+    # @param original_path [String] Original file path that failed
+    # @param fallback_path [String] Fallback file path that also failed
+    # @param original_exception [Array<String>] Original exception [class_name, message]
+    # @param original_exception_object [Exception] Original exception object
+    # @param fallback_exception [Array<String>] Fallback exception [class_name, message]
+    # @param fallback_exception_object [Exception] Fallback exception object
+    # @return [void]
+    def self.instrument_fallback_failure(component_class:, capsule_id:, original_path:, fallback_path:, original_exception:, original_exception_object:, fallback_exception:, fallback_exception_object:)
+      notify(
+        "style_capsule.css_file_writer.fallback_failure",
+        component_class: component_class.name,
+        capsule_id: capsule_id,
+        original_path: original_path,
+        fallback_path: fallback_path,
+        original_exception: original_exception,
+        original_exception_object: original_exception_object,
+        fallback_exception: fallback_exception,
+        fallback_exception_object: fallback_exception_object
+      )
+    end
+
+    # Instrument write failure (non-permission errors)
+    #
+    # @param component_class [Class] Component class
+    # @param capsule_id [String] Capsule ID
+    # @param file_path [String] File path that failed
+    # @param exception [Array<String>] Exception [class_name, message]
+    # @param exception_object [Exception] The exception object
+    # @return [void]
+    def self.instrument_write_failure(component_class:, capsule_id:, file_path:, exception:, exception_object:)
+      notify(
+        "style_capsule.css_file_writer.write_failure",
+        component_class: component_class.name,
+        capsule_id: capsule_id,
+        file_path: file_path,
+        exception: exception,
+        exception_object: exception_object
+      )
+    end
+
+    # Instrument stylesheet registration
+    #
+    # @param namespace [Symbol, String] Namespace
+    # @param file_path [String, nil] File path (if file-based)
+    # @param inline_size [Integer, nil] Inline CSS size in bytes (if inline)
+    # @param cache_strategy [Symbol] Cache strategy
+    # @yield The registration operation
+    # @return [Object] Return value of the block
+    def self.instrument_registration(namespace:, file_path: nil, inline_size: nil, cache_strategy: :none, &block)
+      payload = {
+        namespace: namespace.to_s,
+        cache_strategy: cache_strategy
+      }
+      payload[:file_path] = file_path if file_path
+      payload[:inline_size] = inline_size if inline_size
+
+      instrument(
+        "style_capsule.stylesheet_registry.register",
+        payload
+      ) do
+        yield
+      end
+    end
+  end
+end

data/lib/style_capsule/version.rb

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

data/lib/style_capsule.rb

@@ -89,6 +89,7 @@ end
 #   # Or manually: bin/rails style_capsule:build
 module StyleCapsule
   require_relative "style_capsule/version"
+  require_relative "style_capsule/instrumentation"
   require_relative "style_capsule/css_processor"
   require_relative "style_capsule/css_file_writer"
   require_relative "style_capsule/stylesheet_registry"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: style_capsule
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Andrei Makarov
@@ -268,6 +268,7 @@ files:
 - lib/style_capsule/css_file_writer.rb
 - lib/style_capsule/css_processor.rb
 - lib/style_capsule/helper.rb
+- lib/style_capsule/instrumentation.rb
 - lib/style_capsule/phlex_helper.rb
 - lib/style_capsule/railtie.rb
 - lib/style_capsule/standalone_helper.rb