style_capsule 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1fcbe6c03f9675593d6dca7b3d7d70de2b7d471d2d938993b59877614332ff4
-  data.tar.gz: 6aa5feb7ff25ef755084e7754f328e4340a0d4dc620e1ea8298badbb0387f254
+  metadata.gz: 74203df88bc23dc0b1509f0e7adc5978fe327c982026916e990644c92f65a0db
+  data.tar.gz: 7f7783ef50b66e14859e1f7207262279f20e5f28eb29d3373a85fef9ae2f3a7c
 SHA512:
-  metadata.gz: f06af1e47282aa0220b5ff28e5e0a197a8d76eaa9f3c00639958ca1f9d672c7ad1dd4f672b9de83cc7c521af6a49b9c9f9c9bd0ce476575211b1fc7a7aeb1da2
-  data.tar.gz: 3844dd9da6608b1eff6e495e19b92e3f90d4b41df323118f5fa7c6216603d3b33620c80df8aeb13c2e2506e133e3ab6e424c3dfd76feb16dbbc68b37fac72636
+  metadata.gz: bed787978d271158ca409ffe8445df1f6203e954000d153beae40368861e0077b566557c3f50456373d04998f85ab60ee86b3cd93ed558d31f3d482247fb0b7e
+  data.tar.gz: 22b900ebbf5ce4a219d487f7915b7dcd31ed4552d134af44f056ba79eff8551a4ef62e8070f03887fc4962f2073d06bd3b2d65d35e00f09183d97a730ad24ee2

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # CHANGELOG
 
+## 1.4.0 (2025-11-26)
+
+- Added unified `style_capsule` class method for configuring all StyleCapsule settings (namespace, cache strategy, CSS scoping, head rendering) in a single call
+- Added automatic namespace fallback in `register_stylesheet` helper methods - when namespace is not specified, uses the component's configured namespace from `style_capsule`
+- Removed deprecated `head_rendering!` method (use `style_capsule` instead)
+- Removed deprecated `stylesheet_registrymap_tags` alias (use `stylesheet_registry_tags` instead)
+- Refactored namespace configuration to use instance variables instead of constants for better inheritance behavior
+
+## 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
@@ -16,7 +37,7 @@
 - Rails integration remains fully supported via Railtie
 - Added `StyleCapsule::StandaloneHelper` for non-Rails frameworks
 - `StylesheetRegistry` now works without `ActiveSupport::CurrentAttributes` using thread-local storage fallback
-- Renamed `stylesheet_registrymap_tags` to `stylesheet_registry_tags` (old name kept as deprecated alias)
+- Renamed `stylesheet_registrymap_tags` to `stylesheet_registry_tags` (deprecated alias removed in 1.4.0)
 - Extracted CSS building logic from Rake tasks into `StyleCapsule::ComponentBuilder`
 - Fixed XSS vulnerability in `escape_html_attr` by using `CGI.escapeHTML` for proper HTML entity escaping
 - Optimized ActiveSupport require to avoid exception handling overhead in Rails apps

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.4.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
@@ -101,12 +103,12 @@ StyleCapsule supports two CSS scoping strategies:
 
 ### Configuration
 
-**Per-component:**
+**Per-component (using `style_capsule` - recommended):**
 
 ```ruby
 class MyComponent < ApplicationComponent
   include StyleCapsule::Component
-  css_scoping_strategy :nesting  # Use CSS nesting
+  style_capsule scoping_strategy: :nesting  # Use CSS nesting
 end
 ```
 
@@ -115,7 +117,7 @@ end
 ```ruby
 class ApplicationComponent < Phlex::HTML
   include StyleCapsule::Component
-  css_scoping_strategy :nesting  # Enable for all components
+  style_capsule scoping_strategy: :nesting  # Enable for all components
 end
 ```
 
@@ -127,12 +129,12 @@ MyComponent.clear_css_cache
 
 ## Stylesheet Registry
 
