rainbowindex 0.2.1 → 0.2.2

package/dist/cli.mjs

@@ -1,22 +1,29 @@
 #!/usr/bin/env node
+import {
+  CSS_ENTRY_CANDIDATES,
+  enumerateClassNames
+} from "./chunk-KYDEHYIE.mjs";
 import {
   DEFAULT_EXCLUDES,
   DEFAULT_PATTERNS,
-  MAX_DIRECTIVE_INPUT_SIZE,
-  analyzeProjectCSS,
   collectProjectClasses,
-  extractDirectives,
   finalizeProjectCompilation,
   getFontPreloadLinks,
-  hasApplyLikeDirective,
-  hasRIActivation,
-  resolveDirectives,
   resolveGoogleFonts,
   validateGlobPattern
-} from "./chunk-RPXZ3O6R.mjs";
+} from "./chunk-FHATRQMN.mjs";
+import {
+  MAX_DIRECTIVE_INPUT_SIZE,
+  analyzeProjectCSS,
+  extractDirectives,
+  hasApplyLikeDirective,
+  hasRIActivation,
+  listVariants,
+  resolveDirectives
+} from "./chunk-W6XIBM4M.mjs";
 import {
   devWarn
-} from "./chunk-5N4GPK26.mjs";
+} from "./chunk-SOMDX7V6.mjs";
 
 // src/entries/cli.ts
 import { realpathSync } from "fs";
@@ -314,21 +321,9 @@ Examples:
 import { existsSync } from "fs";
 import { readFile, stat } from "fs/promises";
 import { resolve as resolve2 } from "path";
