rainbowindex 0.4.1 → 0.5.1

package/CHANGELOG.md

@@ -5,6 +5,274 @@ 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
+
+- **`rainbowindex scan <file|glob…>`** — prints every class candidate the
+  scanner extracts from each file, with scanner warnings on stderr. Answers
+  "why doesn't my class generate?" directly: a class missing from the list
+  was never seen by the scanner (check the markup), while a class listed
+  there that still produces no rule fails later (check the build warnings).
+- **RI-1411 — skipped over-long lines are now reported.** The scanner drops
+  lines above the minified-input guard, previously in silence. It now warns
+  once per file with the path and line count. Suppressed for `node_modules`
+  paths, where minified dists are the guard's intended target.
+- **RI-1038 — uppercase `@utility` names warn.** The markup scanner only
+  matches lowercase tokens, so `@utility cardHeader` could never trigger
+  from `class="cardHeader"`. The utility still works through `@a`/`@apply`
+  and inline `@source`, so it is kept — but no longer silently unreachable.
+
+### Changed
+
+- **Fallback stacks moved from preflight into `@font`.** The
+  `--sans-fallback` / `--serif-fallback` / `--mono-fallback` variables were
+  emitted into every project and referenced by nothing. A manual `@font`
+  slot that declares no fallbacks now gets the default system stack appended
+  to its `--font-<slot>` value instead (`sans: "Chartwell";` →
+  `"Chartwell", ui-sans-serif, system-ui, …`); a slot that declares its own
+  fallbacks is untouched. Font tokens no longer depend on a preflight
+  category that users can switch off.
+- **Focus ring uses literal lengths.** `:focus-visible` drew its outline at
+  `var(--spacing)` (4px by default) and offset at half that, so changing the
+  spacing scale silently resized every focus ring. Now a flat 2px width and
+  2px offset.
+- **Placeholder color follows the text color** —
+  `color-mix(in oklab, currentColor 48%, transparent)` instead of a
+  hardcoded gray that ignored the theme in dark mode.
+- **Scanner line-length guard raised from 2,000 to 10,000 characters.** Real
+  minified files run far above this, while hand-written long lines (inline
+  SVG path data, long attribute stacks) sit below it. `MAX_LINE_LENGTH` is
+  exported so tooling and tests derive from it instead of hardcoding.
+- **Default source patterns scan every root HTML file** (`*.html`, not just
+  `index.html`), so Vite multi-page apps are covered without an explicit
+  `@source`. `dist`, `build`, and `public` remain excluded.
+
+### Removed
+
+- **Preflight `select-reset`.** It styled rather than reset, and shipped
+  three defects: its chevron was a `currentColor` SVG in a `background-image`,
+  which resolves to black and disappears on dark backgrounds; the bare
+  `select` selector also hit `<select multiple>`, giving listboxes a floating
+  chevron and 2.5rem of padding; and `appearance: none` stripped the native
+  control on every platform. Style selects in your own CSS.
+- **Preflight `:focus:not(:focus-visible) { outline: none }`** — no current
+  browser draws an outline for plain `:focus`, so the rule was dead.
+
+### Fixed
+
+- **Quoted class attributes on over-long lines are no longer lost.** A
+  `className="…"` sharing a line with multi-KB inline SVG path data
+  generated nothing: the whole-file scan skipped the line for length, and
+  the attribute collector stripped the quotes and then searched only for
+  string literals *nested inside* the value, of which a plain quoted
+  attribute has none. Quoted attribute values are now tokenized directly, in
+  the one shared collector — so JSX, HTML, Vue, Svelte, and object-literal
+  (`{ className: "…" }`) syntax are all fixed together. Non-quoted
+  expression values keep their existing semantics.
+- **List margins are reset.** `list-reset` removed bullets and padding while
+  `ol`, `ul`, and `menu` kept the browser's `margin-block: 1em`, leaving
+  unexplained gaps around navigation and menus.
+- **`fieldset` and `legend` are reset** — their default margin and padding
+  survived while every other form control was flush.
+
 ## [0.4.1] - 2026-08-25
 
 ### 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() {