-For better performance, register styles for head rendering instead of rendering `<style>` tags in the body:
+For better performance, register styles for head rendering instead of rendering `<style>` tags in the body. Use the unified `style_capsule` method to configure all settings:
 
 ```ruby
 class MyComponent < ApplicationComponent
   include StyleCapsule::Component
-  stylesheet_registry namespace: :admin  # Optional namespace
+  style_capsule namespace: :admin  # Configure namespace and enable head rendering
 
   def component_styles
     <<~CSS
@@ -142,12 +144,17 @@ class MyComponent < ApplicationComponent
 end
 ```
 
-With cache strategy:
+With cache strategy and CSS scoping:
 
 ```ruby
 class MyComponent < ApplicationComponent
   include StyleCapsule::Component
-  stylesheet_registry namespace: :admin, cache_strategy: :time, cache_ttl: 1.hour
+  style_capsule(
+    namespace: :admin,
+    cache_strategy: :time,
+    cache_ttl: 1.hour,
+    scoping_strategy: :nesting
+  )
 
   def component_styles
     <<~CSS
@@ -157,11 +164,10 @@ class MyComponent < ApplicationComponent
 end
 ```
 
-Then in your layout:
+Then in your layout (render only the namespace you need):
 
 ```erb
 <head>
-  <%= stylesheet_registry_tags %>
   <%= stylesheet_registry_tags(namespace: :admin) %>
 </head>
 ```
@@ -170,42 +176,58 @@ Or in Phlex (requires including `StyleCapsule::PhlexHelper`):
 
 ```ruby
 head do
-  stylesheet_registry_tags
+  stylesheet_registry_tags(namespace: :admin)
 end
 ```
 
+**Namespace Isolation:** Using namespaces prevents stylesheet leakage between different application contexts. For example, login pages can use `namespace: :login`, ActiveAdmin can use `namespace: :active_admin`, and user components can use `namespace: :user`. Each namespace is rendered separately, improving caching efficiency and preventing style conflicts.
+
 ### Registering Stylesheet Files
 
-You can also register external stylesheet files (not inline CSS) for head rendering:
+You can also register external stylesheet files (not inline CSS) for head rendering. When a component has a configured namespace via `style_capsule`, you don't need to specify it every time:
 
 **In ERB:**
 
 ```erb
-<% register_stylesheet("stylesheets/user/order_select_component", "data-turbo-track": "reload") %>
+<% register_stylesheet("stylesheets/user/my_component", "data-turbo-track": "reload") %>
 <% register_stylesheet("stylesheets/admin/dashboard", namespace: :admin) %>
 ```
 
 **In Phlex (requires including `StyleCapsule::PhlexHelper`):**
 
 ```ruby
-def view_template
-  register_stylesheet("stylesheets/user/order_select_component", "data-turbo-track": "reload")
-  register_stylesheet("stylesheets/admin/dashboard", namespace: :admin)
-  div { "Content" }
+class UserComponent < ApplicationComponent
+  include StyleCapsule::Component
+  include StyleCapsule::PhlexHelper
+  style_capsule namespace: :user  # Set default namespace
+
+  def view_template
+    # Namespace automatically uses :user from style_capsule
+    register_stylesheet("stylesheets/user/my_component", "data-turbo-track": "reload")
+    # Can still override namespace if needed
+    register_stylesheet("stylesheets/shared/common", namespace: :shared)
+    div { "Content" }
+  end
 end
 ```
 
 **In ViewComponent (requires including `StyleCapsule::ViewComponentHelper`):**
 
 ```ruby
-def call
-  register_stylesheet("stylesheets/user/order_select_component", "data-turbo-track": "reload")
-  register_stylesheet("stylesheets/admin/dashboard", namespace: :admin)
-  content_tag(:div, "Content")
+class UserComponent < ApplicationComponent
+  include StyleCapsule::ViewComponent
+  include StyleCapsule::ViewComponentHelper
+  style_capsule namespace: :user  # Set default namespace
+
+  def call
+    # Namespace automatically uses :user from style_capsule
+    register_stylesheet("stylesheets/user/my_component", "data-turbo-track": "reload")
+    content_tag(:div, "Content")
+  end
 end
 ```
 
