rainbowindex 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -5,6 +5,203 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.1] - 2026-08-28
+
+### Fixed
+
+- **Inline SVG path data is no longer scanned for classes.** Raising the
+  line-length guard to 10,000 characters in 0.5.0 let a multi-KB `d="…"`
+  attribute reach the whole-file token scan, where path data tokenizes
+  cleanly against the class grammar: one 10 KB icon component went from 33
+  candidates to 845, the extra 812 being fragments like `9.17-57.2` and
+  `40c-.35-1.1-1.04`. They matched no utility and carried the `plain` origin
+  editors skip, so nothing rendered wrong and nothing was reported — each
+  one just cost a compile lookup and a cache entry on every build. `d` and
+  `points` values are now blanked before extraction, in every file type.
+  Only quoted values are matched, so `d={expr}` bindings still yield their
+  classes.
+- **A JavaScript term is no longer reported as a class.** Candidate origins
+  were assigned purely by span containment, so any token the whole-file scan
+  matched inside a helper call or class attribute inherited that context's
+  origin. The token scan's grammar also matches bare identifiers, so
+  `ri(mode === "default" ? "fill-white" : "fill-black")` reported `mode` with
+  `origin: "helper"` — and editors, which read a certain origin as "this is a
+  class", flagged it as an unknown class. A candidate now inherits a context's
+  origin only when a context-aware collector tokenized it; containment still
+  decides which context wins. Extracted values are unchanged, so no generated
+  CSS moves.
+- **Bare unquoted class attributes keep their `attribute` origin.**
+  `collectAssignedValues` now tokenizes an undelimited value (`class=flex` in
+  HTML, Vue and Svelte) the same way it already tokenized a quoted one. Without
+  this they would have lost provenance and demoted to `plain`.
+- **`@apply` no longer emits a rule with no selector.** A rule carrying both
+  the `group` marker and a `group-*` variant resolved its group root to
+  itself, so stripping the root prefix off the resolved selector left nothing:
+  `.self { @apply group group-hover:underline; }` emitted a bare
+  ` { text-decoration-line: underline; }`, which a browser discards as a parse
+  error, taking the declarations with it. The group root is the element, so
+  the variant now targets the element — `.self:hover`. The same shape reached
+  by climbing rather than matching in place, a nested `&` block inside the
+  group root, is fixed with it.
+- **RI-1002 no longer fires for a bracket token the scanner merely read.** An
+  unresolved arbitrary value is a typo worth reporting when the author wrote
+  the class, but the scanner reads whole files, comments and prose included,
+  where `min-[437px]` is just text — and every such token warned. Classes
+  written by hand still warn: `@source inline(...)`, `@apply`, and a
+  caller-supplied `classNames` list. Provenance is not baked into the compile
+  memo, so a class that is both scanned and authored warns once rather than
+  never.
+
+### Added
+
+- **RI-1412 — whitespace in an arbitrary value now warns.** A class name
+  cannot contain whitespace: `class`, `@a`/`@apply`, and `safelist()` all
+  split on it, so `bg-[url('a b')]` reaches the browser as the two tokens
+  `bg-[url('a` and `b')]` and matches nothing. The scanner has always dropped
+  these, silently, leaving no CSS and no reason why. The warning names the
+  class and points at the `_` escape (`bg-[url('a_b')]` emits `url('a b')`).
+  It fires only where a collector treats its input as a class list — an
+  attribute value, a helper argument, a `safelist()` argument — so ordinary
+  JS and prose stay quiet, `styles["my class"]` in a `className` expression
+  included. Extracted values are unchanged.
+- **`"expression"` candidate origin.** A string literal that is an operand of
+  `==`/`!=` (so also `===`/`!==`) cannot be a class list: in
+  `mode === "default"`, `"default"` is a value being compared. Such literals
+  are still extracted — dropping them would change generated CSS — but they
+  now report `origin: "expression"` instead of `"helper"`/`"attribute"`.
+  Editors should treat it like `"plain"` and never report it as a bad class.
+  Assignment is deliberately not matched: `const base = "px-2"` is an ordinary
+  class list.
+- **`candidate-origin-provenance` capability.** Feature-detect both behaviours
+  above through `editorCapabilities`, never a version compare.
+- **Functional custom utilities — `@utility name-* { … }`.** The body reads
+  `var(--value)` and the class suffix replaces it, nested blocks included:
+  `@utility glow-* { box-shadow: 0 0 var(--value) gold; }` answers `glow-4`
+  and `glow-[3px]`, with `[2px_4px]` decoding to `2px 4px`. An exact static
+  name beats a functional match, so `@utility card` and `@utility card-*`
+  coexist; the longest root wins between functional entries (`a-b-*` over
+  `a-*` for `a-b-4`); and neither a bare root (`glow`) nor a negated class
+  (`-glow-4`) matches. A suffix carrying `;`, `{`, or `}` is rejected rather
+  than allowed to break out of the declaration. `ri()` treats two suffixes of
+  one root as conflicting, so `ri("glow-4 glow-8")` keeps `glow-8`.
+- **Consumer documentation in [`docs/`](docs/README.md).** One page per
+  subject — getting started, class syntax, utilities, theming, fonts, source
+  scanning, class merging, diagnostics, environment variables — and one per
+  integration surface — CLI, PostCSS plugin, Vite plugin, Vite+, Node API,
+  editor API. The README keeps the overview and links out.
+- **Vite+ support.** The Vite plugin now adds every stylesheet that activates
+  Rainbow Index to `fmt.ignorePatterns`, so `vp check` no longer stops at
+  `Syntax error: component value is expected` before it can lint or type
+  check. Directive bodies are not valid CSS — a `@font` entry carries a block
+  after a declaration, a scale removes a token with `!name;`, `@fluid` takes
+  bare keywords, and `@apply` takes variant groups — and Oxfmt parses CSS
+  strictly. Vite+ reads its `fmt` block off the resolved Vite config, so the
+  plugin contributes the patterns from its `config` hook; plain Vite ignores
+  the extra key. Projects without the Vite plugin add the patterns by hand.
+  See [docs/vite-plus.md](docs/vite-plus.md).
+- **`rainbowindex/oxlint`.** A new entry point with one Oxlint rule,
+  `prefer-ri`, which reports an import of `clsx`, `classnames`, or
+  `tailwind-merge`. Each merges classes against a Tailwind utility table, so
+  it resolves conflicts against the wrong utility set and never sees the
+  theme. The rule is off until a project enables it, and the plugin has no
+  dependencies.
+
+### Changed
+
+- **`ri()` caches results in two generations instead of an LRU.** The old
+  cache moved every hit to the end of a `Map` so insertion order tracked
+  recency, which made the steady state — the same class lists on every render
+  — pay a delete and a re-insert per call. The new cache keeps a current and a
+  previous generation: a hit in the current one is a single `Map.get`, and
+  when the current fills it becomes the previous and a fresh one starts. A hit
+  on a previous entry promotes it, so hot keys survive the swap while cold
+  ones age out with the dropped generation. The cache now holds at most twice
+  `RI_CACHE_MAX` (500) entries instead of evicting the oldest quarter at the
+  cap, and `evictLRU` is gone with the design that needed it.
+- **The per-class compile memo is bounded.** Keyed on theme identity, it grew
+  for the life of the process, so a long dev session could hold every class
+  ever compiled against a still-live theme. It now clears wholesale at 50,000
+  entries. Steady state is the project's whole scanned vocabulary, which sits
+  far below the cap — a lower one would clear mid-compile on every rebuild and
+  defeat the memo.
+- **`@apply` resolution is cached per theme, not per invocation.** Every
+  rebuild re-resolved every `@apply` class from scratch, although the scan
+  analysis and pipeline memos keep the theme object stable across rebuilds, so
+  the old results were still valid. The cache is a `WeakMap` keyed on the
+  theme and dies with it. The `[RI-1005]` walk of a custom utility body is
+  cached alongside: its warnings are now replayed into every class that hits
+  the utility rather than emitted once per compile, so they survive a rebuild
+  in which the class that first triggered the walk is gone. The plugin still
+  dedupes repeats downstream.
+- **The resolved source-file list is cached while a watcher runs.** Each
+  rebuild re-globbed the project to find the same files. A cached list is only
+  correct while something reacts to file adds and deletes, so caching is
+  opt-in: the Vite plugin arms it and clears it from the dev-server watcher
+  (`add`, `unlink`, `unlinkDir`). One-shot builds and `postcss-cli --watch`,
+  which has no watcher hook, keep the always-fresh glob. A glob already in
+  flight when an invalidation arrives is not cached.
+- **A source edit that changes no class no longer re-transforms the CSS.** The
+  Vite plugin now keeps a sorted candidate list per source file and compares it
+  on every hot update. An edit to logic, comments, or copy leaves that list
+  identical, and identical candidates produce byte-identical CSS — so the
+  Rainbow Index stylesheets stay out of the update and only the edited module
+  reloads. A first sighting or an unreadable file invalidates conservatively.
+- **`preload-fonts --help` names the faces that produce a tag.** Only local
+  file and raw-URL faces marked `preload` do. Google serves CSS rather than the
+  font binary, so a Google or system slot never emits one — but the help text
+  claimed `@font-face` was covered too. Text only; the command is unchanged.
+
+### Removed
+
+- **The named radius scale.** `rounded-2xs` through `rounded-xl`, the bare
+  `rounded` / `rounded-t` / `rounded-tl` shorthands, the `--rounded-*`
+  variables, the `--rounded-roof` anchor, and the token body of `@rounded` are
+  all gone. A radius is now a spacing multiple: `rounded-4` is
+  `calc(var(--spacing) * 4 * var(--ri-rounded-scale, 1))`. `rounded-none`,
+  `rounded-full`, `rounded-scale-*`, arbitrary values, and every logical side
+  and corner (`rounded-t-4`, `rounded-ss-2`) are unchanged.
+
+  Two scales set the same shape, so they drifted apart: the named tokens hung
+  off `--rounded-roof` while the numeric forms hung off `--spacing`, and
+  `rounded-lg` next to `rounded-4` mixed two rhythms in one component. One
+  scale, anchored to spacing, keeps the whole system in step.
+
+  Migration: replace each named token with the spacing step you want. A
+  `@rounded` body that sets radius tokens now warns with `[RI-1122]`; keep
+  `--corner-scale` and drop the rest. `--roof` is gone — set the radius you
+  want on the element.
+
+### Notes for integrators
+
+`ResolvedTheme` lost `rounded` and `roundedRoof`, `Theme` lost `rounded`,
+`listThemeTokens()` no longer returns a `rounded` record, and
+`CompilationResult` lost `usedRounded`. Nothing prunes `--rounded-*` any more,
+because the token layer no longer emits it. `roundedShape` and
+`roundedShapeScale` stay — `@rounded <shape>` is unchanged.
+
+`CandidateOrigin` gained a member. Code that switches on it exhaustively must
+handle `"expression"`; code that tests `origin !== "plain"` to mean "this is a
+class" was already wrong and is now wrong in a new way — test for the origins
+you trust instead.
+
+`CompilationSnapshot` gained `customFunctionalProps`, the roots of functional
+`@utility` entries and the properties each one claims. `createThemeSnapshot()`
+fills it in; a snapshot built by hand needs the field.
+
+`createCompiler().compile()` takes an optional third argument, the set of
+classes the caller wrote by hand. Omit it and every class counts as authored,
+which is what a caller assembling its own list wants. `compileProject()`
+applies the same split on its own: `classNames` is authored, `sources` content
+is scanned.
+
+`getCustomUtility(theme, name)` is replaced by
+`matchCustomUtility(utility, value, negative, theme)`, which returns the
+matching entry and the text a functional body substitutes for `var(--value)`.
+The `@apply` walk and the declaration expansion both go through it, so they
+can never disagree about which utility a class hit. The old function resolved
+static entries only. Neither name is exported from the package entry, so only
+code importing the internal module path is affected.
+
 ## [0.5.0] - 2026-08-27
 
 ### Added

