rainbowindex 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,536 @@ 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.6.0] - 2026-09-01
+
+### Added
+
+- **Numeric font weights, checked against the fonts you load.** `font-<number>`
+  now sets `font-weight` directly, for any weight from 1 to 1000 —
+  `font-300`, `font-500`, `font-617`. A named `@weight` token of the same
+  spelling still wins, and `font-[850]` is unchanged.
+
+  The number is compared against the `weight` of every loaded `@font` face. A
+  range (`weight: 300 900`, the variable-font case) accepts every number
+  between its bounds; a list or a single value (`weight: 400,700`) accepts
+  only those numbers. A weight that no face provides warns with the new
+  `[RI-1504]`, and the message names the weights that are available.
+
+  A class on its own carries no family, and a page can load several fonts, so
+  that check is a union: one covering face is enough. It stays quiet with no
+  `@font` block, and with a `system` slot, whose OS font has every weight.
+
+  Where the family *is* named — a `font-<slot>` beside the weight in one
+  `@apply` / `@a` / `@utility` class list — that family alone decides:
+
+  ```css
+  [data-slot="code"] {
+  	@a font-mono font-550;   /* Fira Code does not provide weight 550. It has 400, 700. */
+  }
+  ```
+
+  The last family in the list wins, and the two classes must share a variant
+  prefix (`md:font-mono` does not set the family for a plain `font-550`). A
+  weight no font provides is still reported once, by the union check. A class
+  written in markup has no list — the scanner keeps only the set of names — so
+  the union check governs there.
+
+  Completions and the generated class types offer `font-100` … `font-900`
+  beside the named `@weight` tokens, and read `font-<number>` as an open
+  numeric template.
+
+- **Three editor capabilities.** `rainbowindex/editor` gains `isSuppressible`
+  (`diagnostic-suppression`), so an editor offers a `ri-disable` comment only
+  where one would work; `weightIsLoaded` and `describeLoadedWeights`
+  (`font-weight-coverage`), the `[RI-1504]` check, so it can answer which
+  loaded fonts carry a weight; and `ThemeTokens.radii` / `ThemeTokens.fluidRanges`
+  (`named-radii-and-fluid-ranges`), which named radii and named `@fluid` ranges
+  had no token surface for. Gate on the capability strings, never on `version`.
+
+- **`ri-disable` comments.** Two plain CSS comments silence a diagnostic, so a
+  stylesheet carrying them stays valid CSS for every other tool.
+
+  `/* ri-disable RI-1124 */` anywhere in the CSS entry silences that code
+  everywhere. It is the only form that reaches the scanner and compile codes
+  (14xx, 15xx), which carry no position in your CSS. One comment may name
+  several codes: `/* ri-disable RI-1124, RI-1122 */`.
+
+  `/* ri-disable-next-line RI-1124 */` silences one place. Inside a scale body
+  it guards the entry that follows; outside a body it guards the next
+  directive:
+
+  ```css
+  @rounded {
+  	roof: 24px;
+  	/* ri-disable-next-line RI-1124 */
+  	full: 30px;
+  	hut: 8px;   /* still checked */
+  }
+  ```
+
+  Entry precision is available where the emitter knows the entry —
+  `[RI-1035]`, `[RI-1121]`, `[RI-1122]`, `[RI-1124]`. Other codes fall back to
+  the directive.
+
+  `RI-00xx` and `RI-20xx` cannot be silenced: they report a broken build or a
+  broken call, not a style choice. Naming one warns with the new `[RI-1040]`,
+  as does a comment that names no readable code.
+
+- **`compileProject()` reports what it silenced.** The result gains
+  `suppressed`, the set of codes the entry's `ri-disable` comments named, so
+  a caller that pushes warnings of its own can drop the ones the author
+  hid. Every stage inside the compile already pushes through it.
+
+- **Fluid endpoint pairs.** Fluid utilities take both ends of the ramp:
+  `p-fluid-4/8` grows from step 4 to step 8 across the `@fluid` range, and
+  `text-fluid-sm/3xl` ramps between two type steps. Arbitrary lengths and
+  `(--var)` endpoints mix (`p-fluid-[0.5rem]/(--x)`), zero is a legal
+  endpoint, and a descending pair (`p-fluid-8/4`) shrinks as the viewport
+  grows. Fluid type also takes the line-height modifier now:
+  `text-fluid-lg/7`, `text-fluid-sm/3xl/tight`.
+
+- **Named `@fluid` ranges and scope classes.** `@fluid compact { min: 20rem;
+  max: 48rem; }` defines a range, the tokens `--fluid-compact-{min,max}`, and
+  the scope class `fluid-compact`, which points every fluid utility on the
+  element and its descendants at that range through the inherited
+  `--fluid-scope-{min,max}` pair. A unit on a named range warns with
+  `RI-1039`; an unknown range name on the class warns with `RI-1503`.
+
+- **Container-query units in `@fluid`.** `unit` accepts `cqw`, `cqi`,
+  `cqmin`, and `cqmax`, so fluid ramps can track a container instead of the
+  viewport.
+
+- **Named radii in `@rounded`.** A key without a `--` prefix now names a
+  radius: `@rounded { roof: 24px; }` gives the class `rounded-roof` and the
+  token `--rounded-roof`, and the name works with the side and corner
+  suffixes (`rounded-tl-roof`). `--corner-scale` is still the only option;
+  any other `--` key still warns with `[RI-1122]`. Radii without a name stay
+  spacing multiples, so `rounded-4` is unchanged.
+
+- **Utility blocks in every named scale.** A `name { … }` or `name-* { … }`
+  block in a scale body defines a utility in that scale's class family, so the
+  math sits next to the tokens it reads:
+
+  ```css
+  @rounded {
+  	roof: 24px;
+  	roof-minus-* {
+  		border-radius: calc(var(--rounded-roof) - var(--value) * var(--spacing));
+  	}
+  }
+  ```
+
+  `rounded-roof-minus-2` subtracts two spacing steps from `--rounded-roof`.
+  The block uses the `@utility` grammar and the name takes the family's
+  prefix. `@rounded`, `@shadow`, `@blur`, `@z`, `@leading`, `@tracking`,
+  `@opacity`, `@duration`, `@ease`, `@weight`, `@text` and `@animate` all
+  accept them; `@weight` blocks land under `font-`.
+
+  `@color` does not: a colour name feeds `bg-`, `text-`, `border-`, `ring-`
+  and more, so a block would have no one family to land in. `@breakpoint`
+  names variants rather than utilities, and `@spacing` holds a single base
+  value.
+
+  A colon is what separates a utility block from the two block grammars that
+  already existed. `key: value { … }` stays what it was — `@color` options,
+  `@animate` keyframes — and only a block with no key before it is a utility.
+
+  Radius tokens are written to `:root` whether used or not, because a block
+  body is raw CSS that no usage pass can read.
+
+- **`@shadow` aliases.** A shadow value that is only another shadow's class
+  name now emits a reference to it: `@shadow { md: …; card: shadow-md; }`
+  gives `--shadow-card: var(--shadow-md)`. Using `shadow-card` pulls
+  `--shadow-md` into `:root` alongside it, so an alias never renders against
+  an undefined variable. The target may be defined in a later `@shadow`
+  block. An alias to a token that does not exist warns with the new
+  `[RI-1123]` and keeps its value verbatim.
+
+### Removed
+
+- **`@utility` no longer accepts a leading `.` on the name.** `@utility .card`
+  used to be silently treated as `@utility card`. No other directive did
+  this, and the dot was ignored without a word in `@source inline(".card")`,
+  `safelist(".card")`, and `class=".card"` markup, so the one exception
+  taught a rule that held nowhere else. A dotted name now warns with
+  `[RI-1035]` and is skipped, like every other invalid name. Write
+  `@utility card`.
+
+- **The shipped shadow scales are gone.** No `shadow-*` tokens ship any more:
+  the layered `px`–`2xl` scale and its building blocks (`line`, `drop`,
+  `hi-1`–`hi-4`, `dark-line`, `ring`, `layer-1`–`layer-7`) are removed, along
+  with the hardcoded `inset-shadow-*`, `text-shadow-*`, and `drop-shadow-*`
+  size scales. A shadow is now a project decision, not a shipped opinion.
+  Every value form still works — `shadow-none`, `shadow-{color}`,
+  `shadow-[v]`, and the same forms for the other three families — and `ring`
+  and `inset-ring` are untouched. Named sizes come back with
+  `@shadow md: …;`, and bare `shadow` reads the `DEFAULT` token.
+  Because the scale is empty by default, bare `shadow` is no longer a
+  built-in static utility: it resolves only when the theme defines
+  `DEFAULT` (or `md`).
+
+- **The last shipped scales are gone: breakpoints, weights, easing, blur,
+  animations, and the fluid range.** The package now ships exactly two
+  defaults — the colour palette and the `0.25rem` spacing base. Everything
+  else is a project decision:
+
+  | Gone | Was | Comes back with |
+  | --- | --- | --- |
+  | `sm:` `md:` `lg:` `xl:` and `@sm:` `@md:` … | 40/48/64/80rem | `@breakpoint { sm: 40rem; … }` |
+  | `font-thin` … `font-black` | 100–900 | `@weight { bold: 700; … }` |
+  | `ease-in`, `ease-out`, `ease-in-out` | cubic-beziers | `@ease { in: cubic-bezier(0.4, 0, 1, 1); … }` |
+  | `blur-xs` … `blur-3xl`, bare `blur` | 2px–64px, 8px | `@blur { md: 12px; … }` |
+  | `animate-spin`, `animate-pulse`, `animate-bounce`, `animate-ping` | four loops | `@animate { spin: spin 1s linear infinite { … } }` |
+  | `p-fluid-*`, `text-fluid-*`, `fluid-<name>` | 20rem–80rem ramp | `@fluid { min: 20rem; max: 80rem; }` |
+
+  The keyword and arbitrary forms are untouched: `blur-none`, `blur-[3px]`,
+  `ease-linear`, `ease-[cubic-bezier(…)]`, `animate-none`, `animate-[…]`,
+  `font-[850]`, and the whole enter/exit system (`animate-in`, `fade-in-50`,
+  `slide-in-from-top-4`, `blur-in-8`) need no tokens and keep working.
+  `max-w-sm` is a container width, not a breakpoint, and is unchanged.
+
+  Two consequences worth naming. A `@fluid` range no longer half-exists: with
+  no `min`/`max` the `--fluid-*` tokens are not written and every fluid
+  utility resolves to nothing, rather than ramping across a range nobody
+  chose. And `@fluid text`/`@fluid spacing`/named ranges no longer inherit a
+  shipped range to fill their gaps — a bound that is absent is simply not
+  configured, so `[RI-1022]`/`[RI-1023]` now fire only on a bound you
+  actually wrote.
+
+- **The shipped type scale is gone.** No `--text-*` tokens ship any more: the
+  14-step `2xs`–`9xl` text scale, the `leading-*` scale (`3`–`10`, `none`,
+  `tight`, `snug`, `normal`, `relaxed`, `loose`), and the `tracking-*` scale
+  (`tighter`–`widest`) are removed. Type is now a project decision, not a
+  shipped opinion. Every value form still works — `text-[18px]`,
+  `text-lg/[1.5]`, `leading-px`, `leading-[1.5]`, `tracking-[0.1em]` — and
+  `text-{color}` is untouched. Named sizes come back with `@text lg: 1.25rem,
+  1.4;`, `@leading tight: 1.25;`, and `@tracking wide: 0.025em;`.
+  `text-fluid-{size}` needs at least two `@text` steps to interpolate
+  between, and the `text-lg/7` modifier reads `@leading` tokens.
+
+- **`DEFAULT_TEXT_SIZES` is no longer exported.** `ri()` classified
+  `text-{name}` as a size against a hardcoded list that never matched the
+  shipped scale (it held `base`, which the scale lacked, and lacked `md`,
+  which the scale had). The merger now learns every size name from the
+  compiled theme, the way it already learns custom colors and font slots.
+  Before the first compile, `text-{name}` reads as a color.
+
+### Fixed
+
+- **A rejected utility block no longer corrupts the entries beside it.** A
+  block is cut from the directive body whether or not its name survived, but
+  the body was only swapped in when at least one block parsed. So a scale whose
+  blocks were *all* rejected kept its raw `{ … }` text, and the key/value
+  parsers — which do not read braces — took the block's own declarations for
+  scale entries: `@shadow { bad.name-* { box-shadow: … } }` defined a shadow
+  called `box-shadow`. Ten of the twelve block-taking scales were affected;
+  `@rounded` and `@animate` parse braces themselves and were not.
+
+- **A circular `@shadow` alias chain is reported.** `a: shadow-b; b: shadow-a`
+  and the self-alias `a: shadow-a` were accepted and rewritten into `var()`
+  references that point at each other, which CSS treats as guaranteed-invalid —
+  the shadow resolved to nothing, with nothing said. Both now warn with the new
+  `[RI-1125]` and keep their value verbatim, the way `@color` has always
+  reported the same shape with `[RI-1107]`. A chain that is not a cycle still
+  resolves.
+
+- **`FluidUnit` admits the container-query units.** `@fluid { unit: cqw; }`
+  validated and emitted correctly, but the exported type still listed only the
+  four viewport units, so a `FluidConfig` held a value its own type rejected.
+
+- **An empty weight in a `@font` face is no longer read as weight zero.**
+  `Number("")` is `0` and finite, so the trailing comma in `weight: 400,700,`
+  produced a face covering weight 0 and listed it in the `[RI-1504]` inventory.
+  A range is also read either way round now, so `weight: 900 300` describes the
+  same span as `300 900`.
+
+- **Named radii reach completions.** `@rounded { roof: 24px; }` compiled
+  `rounded-roof` and resolved it on hover, but class enumeration never read
+  `theme.radii`, so the name was offered by neither the completion list nor the
+  generated types — unlike every sibling scale, which reads its own record.
+
+- **`ri-disable` now reaches the scanner codes on every surface.** The
+  file-wide comment is the only form that can silence a scan warning
+  (`RI-14xx`), because those codes carry no position in your CSS — but the
+  scanned build path pushed them without consulting it, so
+  `/* ri-disable RI-1408 */` worked headless and did nothing under the CLI,
+  PostCSS, and Vite. The scan warnings now enter through the same filter as
+  every other stage. Vite's `@apply` expansion runs before any compile, so it
+  reads the codes straight out of the entry it holds.
+
+- **A `ri-disable-next-line` comment outside a directive body reports its own
+  mistakes.** Only directive bodies were read for pragma errors, so a typo or
+  an unsilenceable code in a top-level comment was ignored without the
+  `[RI-1040]` it promises. Such a comment is read once now, and an in-body
+  comment still warns exactly once.
+
+- **A named scale entry no longer loses to the built-in it shadows.**
+  `@shadow { none: … }`, `@blur { none: … }` and `@duration { initial: … }`
+  parsed and resolved, then the generator's own keyword branch answered
+  first and the value was dropped without a word. Every named scale now
+  resolves theme-first, matching `@z`, `@leading`, `@opacity`, and `@ease`,
+  which already did.
+
+- **`[RI-1408]` no longer fires on large files that hold no variant groups.**
+  The expansion budget counted plain pass-through text toward its 100,000
+  character limit, so any scanned file over that size warned as soon as it
+  held a single `{` — which every JavaScript and TypeScript file does. The
+  budget now counts only what expansion adds, so it measures the growth it
+  was written to bound. Input (500,000, `[RI-1407]`) and brace depth (10,
+  `[RI-1409]`) are unchanged.
+- **A single oversized variant group is measured before it is built.** The
+  budget was only read between groups, so one group — its prefix copied onto
+  every member — could allocate far past the limit before anything stopped
+  it. Each group is now sized first and left verbatim when it does not fit.
+
+### Changed
+
+- **Clashing with a built-in class name now warns with the new `[RI-1124]`.**
+  `@rounded { full: 30px; }` takes over `rounded-full`; the warning names the
+  class so the takeover is a choice, not a surprise. It fires for every named
+  scale, and only for names the consumer actually wrote — replacing a default
+  token such as `@color { red: … }` or `@blur { sm: … }` stays quiet. The set
+  of built-in names is read from the generators themselves rather than from a
+  hand-kept list, so it cannot drift. Where the built-in belongs to another
+  family and keeps the class — `blur-in` is an enter-animation utility that
+  only shares the `blur-` prefix — the warning says so instead of claiming a
+  takeover that did not happen.
+
+- **`ri()` resolves a named animation as an animation.** `animate-{name}`
+  merged through a hand-kept list of the shipped names, so a name from
+  `@animate` — and now every animation name, since none ships — was not
+  classified at all and could not replace another. The `animate-` prefix now
+  carries `animation`, the way `ease-` and `blur-` already carried theirs.
+
+- **`[RI-1004]` no longer names `sm/md/lg/xl` as built-in variants.** No
+  breakpoint ships, so the suggestion pointed at variants that do not exist
+  until `@breakpoint` names them. It now says so.
+
+- **Variant-group diagnostics name their source file.** `[RI-1407]`,
+  `[RI-1408]` and `[RI-1409]` now read `[RI-1408] src/App.tsx: …`, matching
+  `[RI-1411]`. Under PostCSS and Vite these warnings carried no location at
+  all, so a project-wide warning gave nothing to search for. Warnings
+  deduplicate on the full text, so a repeated breach now reports once per
+  file instead of once per project.
+
+- **A rebuild reads only the files that changed.** `rainbowindex --watch`
+  and the Vite dev server now let the watcher own cache invalidation. The
+  source file list is cached until a file is added or removed — the CLI
+  watcher joins the Vite plugin, which already cached it — and a file's
+  scanned classes are trusted until the watcher reports that file changed,
+  so a rebuild no longer runs a `stat()` on every source file to learn that
+  one of them moved. The union of scanned classes is also kept between
+  rebuilds as a multiset, and only the files whose result changed are folded
+  again: re-unioning from scratch costs one set insert per class occurrence,
+  which on a 2000-file project is roughly 480,000 inserts to rediscover the
+  same few hundred names. A one-shot build arms neither cache — with no
+  watcher to evict entries, it would serve whatever it read last.
+
+- **`compileProject()` reuses its analysis when the CSS is byte-identical.**
+  The memo that the CLI, PostCSS, and Vite builds already shared now sits
+  with the analysis itself, so the headless API gets it too. Repeat compiles
+  of one entry keep a single theme object, which is what every downstream
+  cache is keyed on — custom utilities, variants, and the per-class compile
+  memo. Warnings and diagnostics are still copied per call, so a caller that
+  mutates them cannot corrupt the memo.
+
+## [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