feat(webpack-plugin): unstable_layeredOutput for chunkable CSS via @layer

[layershifter]

Summary

Adds an opt-in GriffelPlugin({ unstable_layeredOutput: true }) that lets webpack's default SplitChunksPlugin chunk Griffel-extracted CSS into multiple files without breaking cascade order.

When the flag is on, every emitted atomic rule is wrapped in a CSS Cascade Layer (@layer griffel.<bucket>[.s<priority>][.q<N>] { … }), and the plugin prepends a build-time-discovered global layer manifest to every griffel-bearing CSS asset. Cross-chunk LVHA, shorthand→longhand priority, and overlapping @media breakpoints all resolve via layer order — independent of which CSS file the browser parses first.

When the flag is off, behavior is byte-identical to today (verified by 23 fixture-based inline-snapshot tests passing without regeneration).

Architecture

• @griffel/core: new opt-in BucketStrategy = 'leading' | 'extended'. 'extended' reclassifies nested-pseudo selectors (e.g. & .foo:hover) into their pseudo bucket so layer order doesn't defeat their specificity. Plumbed through resolveStyleRules and resolveStyleRulesForSlots.
• @griffel/transform: transformSync accepts and forwards bucketStrategy.
• @griffel/webpack-plugin:
  • New helpers: bucketLayerName, mediaPlaceholder, containerPlaceholder, hashOfQuery.
  • generateCSSRules({ wrapInLayer: true }) wraps each @griffel:css-start … @griffel:css-end block in @layer …. Marker comments stay outside the wrapper so parseCSSRules continues to find them at the top level.
  • Loader plumbs bucketStrategy and wrapInLayer from the loader context.
  • GriffelPlugin adds unstable_layeredOutput?: boolean. When on: skips the forced 'griffel' SplitChunks cache group + chunk-merge fallback; sets the loader-context flags; throws on combo with unstable_attachToEntryPoint.
  • processAssets runs a multi-chunk pass: walks all griffel-bearing CSS assets, aggregates the union set of @media and @container queries, sorts via compareMediaQueries, builds a global @layer ...; manifest, substitutes hash placeholders for q<N> indices, prepends the manifest to every asset.
• Runtime DOM renderer: untouched. No @layer at runtime; SSR rehydration unchanged.

Spec: docs/superpowers/specs/2026-04-25-griffel-css-chunking-design.md
Repro: apps/chunking-repro/ — three modes (default, split, layered) for side-by-side inspection.

Trade-offs / known limitations

• Layered rules lose to unlayered consumer / third-party CSS by CSS spec. Recommendation in spec: wrap consumer styles in their own layer. Out of scope here.
• Mixed extraction + runtime caveat: if an app extracts some styles (layered) and renders others at runtime, cascade for that mixed scenario is undefined. Most apps either fully extract or don't extract at all.
• Browser support: @layer requires Chrome 99+ / Safari 15.4+ / Firefox 97+ (released early 2022). Apps with older baselines should leave the flag off.
• Bucket t (@layer / @supports): not split into per-rule sub-layers in V1.

Test plan

• @griffel/core:test — 432 tests pass
• @griffel/transform:test — 80 tests pass
• @griffel/webpack-plugin:test — 59 tests pass (incl. 4 new unstable_layeredOutput tests covering manifest emission, layered output for nested-pseudo + priority shorthands, mutual exclusion with unstable_attachToEntryPoint)
• @griffel/webpack-plugin:type-check — clean
• Existing 23 inline-snapshot fixture tests pass without regeneration (byte-identical default-off path)
• e2e/rspack snapshot unchanged
• End-to-end: apps/chunking-repro builds in all three modes; layered mode produces 3 CSS files each starting with the global manifest, no placeholders remaining

Migration

This ships as unstable_layeredOutput for one release cycle. Once feedback settles (especially the unlayered-vs-layered consumer trade-off and the mixed-mode caveat), promote to a stable layeredOutput option.

🤖 Generated with Claude Code