package/README.md

@@ -20,6 +20,8 @@ The product is not a visual design tool, a component library, or a framework abs
 
 When tradeoffs arise, we consistently prioritize composability, user control, predictable performance, explicit behavior, and correctness over convenience or familiarity.
 
+Full consumer documentation lives in [docs/](docs/README.md).
+
 ## Install
 
 ```sh
@@ -67,15 +69,21 @@ export default defineConfig({
 ```css
 /* src/styles.css */
 @import "rainbowindex";
+
+@color {
+	brand: 0.18 330;
+}
 ```
 
 ```tsx
 // src/App.tsx
 export default function App() {
-	return <div className="flex gap-4 px-6 py-3 bg-blue-500 text-white">Hello</div>;
+	return <div className="flex gap-4 px-6 py-3 bg-brand-500 text-white">Hello</div>;
 }
 ```
 
+The default palette ships only the neutral `theme` color (plus `black`, `white`, `paper`, `ink`, `transparent`, `current`, `inherit`) — declare your palette with `@color`.
+
 To scaffold a fresh app instead, use the CLI:
 
 ```sh
@@ -86,14 +94,15 @@ pnpm dlx rainbowindex init
 
 ## CLI
 
-The `rainbowindex` binary exposes five subcommands. The default is `build`.
+The `rainbowindex` binary exposes six subcommands. The default is `build`.
 
 ```
 rainbowindex <glob> [options]        Generate CSS from source files
 rainbowindex init                    Wire Rainbow Index into the current Vite app
 rainbowindex create <dir>            Scaffold a Vite app with Rainbow Index ready
 rainbowindex generate-types          Generate TypeScript types for ri() autocomplete
-rainbowindex preload-fonts           Generate <link rel="preload"> tags for resolved fonts
+rainbowindex preload-fonts           Print <link rel="preload"> tags for local faces marked preload
+rainbowindex scan <glob>             Print the class names the scanner extracts from files
 ```
 
 Common flags:
