style_capsule 2.0.2 → 2.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afc951f02fe29cd319b521b363049d3dba5e607099216e1782f48b4578f06f4b
-  data.tar.gz: 85916b390e95a3109da5a481f6b193a44309864499b5d3cb4ec4a634960c0ccd
+  metadata.gz: 7a6c3fda27b85ee3899cbe434dd5230de0d1c9c4ff6c961deefa9b058fd8f6b3
+  data.tar.gz: e70f42c7ee1fc234201107862e1c7dfe9f609a9a55333983101aed4d1ec74ff7
 SHA512:
-  metadata.gz: bf300d946cf83d68e40a16862698bd8354f8c51dd927e2fb4e6cb8fd9e3f1d6c6298bb545233132399ea496985e1a1b45b9279bae7b9467663a525ef4893f530
-  data.tar.gz: 95450d3eeef09959b75dca145f06abfe9f5e59619044d3456e43a1c073adac4e51e1c94e59187ddee72ba823de54c4cc640754d80373fdf1e18316e4b7046bb9
+  metadata.gz: 163cd5d8f4f0a324121a866adc94c48f31438cd560ba2b30b2d8f3721b645fe4a339e89308cb38552a96294fd8b01a834936615617ff6889203003f593c4e716
+  data.tar.gz: 39ca2e8c56745ddcbeae553b401e3e1b0a4b92409f0d066f0a50a9309bc3efac5369f38e929e6d04f0df991b8abbbe30723602c7f5458ac152a4bdf67ad4dc3a

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # CHANGELOG
 
+## 2.0.3 (2026-11-03)
+
+- Leave `@keyframes` / `@font-face` / `@property` steps unscoped under selector patching
+- Hoist non-nestable at-rules outside the CSS nesting wrapper
+- Clear pending request stylesheets when head injection cannot find `</head>`
+- Replace ActiveSupport `blank?` on core CSS and content-type checks
+- Warn once when `:file` cache strategy falls back to `:none` without class-method `component_styles`
+- Fail closed when release confirmation input reaches EOF; accept case-insensitive `y`
+- Require a dated CHANGELOG heading for the release version before `gem build`
+- Run the test workflow on pull requests targeting `main`
+
 ## 2.0.2 (2026-09-25)
 
 - Fix `HeadInjectionMiddleware` dropping pending stylesheets on bufferable chunked HTML

data/README.md

@@ -1,8 +1,8 @@
 # style_capsule
 
