rainbowindex 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -5,6 +5,141 @@ 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.4.1] - 2026-08-25
+
+### Added
+
+- **Automatic zero-CLS font fallbacks.** Any `@font` slot whose family is in
+  the built-in metrics table (~100 common Google + system families, generated
+  from `@capsizecss/metrics` at development time — no new runtime dependency)
+  now gets a metrics-adjusted local fallback `@font-face` automatically. The
+  fallback font is picked from the slot's stack, or by the web font's
+  category (Arial / Times New Roman / Courier New). Opt out with
+  `metrics: none;`, pick the matched local font with `metrics: "Segoe UI";`,
+  or keep full manual control with
+  `metrics: "Arial" <size-adjust> <ascent> <descent> <line-gap>;`.
+- **`face:` entries** — local font files are now declared as repeatable
+  `face: <src> [{ overrides }]` entries, one grammar for every face:
+  `display: "Satoshi" { face: /Satoshi.woff2; face: /Satoshi-Italic.woff2 { style: italic; } }`.
+- **Fallback stacks work with `from google`** —
+  `sans: "Inter", ui-sans-serif, sans-serif from google;` now parses as a
+  google slot with fallbacks (previously it silently became a manual stack).
+- **@font now warns instead of ignoring silently**: unknown option keys
+  (RI-1217), `preload` on non-local slots where it can have no effect
+  (RI-1219), and partial or invalid `metrics` values (RI-1220).
+
+### Changed
+
+- The `@font` parser was rebuilt on the shared entry scanner: one pass, no
+  regex preambles, no re-serialization. Public API (`parseFontBody`,
+  `parseNestedFontBlock`) is unchanged.
+- **Incremental rebuilds only re-do changed work** — the scanner keeps a
+  per-file cache keyed on mtime + size, so a CLI watch or Vite HMR rebuild
+  re-reads and re-extracts only the files that actually changed instead of
+  the whole project. The CSS entry analysis is memoized on the entry text
+  (stable theme identity across rebuilds), Google-font resolution keeps its
+  identity when metadata is unchanged, and per-class compilation results
+  (rule, warnings, token usage) are replayed across rebuilds from a
+  theme-keyed cache. A one-file edit in a large project now costs
+  O(changed files) instead of O(project).
+- **`ri()` conditional args hit the cache fast path** — falsy arguments
+  (`ri("flex", isActive && "bg-blue-500")`) no longer force re-tokenization
+  on every call: the raw-key cache skips falsy primitives, making cached
+  conditional-pattern calls ~4x faster.
+- **Cheaper compile passes** — duplicate class names across `@apply` rules
+  resolve once per pass, the `@slot`/`@apply` walks no longer traverse the
+  generated utility CSS, custom `@utility` bodies parse once per body text
+  instead of once per variant form, and the editor candidate collector's
+  context assignment went from quadratic to a sorted sweep. As part of the
+  compile-result replay, engine-level compilation warnings are now
+  deduplicated (final project output already was).
+- **Internal restructuring (behavior-preserving)** — the directive body
+  parsers were split by grammar family: `@color` and `@font` now own their
+  own modules, and the generic key-value/entry grammars sit together in the
+  directives foundation. The `parsers` import surface is unchanged.
+
+### Deprecated
+
+- The older `@font` forms still parse and desugar into the new model, but
+  warn (RI-1218) and will be removed in a future release: `@face { src: …; }`
+  blocks and the `italic:` shorthand (use `face:`), `from "<path>"` (use
+  `face:`), `from system` (use bare `system`), the `fallback:` key (list
+  fallbacks in the slot preamble), the five-key metrics cluster
+  `metricsFallback`/`sizeAdjust`/`ascent`/`descent`/`lineGap` (use
+  `metrics:`), and the `unicodeRange` spelling (use `unicode-range`).
+
+### Removed
+
+- **`@font` `subset:`** — the Google css2 API takes no subset hint, so the
+  key never affected the emitted URL. It now warns (RI-1218) and is ignored.
+- **`FontSlot` / `FontFace` fields** — the five slot-level metrics fields
+  (`metricsFallback`, `sizeAdjust`, `ascent`, `descent`, `lineGap`) are
+  replaced by a single `metrics?: FontMetricsConfig | null`; slot-level
+  `preload` moved onto the faces; `FontFace.subset` is gone. Stylesheets are
+  unaffected — this only touches code importing those types directly.
+
+### Fixed
+
+- **`ri()` stroke-width vs stroke-color conflict — for real this time.** The
+  v0.4.0 changelog described this fix, but the implementation did not ship in
+  that release: `ri("stroke-2 stroke-red-500")` still dropped `stroke-2`. The
+  `stroke` prefix is now actually width-vs-color dual-mode (mirroring
+  `border`/`outline`): decimal and non-color arbitrary values claim
+  `stroke-width`, color values claim `stroke`. Same-property conflicts
+  (`stroke-2` vs `stroke-4`, `stroke-red-500` vs `stroke-blue-500`) still
+  merge as before. The emission↔claim parity suite no longer carries a
+  stroke exception, and regression tests pin the merged output.
+- **Directive rewriter no longer duplicates unclosed blocks** — an
+  unterminated `{` inside a `@color` body made the Vite-plugin pre-pass
+  re-emit the text before it (`@color { accent: 0.18 330 { inline` came out
+  with the entry doubled). The rewriter's two hand-rolled brace walks were
+  replaced by one shared walker built on the same brace matcher the directive
+  scan already uses, which also makes quotes and comments inside blocks
+  behave consistently across the rewrite passes.
+
+## [0.4.0] - 2026-08-20
+
+### Added
+
+- **GitHub Packages publishing** — every release is now also published to
+  GitHub Packages as `@rainbowindex/rainbowindex` (that registry requires an
+  owner-scoped name). The README documents installing it under the usual
+  name via `pnpm add rainbowindex@npm:@rainbowindex/rainbowindex`, so all
+  documented imports and CLI invocations work unchanged.
+
+### Changed
+
+- **Stricter CLI argument validation** — the CLI is now driven by a
+  declarative command table that knows which flags and positionals each
+  command accepts. Flags used under the wrong command, stray positional
+  arguments, and flags missing their value are rejected with an error
+  instead of being silently ignored.
+- **Internal restructuring** (behavior-preserving, net ≈ −4,500 lines) —
+  the merge, scanner, and effects modules were split into focused modules;
+  the spacing/border prefix→property maps are now single-sourced from the
+  merge conflict table with a machine-checked parity test; `@apply` reuses
+  the engine's cascade ordering; the CLI and PostCSS builds share one
+  orchestration path with parallelized font fetches; and all internal
+  import cycles were broken. Public entry points are unchanged.
+
+### Fixed
+
+- **`ri()` stroke-width vs stroke-color conflict** — width-shaped `stroke-*`
+  classes (`stroke-2`, `stroke-1.5`, `stroke-[3px]`) were claiming the
+  `stroke` color property in the merge conflict table, so
+  `ri("stroke-2 stroke-red-500")` dropped `stroke-2` even though the two
+  classes set different CSS properties. The `stroke` prefix is now
+  width-vs-color dual-mode (mirroring `border`/`outline`): decimal and
+  non-color arbitrary values claim `stroke-width`, color values claim
+  `stroke`. Same-property conflicts (`stroke-2` vs `stroke-4`,
+  `stroke-red-500` vs `stroke-blue-500`) still merge as before.
+- **Watch mode double rebuild** — debouncing and rate-limiting now share a
+  single timer, so a burst of file changes landing inside the rate-limit
+  window schedules one rebuild instead of a redundant second one.
+- **`@color` entries without a colon** — a colon-less fragment in an
+  `@color` block now produces a warning and is skipped on its own; it no
+  longer swallowed the entry that followed it.
+
 ## [0.3.0] - 2026-08-14
 
 ### Added — editor tooling API (phase 2)

