rainbowindex 0.1.4 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,133 @@
+# Changelog
+
+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.2.1] - 2026-07-28
+
+### Added — diagnostics
+
+- **Vite misuse guard (`[RI-1606]`)** — the default `rainbowindex` export is
+  the PostCSS plugin; placing it in Vite's `plugins: []` array previously did
+  nothing (no CSS, no error). It now carries an inert Vite-plugin facade that
+  throws `[RI-1606]` when Vite resolves config, pointing to
+  `import rainbowindex from "rainbowindex/vite"`. The guard is never dispatched
+  by PostCSS, so raw PostCSS usage is unaffected.
+
+## [0.2.0] - 2026-07-16
+
+Initial public release. Rainbow Index began as a fork of Tailwind CSS v4; the
+entries below list the capabilities this release adds **on top of** what
+Tailwind CSS v4 provides. Shared functionality (utility classes, variants,
+`@apply`, CSS-first theming, `@source`, arbitrary values, the Vite/PostCSS
+plugins as such) is not repeated here.
+
+### Added — runtime & programmatic API
+
+- **`ri()` class merger** — built-in class composition with right-most-wins
+  conflict resolution, replacing both `clsx` (conditional composition) and
+  `tailwind-merge` (conflict resolution). Understands shorthand property
+  claims (`p-4` owns all four padding sides), variant-order canonicalization
+  (`sm:hover:` ≡ `hover:sm:`), `!important`, negative utilities, and
+  arbitrary properties; bracket-aware tokenization with LRU caching.
+- **`createRi(snapshot)`** — SSR- and multi-tenant-safe merger bound to a
+  frozen compilation snapshot, for servers where concurrent requests may
+  target different themes in one process. `ri()` emits a throttled
+  `[RI-2004]` warning when it detects that situation.
+- **Programmatic compilation API** — `compileProject()`, `createCompiler()`,
+  `createCompilationContext()`, `finalizeCompilationContext()`, and
+  registration helpers (`registerCustomUtility`, `registerCustomTextSizes`,
+  `registerCustomFontFamilies`, `registerColorNames`) as a stable library
+  surface for driving compilation and feeding the merge engine.
+- **`safelist()` helper** — a runtime identity-join whose static string
+  arguments are extracted by the scanner at build time, so component/icon
+  libraries can ship class names that are always emitted.
+- **Package-based safelist auto-discovery** — installed dependencies can
+  declare `rainbowindex.safelistSources` globs in their own `package.json`
+  to opt their published files into scanning, with no manual `@source`.
+- **Browser entry guard** — importing the PostCSS-plugin default export in a
+  browser bundle throws `[RI-2003]` with guidance to use named imports.
+
+### Added — CLI
+
+- **`rainbowindex generate-types`** — generates a `rainbowindex-env.d.ts`
+  with a `RainbowClass` TypeScript union (colors × stops, spacing, text
+  sizes, weights, variants, custom utilities) for editor autocomplete;
+  `--strict` drops the string escape hatch; hand-edited files are backed up
+  before overwrite.
+- **`rainbowindex preload-fonts`** — emits `<link rel="preload" as="font">`
+  tags for resolved font faces.
+- **`rainbowindex init`** — wires Rainbow Index into an existing Vite app:
+  detects the package manager, installs the dependency, patches
+  `vite.config.*`, and creates or updates the CSS entry.
+- **`rainbowindex create <dir>`** — scaffolds a fresh Vite app (default
+  template `react-ts`) with Rainbow Index pre-wired.
+- **`--optimize`** — LightningCSS pass with browser-fallback down-leveling
+  in addition to minification.
+- **Atomic output writes** — CSS output is written via temp-file + rename so
+  interrupted builds never leave partial files.
+
+### Added — theming directives
+
+- **Generative color system (`@color`)** — declare a color as two numbers
+  (`brand: 0.18 330;` — chroma + hue) and get a full 19-stop OKLCH palette
+  with automatic dark mode via ramp mirroring, tuned for even perceived
+  contrast. Also supports explicit values, light/dark pairs, aliases,
+  per-color dark-override strategies, and contrast warnings.
+- **Font system (`@font`)** — register font slots from Google Fonts, local
+  files, or URLs in CSS; multi-face slots (upright + italic via an
+  `italic:` shorthand), system/manual stacks, and metrics-adjusted fallback
+  `@font-face` blocks (size-adjust/ascent/descent overrides) for zero
+  cumulative layout shift. On-disk font metadata cache governed by
+  `RI_OFFLINE`, `RI_FETCH_FONTS`, `RI_CACHE_DIR`, and `RI_FONT_CACHE_TTL`.
+- **`@fluid`** — configurable fluid type/spacing range driving
+  `text-fluid-*` and `*-fluid` spacing/inset utilities with curve keywords.
+- **`@rounded` corner shapes** — border-radius tokens with corner-shape
+  modifiers and `corner-round/scoop/bevel/notch/square/squircle` (plus
+  `corner-[superellipse(N)]`) utilities mapping to the CSS `corner-shape`
+  property.
+- **`@animate`** — register named animations with inline `@keyframes`, plus
+  compositional enter/exit utilities (`animate-in`/`animate-out` with
+  `fade-`, `zoom-`, `spin-`, `blur-`, and `slide-` parts, each driving
+  independent CSS variables) and preset accordion/collapsible keyframes.
+- **`@register`** — declare typed custom properties (`@property`-style
+  registrations with syntax and initial value) directly from CSS.
+- **`@preflight`** — toggle preflight base styles from CSS.
+
+### Added — class-string syntax
+
+- **Variant groups** — `hover:{text-red-500 bg-blue-100 underline}` expands
+  at scan time to the repeated-prefix form; groups stack and nest
+  (`sm:hover:{…}`, `data-[state=open]:{…}`) with depth and output caps, and
+  are also expanded inside `@apply` bodies.
+- **Helper-call-aware scanner** — class literals are extracted from
+  `clsx`/`cn`/`classnames`/`cx`/`twJoin`/`twMerge`/`cva`/`tv`/`classMap`/
+  `safelist` call sites rather than treating source files as flat text.
+- **Math-operator value parsing** — CSS math functions (`calc`, `min`,
+  `max`, `clamp`, `mod`, trigonometric functions, `pow`, `round`, …) are
+  recognized inside utility values.
+
+### Added — integrations
+
+- **Vite plugin extras** — auto-injects a PostCSS config only when none
+  exists, auto-discovers the CSS entry on first dev-server listen (warning
+  `[RI-1602]` if Rainbow Index never activates), tracks per-file versions
+  for HMR, and pre-rewrites Rainbow-Index-specific directive syntax into
+  PostCSS-parseable form before PostCSS runs.
+- **PostCSS plugin `sources` option** — declare scan globs from
+  `postcss.config.js` in addition to CSS `@source`, merged with
+  package-discovered safelist sources.
+
+### Added — diagnostics
+
+- **`RI-NNNN` error-code system** — every warning carries a namespaced code
+  (10xx compilation, 11xx color, 12xx fonts, 13xx merge, 14xx scanner, 15xx
+  typography, 16xx integrations, 20xx CSS functions, 21xx runtime), with a
+  parity test enforcing that every emitted code is documented.
+- **Warning deduplication and severity budgeting** — warnings are deduped
+  and capped per compile, with reserved slots so high-severity errors are
+  never drowned out by informational warnings.
+- **"Did you mean" suggestions** — optimal-string-alignment matching powers
+  typo hints for unknown utilities, variants, and theme variables.