-var CSS_CANDIDATES = Object.freeze([
-  "src/index.css",
-  "src/style.css",
-  "src/styles.css",
-  "src/app.css",
-  "src/global.css",
-  "index.css",
-  "style.css",
-  "styles.css",
-  "app.css",
-  "global.css"
-]);
 var MAX_CSS_FILE_SIZE = MAX_DIRECTIVE_INPUT_SIZE;
 async function findCSSFileAsync(cwd) {
-  const candidates = CSS_CANDIDATES;
+  const candidates = CSS_ENTRY_CANDIDATES;
   const results = await Promise.all(
     candidates.map(async (candidate) => {
       const full = resolve2(cwd, candidate);
@@ -452,19 +447,37 @@ async function generateTypes(opts, cwd) {
       return false;
     });
   };
+  const literalSafe = (names) => names.filter((n) => !n.includes('"') && !n.includes("\\"));
+  const enumeration = enumerateClassNames(theme);
+  const variants = listVariants(theme);
   const colorNames = validateNames(Object.keys(theme.colors), "color");
   const textSizes = validateNames(Object.keys(theme.text), "text");
-  const breakpoints = validateNames(Object.keys(theme.breakpoints), "breakpoint");
   const weightNames = validateNames(Object.keys(theme.weights), "weight");
-  const staticCustomUtilities = validateNames(
-    theme.customUtilities.filter((u) => !u.functional).map((u) => u.name),
-    "utility"
+  const variantNames = literalSafe(variants.filter((v) => v.kind !== "pattern").map((v) => v.name));
+  const finiteClasses = literalSafe(enumeration.classes.map((c) => c.name));
+  const spacingRoots = validateNames(
+    enumeration.templates.filter((t) => t.kind === "spacing").map((t) => t.root),
+    "spacing root"
+  );
+  const numericRoots = validateNames(
+    enumeration.templates.filter((t) => t.kind === "number").map((t) => t.root),
+    "numeric root"
   );
   const functionalCustomUtilities = validateNames(
-    theme.customUtilities.filter((u) => u.functional).map((u) => u.name),
+    enumeration.templates.filter((t) => t.kind === "custom").map((t) => t.root),
     "utility"
   );
   const union = (names) => names.length > 0 ? names.map((n) => `"${n}"`).join(" | ") : "never";
+  const unionLines = (names, perLine) => {
+    if (names.length === 0) return ["  | never"];
+    const lines2 = [];
+    for (let i = 0; i < names.length; i += perLine) {
+      lines2.push(
+        `  | ${names.slice(i, i + perLine).map((n) => `"${n}"`).join(" | ")}`
+      );
+    }
+    return lines2;
+  };
   const lines = [
     "// rainbowindex-env.d.ts (auto-generated \u2014 do not edit)",
     "",
@@ -472,25 +485,44 @@ async function generateTypes(opts, cwd) {
     `type ColorStop = "50" | "100" | "150" | "200" | "250" | "300" | "350" | "400" | "450" | "500" | "550" | "600" | "650" | "700" | "750" | "800" | "850" | "900" | "950";`,
     "type SpacingToken = `${number}` | `${number}_${number}`;",
     `type TextSize = ${union(textSizes)};`,
-    `type Variant = ${union(breakpoints)} | "hover" | "focus" | "focus-visible" | "active" | "disabled" | "dark" | "first" | "last" | "odd" | "even";`,
     `type WeightName = ${union(weightNames)};`,
     "",
-    "type RainbowClass =",
-    '  | `${"bg" | "text" | "border" | "outline" | "accent" | "caret" | "fill" | "stroke"}-${ColorName}-${ColorStop}`',
-    '  | `${"p" | "px" | "py" | "pt" | "pb" | "pl" | "pr" | "ps" | "pe" | "pbs" | "pbe" | "m" | "mx" | "my" | "mt" | "mb" | "ml" | "mr" | "ms" | "me" | "mbs" | "mbe" | "gap" | "gap-x" | "gap-y"}-${SpacingToken}`',
-    "  | `text-${TextSize}`",
-    "  | `text-fluid-${TextSize}`",
-    '  | `font-${"sans" | "serif" | "mono"}`',
-    "  | `font-${WeightName}`",
-    "  | `w-${SpacingToken}` | `h-${SpacingToken}` | `size-${SpacingToken}`"
+    "type Variant =",
+    ...unionLines(variantNames, 8),
+    "  ;",
+    "",
+    "// Every finite class the compiler resolves for this theme \u2014 statics plus",
+    "// theme-token expansions, enumerated and probe-verified.",
+    "type RainbowStatic =",
+    ...unionLines(finiteClasses, 6),
+    "  ;"
   ];
-  if (staticCustomUtilities.length > 0) {
-    lines.push(`  | ${staticCustomUtilities.map((n) => `"${n}"`).join(" | ")}`);
+  if (spacingRoots.length > 0) {
+    lines.push("", `type SpacingRoot = ${union(spacingRoots)};`);
+  }
+  if (numericRoots.length > 0) {
+    lines.push(`type NumericRoot = ${union(numericRoots)};`);
+  }
+  lines.push("", "type RainbowBase =", "  | RainbowStatic");
+  if (spacingRoots.length > 0) {
+    lines.push("  | `${SpacingRoot}-${SpacingToken}`");
+  }
+  if (numericRoots.length > 0) {
+    lines.push("  | `${NumericRoot}-${number}`");
   }
   if (functionalCustomUtilities.length > 0) {
     lines.push(`  | ${functionalCustomUtilities.map((n) => `\`${n}-\${string}\``).join(" | ")}`);
   }
-  lines.push("  | `${Variant}:${Exclude<RainbowClass, `${string}:${string}`>}`");
+  lines.push("  ;");
+  lines.push(
+    "",
+    "type RainbowClass =",
+    "  | RainbowBase",
+    "  // Variant-prefixed classes validate the variant name (chained prefixes",
+    "  // match through the open remainder). Expanding Variant \xD7 RainbowBase",
+    "  // eagerly would exceed TypeScript's union-size limits.",
+    "  | `${Variant}:${string}`"
+  );
   if (!opts.strict) {
     lines.push("  | (string & {});");
   } else {
@@ -1054,7 +1086,7 @@ async function resolveStylesheetPath(cwd, cssFile) {
   if (cssFile) return resolve5(cwd, cssFile);
   const importedCSS = await findImportedStylesheet(cwd);
   if (importedCSS) return importedCSS;
-  for (const candidate of CSS_CANDIDATES) {
+  for (const candidate of CSS_ENTRY_CANDIDATES) {
     const fullPath = resolve5(cwd, candidate);
     if (existsSync3(fullPath)) return fullPath;
   }
@@ -1201,7 +1233,7 @@ function readPackageJSONSync(cwd) {
 
 // src/entries/cli.ts
 function getVersion() {
-  return true ? "0.2.1" : "unknown";
+  return true ? "0.2.2" : "unknown";
 }
 async function main() {
   const args = process.argv.slice(2);

package/dist/editor.d.ts

@@ -0,0 +1,464 @@
+import { P as ParsedDirective, R as ResolvedTheme } from './index-DK6APAGD.js';
+export { b as createThemeSnapshot } from './index-DK6APAGD.js';
+import { C as ColorDefinition, b as CompilationSnapshot, M as MergeAnalysis } from './index-CfDtWufj.js';
+export { n as MergeDrop, o as analyzeMerge, f as defaultTheme } from './index-CfDtWufj.js';
+
+/** Helper-call names whose string arguments are walked for class literals.
+ *  Exported for editor tooling so completion-context detection can match the
+ *  scanner's own behavior. */
+declare const CLASS_HELPER_NAMES: readonly string[];
+/** Variant-config helper names (`cva`/`tv`) whose config objects are walked. */
+declare const VARIANT_HELPER_NAMES: readonly string[];
+interface SourceExtractionInput {
+    path?: string;
+    content: string;
+}
+type CandidateOrigin = "attribute" | "helper" | "safelist" | "plain";
+interface ClassCandidate {
+    /** The class string in expanded form — for variant-group members this
+     *  includes the group prefix (`hover:bg-red-500`) even though the span
+     *  covers only the member token inside the braces. */
+    value: string;
+    /** Absolute [start, end) span of the visible token in the original source.
+     *  `source.slice(start, end)` is the member token for group members and
+     *  `value` itself everywhere else. */
+    start: number;
+    end: number;
+    origin: CandidateOrigin;
+    /** The call the class was found in, when origin is "helper"/"safelist". */
+    helperName?: string;
+    /** For variant-group members: span of the group's variant prefix (`hover:`). */
+    groupPrefix?: {
+        start: number;
+        end: number;
+    };
+}
+declare function expandVariantGroups(input: string, warnings?: string[]): string;
+declare function extractClasses(source: string, warnings?: string[]): Set<string>;
+declare function extractClassesFromSource(input: SourceExtractionInput, warnings?: string[]): Set<string>;
+/**
+ * Position-aware variant of `extractClassesFromSource` for editor tooling.
+ * Same extractors, same filters, same pruning — the value set of the result
+ * always equals `extractClassesFromSource(input)`. Each candidate additionally
+ * carries its source span, its collection origin, and (for variant-group
+ * members) the group's prefix span. Candidates are sorted by position and
+ * deduped by span + value; a span found by both the whole-file scan and a
+ * context-aware collector reports the collector's origin.
+ */
+declare function extractClassCandidates(input: SourceExtractionInput, warnings?: string[]): ClassCandidate[];
+
+/**
+ * Lightweight source-file detection — no heavy dependencies (tinyglobby, etc.).
+ * Kept separate so the Vite integration can import it without pulling in
+ * Node-only glob machinery into browser bundles.
+ */
+declare function isSourceFile(file: string): boolean;
+
+/**
+ * Default CSS entry candidates — the paths the CLI, the Vite plugin, and
+ * editor tooling probe (in order) when locating the project's Rainbow Index
+ * CSS input. Pure data, no filesystem access: IO-free consumers (editor
+ * tooling) reuse the exact detection order with their own file access and
+ * confirm a hit with `hasRIActivation()` on the file's contents.
+ */
+declare const CSS_ENTRY_CANDIDATES: readonly string[];
+
+/** Import specifiers that activate RainbowIndex. Single source for the
+ *  activation scan here, the PostCSS import matcher, and the strip regex. */
+declare const RI_IMPORT_SPECIFIERS: readonly string[];
+/**
+ * Detect whether source activates RainbowIndex: any RI directive token
+ * (including PostCSS-only `@apply` and `@slot`) or an `@import` of the
+ * package CSS, outside comments/strings. One fused scan covers both.
+ */
+declare function hasRIActivation(src: string): boolean;
+
+/**
+ * Structured diagnostics — the typed view of the `[RI-NNNN] message` warning
+ * strings, for editor tooling that anchors problems to source spans.
+ *
+ * The legacy string arrays stay the wire format everywhere (and the warning
+ * budget/dedup in warnings.ts keeps operating on them); a Diagnostic carries
+ * the same full message text verbatim, plus the parsed code, a severity
+ * derived from the documented code-range convention, and — when the emission
+ * site knew one — a [start, end) span into the CSS input. Consumers can rely
+ * on `diagnostics[i].message === warnings[i]` wherever both are returned.
+ */
+type DiagnosticSeverity = "error" | "warning";
+interface Diagnostic {
+    /** The RI-NNNN code, or null when the message carries no parseable code. */
+    code: string | null;
+    severity: DiagnosticSeverity;
+    /** The full legacy warning text, including the `[RI-NNNN]` prefix. */
+    message: string;
+    /** [start, end) span in the analyzed CSS input, or null when unknown. */
+    start: number | null;
+    end: number | null;
+}
+/** Extract the RI-NNNN code from a legacy warning string, or null. */
+declare function warningCode(message: string): string | null;
+/**
+ * Severity by code range — the same convention warnings.ts budgets by:
+ * RI-0xxx (fatal/bootstrap) and RI-2xxx (compile/runtime errors) are errors,
+ * everything else (informational 1xxx ranges) is a warning.
+ */
+declare function severityForCode(code: string | null): DiagnosticSeverity;
+/** Wrap a legacy warning string as a Diagnostic, with an optional span. */
+declare function diagnosticFromWarning(message: string, span?: readonly [number, number] | null): Diagnostic;
+
+/**
+ * Theme-only project analysis — the cheap front half of compileProject.
+ *
+ * Kept in a leaf module (no assembly/font machinery in the import graph) so
+ * IO-free consumers — the `rainbowindex/editor` entry — can turn a CSS input
+ * string into a ResolvedTheme without dragging Node-only code along.
+ * `project/pipeline.ts` re-exports this module, so existing importers are
+ * unaffected.
+ */
+
+interface ProjectAnalysis {
+    directives: ParsedDirective[];
+    theme: ResolvedTheme;
+    warnings: string[];
+    warningSeen: Set<string>;
+    /**
+     * Structured view of `warnings` — same messages, same order
+     * (`diagnostics[i].message === warnings[i]`), each with the parsed code,
+     * range-derived severity, and a [start, end) span into the CSS input when
+     * the emitter knew one: directive-parse problems point at the offending
+     * at-rule, resolver problems at the directive whose body produced them.
+     */
+    diagnostics: Diagnostic[];
+}
+declare function analyzeProjectCSS(css: string): ProjectAnalysis;
+
+/**
+ * Parses utility class strings into structured tokens.
+ *
+ * "hover:bg-red-500"  → { variants: ["hover"], utility: "bg", value: "red-500" }
+ * "sm:p-4"            → { variants: ["sm"], utility: "p", value: "4" }
+ * "text-center!"      → { variants: [], utility: "text-center", value: null, important: true }
+ * "p-[13px]"          → { variants: [], utility: "p", value: "[13px]", arbitrary: true }
+ * "@md:flex"           → { variants: ["@md"], utility: "flex", value: null }
+ * "pl-physical-4"     → { variants: [], utility: "pl", value: "4", physical: true }
+ */
+interface ParsedUtility {
+    /** Original class string before parsing */
+    raw: string;
+    /** Variant prefixes in order, e.g. ["hover"], ["sm", "hover"] */
+    variants: string[];
+    /** The utility name (everything before the value separator), e.g. "bg", "p", "text" */
+    utility: string;
+    /** The value part after the last `-`, or null for valueless utilities like "flex" */
+    value: string | null;
+    /** Whether the value is an arbitrary bracket expression like [13px] */
+    arbitrary: boolean;
+    /** Whether !important is applied */
+    important: boolean;
+    /** Whether the -physical- infix is present */
+    physical: boolean;
+    /** Whether the utility is negative (prefixed with -) */
+    negative: boolean;
+    /** When the class is an arbitrary property like [color:red] */
+    arbitraryProperty: {
+        property: string;
+        value: string;
+    } | null;
+    /**
+     * Explicit type hint extracted from an arbitrary value, e.g. the `length`
+     * in `border-[length:1rem]` or `border-(color:--my-color)`. When set, it
+     * forces a specific dispatch path in generators — see `borderGenerator`,
+     * `colorGenerator`, etc. Null when no hint was provided.
+     */
+    dataType: string | null;
+}
+/**
+ * Parse a single utility class string into its structural components.
+ */
+declare function parseUtility(raw: string): ParsedUtility;
+
+interface CSSDeclaration {
+    property: string;
+    value: string;
+}
+
+/**
+ * Variant resolution — maps variant names to CSS wrappers.
+ *
+ * Handles pseudo-classes, pseudo-elements, media queries, responsive breakpoints,
+ * container queries, data/aria attributes, :has()/:not(), arbitrary variants,
+ * and custom variants.
+ */
+
+type VariantKind = "pseudo-class" | "pseudo-element" | "media" | "breakpoint" | "container" | "special" | "custom" | "pattern";
+interface VariantInfo {
+    /** The variant as typed before the `:` — for patterns, the family prefix. */
+    name: string;
+    kind: VariantKind;
+    /** What the variant emits — a selector suffix, an at-rule, or (for
+     *  patterns) a description of the accepted form. */
+    wraps: string;
+}
+/**
+ * Enumerate every concrete variant the given theme resolves, plus the
+ * open-ended pattern families. Concrete entries (kind ≠ "pattern") are
+ * guaranteed to resolve via resolveVariant — the list mirrors its checks,
+ * including the CSS-length guard on breakpoint values.
+ */
+declare function listVariants(theme: ResolvedTheme): VariantInfo[];
+
+/**
+ * Class inspector — single-class validation and explanation for editor
+ * tooling, running the exact resolution the compile loop performs.
+ *
+ * The compiler intentionally drops unknown utilities silently (reserved
+ * RI-1001): the build scanner over-collects, so at build time an unresolved
+ * candidate is usually noise. Inside an editor the certainty is inverted — a
+ * token in a class attribute is meant to be a class — so the inspector
+ * finally gives RI-1001 a voice: `validate()` reports WHY a class produces no
+ * CSS, with a typo suggestion when one is close enough.
+ *
+ * An inspector instance owns the per-theme caches the compile loop rebuilds
+ * per pass (custom-variant map, variant memo, breakpoint weights) plus a
+ * resolution cache, so per-keystroke validation of the same classes is cheap.
+ * Create one per theme and drop it when the theme changes.
+ */
+
+type ClassValidation = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "unknown-utility" | "unknown-variant" | "invalid-arbitrary";
+    /** The failing fragment — the variant for "unknown-variant", the
+     *  base class (variants stripped) otherwise. */
+    offender: string;
+    /** Closest known name within typo distance, when one exists. */
+    suggestion?: string;
+};
+interface ClassExplanation {
+    parsed: ParsedUtility;
+    /** Root declarations before variant wrapping. */
+    declarations: CSSDeclaration[];
+    /** Escaped selector, including variant suffixes (`.hover\:px-2:hover`). */
+    selector: string;
+    /** The complete rule text, including wrapping at-rules. */
+    css: string;
+    /** Deterministic ordering key — lower emits earlier in generated CSS. */
+    sortKey: number;
+}
+interface ClassInspector {
+    readonly theme: ResolvedTheme;
+    /** Would this class produce CSS under the theme? Reports why not. */
+    validate(className: string): ClassValidation;
+    /** Structured breakdown + generated CSS, or null when invalid. */
+    explain(className: string): ClassExplanation | null;
+    /** Every variant the theme resolves (cached). */
+    variants(): readonly VariantInfo[];
+}
+declare function createClassInspector(theme: ResolvedTheme): ClassInspector;
+
+/**
+ * Typo suggestion helpers using optimal string alignment (OSA) distance —
+ * Levenshtein plus adjacent transpositions, so `felx` → `flex` is distance 1.
+ * Shared between engine.ts and css-functions.ts.
+ */
+/**
+ * Find the closest match to `input` from a list of candidates.
+ * Returns null if no candidate is within `maxDistance`.
+ */
+declare function findClosest(input: string, candidates: string[], maxDistance?: number): string | null;
+
+/**
+ * Class enumeration — the completion universe for editor tooling.
+ *
+ * Design: candidates are generated from a deliberately GENEROUS value-space
+ * table (which theme namespaces and keyword families to TRY per functional
+ * root), then every candidate is probed through the real utility resolver.
+ * The resolver is the single authority — an enumerated class is one that
+ * actually compiles, so the table can over-approximate freely and can never
+ * emit something `validate()` would reject. Coverage is enforced the other
+ * way by tests: every PREFIX_DISPATCH root must appear in the table (an empty
+ * spec marks a statics-only root), so adding a generator root without
+ * deciding its value space fails CI.
+ *
+ * Statics come from the merge conflict tables (STATIC_UTILITIES) plus each
+ * generator's own static-map keys — probed too, for the same guarantee.
+ */
+
+type ValueSpaceKind = "color" | "special-color" | "spacing" | "fraction" | "text-size" | "fluid-text-size" | "font-slot" | "weight" | "rounded" | "rounded-side" | "shadow" | "z" | "ease" | "blur" | "animation" | "leading" | "tracking" | "opacity" | "duration" | "breakpoint" | "int" | "percent" | "keywords";
+interface ValueSpaceSpec {
+    kinds: readonly ValueSpaceKind[];
+    /** Extra value parts to try verbatim (for "keywords" and beyond). */
+    keywords?: readonly string[];
+}
+/** Root → value spaces to try. Coverage of every PREFIX_DISPATCH root is
+ *  enforced by __tests__/core/enumerate.test.ts. */
+declare const UTILITY_VALUE_SPACES: ReadonlyMap<string, ValueSpaceSpec>;
+interface EnumeratedClass {
+    name: string;
+    /** How the class was produced: a static table, a custom @utility, or the
+     *  value-space kind that filled the functional root. */
+    kind: ValueSpaceKind | "static" | "custom";
+    /** The functional root, or null for statics/custom statics. */
+    root: string | null;
+}
+interface ClassTemplate {
+    root: string;
+    /** The open-ended space: numeric spacing scale, plain numbers, or a
+     *  functional custom utility that accepts any suffix. */
+    kind: "spacing" | "number" | "custom";
+    example: string;
+}
+interface ClassEnumeration {
+    /** Every finite concrete class, probed valid, sorted by name. */
+    classes: EnumeratedClass[];
+    /** Families whose value space is infinite — offer as snippets. */
+    templates: ClassTemplate[];
+}
+/**
+ * Enumerate the finite completion universe for a theme. Every returned class
+ * has been resolved by the real utility resolver — `validate()` accepts each
+ * one by construction. Infinite families (the spacing scale, numeric values,
+ * functional custom utilities) come back as templates; a template is emitted
+ * only when at least one of its probes resolved.
+ */
+declare function enumerateClassNames(theme: ResolvedTheme): ClassEnumeration;
+
+/**
+ * Color swatches and theme-token introspection for editor tooling.
+ *
+ * Resolves a theme color (and stop) to concrete light/dark colors — the same
+ * OKLCH math the CSS variable emitter uses (generateStop / computeDarkStop),
+ * plus an sRGB hex conversion for completion-item swatches and sidebar chips.
+ * Pure computation, no IO.
+ */
+
+/** The canonical palette stops every generative color defines. */
+declare const CANONICAL_COLOR_STOPS: readonly number[];
+/** Convert an OKLCH color to a #rrggbb hex string (sRGB, channel-clamped). */
+declare function oklchToHex(l: number, c: number, h: number): string;
+/** Best-effort hex for the CSS color texts theme definitions hold: `oklch()`
+ *  and hex literals. Anything else (named colors, rgb(), vars) returns null —
+ *  the raw CSS text still travels alongside. */
+declare function cssColorToHex(css: string): string | null;
+interface SwatchColor {
+    /** CSS color text (`oklch(…)`, or the definition's own value verbatim). */
+    css: string;
+    /** sRGB hex, or null when the CSS text isn't convertible. */
+    hex: string | null;
+}
+interface ColorSwatch {
+    light: SwatchColor;
+    /** Null when the theme's dark mode is off or the color has no dark form. */
+    dark: SwatchColor | null;
+}
+/**
+ * Resolve a theme color name (+ stop, for generative palettes) to concrete
+ * light/dark swatch colors — exactly the values the emitted CSS variables
+ * carry. Theme-defined colors always win; the fixed semantic swatches
+ * (paper/ink/white/black) apply only when the theme does not define the name,
+ * mirroring the emitter (a user `@color { white: … }` palette emits
+ * `--color-white-*` variables that suffixed utilities resolve against).
+ * Returns null for unknown names, unresolvable aliases, and keyword colors
+ * with no concrete value (transparent, currentColor).
+ */
+declare function resolveColorSwatch(theme: ResolvedTheme, name: string, stop?: number): ColorSwatch | null;
+interface ThemeTokens {
+    /** Color names with their definition kind — pair with resolveColorSwatch. */
+    colors: Array<{
+        name: string;
+        kind: ColorDefinition["type"];
+    }>;
+    colorStops: readonly number[];
+    spacingBase: string;
+    textSizes: Array<{
+        name: string;
+        fontSize: string;
+        lineHeight: string;
+    }>;
+    breakpoints: Record<string, string>;
+    rounded: Record<string, string>;
+    shadows: Record<string, string>;
+    weights: Record<string, number>;
+    easing: Record<string, string>;
+    blur: Record<string, string>;
+    z: Record<string, string>;
+    leading: Record<string, string>;
+    tracking: Record<string, string>;
+    opacity: Record<string, string>;
+    duration: Record<string, string>;
+    fonts: Array<{
+        slot: string;
+        family: string;
+    }>;
+    animations: string[];
+}
+/** One render-ready view of a theme's token namespaces for sidebar chips and
+ *  completion detail — plain data, no theme internals to traverse. */
+declare function listThemeTokens(theme: ResolvedTheme): ThemeTokens;
+
+/**
+ * Editor session — the façade that ties the editor toolkit together.
+ *
+ * An editor host holds one session per workspace, calls `setCss()` whenever
+ * the project's CSS entry changes, and everything else per keystroke. The
+ * session owns the caching story: theme analysis, the class inspector, the
+ * enumeration, token introspection, and the merge snapshot are computed
+ * lazily and invalidated together when the CSS changes — callers never
+ * juggle per-theme cache keys themselves. Every capability is also exported
+ * à la carte from `rainbowindex/editor` for hosts that want finer control.
+ *
+ * Pure computation, no IO: the host reads the CSS file (see
+ * CSS_ENTRY_CANDIDATES / hasRIActivation for locating it) and passes text.
+ */
+
+interface EditorSession {
+    /** The CSS input the session is currently analyzing. */
+    readonly css: string;
+    /** Swap the CSS input; all theme-derived caches invalidate together.
+     *  A no-op when the text is unchanged. */
+    setCss(css: string): void;
+    readonly theme: ResolvedTheme;
+    /** Positioned diagnostics for the CSS input (see ProjectAnalysis). */
+    readonly diagnostics: readonly Diagnostic[];
+    /** Single-class validation/explanation, cached per theme. */
+    readonly inspector: ClassInspector;
+    /** The finite completion universe + templates, cached per theme. */
+    enumerate(): ClassEnumeration;
+    /** Render-ready token namespaces, cached per theme. */
+    tokens(): ThemeTokens;
+    /** The merge snapshot for this theme, cached. */
+    snapshot(): CompilationSnapshot;
+    /** analyzeMerge bound to this theme's snapshot. */
+    analyzeMerge(classes: readonly string[]): MergeAnalysis;
+    /** Position-aware class extraction for a source document. */
+    extractCandidates(content: string, path?: string): ClassCandidate[];
+    /** Light/dark swatch for a theme color (+ stop), or null. */
+    swatch(name: string, stop?: number): ColorSwatch | null;
+}
+declare function createEditorSession(options?: {
+    css?: string;
+}): EditorSession;
+
+/**
+ * `rainbowindex/editor` — the IO-free toolkit editor integrations build on.
+ *
+ * Everything exported here is pure computation: strings in, structures out.
+ * No filesystem, no network, no module-level mutation — the entry behaves in
+ * browser-based editor hosts (vscode.dev) exactly as it does in Node. File
+ * access stays with the editor host; this module supplies the semantics:
+ * what the scanner extracts (and where), what activates Rainbow Index, and
+ * where a project's CSS entry usually lives.
+ *
+ * Editor integrations load whatever version the workspace has installed, so
+ * the surface is feature-detectable: gate on `editorCapabilities` entries,
+ * not on `version`, when deciding what the installed copy supports.
+ */
+/** Package version — build-time injected; "0.0.0-dev" when run from source. */
+declare const version: string;
+/** Editor API protocol version — bumped only on breaking changes to this entry. */
+declare const EDITOR_API_VERSION = 1;
+/** Feature-detection roster for this entry. */
+declare const editorCapabilities: readonly string[];
+
+export { CANONICAL_COLOR_STOPS, CLASS_HELPER_NAMES, CSS_ENTRY_CANDIDATES, type CandidateOrigin, type ClassCandidate, type ClassEnumeration, type ClassExplanation, type ClassInspector, type ClassTemplate, type ClassValidation, ColorDefinition, type ColorSwatch, CompilationSnapshot, type Diagnostic, type DiagnosticSeverity, EDITOR_API_VERSION, type EditorSession, type EnumeratedClass, MergeAnalysis, ParsedDirective, type ParsedUtility, type ProjectAnalysis, RI_IMPORT_SPECIFIERS, ResolvedTheme, type SourceExtractionInput, type SwatchColor, type ThemeTokens, UTILITY_VALUE_SPACES, VARIANT_HELPER_NAMES, type ValueSpaceKind, type ValueSpaceSpec, type VariantInfo, type VariantKind, analyzeProjectCSS, createClassInspector, createEditorSession, cssColorToHex, diagnosticFromWarning, editorCapabilities, enumerateClassNames, expandVariantGroups, extractClassCandidates, extractClasses, extractClassesFromSource, findClosest, hasRIActivation, isSourceFile, listThemeTokens, listVariants, oklchToHex, parseUtility, resolveColorSwatch, severityForCode, version, warningCode };