-[![Gem Version](https://badge.fury.io/rb/style_capsule.svg?v=2.0.2)](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://app.codecov.io/github/amkisko/style_capsule.rb)
+[![Gem Version](https://badge.fury.io/rb/style_capsule.svg?v=2.0.3)](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://app.codecov.io/github/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.
+CSS scoping for Ruby components. Attribute selectors encapsulate styles for Phlex, ViewComponent, and ERB so rules stay inside the component wrapper. Works with Rails and standalone in other Ruby frameworks (Sinatra, Hanami, and similar) or plain Ruby. Cache strategies: none, time-based, custom proc, and file-based.
 
 Design changes go through `rfcs/` (RFC 0001).
 
@@ -18,15 +18,15 @@ Then run `bundle install`.
 
 ## Features
 
-- **Attribute-based CSS scoping** (no class name renaming)
-- **Phlex, ViewComponent, and ERB support** with automatic Rails integration
-- **Per-component-type scope IDs** (shared across instances)
-- **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
+- Attribute-based CSS scoping (class names stay as written)
+- Phlex, ViewComponent, and ERB; Rails integration via the railtie
+- Per-component-type scope IDs (shared across instances)
+- Optional CSS nesting (`:nesting`) for browsers that support it
+- Stylesheet registry for head rendering, namespaces, and asset bundlers such as Propshaft
+- Cache strategies: none, time-based, custom proc, and file-based
+- `ActiveSupport::Notifications` events for CSS processing and file writes
+- Fallback output directory when the primary path is not writable
+- Path traversal checks, input validation, and CSS size limits
 
 ## Usage
 
@@ -103,8 +103,8 @@ StyleCapsule supports two CSS scoping strategies:
    - Better browser support (all modern browsers)
    - Output: `[data-capsule="abc123"] .section { color: red; }`
 
-2. **CSS Nesting (optional)**: Wraps entire CSS in `[data-capsule="..."] { ... }`
-   - More performant (no CSS parsing needed)
+2. **CSS Nesting (optional)**: Wraps nestable rules in `[data-capsule="..."] { ... }`
+   - Skips per-selector rewrite; hoists `@keyframes` / `@font-face` and similar to top level
    - Requires CSS nesting support (Chrome 112+, Firefox 117+, Safari 16.5+)
    - Output: `[data-capsule="abc123"] { .section { color: red; } }`
 
@@ -145,7 +145,7 @@ MyComponent.clear_css_cache
 
 ## Stylesheet Registry
 
-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:
+Register styles for head rendering when the layout should emit links or shared style tags instead of body `<style>` tags. Configure with `style_capsule`:
 
 ```ruby
 class MyComponent < ApplicationComponent
@@ -323,7 +323,7 @@ StyleCapsule::CssFileWriter.configure(
 )
 ```
 
-**Fallback Directory:** In production environments where the app directory is read-only (e.g., Docker containers), StyleCapsule automatically falls back to writing files under a per-user directory in `Dir.tmpdir` 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.
+**Fallback Directory:** When the primary output directory is not writable (for example a read-only app tree in a container), writes go under a per-user directory in `Dir.tmpdir`. If that write also fails, rendering uses inline CSS.
 
 **Precompilation:**
 
@@ -338,7 +338,7 @@ Files are automatically built during `bin/rails assets:precompile`.
 
 ## 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.
+Subscribe to `ActiveSupport::Notifications` for CSS processing and file write events. Metric payloads are built only when a subscriber is present.
 
 ### Available Events
 
@@ -469,9 +469,9 @@ For setup examples, API notes, and the relationship between `style_capsule` and
 ## How It Works
 
 1. **Scope ID Generation**: Each component class gets a unique scope ID based on its class name (shared across all instances)
-2. **CSS Rewriting**: CSS selectors are rewritten to include `[data-capsule="..."]` attribute selectors
-3. **HTML Wrapping**: Component content is automatically wrapped in a scoped element
-4. **No Class Renaming**: Class names remain unchanged (unlike Shadow DOM)
+2. **CSS Rewriting**: CSS selectors gain `[data-capsule="..."]` attribute selectors (or a nesting wrapper)
+3. **HTML Wrapping**: Component content is wrapped in a scoped element
+4. **Class names**: Class names in CSS and markup stay as written
 
 ## Development
 

data/docs/changelogs/20260904180000_audit-fixes.md

@@ -1,9 +1,13 @@
 # Audit fixes for style_capsule 2.0.1
 
-Recorded 2026-09-04. Implements the ranked findings from docs/issues/20260904174500_engineering-and-dependency-audit.md. Shipped in product CHANGELOG 2.0.2. json lockfile bump is recorded in docs/dependencies/20260904174500_json-cve-2026-71847.md.
+## Participants
+
+Andrei Makarov (@amkisko)
 
 ## Decisions
 
+Recorded 2026-09-04. Implements the ranked findings from docs/issues/20260904174500_engineering-and-dependency-audit.md. Shipped in product CHANGELOG 2.0.2. json lockfile bump is recorded in docs/dependencies/20260904174500_json-cve-2026-71847.md.
+
 Treat stored CSS as untrusted at the style-tag boundary. CssProcessor.reject_style_element_breakout! matches a case-insensitive style closer and raises ArgumentError. Call it after the size check in scope_selectors and scope_with_nesting, and again in render_inline_stylesheet. Empty CSS still returns early without that check.
 
 Allowlist non-Rails fallback link attributes. Emit only media, title, crossorigin, integrity, nonce, type, id, class, and data-* names. Escape values with CGI.escapeHTML. Never emit option href, rel, or event handlers. Keep href as /assets/#{validated_path}.css.

data/docs/changelogs/20260925094000_head-injection-bufferable-chunked.md

@@ -2,7 +2,7 @@
 
 ## Participants
 
-Andrei Makarov
+Andrei Makarov (@amkisko)
 
 ## Decisions
 

data/docs/changelogs/20260928193000_sync-appraisal-locks-after-version-bump.md

@@ -0,0 +1,19 @@
+## Participants
+
+Andrei Makarov (@amkisko)
+
+## Decisions
+
+Sync appraisal lockfiles to style_capsule 2.0.2 after the release bump left gemfiles/*.gemfile.lock on 2.0.1. Change usr/bin/release.rb to run appraisal install so path-gem version changes update those locks before the next push.
+
+## Effects
+
+test #37 on main (c41eb95) failed: all three matrix jobs exited bundle with code 16 under frozen install because the gemspec version no longer matched the appraisal locks. quality used Gemfile.lock (already 2.0.2) and passed. After updating the three locks, BUNDLE_FROZEN=true bundle check succeeds for each appraisal gemfile. BUNDLE_GEMFILE=gemfiles/rails8ruby34.gemfile bundle exec polyrun parallel-rspec --workers 5 --merge-failures exited 0.
+
+## Next
+
+Push patch/sync-appraisal-locks-2-0-2 and confirm the test workflow on main after merge.
+
+## Source
+
+https://github.com/amkisko/style_capsule.rb/actions/runs/36104324632

data/docs/issues/20260904174500_engineering-and-dependency-audit.md

@@ -1,9 +1,13 @@
 # Engineering and dependency audit of style_capsule 2.0.1
 
-Recorded 2026-09-04. Library gem. No product UI, database, queue, or worker. Pipeline is CSS and HTML in, processor and helpers, class and thread caches, optional file writer, stylesheet registry, optional Rack head injection, HTML out.
+## Participants
+
+Andrei Makarov (@amkisko)
 
 ## Decisions
 
+Recorded 2026-09-04. Library gem. No product UI, database, queue, or worker. Pipeline is CSS and HTML in, processor and helpers, class and thread caches, optional file writer, stylesheet registry, optional Rack head injection, HTML out.
+
 This pass is an audit only. No code change, no lockfile bump, no workflow edit. Rankings follow engineering-audit order: danger, then certainty, then impact, then fix cost. Dependency-audit ran because the request named both. The published gemspec has no runtime gems. json 2.21.1 is a development lockfile pin from activesupport and rubocop, not a consumer runtime of this gem.
 
 ## Effects

data/docs/issues/20260917123253_ci-drop-automatic-dependency-audit.md

@@ -2,7 +2,7 @@ CI quality failed on a trailing blank line in spec/support/junit_formatter.rb. T
 
 ## Participants
 
-- amkisko
+Andrei Makarov (@amkisko)
 
 ## Decisions
 

data/docs/issues/20261103150931_engineering-prose-release-audit.md

@@ -0,0 +1,40 @@
+# Engineering and prose audit before 2.0.3 publish
+
+## Participants
+
+Andrei Makarov (@amkisko)
+
+## Decisions
+
+Re-audit main for the unpublished 2.0.3 cut after the 2026-10-28 release-tooling pass. Include CssProcessor keyframes and nesting hoist, pending head clear when `</head>` is missing, ActiveSupport-free blank checks, `:file` cache fallback warning, release confirmation and changelog gates, pull_request CI, and ASCII docs punctuation. Leave tag and RubyGems publish to `make release` after commit.
+
+## Effects
+
+Pipeline: component/helper render -> CssProcessor -> StylesheetRegistry / CssFileWriter -> HeadInjectionMiddleware -> HTML. Boundary mode covered Rack body buffering and filesystem writes. Resource and identification modes: no new person identifiers in gem logs; cold-require numbers stay session observations. Queue, worker, learned-system, and physical plant modes skipped (absent).
+
+Ranked fixes applied:
+
+1. Skip selector patching inside `@keyframes` / `@font-face` / `@property` (high confidence, observed; prior keyframes example was futile).
+2. Hoist non-nestable at-rules outside the nesting wrapper (high confidence, observed).
+3. Clear pending request stylesheets when inject cannot find `</head>` or tags are empty (high confidence, observed).
+4. Replace `blank?` with nil/empty checks in CssProcessor and HeadInjectionMiddleware (high confidence, observed).
+5. Warn once when `:file` falls back to `:none` without class-method `component_styles` (high confidence, observed).
+6. Changelog heading and confirmation specs; CHANGELOG dated 2026-11-03; prose pass on README, gemspec, docs/non_rails_support.md, and builder skip warn punctuation.
+
+Deferred:
+
+- Class-level CSS cache mutex under threaded hosts.
+- Deduping Phlex / ViewComponent / helper render paths and stylesheet_registry split.
+- `component_styles` double evaluation per render.
+- CssFileWriter positive-path cache revalidation after external delete.
+- Optional max-bytes skip for middleware buffering.
+
+## Next
+
+Commit, then `make release`.
+
+## Source
+
+- docs/reviews/20261103150931_engineering-prose-release-audit.md
+- CHANGELOG.md section 2.0.3 (2026-11-03)
+- Prior pass: docs/reviews/20261028_engineering-audit-release-preparation.md

data/docs/non_rails_support.md

@@ -81,5 +81,5 @@ stylesheets = StyleCapsule::StylesheetRegistry.request_inline_stylesheets
 
 ## Configuration entry points
 
-- **`style_capsule`** — Preferred class-level DSL for namespace, cache strategy, CSS scoping (`:selector_patching` or `:nesting`), head rendering, and wrapper `tag:`.
-- **`stylesheet_registry`** — Older alias that enables head rendering and cache options; new code should prefer `style_capsule` for a single configuration surface.
+- `style_capsule` - Class-level DSL for namespace, cache strategy, CSS scoping (`:selector_patching` or `:nesting`), head rendering, and wrapper `tag:`.
+- `stylesheet_registry` - Older alias for head rendering and cache options; use `style_capsule` in new code.

data/docs/reviews/20261028_engineering-audit-release-preparation.md

@@ -0,0 +1,25 @@
+# Engineering audit and release preparation
+
+## Participants
+
+Andrei Makarov (@amkisko)
+
+## Decisions
+
+- Treat end-of-input at the release confirmation prompt as rejection.
+- Keep the ViewComponent loading-error test isolated from unrelated class ancestry checks.
+- Run tests for pull requests targeting `main`.
+
+## Effects
+
+- `make test`, RBS validation, RuboCop, and the sharded suite pass.
+- The 2.0.3 gem builds and passes `Gem::Package#verify`.
+- A local cold require used 0.398 CPU seconds and 33,308,672 bytes peak RSS. These are single-machine observations, not release budgets.
+
+## Next
+
+- Review the worktree, commit it, and let the release workflow create the tag and publish the gem.
+
+## Source
+
+Iterative engineering audit on 2026-10-28.

data/docs/reviews/20261103150931_engineering-prose-release-audit.md

@@ -0,0 +1,42 @@
+# Engineering and prose audit before 2.0.3 publish
+
+## Participants
+
+Andrei Makarov (@amkisko)
+
+## Decisions
+
+Re-audit main for the unpublished 2.0.3 cut. Include member CssProcessor keyframes and nesting, pending head clear, blank checks, file-cache warn, release gates, pull_request CI, and ASCII docs punctuation. Leave tag and RubyGems publish to make release after commit.
+
+## Effects
+
+Pipeline: render -> CssProcessor -> registry / file writer -> head inject -> HTML. Boundary mode covered Rack buffering and disk writes. Resource and identification modes: no new person identifiers in gem logs. Queue, worker, learned-system, and physical plant modes skipped (absent).
+
+Ranked fixes applied:
+
+1. Unscoped `@keyframes` / `@font-face` / `@property` steps under selector patching (high confidence, observed).
+2. Hoist non-nestable at-rules outside nesting wrapper (high confidence, observed).
+3. Clear pending request stylesheets when `</head>` is missing (high confidence, observed).
+4. Nil/empty checks instead of ActiveSupport `blank?` on core paths (high confidence, observed).
+5. Warn once on illegal `:file` cache fallback (high confidence, observed).
+6. Changelog heading and confirmation specs; CHANGELOG dated 2026-11-03.
+7. ASCII and marketing-tone pass on README, CHANGELOG, gemspec, and docs/non_rails_support.md.
+
+Deferred (documented in the issue): class CSS cache mutex, helper/component dedupe, double `component_styles` eval, file-path cache revalidation, middleware max-bytes.
+
+Checks observed in this session:
+
+- bundle exec rubocop on touched Ruby files: 11 files, no offenses.
+- bundle exec rbs validate: ok.
+- bundle exec rspec on css_processor, stylesheet_registry, head_injection_middleware, component, view_component, release_version_check: 249 examples, 0 failures.
+- bundle exec polyrun parallel-rspec --workers 5 --merge-failures: exit 0; coverage/merged-summary.txt 97.00% lines (1101 / 1135) across 19 files.
+- gem build style_capsule.gemspec and Gem::Package#verify for 2.0.3: ok.
+
+## Next
+
+Commit, then make release.
+
+## Source
+
+- docs/issues/20261103150931_engineering-prose-release-audit.md
+- CHANGELOG.md section 2.0.3 (2026-11-03)

data/lib/style_capsule/component.rb

@@ -168,7 +168,7 @@ module StyleCapsule
 
         # File caching is only allowed for class method component_styles
         if cache_strategy == :file && !file_caching_allowed?
-          # Fall back to :none strategy if file caching requested but not allowed
+          warn_file_cache_fallback(self.class)
           cache_strategy = :none
           cache_ttl = nil
           cache_proc = nil

data/lib/style_capsule/component_builder.rb

@@ -113,7 +113,7 @@ module StyleCapsule
           file_path
         rescue ArgumentError, NoMethodError => e
           # Component requires arguments or has dependencies - skip it (common for ViewComponent with required kwargs)
-          warn "[style_capsule] Skipped #{component_class.name} in style_capsule:build — #{e.class}: #{e.message}"
+          warn "[style_capsule] Skipped #{component_class.name} in style_capsule:build - #{e.class}: #{e.message}"
           output_proc&.call("Skipped #{component_class.name}: #{e.message}")
           nil
         end

data/lib/style_capsule/component_styles_support.rb

@@ -48,6 +48,16 @@ module StyleCapsule
 
     private
 
+    def warn_file_cache_fallback(component_class)
+      return if component_class.instance_variable_get(:@_style_capsule_file_cache_warned)
+
+      component_class.instance_variable_set(:@_style_capsule_file_cache_warned, true)
+      label = component_class.name
+      label = component_class.inspect if label.nil? || label.empty?
+      warn "[StyleCapsule] :file cache strategy requires class-method component_styles; " \
+           "falling back to :none for #{label}"
+    end
+
     # Check if component defines instance method styles
     #
     # @return [Boolean]

data/lib/style_capsule/css_processor.rb

@@ -7,15 +7,25 @@ module StyleCapsule
   #
   # Supports two scoping strategies:
   # 1. Selector patching (default): Adds [data-capsule="..."] prefix to each selector
-  #    - Better browser support (all modern browsers)
+  #    - Wider 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)
+  # 2. CSS nesting (optional): Wraps style rules in [data-capsule="..."] { ... }
+  #    - Avoids per-selector rewrite
   #    - Requires CSS nesting support (Chrome 112+, Firefox 117+, Safari 16.5+)
+  #    - Hoists non-nestable at-rules (@keyframes, @font-face, @import, ...) to top level
+  # rubocop:disable Metrics/ModuleLength -- processor owns patching, nesting hoist, and validation
   module CssProcessor
     # Maximum CSS content size (1MB) to prevent DoS attacks
     MAX_CSS_SIZE = 1_000_000
 
+    # At-rules whose inner selectors must not receive attribute scoping
+    NON_SCOPING_AT_RULES = %w[keyframes font-face property].freeze
+
+    # At-rules that must stay at the top level under CSS nesting
+    HOISTABLE_AT_RULES = %w[
+      keyframes font-face import charset namespace property
+    ].freeze
+
     # Rewrite CSS selectors to include attribute-based scoping
     #
     # Transforms:
@@ -26,25 +36,17 @@ module StyleCapsule
     #   [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)
+    # Uses attribute selectors instead of renaming classes, so styles apply only
+    # within scoped components. Leaves @keyframes / @font-face / @property steps alone.
     #
     # @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
-    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- selector patching walks CSS rules
     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
       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
@@ -52,72 +54,22 @@ module StyleCapsule
       reject_style_element_breakout!(css_string)
       validate_capsule_id!(capsule_id)
 
-      # 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 so they do not interfere with selector matching.
-        # Comments are removed from the output (typical for production CSS).
-        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
-
-        css_without_comments
+        patch_selectors(strip_comments(css_string.dup), capsule_attr)
       end
     end
-    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
-    # Scope CSS using CSS nesting (wraps entire CSS in [data-capsule] { ... })
+    # Scope CSS using CSS nesting (wraps nestable rules 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+).
+    # Avoids per-selector rewrite. Requires CSS nesting support in browsers
+    # (Chrome 112+, Firefox 117+, Safari 16.5+). Non-nestable at-rules are written
+    # before the wrapper so @keyframes and @font-face stay valid.
     #
     # Transforms:
     #   .section { color: red; }
@@ -132,12 +84,12 @@ 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
+    # @return [String] CSS with nesting wrapper and hoisted at-rules
     # @raise [ArgumentError] If CSS content exceeds maximum size or capsule_id is invalid
+    # rubocop:disable Metrics/AbcSize -- size check, breakout, instrument, then hoist and wrap
     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
       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
@@ -145,27 +97,27 @@ module StyleCapsule
       reject_style_element_breakout!(css_string)
       validate_capsule_id!(capsule_id)
 
-      # 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}"
+        hoisted, nestable = hoist_top_level_at_rules(css_string)
+        parts = []
+        parts << hoisted unless hoisted.empty?
+        parts << "#{capsule_attr} {\n#{nestable}\n}" unless nestable.strip.empty?
+        parts.join("\n")
       end
     end
+    # rubocop:enable Metrics/AbcSize
 
     # 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
 
@@ -177,7 +129,10 @@ module StyleCapsule
     # @param css_string [String, nil] CSS that will be placed inside a style tag
     # @raise [ArgumentError] If the string contains a style element closer
     def self.reject_style_element_breakout!(css_string)
-      return if css_string.blank?
+      # Core path must not call ActiveSupport String#blank?
+      # rubocop:disable Rails/Blank -- standalone hosts may lack ActiveSupport
+      return if css_string.nil? || css_string.empty?
+      # rubocop:enable Rails/Blank
       return unless css_string.match?(%r{</style}i)
 
       raise ArgumentError, "CSS content must not contain a style element closer"
@@ -192,23 +147,191 @@ module StyleCapsule
         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!
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- walks braces and at-rules in one pass
+    def self.patch_selectors(css, capsule_attr)
+      output = +""
+      index = 0
+      length = css.length
+      brace_depth = 0
+      suppress_below_depth = nil
+
+      while index < length
+        while index < length && css[index].match?(/\s/)
+          output << css[index]
+          index += 1
+        end
+        break if index >= length
+
+        if css[index] == "}"
+          output << "}"
+          index += 1
+          brace_depth -= 1
+          if !suppress_below_depth.nil? && brace_depth <= suppress_below_depth
+            suppress_below_depth = nil
+          end
+          next
+        end
+
+        selector_start = index
+        while index < length && css[index] != "{" && css[index] != "}"
+          index += 1
+        end
+
+        selectors_raw = css[selector_start...index]
+        if index >= length || css[index] == "}"
+          output << selectors_raw
+          next
+        end
+
+        selectors = selectors_raw.strip
+        at_name = selectors[/\A@([a-zA-Z-]+)/, 1]&.downcase
+        entering_non_scoping = at_name && NON_SCOPING_AT_RULES.include?(at_name) && suppress_below_depth.nil?
+
+        skip_scoping = !suppress_below_depth.nil? ||
+          selectors.start_with?("@") ||
+          selectors_raw.include?("[data-capsule=") ||
+          selectors.empty?
+
+        if skip_scoping
+          output << selectors_raw
+          if entering_non_scoping
+            suppress_below_depth = brace_depth
+          end
+        else
+          scoped_selectors = selectors.split(",").map do |selector|
+            selector = selector.strip
+            next selector if selector.empty?
+
+            if selector.start_with?(":host")
+              selector
+                .gsub(/^:host-context\(([^)]+)\)/, "#{capsule_attr} \\1")
+                .gsub(/^:host\(([^)]+)\)/, "#{capsule_attr}\\1")
+                .gsub(/^:host\b/, capsule_attr)
+            else
+              "#{capsule_attr} #{selector}"
+            end
+          end.join(", ")
+
+          leading = selectors_raw[/\A\s*/]
+          trailing = selectors_raw[/\s*\z/]
+          output << "#{leading}#{scoped_selectors}#{trailing}"
+        end
+
+        output << "{"
+        index += 1
+        brace_depth += 1
+      end
+
+      output
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- splits top-level CSS into hoistable and nestable parts
+    def self.hoist_top_level_at_rules(css)
+      hoisted = []
+      nestable = +""
+      index = 0
+      length = css.length
+
+      while index < length
+        while index < length && css[index].match?(/\s/)
+          nestable << css[index]
+          index += 1
+        end
+        break if index >= length
+
+        if css[index] == "@"
+          at_name = css[index..][/\A@([a-zA-Z-]+)/, 1]&.downcase
+          if at_name && HOISTABLE_AT_RULES.include?(at_name)
+            block, index = read_top_level_at_rule(css, index)
+            hoisted << block.strip
+            next
+          end
+        end
+
+        rule, index = read_top_level_rule(css, index)
+        nestable << rule
+      end
+
+      [hoisted.join("\n"), nestable]
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- semicolon vs braced at-rule forms
+    def self.read_top_level_at_rule(css, index)
+      start_index = index
+      length = css.length
+
+      while index < length && css[index] != "{" && css[index] != ";"
+        index += 1
+      end
+
+      if index < length && css[index] == ";"
+        index += 1
+        return [css[start_index...index], index]
+      end
+
+      raise ArgumentError, "Unterminated at-rule in CSS" if index >= length
+
+      index = consume_braced_block(css, index)
+      [css[start_index...index], index]
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+    def self.read_top_level_rule(css, index)
+      start_index = index
+      length = css.length
+
+      while index < length && css[index] != "{"
+        index += 1
+      end
+
+      return [css[start_index...index], index] if index >= length
+
+      index = consume_braced_block(css, index)
+      [css[start_index...index], index]
+    end
+
+    # rubocop:disable Metrics/MethodLength -- brace depth walk with unterminated guard
+    def self.consume_braced_block(css, index)
+      length = css.length
+      raise ArgumentError, "Expected opening brace in CSS" unless css[index] == "{"
+
+      depth = 0
+      while index < length
+        case css[index]
+        when "{"
+          depth += 1
+        when "}"
+          depth -= 1
+          index += 1
+          return index if depth.zero?
+
+          next
+        end
+        index += 1
+      end
+
+      raise ArgumentError, "Unterminated CSS block"
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    private_class_method :strip_comments, :validate_capsule_id!, :patch_selectors,
+      :hoist_top_level_at_rules, :read_top_level_at_rule, :read_top_level_rule,
+      :consume_braced_block
   end
+  # rubocop:enable Metrics/ModuleLength
 end

data/lib/style_capsule/head_injection_middleware.rb

@@ -61,7 +61,10 @@ module StyleCapsule
     end
 
     def html_content_type?(content_type)
-      return false if content_type.blank?
+      # Core path must not call ActiveSupport String#blank?
+      # rubocop:disable Rails/Blank -- standalone hosts may lack ActiveSupport
+      return false if content_type.nil? || content_type.empty?
+      # rubocop:enable Rails/Blank
 
       content_type.split(";", 2).first.to_s.strip.match?(HTML_CONTENT_TYPE)
     end

data/lib/style_capsule/stylesheet_registry.rb

@@ -728,10 +728,16 @@ module StyleCapsule
       return html if pending_stylesheets.empty?
 
       closing_head_index = html.match(%r{</head>}i)&.begin(0)
-      return html unless closing_head_index
+      unless closing_head_index
+        clear
+        return html
+      end
 
       tags = render_stylesheet_tags(pending_stylesheets, view_context)
-      return html if tags.empty?
+      if tags.empty?
+        clear
+        return html
+      end
 
       injected = html.dup
       injected.insert(closing_head_index, "#{tags}\n")

data/lib/style_capsule/version.rb

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

data/lib/style_capsule/view_component.rb

@@ -167,7 +167,7 @@ module StyleCapsule
 
         # File caching is only allowed for class method component_styles
         if cache_strategy == :file && !file_caching_allowed?
-          # Fall back to :none strategy if file caching requested but not allowed
+          warn_file_cache_fallback(self.class)
           cache_strategy = :none
           cache_ttl = nil
           cache_proc = nil

data/sig/style_capsule.rbs

@@ -6,9 +6,12 @@ module StyleCapsule
   end
 
   module CssProcessor
+    MAX_CSS_SIZE: Integer
+    NON_SCOPING_AT_RULES: Array[String]
+    HOISTABLE_AT_RULES: Array[String]
+
     def self.scope_selectors: (String css_string, String capsule_id, ?component_class: Class | String | nil) -> String
     def self.scope_with_nesting: (String css_string, String capsule_id, ?component_class: Class | String | nil) -> String
-    def self.strip_comments: (String css) -> String
     def self.reject_style_element_breakout!: (String | nil css_string) -> void
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: style_capsule
 version: !ruby/object:Gem::Version
-  version: 2.0.2
+  version: 2.0.3
 platform: ruby
 authors:
 - Andrei Makarov
@@ -273,11 +273,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.0'
-description: Provides component-scoped CSS encapsulation using [data-capsule] attributes
-  for Phlex components, ViewComponent components, and ERB templates. Styles are automatically
-  scoped to prevent leakage between components. Inspired by component-based CSS approaches
-  like Angular's view encapsulation and CSS modules. Works with Rails and can be used
-  standalone in other Ruby frameworks (Sinatra, Hanami, etc.) or plain Ruby scripts.
+description: Attribute-based CSS scoping via [data-capsule] for Phlex, ViewComponent,
+  and ERB. Works with Rails and standalone in other Ruby frameworks or plain Ruby.
 email:
 - contact@kiskolabs.com
 executables: []
@@ -290,10 +287,14 @@ files:
 - SECURITY.md
 - docs/changelogs/20260904180000_audit-fixes.md
 - docs/changelogs/20260925094000_head-injection-bufferable-chunked.md
+- docs/changelogs/20260928193000_sync-appraisal-locks-after-version-bump.md
 - docs/dependencies/20260904174500_json-cve-2026-71847.md
 - docs/issues/20260904174500_engineering-and-dependency-audit.md
 - docs/issues/20260917123253_ci-drop-automatic-dependency-audit.md
+- docs/issues/20261103150931_engineering-prose-release-audit.md
 - docs/non_rails_support.md
+- docs/reviews/20261028_engineering-audit-release-preparation.md
+- docs/reviews/20261103150931_engineering-prose-release-audit.md
 - lib/style_capsule.rb
 - lib/style_capsule/asset_path.rb
 - lib/style_capsule/class_registry.rb