package/{LICENSE.md → LICENSE}

@@ -1,12 +1,12 @@
 MIT License
 
-This project is a fork of Tailwind CSS v4.
+This project is a fork of Tailwind CSS v4. Portions of this software are derived from Tailwind CSS: Copyright (c) Tailwind Labs, Inc.
 
-Portions of this software are derived from Tailwind CSS: Copyright (c) Tailwind Labs, Inc.
+The class merging algorithm is derived from tailwind-merge: Copyright (c) 2021 Dany Castillo
 
 The animation system is inspired by tw-animate-css: Copyright (c) 2025 Wombosvideo (Luca Bosin)
 
-Rainbow Index modifications and additions: Copyright (c) 2026 Milo Tech Forecast
+Rainbow Index Copyright (c) 2026 Milo Tech Forecast
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
 documentation files (the "Software"), to deal in the Software without restriction, including without limitation the

package/README.md

@@ -1,192 +1,329 @@
-# rainbowindex
+<p align="center">
+  <a href="https://rainbowindex.dev" target="_blank">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/rainbowindex/rainbowindex/HEAD/.github/logo-dark.svg">
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/rainbowindex/rainbowindex/HEAD/.github/logo-light.svg">
+      <img alt="Rainbow Index" src="https://raw.githubusercontent.com/rainbowindex/rainbowindex/HEAD/.github/logo-light.svg" width="144" height="41" style="max-width: 100%;">
+    </picture>
+  </a>
+</p>
 