@@ -103,7 +112,7 @@ Common flags:
 | `-o`, `--output <file>` | Output CSS file path. Required with `--watch`. |
 | `--watch` | Re-run on source-file changes (chokidar). |
 | `--minify` | Minification + browser-fallback passes via LightningCSS. `--optimize` is an accepted alias. |
-| `--css <file>` | CSS input with directives. Auto-detected if omitted. |
+| `--css <file>` | CSS input with directives. Auto-detected if omitted. For `init`/`create`: the stylesheet to create or patch (default `src/index.css`). |
 | `--strict` | Drop the string escape hatch in generated types. |
 | `--template <name>` | Vite template to scaffold (default: `react-ts`). |
 
@@ -130,7 +139,7 @@ Options:
 
 | Option | Type | Description |
 | --- | --- | --- |
-| `sources` | `string[]` | Glob patterns for files to scan. Can also be declared via `@source` in CSS. |
+| `sources` | `string[]` | Glob patterns for files to scan. Can also be declared via `@source` in CSS. Any positive glob (here or via `@source`) replaces the default scan patterns. |
 | `cwd` | `string` | Working directory. Defaults to `process.cwd()`. |
 
 ## Vite plugin
@@ -139,7 +148,25 @@ Options:
 import rainbowindex from "rainbowindex/vite";
 ```
 
-Auto-detects your CSS entry, injects a PostCSS config if none exists, supports HMR with file versioning. No options required for the common case.
+Auto-detects your CSS entry, injects a PostCSS config if none exists, supports HMR with file versioning. The plugin takes no options — to pass PostCSS options, create a `postcss.config.js` and register the PostCSS plugin there yourself.
+
+## Vite+
+
+[Vite+](https://viteplus.dev) works out of the box. Directive syntax is not valid CSS, so Oxfmt — the formatter behind `vp fmt` and `vp check` — cannot parse a stylesheet that holds directives, and the whole check fails before it lints or type checks. The Vite plugin prevents that: it adds every activated stylesheet to `fmt.ignorePatterns`, and leaves the rest of the project formatted. Without the Vite plugin, add the pattern yourself.
+
+One more integration is opt-in:
+
+```ts
+// vite.config.ts — lint rule: merge classes with ri(), not clsx/tailwind-merge
+export default defineConfig({
+	lint: {
+		jsPlugins: [{ name: "rainbowindex", specifier: "rainbowindex/oxlint" }],
+		rules: { "rainbowindex/prefer-ri": "error" },
+	},
+});
+```
+
+See [docs/vite-plus.md](docs/vite-plus.md).
 
 ## Class syntax
 
@@ -152,7 +179,7 @@ Roughly the same surface area as Tailwind: spacing, sizing, typography, color, l
 Prefix any utility with one or more variants, separated by `:`.
 
 ```html
