style_capsule 2.0.1 → 2.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66f1dc7d0d5addb480cfba5b2301305f390e23b8f6d533c69e57d8703fe9bf9d
-  data.tar.gz: 559cb7b3d87328da61419bf7a8ce1f4014a4425e4476966bfa0b129acc2fca26
+  metadata.gz: 7a6c3fda27b85ee3899cbe434dd5230de0d1c9c4ff6c961deefa9b058fd8f6b3
+  data.tar.gz: e70f42c7ee1fc234201107862e1c7dfe9f609a9a55333983101aed4d1ec74ff7
 SHA512:
-  metadata.gz: cfa2dd98b0465d2d83145b11801e35b7f7a1f1e8d4d26fb18ae8f2c9af35b4d6d4b58a8d4fed3c66d037c45dd8e1a988091b9d8aef28b50e9981c1a03a3f0807
-  data.tar.gz: 10390d9e96e507b1966a4b31bc4eb490d232eda1034f029a1604d7765d75653c75b1649054aa0170b2b32acba4eca406b5c49922823696e95da3f0da24ce4c40
+  metadata.gz: 163cd5d8f4f0a324121a866adc94c48f31438cd560ba2b30b2d8f3721b645fe4a339e89308cb38552a96294fd8b01a834936615617ff6889203003f593c4e716
+  data.tar.gz: 39ca2e8c56745ddcbeae553b401e3e1b0a4b92409f0d066f0a50a9309bc3efac5369f38e929e6d04f0df991b8abbbe30723602c7f5458ac152a4bdf67ad4dc3a

data/CHANGELOG.md

@@ -1,6 +1,25 @@
 # CHANGELOG
 
-## Unreleased
+## 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
+- Inject when the Rack body responds to `to_ary`; skip only non-bufferable streaming bodies
+- After rewrite, set `Content-Length` and remove `Transfer-Encoding`
+- Fail closed when CSS would close a style tag before it is written into HTML
+- Escape allowed attributes on the non-Rails stylesheet link fallback
+- Bound the inline stylesheet cache
+- Align documented Ruby and Rails floors with the gemspec
 
 ## 2.0.1 (2026-07-03)
 

data/README.md

@@ -1,8 +1,10 @@
 # style_capsule
 
-[![Gem Version](https://badge.fury.io/rb/style_capsule.svg?v=2.0.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=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).
 
 ## Installation
 
@@ -16,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
 
@@ -101,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; } }`
 
@@ -143,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
@@ -256,7 +258,7 @@ By default, `StyleCapsule::HeadInjectionMiddleware` appends pending request-scop
 config.style_capsule.head_injection_middleware = false
 ```
 
-The middleware skips chunked responses (`Transfer-Encoding: chunked`) and does not buffer the body when no pending request-scoped stylesheets remain. For ActionController::Live, SSE, or other streaming HTML, disable it and inject manually with `StyleCapsule::StylesheetRegistry.inject_pending_head_stylesheets` if needed.
+The middleware only rewrites bufferable bodies (Rack bodies that respond to `to_ary`). Chunked HTML with a bufferable body is injected, then returned with `Content-Length` and without `Transfer-Encoding`. Non-bufferable streaming bodies (ActionController::Live, SSE, and similar) are left alone; disable the middleware and inject manually with `StyleCapsule::StylesheetRegistry.inject_pending_head_stylesheets` if needed. The middleware does not buffer when no pending request-scoped stylesheets remain. When it does rewrite, it holds the full 2xx HTML body in memory.
 
 ## Caching Strategies
 