package/README.md

@@ -28,6 +28,28 @@ 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.
 
+### From GitHub Packages
+
+Every release is also published to [GitHub Packages](https://github.com/rainbowindex/rainbowindex/pkgs/npm/rainbowindex) as `@rainbowindex/rainbowindex` — the same build under an owner-scoped name, which that registry requires. Point the scope at the registry in your project's `.npmrc`:
+
+```ini
+@rainbowindex:registry=https://npm.pkg.github.com
+```
+
+GitHub Packages authenticates every read, including public ones, so put a [personal access token (classic)](https://github.com/settings/tokens) with the `read:packages` scope in your `~/.npmrc`:
+
+```ini
+//npm.pkg.github.com/:_authToken=YOUR_TOKEN
+```
+
+Then install under the alias `rainbowindex`, so every import, `@import`, and CLI invocation in the docs below works unchanged:
+
+```sh
+pnpm add rainbowindex@npm:@rainbowindex/rainbowindex
+```
+
+Without the alias — `pnpm add @rainbowindex/rainbowindex` — the package resolves under its scoped name, and specifiers become `@rainbowindex/rainbowindex`, `@rainbowindex/rainbowindex/vite`, and so on.
+
 ## Quick start (Vite)
 
 The fastest path is the Vite plugin, which auto-injects PostCSS config and discovers your CSS entry on first dev-server listen.
@@ -189,7 +211,7 @@ 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. One slot can own multiple `@face` faces (e.g. upright + italic) or use the `italic:` shorthand. |
+| `@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). |
 | `@fluid` | Configure fluid type/spacing range. |
 | `@animate` | Register named animations with inline `@keyframes`. |
@@ -220,10 +242,11 @@ Example:
 }
 
 @font {
-	sans: "Inter" from google { weight: 400 700; }
-	display: "Satoshi" from "/fonts/Satoshi.woff2" {
+	sans: "Inter", ui-sans-serif, sans-serif from google { weight: 400 700; }
+	display: "Satoshi" {
 		weight: 300 900;
-		italic: "/fonts/Satoshi-Italic.woff2";   /* second face, font-style: italic */
+		face: /fonts/Satoshi.woff2;
+		face: /fonts/Satoshi-Italic.woff2 { style: italic; }
 	}
 }
 

package/dist/browser.d.ts

@@ -1,5 +1,5 @@
-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 createRi, f as defaultTheme, g as finalizeCompilationContext, r as registerColorNames, h as registerCustomFontFamilies, i as registerCustomTextSizes, j as registerCustomUtility, k as ri } from './index-CfDtWufj.js';
-export { s as safelist } from './safelist-CH3_PywB.js';
+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';
 
 declare function browserEntryUnavailable(): never;
 

package/dist/browser.mjs

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

package/dist/chunk-3HRMFZGE.mjs

@@ -0,0 +1,19 @@
+// src/scanner/source-files.ts
+var SOURCE_FILE_EXTENSIONS = Object.freeze([
+  "html",
+  "js",
+  "jsx",
+  "ts",
+  "tsx",
+  "md",
+  "mdx",
+  "vue",
+  "svelte"
+]);
+function isSourceFile(file) {
+  return SOURCE_FILE_EXTENSIONS.some((ext) => file.endsWith(`.${ext}`));
+}
+
+export {
+  isSourceFile
+};