-<button class="bg-blue-500 hover:bg-blue-600 dark:bg-blue-400 sm:px-6">…</button>
+<button class="bg-brand-500 hover:bg-brand-600 dark:bg-brand-400 sm:px-6">…</button>
 ```
 
 Supported variants:
@@ -165,6 +192,8 @@ Supported variants:
 - **Attribute selectors** — `data-[state=open]`, `aria-[pressed=true]`
 - **Arbitrary** — `[selector]`, `[@media(...)]`
 
+This list is a subset — the full variant tables are in [docs/class-syntax.md](docs/class-syntax.md).
+
 ### Arbitrary values
 
 ```html
@@ -183,24 +212,21 @@ When multiple utilities share the same variant prefix, group them with `{…}` i
 
 ```html
 <!-- These two lines are equivalent -->
-<div class="hover:text-red-500 hover:bg-blue-100 hover:underline">…</div>
-<div class="hover:{text-red-500 bg-blue-100 underline}">…</div>
+<div class="hover:text-brand-500 hover:bg-brand-100 hover:underline">…</div>
+<div class="hover:{text-brand-500 bg-brand-100 underline}">…</div>
 ```
 
-Groups stack and nest:
+Prefixes chain:
 
 ```html
 <!-- Chained variants -->
-<div class="sm:hover:{bg-gray-700 text-white}">…</div>
+<div class="sm:hover:{bg-theme-700 text-white}">…</div>
 
 <!-- Multiple groups in one class string -->
-<div class="focus:{outline-2 outline-blue-500} disabled:{opacity-50 cursor-not-allowed}">…</div>
-
-<!-- The data-attribute case -->
-<div class="data-[active]:{relative px-2} data-[slot=sidebar]:{fixed leading-none}">…</div>
+<div class="focus:{outline-2 outline-brand-500} disabled:{opacity-50 cursor-not-allowed}">…</div>
 ```
 