@@ -317,11 +319,11 @@ StyleCapsule::CssFileWriter.configure(
   filename_pattern: ->(component_class, capsule_id) {
     "capsule-#{capsule_id}.css"
   },
-  fallback_dir: "/tmp/style_capsule"  # Optional, defaults to /tmp/style_capsule
+  fallback_dir: StyleCapsule::CssFileWriter::FALLBACK_OUTPUT_DIR
 )
 ```
 
-**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.
+**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:**
 
@@ -336,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
 
@@ -452,9 +454,9 @@ end
 
 ## Requirements
 
-- Ruby >= 3.0
-- Rails >= 6.0, < 9.0 (optional, for Rails integration)
-- ActiveSupport >= 6.0, < 9.0 (optional, for Rails integration)
+- Ruby >= 3.4
+- Rails >= 7.0, < 9.0 (optional, for Rails integration)
+- ActiveSupport >= 7.0, < 9.0 (optional, for Rails integration)
 
 **Note**: The gem can be used without Rails! See [Non-Rails Support](#non-rails-support) below.
 
@@ -467,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
 
@@ -478,11 +480,11 @@ bundle install
 bundle exec appraisal install
 
 # Run tests
-bundle exec rspec
+bundle exec polyrun parallel-rspec --workers 5 --merge-failures
 
 # Run tests for all Rails versions
-bundle exec appraisal rails72 rspec
-bundle exec appraisal rails8ruby34 rspec
+bundle exec appraisal rails72 polyrun parallel-rspec --workers 5 --merge-failures
+bundle exec appraisal rails8ruby34 polyrun parallel-rspec --workers 5 --merge-failures
 
 # Linting
 bundle exec standardrb --fix
@@ -513,12 +515,25 @@ gem push style_capsule-*.gem
 
 StyleCapsule includes security protections:
 - Path traversal protection
-- Input validation
+- Capsule id and HTML attribute validation and escaping
 - Size limits (1MB per component)
-- XSS prevention via Rails' HTML escaping
+- Reject CSS that would close a style tag
 
 For detailed security information, see [SECURITY.md](SECURITY.md).
 
+## Links
+
+- [GitHub](https://github.com/amkisko/style_capsule.rb)
+- [GitLab](https://gitlab.com/amkisko/style_capsule.rb)
+- [RubyGems](https://rubygems.org/gems/style_capsule)
+- [Versions Atom](https://rubygems.org/gems/style_capsule/versions.atom) (feed id `9946895197223`)
+- [libraries.io](https://libraries.io/rubygems/style_capsule)
+- [Deps.dev](https://deps.dev/rubygems/style_capsule)
+- [SonarCloud](https://sonarcloud.io/project/overview?id=amkisko_style_capsule.rb)
+- [Snyk](https://snyk.io/test/github/amkisko/style_capsule.rb)
+- [Codecov](https://app.codecov.io/github/amkisko/style_capsule.rb)
+- [OpenSSF Scorecard](https://scorecard.dev/viewer/?uri=github.com/amkisko/style_capsule.rb)
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/SECURITY.md

@@ -2,27 +2,24 @@
 
 ## Reporting a Vulnerability
 
-**Do NOT** open a public GitHub issue for security vulnerabilities.
+Email security details to: security@kiskolabs.com
 
-Email security details to: **security@kiskolabs.com**
-
-Include: description, steps to reproduce, potential impact, and suggested fix (if available).
+Send the report only to that address. Include description, steps to reproduce, potential impact, and a suggested fix when you have one.
 
 ### Response Timeline
 
-- We will acknowledge receipt of your report
-- We will provide an initial assessment
-- We will keep you informed of our progress and resolution timeline
+- We will acknowledge receipt of your report.
+- We will provide an initial assessment.
+- We will keep you informed of our progress and resolution timeline.
 
 ### Disclosure Policy
 
-- 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
+- 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.
 
 ## Automation Security
 
-* **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.
-
-* **Supply Chain:** All automated dependencies must be verified.
+- Keep production credentials, API keys, and personal data out of prompts sent to third-party models or automation services.
+- Verify automated dependencies.

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

@@ -0,0 +1,33 @@
+# Audit fixes for style_capsule 2.0.1
+
+## 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.
+
+Cap the inline CSS cache at 256 entries with Hash insertion-order shift. Mutex around cache mutations uses unlocked cleanup internals so cached_inline does not deadlock if a cache proc re-enters. Mutex also wraps register_eager writes and clear_manifest. The process-wide manifest is not capped.
+
+CssFileWriter fallback directory is File.join(Dir.tmpdir, "style_capsule-#{Process.uid}"). Specs compare the FALLBACK_OUTPUT_DIR constant.
+
+Add pull_request to .github/workflows/test.yml. Drop npm and docker from Dependabot. Do not add fake gemfiles Dependabot directories. Remove unused memory_profiler from the gemspec. Do not split stylesheet_registry.rb in this pass.
+
+## Effects
+
+Specs added for style-tag breakout in CssProcessor and render_inline_stylesheet, quote and href and onload options on the non-Rails link fallback, and inline cache eviction of the oldest key. bundle exec rspec: 498 examples, 0 failures. bundle-audit check --no-update is clean on all four lockfiles with json 2.21.2.
+
+README Requirements match the gemspec (Ruby >= 3.4, Rails >= 7.0, < 9.0). Badge uses v=2.0.1. Security section names style-tag closer rejection and capsule id and HTML attribute validation. Middleware docs state that rewrite buffers the full 2xx HTML body.
+
+## Next
+
+stylesheet_registry.rb remains over the house line-count ceiling. Split only if a later change owns that file.
+
+## Source
+
+Parent issue docs/issues/20260904174500_engineering-and-dependency-audit.md. json note docs/dependencies/20260904174500_json-cve-2026-71847.md. Branch patch/audit-fixes. Release 2.0.2.

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

@@ -0,0 +1,25 @@
+# HeadInjectionMiddleware injects bufferable chunked HTML
+
+## Participants
+
+Andrei Makarov (@amkisko)
+
+## Decisions
+
+HeadInjectionMiddleware no longer skips every response with Transfer-Encoding chunked. Injection runs when the Rack body responds to to_ary. Non-bufferable streaming bodies are still passed through without calling each. After a successful rewrite, Transfer-Encoding is removed and Content-Length is set to the injected body size.
+
+## Effects
+
+Pending request-scoped stylesheet tags reach head on bufferable chunked HTML. True streaming responses without to_ary stay untouched. README late-head section matches that contract. Specs cover bufferable chunked inject and non-bufferable pass-through.
+
+## Next
+
+Shipped in 2.0.2. Confirm consumers that relied on the old skip still expect streaming bodies without to_ary.
+
+## Source
+
+lib/style_capsule/head_injection_middleware.rb
+spec/style_capsule/head_injection_middleware_spec.rb
+CHANGELOG.md 2.0.2
+README.md Late head injection
+Release 2.0.2.

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/dependencies/20260904174500_json-cve-2026-71847.md

@@ -0,0 +1,37 @@
+# json 2.21.1 CVE-2026-71847 in development lockfiles
+
+Recorded 2026-09-04 during an engineering and dependency audit of style_capsule 2.0.1. Not a drive-by hunt. bundler-audit reported the advisory on every lockfile this repository audits in CI.
+
+## Dependency
+
+Name: json. Locked version: 2.21.1. Constraint in this repo: none in the gemspec. The published gem has no runtime gems. Gemfile.lock shows json as a dependency of activesupport 8.1.3.1 and of rubocop 1.88.2 via json (~> 2.3). The same 2.21.1 pin appears in gemfiles/rails72.gemfile.lock, gemfiles/rails8ruby34.gemfile.lock, and gemfiles/rails8ruby4.gemfile.lock.
+
+## Symptom
+
+bundle-audit check fails. Title: JSON::ResumableParser#partial_value use-after-free crash on truncated duplicate-key streams. CVE-2026-71847. GHSA-9hj4-r449-hfvc. CVSS 8.7 availability. Affected 2.20.0 through 2.21.1. Solution: >= 2.21.2. StyleCapsule source does not parse JSON. A host that only adds this gem does not get json from this gemspec. Developers and CI that install this lockfile do.
+
+## Evidence
+
+Commands:
+
+bundle-audit update then bundle-audit check --no-update on Gemfile.lock.
+
+bundle-audit check --no-update --gemfile-lock gemfiles/rails72.gemfile.lock
+
+bundle-audit check --no-update --gemfile-lock gemfiles/rails8ruby34.gemfile.lock
+
+bundle-audit check --no-update --gemfile-lock gemfiles/rails8ruby4.gemfile.lock
+
+Observed: advisory database updated 2026-09-04, commit 478717d. All four locks named json 2.21.1 and the CVE above. bundle outdated --strict listed json 2.21.1 with newest 2.21.2. Rubygems versions API: 2.21.1 created 2026-07-13, 2.21.2 created 2026-07-31. GitHub advisory GHSA-9hj4-r449-hfvc. .github/workflows/dependency-audit.yml runs bundle-audit on every Gemfile.lock on push, pull_request, and weekly cron.
+
+## Suggested fix
+
+Upgrade. bundle update json in the root Gemfile and in each appraisal gemfile until lockfiles resolve json >= 2.21.2. Do not add json as a direct dependency only to pin it unless Bundler cannot reach 2.21.2 through activesupport and rubocop. No patch or vendor is needed. An upstream report is already published.
+
+## Next
+
+Lockfiles now pin json 2.21.2. bundle-audit check --no-update is clean on Gemfile.lock, gemfiles/rails72.gemfile.lock, gemfiles/rails8ruby34.gemfile.lock, and gemfiles/rails8ruby4.gemfile.lock. Keep the published gemspec free of json unless a later feature parses JSON on the hot path.
+
+## Source
+
+ruby-advisory-db via bundler-audit, commit 478717d. GHSA-9hj4-r449-hfvc. CVE-2026-71847. Rubygems json 2.21.2. Gemfile.lock activesupport and rubocop entries. .github/workflows/dependency-audit.yml. Parent issue usr/docs/issues/20260904174500_engineering-and-dependency-audit.md.

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

@@ -0,0 +1,51 @@
+# Engineering and dependency audit of style_capsule 2.0.1
+
+## 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
+
+Test workflow .github/workflows/test.yml runs on workflow_dispatch and push to main only. Lint and appraisal rspec do not run on pull_request. dependency-audit.yml does run on pull_request and would fail today on json 2.21.1 in Gemfile.lock and gemfiles/*.gemfile.lock.
+
+Inline CSS is interpolated into style tags and marked html_safe. Helpers use raw(scoped_css). README documents Theme#scoped_css from stored CSS and shows raw in ERB. README Security section claims XSS prevention via Rails HTML escaping. Capsule id is validated. CSS body is not sanitized for a style-tag break. Specs cover attribute escaping in StandaloneHelper, not a closing style tag in CSS.
+
+Non-Rails file stylesheet fallback interpolates option keys and values into a link tag. AssetPath rejects path traversal, quotes, angle brackets, and overlong logical paths. It does not reject a javascript: href scheme or quote characters in option values.
+
+StylesheetRegistry @inline_cache and @manifest are process-wide hashes without a mutex. Component CSS cache and helper scope cache cap at 256. File path cache caps at 512 with a mutex. Inline cache only drops entries that have expires_at. Registrations with type proc or no TTL grow for the process lifetime. README claims thread-safe head rendering.
+
+HeadInjectionMiddleware buffers a 2xx HTML body to inject before the first closing head tag. Chunked transfer is skipped. Live and SSE caveats are documented. Impact of the buffer under large HTML is inference. No RSS or timing bench this session.
+
+CssFileWriter falls back to /tmp/style_capsule, writes CSS, then returns nil so the registry can fall back to inline. Shared-host /tmp collision and symlink follow are inference. Fallback specs exist.
+
+README Requirements still say Ruby >= 3.0 and Rails >= 6.0. Gemspec required_ruby_version is >= 3.4. Development Rails gems are >= 7.0, < 9.0. Appraisals cover Rails 7.2 and 8.1 on Ruby 3.4 and 4.0. README badge still uses v=2.0.0. Version constant is 2.0.1.
+
+lib/style_capsule/stylesheet_registry.rb is 827 lines. House guidance prefers around 150 with a 300 ceiling. AssetPath and HeadInjectionMiddleware are already split out.
+
+CssProcessor walks CSS with regex up to 1MB. A comment claims MAX_CSS_SIZE mitigates ReDoS. ReDoS was not proven. Spike was not run.
+
+Dependabot lists npm and docker at directory / with no package.json and no Dockerfile. Bundler updates only directory /. Appraisal lockfiles under gemfiles/ are not a separate Dependabot directory.
+
+memory_profiler is a development gemspec dependency. No spec or lib caller was found this session.
+
+bundle-audit check --no-update on Gemfile.lock, gemfiles/rails72.gemfile.lock, gemfiles/rails8ruby34.gemfile.lock, and gemfiles/rails8ruby4.gemfile.lock all reported json 2.21.1, CVE-2026-71847, GHSA-9hj4-r449-hfvc, fix >= 2.21.2. Advisory database updated 2026-09-04, commit 478717d. Evidence is in usr/docs/dependencies/20260904174500_json-cve-2026-71847.md.
+
+bundle outdated --strict listed erb 6.0.6 to 6.0.7, io-console 0.8.2 to 0.9.2, json 2.21.1 to 2.21.2, polyrun 2.2.2 to 2.2.4, psych 5.4.0 to 5.5.0, rack 3.2.6 to 3.2.7, reline 0.6.3 to 0.7.0, view_component 4.12.0 to 4.15.0, webmock 3.26.2 to 3.26.4, zeitwerk 2.8.2 to 2.8.3. Release-date lag for those three named packages versus latest: json 18 days, polyrun 41 days, view_component 82 days. Full lockfile libyears versus every gem latest date was not computed. rspec was not run.
+
+Modes skipped with reason: product-surface, this gem has no own UI. Privacy, the gem does not collect personal data; host CSS may appear in instrumentation payloads when a subscriber exists. Observability, no product runtime or SLO of its own. Learned systems, none. Resource cheaper-or-greener without a bench stays inference. Identity claims without HAR or log fixtures stay inference.
+
+A later pass on 2026-09-04 implemented the ranked fixes on branch patch/audit-fixes. See usr/docs/changelogs/20260904180000_audit-fixes.md. bundle exec rspec: 498 examples, 0 failures. bundle exec rubocop and bundle exec rbs validate ran after the cop fix in CssProcessor.reject_style_element_breakout!. This file remains the audit record.
+
+## Next
+
+stylesheet_registry.rb remains over the house line-count ceiling. Split only if a later change owns that file. json lockfile bump is tracked in usr/docs/dependencies/20260904174500_json-cve-2026-71847.md.
+
+## Source
+
+engineering-audit and dependency-audit skills in .agents/skills. README Requirements and Security. style_capsule.gemspec. lib/style_capsule/version.rb. lib/style_capsule/stylesheet_registry.rb. lib/style_capsule/helper.rb. lib/style_capsule/standalone_helper.rb. lib/style_capsule/css_file_writer.rb. lib/style_capsule/head_injection_middleware.rb. .github/workflows/test.yml. .github/workflows/dependency-audit.yml. .github/dependabot.yml. Gemfile.lock and gemfiles/*.gemfile.lock. bundle-audit 0.9.x against ruby-advisory-db commit 478717d. bundle outdated --strict. ruby -Ilib require of StyleCapsule::ClassRegistry. Rubygems version API dates for json, polyrun, and view_component. Downstream canvas is outside this repo.

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

@@ -0,0 +1,28 @@
+CI quality failed on a trailing blank line in spec/support/junit_formatter.rb. Test CI also ran bundler-audit or osv-scanner, which fail whenever an advisory lands even when a separate dependency audit already exists.
+
+## Participants
+
+Andrei Makarov (@amkisko)
+
+## Decisions
+
+- Drop bundler-audit and security jobs from test.yml so tests no longer wait on advisory freshness.
+- Keep dependency-audit.yml as workflow_dispatch only. Do not run it on push, pull request, or schedule.
+- Disable osv-scanner in Trunk Check.
+- Disable markdownlint MD013 in .markdownlint.yaml. Keep AGENTS.md in Trunk so other markdownlint rules still run.
+- Keep lockfile and spec fixes that were already blocking quality or tests.
+
+## Effects
+
+- Test CI runs lint and specs without an advisory gate.
+- Trunk Check no longer treats dependency CVEs as a required check.
+- Manual dependency-audit remains available on workflow_dispatch.
+
+## Next
+
+- Run dependency audit on demand when a release or a known advisory needs it.
+- Do not reintroduce advisory scanners into test.yml.
+
+## Source
+
+- GitHub Actions test and Trunk Check failures on 2026-09-17

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]