-Registered files are rendered via `stylesheet_registry_tags` in your layout, just like inline CSS.
+Registered files are rendered via `stylesheet_registry_tags` in your layout, just like inline CSS. The namespace is automatically used from the component's `style_capsule` configuration when not explicitly specified.
 
 ## Caching Strategies
 
@@ -214,22 +236,22 @@ Registered files are rendered via `stylesheet_registry_tags` in your layout, jus
 ```ruby
 class MyComponent < ApplicationComponent
   include StyleCapsule::Component
-  stylesheet_registry  # No cache strategy set (default: :none)
+  style_capsule  # No cache strategy set (default: :none)
 end
 ```
 
 ### Time-Based Caching
 
 ```ruby
-stylesheet_registry cache_strategy: :time, cache_ttl: 1.hour  # Using ActiveSupport::Duration
+style_capsule cache_strategy: :time, cache_ttl: 1.hour  # Using ActiveSupport::Duration
 # Or using integer seconds:
-stylesheet_registry cache_strategy: :time, cache_ttl: 3600  # Cache for 1 hour
+style_capsule cache_strategy: :time, cache_ttl: 3600  # Cache for 1 hour
 ```
 
 ### Custom Proc Caching
 
 ```ruby
-stylesheet_registry cache_strategy: ->(css, capsule_id, namespace) {
+style_capsule cache_strategy: ->(css, capsule_id, namespace) {
   cache_key = "css_#{capsule_id}_#{namespace}"
   should_cache = css.length > 100
   expires_at = Time.now + 1800
@@ -246,7 +268,7 @@ Writes CSS to files for HTTP caching. **Requires class method `def self.componen
 ```ruby
 class MyComponent < ApplicationComponent
   include StyleCapsule::Component
-  stylesheet_registry cache_strategy: :file
+  style_capsule cache_strategy: :file
 
   # Must use class method for file caching
   def self.component_styles
@@ -265,10 +287,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 +305,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

@@ -227,23 +227,104 @@ module StyleCapsule
         end
       end
 
-      # Deprecated: Use stylesheet_registry instead
-      # @deprecated Use {#stylesheet_registry} instead
-      def head_rendering!
-        stylesheet_registry
-      end
-
-      # Check if component uses head rendering
+      # Check if component uses head rendering (checks instance variable, then parent class, defaults to false)
+      #
+      # @return [Boolean] Whether head rendering is enabled (default: false)
       def head_rendering?
-        return false unless defined?(@head_rendering)
-        @head_rendering
+        if defined?(@head_rendering)
+          @head_rendering
+        elsif superclass.respond_to?(:head_rendering?, true)
+          superclass.head_rendering?
+        else
+          false
+        end
       end
 
       public :head_rendering?
 
-      # Get the namespace for stylesheet registry
+      # Get the namespace for stylesheet registry (checks instance variable, then parent class, defaults to nil)
+      #
+      # @return [Symbol, String, nil] The namespace identifier (default: nil)
       def stylesheet_namespace
-        @stylesheet_namespace if defined?(@stylesheet_namespace)
+        if defined?(@stylesheet_namespace) && @stylesheet_namespace
+          @stylesheet_namespace
+        elsif superclass.respond_to?(:stylesheet_namespace, true)
+          superclass.stylesheet_namespace
+        end
+      end
+
+      # Configure StyleCapsule settings
+      #
+      # All settings support class inheritance - child classes inherit settings from parent classes
+      # and can override them by calling style_capsule again with different values.
+      #
+      # @param namespace [Symbol, String, nil] Default namespace for stylesheets
+      # @param cache_strategy [Symbol, String, Proc, nil] Cache strategy: :none (default), :time, :proc, :file
+      # @param cache_ttl [Integer, ActiveSupport::Duration, nil] Time-to-live in seconds (for :time strategy)
+      # @param cache_proc [Proc, nil] Custom cache proc (for :proc strategy)
+      # @param scoping_strategy [Symbol, nil] CSS scoping strategy: :selector_patching (default) or :nesting
+      # @param head_rendering [Boolean, nil] Enable head rendering (default: true if any option is set, false otherwise)
+      # @return [void]
+      # @example Basic usage with namespace
+      #   class AdminComponent < ApplicationComponent
+      #     include StyleCapsule::Component
+      #     style_capsule namespace: :admin
+      #
+      #     def view_template
+      #       register_stylesheet("stylesheets/admin/dashboard")  # Uses :admin namespace automatically
+      #       div { "Content" }
+      #     end
+      #   end
+      # @example With all options
+      #   class MyComponent < ApplicationComponent
+      #     include StyleCapsule::Component
+      #     style_capsule(
+      #       namespace: :user,
+      #       cache_strategy: :time,
+      #       cache_ttl: 1.hour,
+      #       scoping_strategy: :nesting
+      #     )
+      #   end
+      # @example Inheritance - child class inherits parent settings
+      #   class BaseComponent < ApplicationComponent
+      #     include StyleCapsule::Component
+      #     style_capsule namespace: :admin, cache_strategy: :time, cache_ttl: 1.hour
+      #   end
+      #
+      #   class ChildComponent < BaseComponent
+      #     # Inherits namespace: :admin, cache_strategy: :time, cache_ttl: 1.hour
+      #     # Can override specific settings:
+      #     style_capsule namespace: :user  # Overrides namespace, keeps cache settings
+      #   end
+      def style_capsule(namespace: nil, cache_strategy: nil, cache_ttl: nil, cache_proc: nil, scoping_strategy: nil, head_rendering: nil)
+        # Set namespace (stored in instance variable, but getter checks parent class for inheritance)
+        if namespace
+          @stylesheet_namespace = namespace
+        end
+
+        # Configure cache strategy if provided
+        if cache_strategy || cache_ttl || cache_proc
+          normalized_strategy, normalized_proc = normalize_cache_strategy(cache_strategy || :none, cache_proc)
+          @inline_cache_strategy = normalized_strategy
+          # Explicitly set cache_ttl (even if nil) to override parent's value when cache settings are changed
+          @inline_cache_ttl = cache_ttl
+          @inline_cache_proc = normalized_proc
+        end
+
+        # Configure CSS scoping strategy if provided
+        if scoping_strategy
+          unless [:selector_patching, :nesting].include?(scoping_strategy)
+            raise ArgumentError, "scoping_strategy must be :selector_patching or :nesting (got: #{scoping_strategy.inspect})"
+          end
+          @css_scoping_strategy = scoping_strategy
+        end
+
+        # Enable head rendering if explicitly set or if any option is provided (except scoping_strategy)
+        if head_rendering.nil?
+          @head_rendering = true if namespace || cache_strategy || cache_ttl || cache_proc
+        else
+          @head_rendering = head_rendering
+        end
       end
 
       # Get the custom scope ID if set (alias for capsule_id getter)
@@ -251,22 +332,55 @@ module StyleCapsule
         @custom_capsule_id if defined?(@custom_capsule_id)
       end
 
-      # Get inline cache strategy
+      # Get inline cache strategy (checks instance variable, then parent class, defaults to nil)
+      #
+      # @return [Symbol, nil] The cache strategy (default: nil)
       def inline_cache_strategy
-        @inline_cache_strategy if defined?(@inline_cache_strategy)
+        if defined?(@inline_cache_strategy) && @inline_cache_strategy
+          @inline_cache_strategy
+        elsif superclass.respond_to?(:inline_cache_strategy, true)
+          superclass.inline_cache_strategy
+        end
       end
 
-      # Get inline cache TTL
+      # Get inline cache TTL (checks instance variable, then parent class, defaults to nil)
+      #
+      # @return [Integer, ActiveSupport::Duration, nil] The cache TTL (default: nil)
       def inline_cache_ttl
-        @inline_cache_ttl if defined?(@inline_cache_ttl)
+        if defined?(@inline_cache_ttl)
+          @inline_cache_ttl
+        elsif superclass.respond_to?(:inline_cache_ttl, true)
+          superclass.inline_cache_ttl
+        end
       end
 
-      # Get inline cache proc
+      # Get inline cache proc (checks instance variable, then parent class, defaults to nil)
+      #
+      # @return [Proc, nil] The cache proc (default: nil)
       def inline_cache_proc
-        @inline_cache_proc if defined?(@inline_cache_proc)
+        if defined?(@inline_cache_proc)
+          @inline_cache_proc
+        elsif superclass.respond_to?(:inline_cache_proc, true)
+          superclass.inline_cache_proc
+        end
       end
 
-      public :head_rendering?, :stylesheet_namespace, :custom_capsule_id, :inline_cache_strategy, :inline_cache_ttl, :inline_cache_proc
+      public :head_rendering?, :stylesheet_namespace, :style_capsule, :custom_capsule_id, :inline_cache_strategy, :inline_cache_ttl, :inline_cache_proc
+
+      # Get CSS scoping strategy (checks instance variable, then parent class, defaults to :selector_patching)
+      #
+      # @return [Symbol] The current scoping strategy (default: :selector_patching)
+      def css_scoping_strategy
+        if defined?(@css_scoping_strategy) && @css_scoping_strategy
+          @css_scoping_strategy
+        elsif superclass.respond_to?(:css_scoping_strategy, true)
+          superclass.css_scoping_strategy
+        else
+          :selector_patching
+        end
+      end
+
+      public :css_scoping_strategy
 
       # Set or get options for stylesheet_link_tag when using file-based caching
       #
@@ -289,58 +403,6 @@ module StyleCapsule
       end
 
       public :stylesheet_link_options
-
-      # Set or get CSS scoping strategy
-      #
-      # @param strategy [Symbol, nil] Scoping strategy: :selector_patching (default) or :nesting (omit to get current value)
-      #   - :selector_patching: Adds [data-capsule="..."] prefix to each selector (better browser support)
-      #   - :nesting: Wraps entire CSS in [data-capsule="..."] { ... } (more performant, requires CSS nesting support)
-      # @return [Symbol] The current scoping strategy (default: :selector_patching)
-      # @example Using CSS nesting (requires Chrome 112+, Firefox 117+, Safari 16.5+)
-      #   class MyComponent < ApplicationComponent
-      #     include StyleCapsule::Component
-      #     css_scoping_strategy :nesting  # More performant, no CSS parsing needed
-      #
-      #     def component_styles
-      #       <<~CSS
-      #         .section { color: red; }
-      #         .heading:hover { opacity: 0.8; }
-      #       CSS
-      #     end
-      #   end
-      #   # Output: [data-capsule="abc123"] { .section { color: red; } .heading:hover { opacity: 0.8; } }
-      # @example Using selector patching (default, better browser support)
-      #   class MyComponent < ApplicationComponent
-      #     include StyleCapsule::Component
-      #     css_scoping_strategy :selector_patching  # Default
-      #
-      #     def component_styles
-      #       <<~CSS
-      #         .section { color: red; }
-      #       CSS
-      #     end
-      #   end
-      #   # Output: [data-capsule="abc123"] .section { color: red; }
-      def css_scoping_strategy(strategy = nil)
-        if strategy.nil?
-          # Check if this class has a strategy set
-          if defined?(@css_scoping_strategy) && @css_scoping_strategy
-            @css_scoping_strategy
-          # Otherwise, check parent class (for inheritance)
-          elsif superclass.respond_to?(:css_scoping_strategy, true)
-            superclass.css_scoping_strategy
-          else
-            :selector_patching
-          end
-        else
-          unless [:selector_patching, :nesting].include?(strategy)
-            raise ArgumentError, "css_scoping_strategy must be :selector_patching or :nesting (got: #{strategy.inspect})"
-          end
-          @css_scoping_strategy = strategy
-        end
-      end
-
-      public :css_scoping_strategy
     end
 
     # Module that wraps view_template to add scoped wrapper
@@ -463,9 +525,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)