-Expansion happens at scan-time, so the runtime never sees the grouped form. Nesting is capped at depth 10; expanded output is capped at 1MB.
+Expansion happens at scan-time, so the runtime never sees the grouped form. Only plain prefixes work — bracketed variants like `data-[state=open]:` cannot prefix a group, and braces do not nest (chain the prefixes instead). Expansion input is capped at 500,000 characters, output at 100,000.
 
 ## Theming with CSS directives
 
@@ -211,8 +237,8 @@ Customization happens in your CSS input, not a JS config. The engine recognizes:
 | `@color` | Define color tokens. Supports generative (`chroma hue`), explicit (`oklch(...)`, `#rrggbb`), light/dark pairs, and aliases. |
 | `@spacing` | Set the spacing base unit. |
 | `@text` | Define text size tokens (`size, line-height`). |
-| `@font`, `@font-face` | Register font families inside a single `@font { … }` block. Local files are repeatable `face:` entries (e.g. upright + italic). Known families get an automatic zero-CLS metrics fallback (`metrics: none` opts out). |
-| `@rounded` | Border-radius tokens; modifier sets corner shape (`round`, `squircle`, `superellipse(N)`, etc). |
+| `@font` | Register font families inside a single `@font { … }` block. Local files are repeatable `face:` entries (e.g. upright + italic). Known families get an automatic zero-CLS metrics fallback (`metrics: none` opts out). Plain `@font-face` rules are standard CSS and pass through untouched. |
+| `@rounded` | Corner shape (`round`, `squircle`, `superellipse(N)`, etc). Radii are spacing multiples, so there are no radius tokens. |
 | `@fluid` | Configure fluid type/spacing range. |
 | `@animate` | Register named animations with inline `@keyframes`. |
 | `@utility` | Define a custom utility (static or functional `name-*`). |
@@ -221,7 +247,10 @@ Customization happens in your CSS input, not a JS config. The engine recognizes:
 | `@slot` | Slot marker inside `@custom` block form. |
 | `@source` | Declare additional source globs from CSS. Supports `not "..."` and `inline("...")`. |
 | `@preflight` | Toggle preflight base styles. |
-| `@layer`, `@media`, `@custom-media`, `@import` | Standard CSS plus a few extensions. |
+| `@breakpoint`, `@shadow`, `@weight`, `@ease`, `@blur`, `@z`, `@leading`, `@tracking`, `@opacity`, `@duration` | Key-value token scales; `!key;` removes a token. |
+| `@register` | Emit CSS `@property` registrations. |
+| `@layer` | Place the generated output in cascade layers (intercepted, own grammar). |
+| `@media`, `@import`, other standard at-rules | Standard CSS — passed through untouched. |
 
 Example:
 
@@ -250,11 +279,11 @@ Example:
 	}
 }
 
-@source "../emails/**/*.html";
-@source not "../**/legacy/*";
+@source "emails/**/*.html";
+@source not "src/**/legacy/*";
 ```
 
-Default theme keys: `colors`, `spacing`, `text`, `breakpoints`, `rounded`, `shadows`, `weights`, `easing`, `fluid`, `animations`, `blur`, `z`.
+Default theme scales: `colors`, `spacing`, `text`, `breakpoints`, `shadows`, `weights`, `easing`, `fluid`, `animations`, `blur`, `leading`, `tracking`. The `z`, `opacity`, and `duration` scales ship empty — numeric class forms are computed, and their directives add named tokens.
 
 ## `ri()` — runtime class merger
 
@@ -263,8 +292,8 @@ Default theme keys: `colors`, `spacing`, `text`, `breakpoints`, `rounded`, `shad
 ```ts
 import { ri } from "rainbowindex";
 
-ri("px-2 py-1", isActive && "bg-blue-500", "px-4");
-// → "py-1 bg-blue-500 px-4"   (px-2 is dropped — px-4 wins)
+ri("px-2 py-1", isActive && "bg-brand-500", "px-4");
+// → "py-1 bg-brand-500 px-4"   (px-2 is dropped — px-4 wins)
 ```
 
 Accepted inputs:
@@ -297,17 +326,17 @@ themes in the same Node process, that shared state will leak — use
 // Anywhere ri() is single-compile-safe (browser, Vite, PostCSS):
 import { ri } from "rainbowindex";
 
-const className = ri("px-2 py-1", isActive && "bg-blue-500", "px-4");
+const className = ri("px-2 py-1", isActive && "bg-brand-500", "px-4");
 ```
 
 ```ts
-// SSR / multi-tenant — capture the snapshot at compile time, bind per-request:
-import { compileProject, createRi, finalizeCompilationContext } from "rainbowindex";
+// SSR / multi-tenant — bind a merger to one compile, isolated per theme:
+import { compileProject, createRi } from "rainbowindex";
+import { createThemeSnapshot } from "rainbowindex/editor";
 
 // At server startup (once per theme):
-const ctx = await compileProject({ cwd, css });
-const snapshot = finalizeCompilationContext(ctx);
-const ri = createRi(snapshot);
+const result = await compileProject({ css });
+const ri = createRi(createThemeSnapshot(result.theme));
 
 // In your request handler:
 function render(req, res) {
@@ -316,9 +345,9 @@ function render(req, res) {
 }
 ```
 
-If you call `ri()` while a compilation is still in progress (e.g. inside a
-server-rendering pass that triggers a fresh compile), the runtime emits a
-throttled `[RI-2004]` warning. That's your signal to switch to `createRi()`.
+In any Node/SSR process, the default `ri()` emits a throttled `[RI-2004]`
+warning (at most once per 60 s) to flag its shared module state. Switching to
+`createRi(snapshot)` silences it.
 
 ## Editor tooling API
 
@@ -370,16 +399,16 @@ Warnings carry `RI-NNNN` codes. Ranges:
 
 | Range | Subsystem |
 | --- | --- |
+| 00xx | PostCSS plugin bootstrap (thrown) |
 | 10xx | Compilation & directives |
-| 11xx | Color directives |
+| 11xx | Color directives & resolver catch-alls |
 | 12xx | Font system |
 | 13xx | Merge / compilation context |
 | 14xx | Source scanner |
 | 15xx | Typography utilities |
 | 16xx | Integration plugins (Vite, PostCSS, CLI wiring) |
-| 20xx | CSS function processing |
-| 21xx | `ri()` runtime |
+| 20xx | CSS functions, `ri()` runtime & `compile()` validation |
 
-See the [diagnostics reference](https://rainbowindex.dev/docs/diagnostics) for the full code → cause → fix table.
+See [docs/diagnostics.md](docs/diagnostics.md) for the full code → cause → fix table.
 
 Warnings are deduplicated and capped at 200 per compile, with 20 slots reserved for high-severity errors.

package/dist/browser.d.ts

@@ -1,5 +1,5 @@
-export { C as ColorDefinition, a as CompilationContext, b as CompilationSnapshot, F as FluidConfig, T as TextSize, c as Theme, d as createCompilationContext, e as defaultTheme, f as finalizeCompilationContext, r as registerColorNames, g as registerCustomFontFamilies, h as registerCustomTextSizes, i as registerCustomUtility } from './context-ruu2x_jR.js';
-export { D as DEFAULT_TEXT_SIZES, c as createRi, r as ri, s as safelist } from './safelist-D9-Plqta.js';
+export { C as ColorDefinition, a as CompilationContext, b as CompilationSnapshot, D as DEFAULT_TEXT_SIZES, F as FluidConfig, T as TextSize, c as Theme, d as createCompilationContext, e as defaultTheme, f as finalizeCompilationContext, r as registerColorNames, g as registerCustomFontFamilies, h as registerCustomTextSizes, i as registerCustomUtility } from './context-B9yhJxd5.js';
+export { c as createRi, r as ri, s as safelist } from './safelist-DAkKuxCk.js';
 
 declare function browserEntryUnavailable(): never;
 

package/dist/browser.mjs

@@ -13,7 +13,7 @@ import {
   registerCustomTextSizes,
   registerCustomUtility,
   ri
-} from "./chunk-KRZL4IDK.mjs";
+} from "./chunk-4UKFK2GE.mjs";
 
 // src/entries/browser.ts
 function browserEntryUnavailable() {

package/dist/{chunk-CMB6BHVE.mjs → chunk-4CTJLMYM.mjs}

@@ -1,6 +1,6 @@
 import {
   compileScannedProject
-} from "./chunk-DT5HYIM3.mjs";
+} from "./chunk-F4VCBISU.mjs";
 import {
   APPLY_ALIASES,
   DIRECTIVE_NAMES_SET,
@@ -11,16 +11,16 @@ import {
   computeSortKey,
   expandVariantGroups,
   forEachApplyClass,
-  getCustomUtility,
   hasApplyLikeDirective,
   hasCSSFunctions,
   hasRIActivation,
+  matchCustomUtility,
   parseUtility,
   pushWarningsDeduped,
   resolveUtilityDeclarations,
   resolveVariant,
   splitSelectorList
-} from "./chunk-ZI5ZYNSU.mjs";
+} from "./chunk-PDORZSQX.mjs";
 
 // src/integrations/postcss/index.ts
 import postcss2 from "postcss";
@@ -28,6 +28,7 @@ import { isAbsolute } from "path";
 
 // src/integrations/postcss/apply.ts
 import postcss from "postcss";
+var applyStateByTheme = /* @__PURE__ */ new WeakMap();
 function makeDeclGroup(r) {
   const sortKey = computeSortKey(r.declarations[0]?.property ?? "");
   return {
@@ -100,9 +101,16 @@ function processApply(root, theme, warnings) {
       atRule.name = "apply";
     });
   }
-  const customVariantMap = new Map(theme.customVariants.map((cv) => [cv.name, cv]));
-  const checkedApplyRoots = /* @__PURE__ */ new Set();
-  const resolveCache = /* @__PURE__ */ new Map();
+  let state = applyStateByTheme.get(theme);
+  if (!state) {
+    state = {
+      customVariantMap: new Map(theme.customVariants.map((cv) => [cv.name, cv])),
+      applyRootWarnings: /* @__PURE__ */ new Map(),
+      resolveCache: /* @__PURE__ */ new Map()
+    };
+    applyStateByTheme.set(theme, state);
+  }
+  const { customVariantMap, applyRootWarnings, resolveCache } = state;
   for (let depth = 0; depth < MAX_APPLY_DEPTH; depth++) {
     const applyNodes = [];
     const classListByNode = /* @__PURE__ */ new Map();
@@ -128,7 +136,7 @@ function processApply(root, theme, warnings) {
         warnings,
         customVariantMap,
         groupRoots,
-        checkedApplyRoots,
+        applyRootWarnings,
         resolveCache
       );
     }
@@ -146,7 +154,7 @@ function processApply(root, theme, warnings) {
     }
   }
 }
-function expandApply(atRule, classNames, theme, warnings, customVariantMap, groupRoots, checkedApplyRoots, resolveCache) {
+function expandApply(atRule, classNames, theme, warnings, customVariantMap, groupRoots, applyRootWarnings, resolveCache) {
   const parentRule = atRule.parent;
   if (parentRule?.type !== "rule") {
     warnings.push("[RI-1006] @apply must be used inside a CSS rule, not at the top level.");
@@ -177,7 +185,7 @@ function expandApply(atRule, classNames, theme, warnings, customVariantMap, grou
           theme,
           entryWarnings,
           customVariantMap,
-          checkedApplyRoots
+          applyRootWarnings
         ),
         warnings: entryWarnings
       };
@@ -252,19 +260,24 @@ function expandApply(atRule, classNames, theme, warnings, customVariantMap, grou
     parentContainer.insertAfter(insertAfter, rule);
     insertAfter = rule;
   }
-  const groupInfoByKey = /* @__PURE__ */ new Map();
-  let hasGroupVariants = false;
-  for (const [key, bucket] of variantBuckets) {
-    const info = resolveGroupVariantInfo(bucket.wrappers, parentRule, groupRoots);
-    groupInfoByKey.set(key, info);
-    if (info) hasGroupVariants = true;
-  }
   let fullSelectorMemo = null;
   const fullNestingSelector = () => {
     if (fullSelectorMemo === null)
       fullSelectorMemo = resolveFullNestingSelector(parentRule);
     return fullSelectorMemo;
   };
+  const groupInfoByKey = /* @__PURE__ */ new Map();
+  let hasGroupVariants = false;
+  for (const [key, bucket] of variantBuckets) {
+    const info = resolveGroupVariantInfo(
+      bucket.wrappers,
+      parentRule,
+      groupRoots,
+      fullNestingSelector
+    );
+    groupInfoByKey.set(key, info);
+    if (info) hasGroupVariants = true;
+  }
   let docRootMemo = null;
   const docRoot = () => {
     if (docRootMemo === null) docRootMemo = parentContainer.root();
@@ -276,7 +289,7 @@ function expandApply(atRule, classNames, theme, warnings, customVariantMap, grou
     if (groupVariantInfo) {
       const fullSelector = fullNestingSelector();
       const { groupRootSelector } = groupVariantInfo;
-      const rootBranches = splitSelectorList(groupRootSelector);
+      const rootBranches = groupVariantInfo.isSelf ? [] : splitSelectorList(groupRootSelector);
       const fullBranches = splitSelectorList(fullSelector);
       const baseBranches = [];
       for (const fb of fullBranches) {
@@ -332,7 +345,7 @@ function expandApply(atRule, classNames, theme, warnings, customVariantMap, grou
   }
   atRule.remove();
 }
-function resolveGroupVariantInfo(wrappers, parentRule, groupRoots) {
+function resolveGroupVariantInfo(wrappers, parentRule, groupRoots, fullNestingSelector) {
   if (groupRoots.size === 0) return null;
   const hasGroupVariant = wrappers.some(
     (w) => w.selectorSuffix && w.replaceAmpersand && GROUP_VARIANT_RE.test(w.selectorSuffix)
@@ -340,23 +353,23 @@ function resolveGroupVariantInfo(wrappers, parentRule, groupRoots) {
   if (!hasGroupVariant) return null;
   const groupInfo = findGroupAncestor(parentRule, groupRoots);
   if (!groupInfo) return null;
+  const isSelf = fullNestingSelector() === groupInfo.groupRootSelector;
   const rewrittenWrappers = wrappers.map((w) => {
     if (!w.selectorSuffix || !w.replaceAmpersand) return w;
     const match = w.selectorSuffix.match(GROUP_VARIANT_RE);
     if (!match) return w;
     const pseudo = match[1];
+    if (isSelf) return { ...w, selectorSuffix: `&${pseudo}` };
     const rootBranches = splitSelectorList(groupInfo.groupRootSelector);
     const newSuffix = rootBranches.map((b) => `${b}${pseudo} &`).join(", ");
     return { ...w, selectorSuffix: newSuffix };
   });
-  return { rewrittenWrappers, groupRootSelector: groupInfo.groupRootSelector };
+  return { rewrittenWrappers, groupRootSelector: groupInfo.groupRootSelector, isSelf };
 }
 var MARKER_CLASSES = /* @__PURE__ */ new Set(["group"]);
 var MAX_CUSTOM_APPLY_DEPTH = 5;
-function findCustomUtility(utility, value, theme) {
-  const target = value === null ? utility : `${utility}-${value}`;
-  const cu = getCustomUtility(theme, target);
-  return cu && !cu.functional ? cu : void 0;
+function findCustomUtility(utility, value, negative, theme) {
+  return matchCustomUtility(utility, value, negative, theme)?.cu;
 }
 function checkCustomApplyWarnings(cu, theme, warnings, visiting = /* @__PURE__ */ new Set()) {
   if (!hasApplyLikeDirective(cu.body)) return;
@@ -378,12 +391,12 @@ function checkCustomApplyWarnings(cu, theme, warnings, visiting = /* @__PURE__ *
   visiting.add(cu.name);
   for (const innerClass of innerClasses) {
     const parsed = parseUtility(innerClass);
-    const innerCu = findCustomUtility(parsed.utility, parsed.value, theme);
+    const innerCu = findCustomUtility(parsed.utility, parsed.value, parsed.negative, theme);
     if (innerCu) checkCustomApplyWarnings(innerCu, theme, warnings, visiting);
   }
   visiting.delete(cu.name);
 }
-function resolveClassName(className, theme, warnings, customVariantMap, checkedApplyRoots) {
+function resolveClassName(className, theme, warnings, customVariantMap, applyRootWarnings) {
   const parsed = parseUtility(className);
   if (parsed.variants.length === 0 && MARKER_CLASSES.has(parsed.utility) && parsed.value === null) {
     return null;
@@ -394,10 +407,15 @@ function resolveClassName(className, theme, warnings, customVariantMap, checkedA
     return null;
   }
   const declarations = [...utilResult.declarations];
-  const cu = findCustomUtility(parsed.utility, parsed.value, theme);
-  if (cu && !checkedApplyRoots.has(cu.name)) {
-    checkedApplyRoots.add(cu.name);
-    checkCustomApplyWarnings(cu, theme, warnings);
+  const cu = findCustomUtility(parsed.utility, parsed.value, parsed.negative, theme);
+  if (cu) {
+    let cuWarnings = applyRootWarnings.get(cu.name);
+    if (!cuWarnings) {
+      cuWarnings = [];
+      checkCustomApplyWarnings(cu, theme, cuWarnings);
+      applyRootWarnings.set(cu.name, cuWarnings);
+    }
+    warnings.push(...cuWarnings);
   }
   const variantWrappers = [];
   for (const variant of parsed.variants) {