-The core CSS compiler for Rainbow Index. This package handles parsing, transformation, and generation—everything needed
-to turn utility classes into CSS.
+**Rainbow Index** is a CSS-first system for building and maintaining consistent user interfaces.
 
-The compiler has zero runtime dependencies and uses a custom CSS parser. Most projects will interact with Rainbow Index
-through the [Vite plugin](../vite) or [CLI](../cli), but direct access to the compiler is useful for building custom
-tooling or understanding how the system works.
+The project began as a fork of [Tailwind CSS](https://github.com/tailwindlabs/tailwindcss), then diverged with clear intent: to treat CSS as the primary source of truth for styling decisions and to provide tooling that translates design system definitions into predictable, inspectable output. Styling behavior is explicit and traceable, allowing developers to understand not only what is happening, but why.
 
-## Installation
+We built the system around composable primitives rather than finished components. Instead of prescribing layout patterns or UI components, it focuses on utilities, directives, and tokens that can be combined without accumulating configuration debt.
 
-```bash
-npm install rainbowindex
-```
+Rainbow Index challenges several assumptions common in modern styling workflows. Configuration does not default to JavaScript. Flexibility is not achieved through layered indirection. Utility-based systems are not assumed to be verbose, opaque, or fragile.
+
+The product is not a visual design tool, a component library, or a framework abstraction layer. It assumes familiarity with core CSS concepts and expects users to engage with the underlying model.
+
+When tradeoffs arise, we consistently prioritize composability, user control, predictable performance, explicit behavior, and correctness over convenience or familiarity.
 
-## Usage
+## Install
 
-### Compile Classes
+```sh
+pnpm add rainbowindex
+```
+
+Requires Node `>=20.19`. The package is **ESM-only** — there is no CommonJS build, so `require("rainbowindex")` is only supported on runtimes that can `require()` ES modules (Node 20.19+); use `import` otherwise (e.g. an ESM `postcss.config.js`/`.mjs`). `postcss` is a required peer dependency, `vite` an optional one; `lightningcss`, `chokidar`, and `tinyglobby` are bundled as direct deps.
 
-The most common operation: turn a list of utility class names into CSS.
+## Quick start (Vite)
 
-```typescript
-import { compileClasses, createDesignSystem } from "rainbowindex";
+The fastest path is the Vite plugin, which auto-injects PostCSS config and discovers your CSS entry on first dev-server listen.
 
-const designSystem = createDesignSystem();
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import rainbowindex from "rainbowindex/vite";
 
-const result = compileClasses(["p-4", "bg-blue-500", "hover:bg-blue-600"], {
-    designSystem,
+export default defineConfig({
+	plugins: [rainbowindex()],
 });
+```
+
+```css
+/* src/styles.css */
+@import "rainbowindex";
+```
+
+```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>;
+}
+```
+
+To scaffold a fresh app instead, use the CLI:
 
-console.log(result.css);
-// .p-4 { padding: 1rem; }
-// .bg-blue-500 { background-color: oklch(55.3% 0.213 253.075); }
-// .hover\:bg-blue-600:hover { background-color: oklch(47.4% 0.195 251.802); }
+```sh
+pnpm dlx rainbowindex create my-app --template react-ts
+# or wire into an existing Vite app
+pnpm dlx rainbowindex init
 ```
 
-### Parse and Print CSS
+## CLI
 
-The parser produces an AST that can be inspected, transformed, or printed back to a string. This is useful for tools
-that need to analyze or modify CSS programmatically.
+The `rainbowindex` binary exposes five subcommands. The default is `build`.
 
-```typescript
-import { parse, print } from "rainbowindex";
+```
+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
+```
+
+Common flags:
 
-const { ast } = parse(`
-  .button {
-    padding: 1rem;
-    background: blue;
-  }
-`);
+| Flag | Description |
+| --- | --- |
+| `-o`, `--output <file>` | Output CSS file path. Required with `--watch`. |
+| `--watch` | Re-run on source-file changes (chokidar). |
+| `--minify` | Minify output via LightningCSS. |
+| `--optimize` | Minification + browser-fallback passes. |
+| `--css <file>` | CSS input with directives. Auto-detected if omitted. |
+| `--strict` | Drop the string escape hatch in generated types. |
+| `--template <name>` | Vite template to scaffold (default: `react-ts`). |
 
-const output = print(ast);
+Example:
+
+```sh
+rainbowindex "src/**/*.{ts,tsx}" -o dist/styles.css --watch
 ```
 
-### Transform CSS with Theme
+## PostCSS plugin
+
+The package's default Node export is a PostCSS plugin.
 
-When processing CSS that contains Rainbow Index directives (`@theme`, `@apply`, etc.), use `transformCSS` to expand
-them.
+```js
+// postcss.config.js
+import rainbowindex from "rainbowindex";
 
-```typescript
-import { parse, transformCSS, createDesignSystem, print } from "rainbowindex";
+export default {
+	plugins: [rainbowindex({ sources: ["src/**/*.{ts,tsx,html}"] })],
+};
+```
 
-const designSystem = createDesignSystem();
+Options:
 
-const { ast } = parse(`
-  @theme {
-    --color-primary: oklch(0.6 0.2 250);
-  }
+| Option | Type | Description |
+| --- | --- | --- |
+| `sources` | `string[]` | Glob patterns for files to scan. Can also be declared via `@source` in CSS. |
+| `cwd` | `string` | Working directory. Defaults to `process.cwd()`. |
 
-  .button {
-    background: var(--color-primary);
-  }
-`);
+## Vite plugin
 
-const transformed = transformCSS(ast, { designSystem });
-const output = print(transformed);
+```ts
+import rainbowindex from "rainbowindex/vite";
 ```
 
-## Directive Handling
+Auto-detects your CSS entry, injects a PostCSS config if none exists, supports HMR with file versioning. No options required for the common case.
 
-Rainbow Index processes `@rainbowindex` directives as injection points for generated styles. Unknown at-rules (including
-`@tailwind`) are preserved and pass through unchanged, rather than being treated as migration inputs.
+## Class syntax
 
-## API Reference
+### Utilities
 
-### `compileClasses(candidates, options)`
+Roughly the same surface area as Tailwind: spacing, sizing, typography, color, layout, borders, effects, animations, and SVG. Use `rainbowindex generate-types` for autocomplete in your editor.
 
-Compile utility class names into CSS.
+### Variants
 
-```typescript
-interface CompileOptions {
-    designSystem: DesignSystem;
-}
+Prefix any utility with one or more variants, separated by `:`.
 
-interface CompileResult {
-    css: string;
-    classes: string[];
-}
+```html
+<button class="bg-blue-500 hover:bg-blue-600 dark:bg-blue-400 sm:px-6">…</button>
 ```
 
-### `createDesignSystem()`
+Supported variants:
 
-Create a design system instance with the default theme, utilities, and variants. The design system is the central
-registry that maps class names to CSS output.
+- **Pseudo-classes** — `hover`, `focus`, `focus-visible`, `active`, `visited`, `disabled`, `enabled`, `checked`, `empty`, `first`, `last`, `odd`, `even`, `only`
+- **Pseudo-elements** — `before`, `after`, `placeholder`, `file`, `marker`, `selection`, `first-line`, `first-letter`, `backdrop`
+- **Media** — `dark`, `print`, `portrait`, `landscape`, `motion-safe`, `motion-reduce`, `starting`
+- **Breakpoints** — `sm`, `md`, `lg`, `xl` (theme-driven, customizable via `@breakpoint`)
+- **Container queries** — `@sm`, `@md`, …
+- **Attribute selectors** — `data-[state=open]`, `aria-[pressed=true]`
+- **Arbitrary** — `[selector]`, `[@media(...)]`
 
-```typescript
-interface DesignSystem {
-    theme: Theme;
-    utilities: Utilities;
-    variants: Variants;
-    parseCandidate(candidate: string): Candidate[];
-    compileAstNodes(candidate: Candidate): AstNode[];
-    getClassOrder(classes: string[]): [string, bigint | null][];
-}
+### Arbitrary values
+
+```html
+<div class="w-[37rem] bg-[#1a73e8] data-[state=open]:opacity-100"></div>
 ```
 
-### `parse(css, options?)`
+CSS variable shorthand:
 
-Parse a CSS string into an AST.
+```html
+<div class="bg-(--brand-color) text-(--brand-text)"></div>
+```
 
-```typescript
-interface ParseOptions {
-    from?: string; // Source file path for source maps
-}
+### Variant groups
 
-interface ParseResult {
-    ast: AstNode[];
-}
+When multiple utilities share the same variant prefix, group them with `{…}` instead of repeating the prefix:
+
+```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>
 ```
 
-### `print(ast, options?)`
+Groups stack and nest:
 
-Convert an AST back to a CSS string.
+```html
+<!-- Chained variants -->
+<div class="sm:hover:{bg-gray-700 text-white}">…</div>
 
-```typescript
-interface PrintOptions {
-    minify?: boolean;
-    indent?: string;
-}
+<!-- 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>
 ```
 
-### `transformCSS(ast, options)`
+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.
+
+## Theming with CSS directives
+
+Customization happens in your CSS input, not a JS config. The engine recognizes:
+
+| Directive | Purpose |
+| --- | --- |
+| `@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. One slot can own multiple `@face` faces (e.g. upright + italic) or use the `italic:` shorthand. |
+| `@rounded` | Border-radius tokens; modifier sets corner shape (`round`, `squircle`, `superellipse(N)`, etc). |
+| `@fluid` | Configure fluid type/spacing range. |
+| `@animate` | Register named animations with inline `@keyframes`. |
+| `@utility` | Define a custom utility (static or functional `name-*`). |
+| `@apply` | Compose utilities into a single rule. |
+| `@custom` | Define a custom variant. |
+| `@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. |
+
+Example:
+
+```css
+@import "rainbowindex";
+
+@color {
+	brand: 0.18 330;                   /* generative: chroma hue */
+	brand-soft: oklch(0.92 0.04 330);  /* explicit */
+	surface: oklch(0.98 0.01 260) / oklch(0.15 0.01 260);  /* light/dark pair */
+}
+
+@spacing { base: 0.5rem; }
 
-Transform a CSS AST, processing `@theme`, `@apply`, and other directives.
+@text {
+	display: 4rem, 1.05;
+	body: 1rem, 1.5;
+}
 
-```typescript
-interface TransformOptions {
-    designSystem: DesignSystem;
+@font {
+	sans: "Inter" from google { weight: 400 700; }
+	display: "Satoshi" from "/fonts/Satoshi.woff2" {
+		weight: 300 900;
+		italic: "/fonts/Satoshi-Italic.woff2";   /* second face, font-style: italic */
+	}
 }
+
+@source "../emails/**/*.html";
+@source not "../**/legacy/*";
 ```
 
-## Default Theme
+Default theme keys: `colors`, `spacing`, `text`, `breakpoints`, `rounded`, `shadows`, `weights`, `easing`, `fluid`, `animations`, `blur`, `z`.
+
+## `ri()` — runtime class merger
 
-The default theme provides a comprehensive set of design tokens:
+`ri()` merges class strings with right-most-wins conflict resolution. It replaces both `clsx` (for conditional composition) and `tailwind-merge` (for conflict resolution).
 
-**Colors** — Full OKLCH palette: gray, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo,
-violet, purple, fuchsia, pink, rose.
+```ts
+import { ri } from "rainbowindex";
 
-**Spacing** — Scale from 0 to 96: 0, 0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 16, 20, 24, 28, 32,
-36, 40, 44, 48, 52, 56, 60, 64, 72, 80, 96.
+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)
+```
+
+Accepted inputs:
 
-**Typography** — Font sizes, weights, and line heights.
+```ts
+type ClassInput = string | false | null | undefined | ClassInput[];
+ri(...inputs: ClassInput[]): string;
+```
 
-**Breakpoints** — Numeric (rem-based) and named.
+Conflict resolution understands shorthands: `p-4` claims all four padding sides, but only drops if every side is overwritten by a class to its right.
+
+### `ri()` vs `createRi()` — which one do I use?
+
+| Situation | Use |
+| --- | --- |
+| Browser bundle / client components | **`ri()`** |
+| Vite build / PostCSS one-shot | **`ri()`** |
+| Single Node compile that exits | **`ri()`** |
+| Concurrent SSR (one server, many requests) | **`createRi(snapshot)`** |
+| Multi-tenant compile (different themes in the same process) | **`createRi(snapshot)`** |
+| Edge / serverless functions sharing module state across invocations | **`createRi(snapshot)`** |
+
+`ri()` reads module-level state published by the most recent compile. That's
+fast and ergonomic in any environment where there is exactly one compile
+per process. If two requests can be merging classes against two different
+themes in the same Node process, that shared state will leak — use
+`createRi(snapshot)` to bind each request to its own frozen snapshot.
+
+```ts
+// 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");
+```
+
+```ts
+// SSR / multi-tenant — capture the snapshot at compile time, bind per-request:
+import { compileProject, createRi, finalizeCompilationContext } from "rainbowindex";
+
+// At server startup (once per theme):
+const ctx = await compileProject({ cwd, css });
+const snapshot = finalizeCompilationContext(ctx);
+const ri = createRi(snapshot);
+
+// In your request handler:
+function render(req, res) {
+	const html = `<div class="${ri("px-2 py-1", req.dark && "dark:bg-slate-900")}">…</div>`;
+	res.send(html);
+}
+```
 
-## Utilities
+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()`.
 
-Core utilities included:
+## Environment variables
 
-- **Spacing**: `p-*`, `m-*`, `gap-*`, `space-*`
-- **Sizing**: `w-*`, `h-*`, `min-w-*`, `max-w-*`, `min-h-*`, `max-h-*`
-- **Colors**: `bg-*`, `text-*`, `border-*`
-- **Typography**: `font-*`, `text-*`, `leading-*`, `tracking-*`
-- **Layout**: `flex`, `grid`, `block`, `inline`, `hidden`
-- **Flexbox**: `flex-*`, `items-*`, `justify-*`, `grow-*`, `shrink-*`
-- **Grid**: `grid-cols-*`, `grid-rows-*`, `col-span-*`, `row-span-*`
-- **Effects**: `shadow-*`, `opacity-*`, `blur-*`
-- **Borders**: `rounded-*`, `border-*`
+| Variable | Effect |
+| --- | --- |
+| `RI_DEBUG=1` | Enable debug logging. |
+| `RI_OFFLINE=1` | Skip network calls; use cached font data only. |
+| `RI_FETCH_FONTS=0` | Disable Google Fonts metadata requests. |
+| `RI_CACHE_DIR` | Override font cache directory (default: `node_modules/.cache/rainbowindex`). |
+| `RI_FONT_CACHE_TTL` | Font cache max age in seconds (default: `604800` — 7 days). |
 
-## Variants
+## Diagnostics
 
-Built-in variants:
+Warnings carry `RI-NNNN` codes. Ranges:
 
-- **Pseudo-classes**: `hover`, `focus`, `active`, `visited`, `disabled`, `first`, `last`, `odd`, `even`
-- **Pseudo-elements**: `before`, `after`, `placeholder`, `selection`
-- **Media**: `dark`, numeric breakpoints (`48:`, `64:`, etc.)
-- **Compound**: `group-*`, `peer-*`
-- **Data/Aria**: `data-*`, `aria-*`
+| Range | Subsystem |
+| --- | --- |
+| 10xx | Compilation & directives |
+| 11xx | Color directives |
+| 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 |
 
-## License
+See the [diagnostics reference](https://rainbowindex.dev/docs/diagnostics) for the full code → cause → fix table.
 
-MIT
+Warnings are deduplicated and capped at 200 per compile, with 20 slots reserved for high-severity errors.