silvery 0.18.2 → 0.19.0

package/dist/index-D3saHouR.d.mts

@@ -0,0 +1,1392 @@
+//#region packages/ansi/src/detection.d.ts
+interface TerminalCaps {
+  /** Terminal program name (from TERM_PROGRAM) */
+  program: string;
+  /** TERM value */
+  term: string;
+  /** Color support level */
+  colorLevel: "none" | "basic" | "256" | "truecolor";
+  /** Kitty keyboard protocol supported */
+  kittyKeyboard: boolean;
+  /** Kitty graphics protocol (inline images) */
+  kittyGraphics: boolean;
+  /** Sixel graphics supported */
+  sixel: boolean;
+  /** OSC 52 clipboard */
+  osc52: boolean;
+  /** OSC 8 hyperlinks */
+  hyperlinks: boolean;
+  /** OSC 9/99 notifications */
+  notifications: boolean;
+  /** Bracketed paste mode */
+  bracketedPaste: boolean;
+  /** SGR mouse tracking */
+  mouse: boolean;
+  /** Synchronized output (DEC 2026) */
+  syncOutput: boolean;
+  /** Unicode/emoji support */
+  unicode: boolean;
+  /** SGR 4:x underline style subparameters (curly, dotted, dashed) */
+  underlineStyles: boolean;
+  /** SGR 58 underline color */
+  underlineColor: boolean;
+  /** Text-presentation emoji (⚠, ☑, ⭐) rendered as 2-wide.
+   * Modern terminals (Ghostty, iTerm, Kitty) render these at emoji width (2 cells).
+   * Terminal.app renders them at text width (1 cell). */
+  textEmojiWide: boolean;
+  /** OSC 66 text sizing protocol likely supported (Kitty 0.40+, Ghostty) */
+  textSizingSupported: boolean;
+  /** Heuristic: likely dark background (for theme selection) */
+  darkBackground: boolean;
+  /** Heuristic: likely has Nerd Font installed (for icon selection) */
+  nerdfont: boolean;
+}
+/**
+ * Default capabilities (assumes modern terminal with full support).
+ */
+declare function defaultCaps(): TerminalCaps;
+/** Detect terminal capabilities from environment variables.
+ * Synchronous. Minimal I/O: may run `defaults` on macOS for Apple_Terminal.
+ */
+declare function detectTerminalCaps(): TerminalCaps;
+//#endregion
+//#region packages/ansi/src/types.d.ts
+/**
+ * Type definitions for @silvery/ansi
+ */
+/**
+ * Color level supported by terminal.
+ * - 'basic': 16 colors (SGR 30-37, 40-47)
+ * - '256': 256 colors (SGR 38;5;n)
+ * - 'truecolor': 16M colors (SGR 38;2;r;g;b)
+ */
+type ColorLevel = "basic" | "256" | "truecolor";
+//#endregion
+//#region packages/ansi/src/color-maps.d.ts
+/**
+ * Color tier for preview quantization.
+ *
+ * Mirrors the tiers a real terminal would resolve to when the output phase
+ * emits ANSI: `truecolor` (pass-through), `256` (6×6×6 cube + grayscale ramp),
+ * `ansi16` (nearest of 16 slots), `mono` (luminance → black/white).
+ */
+type ColorTier = "truecolor" | "256" | "ansi16" | "mono";
+/**
+ * Hex-in / hex-out quantization for previews.
+ *
+ * Takes any hex color and returns the hex a real terminal at that tier would
+ * actually emit. Used by the Sterling storybook to make the `1/2/3/4` tier
+ * toggle visibly different in-process — the output phase already does this
+ * when writing to a real TTY, but preview surfaces (theme swatches, rendered
+ * components inside a storybook app) bypass output-phase quantization. Apply
+ * `quantizeHex` at render time to mimic tier-specific terminal output.
+ *
+ *   - `truecolor`: returns the input unchanged (normalized to `#rrggbb`).
+ *   - `256`: snaps to the nearest xterm-256 slot, then returns that slot's hex.
+ *   - `ansi16`: snaps to one of the 16 standard slots (canonical xterm RGB).
+ *   - `mono`: luminance threshold (>= 0.5 → `#ffffff`, else `#000000`).
+ *
+ * Returns the input unchanged if it cannot be parsed as a hex color.
+ */
+declare function quantizeHex(hex: string, tier: ColorTier): string;
+/**
+ * Pre-quantize every hex leaf in a Theme (or any object tree) to the
+ * requested color tier.
+ *
+ * Walks the input recursively — each string leaf matching `#rgb` / `#rrggbb`
+ * is passed through {@link quantizeHex}; all other values (numbers, booleans,
+ * non-hex strings like `"Nord"`, null/undefined, arrays of non-hex values)
+ * pass through unchanged. Arrays and nested objects are rebuilt with
+ * quantized leaves.
+ *
+ * Works on both the legacy ANSI Theme (flat hex tokens + `palette` array)
+ * and the Sterling Theme (nested roles + flat tokens) — the structural rule
+ * "any leaf that looks like a hex is a color value" holds for both.
+ *
+ * @example Pre-cache tier variants
+ * ```ts
+ * import { pickColorLevel } from "silvery"
+ *
+ * const themes = {
+ *   truecolor: theme,
+ *   ansi16: pickColorLevel(theme, "ansi16"),
+ *   mono: pickColorLevel(theme, "mono"),
+ * }
+ * ```
+ *
+ * @example Storybook — show multiple tiers simultaneously
+ * ```tsx
+ * <ThemeProvider theme={pickColorLevel(theme, "ansi16")}>
+ *   <AlertPreview />
+ * </ThemeProvider>
+ * ```
+ *
+ * Notes:
+ * - `truecolor` is a no-op — returns the input unchanged (identity).
+ * - The result is structurally identical to the input (same keys, same
+ *   nesting); only hex leaves are remapped.
+ * - Idempotent per tier: `pickColorLevel(pickColorLevel(t, "ansi16"), "ansi16")`
+ *   yields the same hex values as `pickColorLevel(t, "ansi16")`.
+ * - Does not freeze the returned object. Callers that want immutability
+ *   should `Object.freeze()` (or deep-freeze) the result themselves.
+ */
+declare function pickColorLevel<T>(theme: T, tier: ColorTier): T;
+//#endregion
+//#region packages/ansi/src/flatten.d.ts
+/**
+ * Generic flat-projection helper for design-system Themes.
+ *
+ * Any DesignSystem whose Theme is a nested POJO of hex-string leaves can
+ * project those leaves as hyphen-keyed siblings on the SAME object — the
+ * "flat form" — with no copy and no Proxy. Both paths reference the same
+ * string. The object is frozen at the end.
+ *
+ * ```ts
+ * const theme = bakeFlat({
+ *   accent: { fg: "#0969da", bg: "#0969da", fgOn: "#ffffff",
+ *             hover: { fg: "#0550ae", bg: "#0550ae" } },
+ *   surface: { default: "#ffffff", subtle: "#f6f8fa" },
+ *   cursor: { fg: "#ffffff", bg: "#0969da" },
+ * })
+ *
+ * theme.accent.bg === theme["bg-accent"]               // true — same reference
+ * theme["bg-accent-hover"]                             // "#0550ae"
+ * theme["bg-surface-subtle"]                           // "#f6f8fa"
+ * ```
+ *
+ * Consumed by:
+ *   - Sterling (`@silvery/theme/sterling`) via `defineDesignSystem({ flatten: true })`
+ *   - Any alternative DesignSystem that wants flat-projection for free
+ *
+ * @see defaultFlattenRule — the channel-role-state rule Sterling uses
+ * @see FlattenRule — bring-your-own rule for non-Sterling conventions
+ */
+/**
+ * Given a nested path to a hex leaf, return the flat-key sibling to write
+ * onto the root object. Return `null` to skip that leaf (no flat alias).
+ *
+ * Paths are arrays of segment names as they appear in the nested object,
+ * e.g. `["accent", "hover", "bg"]`.
+ */
+type FlattenRule = (path: readonly string[]) => string | null;
+/**
+ * Channel-role-state default rule. Matches Sterling / Primer / CSS-var
+ * conventions: `{kind}-{role}[-{state}]`, with `fg-on-{role}` for `fgOn`,
+ * and implicit-kind collapse for the `surface` / `border` roles.
+ *
+ * Mapping examples:
+ * | Path                         | Flat key                    |
+ * | ---------------------------- | --------------------------- |
+ * | `accent.fg`                  | `fg-accent`                 |
+ * | `accent.bg`                  | `bg-accent`                 |
+ * | `accent.fgOn`                | `fg-on-accent`              |
+ * | `accent.border`              | `border-accent`             |
+ * | `accent.hover.bg`            | `bg-accent-hover`           |
+ * | `accent.active.fg`           | `fg-accent-active`          |
+ * | `info.hover.bg`              | `bg-info-hover`             |
+ * | `cursor.fg`                  | `fg-cursor`                 |
+ * | `muted.bg`                   | `bg-muted`                  |
+ * | `surface.default`            | `bg-surface-default`        |
+ * | `surface.subtle`             | `bg-surface-subtle`         |
+ * | `surface.hover`              | `bg-surface-hover`          |
+ * | `border.default`             | `border-default`            |
+ * | `border.focus`               | `border-focus`              |
+ * | `border.muted`               | `border-muted`              |
+ *
+ * Returns `null` for depth-1 leaves (e.g. `mode`, `name` — not role-scoped)
+ * so metadata doesn't get flattened. The caller (`bakeFlat`) already filters
+ * non-hex leaves, but the rule also guards paths shorter than 2 segments.
+ */
+declare const defaultFlattenRule: FlattenRule;
+/**
+ * Populate flat hyphen-keys onto `theme` in-place by walking hex leaves and
+ * asking `rule` where each leaf should also live at the root.
+ *
+ * Both the nested and flat forms reference the SAME string (not copies) —
+ * `bakeFlat({...}).accent.bg === bakeFlat({...})["bg-accent"]`.
+ *
+ * `rule` defaults to {@link defaultFlattenRule} (channel-role-state).
+ * Rules returning `null` for a path skip that leaf — useful for suppressing
+ * metadata or implementing partial projections.
+ *
+ * The returned object is deep-frozen. The input object is mutated in place
+ * and returned; callers that want an unfrozen copy should `structuredClone`
+ * before calling.
+ *
+ * @param theme  nested POJO of hex-string leaves (plus optional metadata)
+ * @param rule   how to compute flat keys from nested paths
+ * @returns      the same object, with flat keys added and frozen
+ */
+declare function bakeFlat<T extends object>(theme: T, rule?: FlattenRule): T;
+//#endregion
+//#region packages/ansi/src/terminal-control.d.ts
+/**
+ * Enable mouse tracking with full hover support.
+ *
+ * Uses two modes:
+ * - **1003** (any-event tracking): Reports ALL mouse motion — clicks, drags, AND hover.
+ *   This is what makes onMouseEnter/onMouseLeave work. Without it, only clicks are reported.
+ * - **1006** (SGR encoding): Decimal coordinates with no 223-column limit.
+ *
+ * WARNING: Do NOT replace 1003 with 1000+1002. The xterm mouse modes form a hierarchy:
+ *   1000 = clicks only
+ *   1002 = clicks + drag (motion while button held)
+ *   1003 = clicks + drag + hover (ALL motion, even without button)
+ * Mode 1003 supersedes 1000 and 1002. Using 1000+1002 instead of 1003 silently
+ * disables hover — onMouseEnter/onMouseLeave stop firing with no error.
+ */
+declare function enableMouse(): string;
+/**
+ * Disable mouse tracking. Disables in reverse order of enabling.
+ */
+declare function disableMouse(): string;
+/**
+ * Enable the Kitty keyboard protocol (push mode).
+ *
+ * Sends CSI > flags u to opt into the specified modes.
+ * Supported by: Ghostty, Kitty, WezTerm, foot. Ignored by unsupported terminals.
+ *
+ * Flags are a bitfield:
+ *
+ * | Flag | Bit | Description                               |
+ * | ---- | --- | ----------------------------------------- |
+ * | 1    | 0   | Disambiguate escape codes                 |
+ * | 2    | 1   | Report event types (press/repeat/release)  |
+ * | 4    | 2   | Report alternate keys                     |
+ * | 8    | 3   | Report all keys as escape codes           |
+ * | 16   | 4   | Report associated text                    |
+ *
+ * @param flags Bitfield of Kitty keyboard flags
+ */
+declare function enableKittyKeyboard(flags?: number): string;
+/**
+ * Disable the Kitty keyboard protocol (pop mode stack).
+ * Sends CSI < u to restore the previous keyboard mode.
+ */
+declare function disableKittyKeyboard(): string;
+//#endregion
+//#region packages/ansi/src/style/style.d.ts
+/**
+ * Resolve a color value against a theme — the canonical token resolver.
+ *
+ * If the color starts with `$`, looks up the token in the theme.
+ * Supports `$primary`, `$surface-bg` (hyphens stripped), `$color0`–`$color15` (palette).
+ * Non-`$` strings pass through unchanged. Returns undefined if no theme or unknown token.
+ *
+ * Compatible with @silvery/theme's Theme type (or any object with string properties).
+ */
+declare function resolveThemeColor(name: string | undefined, theme: object | undefined): string | undefined;
+//#endregion
+//#region packages/ansi/src/theme/types.d.ts
+/**
+ * Core type definitions for the theme system.
+ *
+ * Two-layer architecture:
+ *   Layer 1: ColorScheme — 22 terminal colors (what schemes expose; auto-detectable)
+ *   Layer 2: Theme — ~33 semantic tokens (what UI apps consume)
+ *
+ * Pipeline: Scheme catalog → ColorScheme (22) → deriveTheme() → Theme (33)
+ */
+interface ColorScheme {
+  name?: string;
+  dark?: boolean;
+  primary?: string;
+  black: string;
+  red: string;
+  green: string;
+  yellow: string;
+  blue: string;
+  magenta: string;
+  cyan: string;
+  white: string;
+  brightBlack: string;
+  brightRed: string;
+  brightGreen: string;
+  brightYellow: string;
+  brightBlue: string;
+  brightMagenta: string;
+  brightCyan: string;
+  brightWhite: string;
+  foreground: string;
+  background: string;
+  cursorColor: string;
+  cursorText: string;
+  selectionBackground: string;
+  selectionForeground: string;
+}
+declare const COLOR_SCHEME_FIELDS: readonly ["black", "red", "green", "yellow", "blue", "magenta", "cyan", "white", "brightBlack", "brightRed", "brightGreen", "brightYellow", "brightBlue", "brightMagenta", "brightCyan", "brightWhite", "foreground", "background", "cursorColor", "cursorText", "selectionBackground", "selectionForeground"];
+interface Theme$1 {
+  name: string;
+  bg: string;
+  fg: string;
+  muted: string;
+  mutedbg: string;
+  surface: string;
+  surfacebg: string;
+  popover: string;
+  popoverbg: string;
+  inverse: string;
+  inversebg: string;
+  cursor: string;
+  cursorbg: string;
+  selection: string;
+  selectionbg: string;
+  primary: string;
+  primaryfg: string;
+  secondary: string;
+  secondaryfg: string;
+  accent: string;
+  accentfg: string;
+  error: string;
+  errorfg: string;
+  warning: string;
+  warningfg: string;
+  success: string;
+  successfg: string;
+  info: string;
+  infofg: string;
+  border: string;
+  inputborder: string;
+  focusborder: string;
+  link: string;
+  disabledfg: string;
+  palette: string[];
+  brand: string;
+  /** Kebab key for $brand-hover. Hover lightness shift (+0.04L OKLCH). */
+  "brand-hover": string;
+  /** Kebab key for $brand-active. Active lightness shift (+0.08L OKLCH). */
+  "brand-active": string;
+  /** Kebab key for $primary-hover. */
+  "primary-hover": string;
+  /** Kebab key for $primary-active. */
+  "primary-active": string;
+  /** Kebab key for $accent-hover. */
+  "accent-hover": string;
+  /** Kebab key for $accent-active. */
+  "accent-active": string;
+  /** Kebab key for $fg-hover. */
+  "fg-hover": string;
+  /** Kebab key for $fg-active. */
+  "fg-active": string;
+  /** Kebab key for $bg-selected-hover. */
+  "bg-selected-hover": string;
+  /** Kebab key for $bg-surface-hover. */
+  "bg-surface-hover": string;
+  red: string;
+  orange: string;
+  yellow: string;
+  green: string;
+  teal: string;
+  blue: string;
+  purple: string;
+  pink: string;
+  /**
+   * Named typography variants — resolved by `<Text variant="h1">`.
+   *
+   * Each variant is a bundle of visual defaults (color, bold, italic, dim,
+   * underlineStyle). Caller props always win over variant values — the variant
+   * is the *default*, not an override.
+   *
+   * Apps extend variants via:
+   * ```tsx
+   * <ThemeProvider tokens={{ variants: { hero: { color: "$brand", bold: true } } }}>
+   * ```
+   */
+  variants: Record<string, Variant$1>;
+}
+/**
+ * Metadata describing how the active color scheme was determined.
+ *
+ * Returned by `detectScheme()` and surfaced at runtime via `useActiveScheme()`.
+ * Lets apps log how the theme was detected ("catppuccin-mocha at 87% confidence via
+ * fingerprint") or render a debug badge without re-running detection.
+ *
+ * @example
+ * ```tsx
+ * const scheme = useActiveScheme()
+ * if (scheme?.source === "fingerprint") {
+ *   console.log(`detected ${scheme.matchedName} at ${Math.round((scheme.confidence ?? 0) * 100)}%`)
+ * }
+ * ```
+ */
+interface ActiveScheme {
+  /** Scheme name pulled from Theme.name or the override. */
+  name: string;
+  /** How the active theme was determined. */
+  source: "probe" | "fingerprint" | "fallback" | "override";
+  /** Confidence [0,1] — only meaningful for "fingerprint" source. */
+  confidence?: number;
+  /** Catalog scheme name matched (only for "fingerprint" source). */
+  matchedName?: string;
+}
+type AnsiPrimary = "yellow" | "cyan" | "magenta" | "green" | "red" | "blue" | "white";
+type HueName = "red" | "orange" | "yellow" | "green" | "teal" | "blue" | "purple" | "pink";
+/**
+ * A typography variant — a named bundle of visual properties that can be
+ * applied to a Text component via `variant="h1"`. The variant acts as a
+ * *default*: caller props always win over variant values.
+ *
+ * Color values follow the same syntax as `TextColor` — `$token` strings,
+ * hex values, ANSI names, or any string accepted by the color system.
+ */
+interface Variant$1 {
+  color?: string;
+  backgroundColor?: string;
+  bold?: boolean;
+  italic?: boolean;
+  dim?: boolean;
+  underlineStyle?: "single" | "double" | "curly" | "dotted" | "dashed";
+}
+//#endregion
+//#region packages/ansi/src/theme/derive.d.ts
+interface ThemeAdjustment {
+  token: string;
+  from: string;
+  to: string;
+  against: string;
+  target: number;
+  ratioBefore: number;
+  ratioAfter: number;
+}
+declare function deriveTheme$1(palette: ColorScheme, mode?: "ansi16" | "truecolor", adjustments?: ThemeAdjustment[]): Theme$1;
+//#endregion
+//#region packages/ansi/src/theme/orchestrator.d.ts
+/** How the final scheme was decided. */
+type DetectSource = "override" | "fingerprint" | "probed" | "bg-mode" | "fallback";
+/** Where each slot's value came from. */
+type SlotSource = "probed" | "catalog" | "fallback";
+interface DetectSchemeResult {
+  /** The resolved 22-slot color scheme. */
+  scheme: ColorScheme;
+  /** The derived, validated Theme (via loadTheme). */
+  theme: Theme$1;
+  /** How the scheme was determined overall. */
+  source: DetectSource;
+  /** 0–1 confidence heuristic (exact override = 1, fingerprint = match score, fallback = 0). */
+  confidence: number;
+  /** Per-slot provenance. Keys are ColorScheme field names. */
+  slotSources: Partial<Record<keyof ColorScheme, SlotSource>>;
+  /** If fingerprint matched, the catalog scheme name. */
+  matchedName?: string;
+}
+interface DetectSchemeOptions {
+  /** Explicit override — if provided, skips all probing. */
+  override?: ColorScheme;
+  /** Catalog to fingerprint against. If empty or undefined, skip fingerprinting. */
+  catalog?: readonly ColorScheme[];
+  /** OSC probe timeout (ms). Default 150. */
+  timeoutMs?: number;
+  /** Force dark/light inference when no bg is probed. */
+  darkFallback?: boolean;
+  /**
+   * Apply strict invariant validation to the loaded Theme. Default `lenient`.
+   * See `loadTheme`'s `enforce` parameter.
+   */
+  enforce?: "strict" | "lenient" | "off";
+  /** Add WCAG contrast check to the invariant validation. Default `false`. */
+  wcag?: boolean;
+}
+//#endregion
+//#region packages/ansi/src/theme/tokens.d.ts
+/**
+ * Built-in variant names — the standard typography presets shipped by silvery.
+ * These are the default keys in `Theme.variants`.
+ */
+type VariantName = "h1" | "h2" | "h3" | "body" | "body-muted" | "fine-print" | "strong" | "em" | "link" | "key" | "code" | "kbd";
+/**
+ * Any variant name — built-in or app-defined. The `(string & {})` tail is the
+ * Tailwind trick: preserves IDE autocomplete for the literal union while still
+ * accepting any runtime string value.
+ */
+type KnownVariant = VariantName | (string & {});
+//#endregion
+//#region packages/ansi/src/theme/detect.d.ts
+interface DetectedScheme {
+  fg: string | null;
+  bg: string | null;
+  ansi: (string | null)[];
+  dark: boolean;
+  palette: Partial<ColorScheme>;
+}
+declare function detectTerminalScheme(timeoutMs?: number): Promise<DetectedScheme | null>;
+interface DetectThemeOptions {
+  /** Fallback ColorScheme when detection fails or returns partial data.
+   * Detected colors override matching fallback fields.
+   * When omitted, defaults based on dark/light detection:
+   *   dark  → `fallbackDark` (if set) or built-in defaultDarkScheme
+   *   light → `fallbackLight` (if set) or built-in defaultLightScheme */
+  fallback?: ColorScheme;
+  /** Fallback for dark terminals (overrides `fallback` for dark mode). */
+  fallbackDark?: ColorScheme;
+  /** Fallback for light terminals (overrides `fallback` for light mode). */
+  fallbackLight?: ColorScheme;
+  /** Timeout per OSC query in ms (default 150). */
+  timeoutMs?: number;
+  /** Terminal capabilities (from detectTerminalCaps). When provided:
+   * - colorLevel "none"/"basic" skips OSC detection and returns ANSI 16 theme
+   * - darkBackground informs fallback selection when detection fails */
+  caps?: {
+    colorLevel?: string;
+    darkBackground?: boolean;
+  };
+}
+//#endregion
+//#region packages/ansi/src/osc-palette.d.ts
+/**
+ * OSC 4 Terminal Color Palette Query/Set — pure ANSI protocol.
+ */
+declare function queryPaletteColor(index: number, write: (data: string) => void): void;
+declare function queryMultiplePaletteColors(indices: number[], write: (data: string) => void): void;
+declare function setPaletteColor(index: number, color: string, write: (data: string) => void): void;
+declare function parsePaletteResponse(input: string): {
+  index: number;
+  color: string;
+} | null;
+//#endregion
+//#region packages/ansi/src/osc-colors.d.ts
+/**
+ * OSC 10/11/12 Terminal Color Queries — pure ANSI protocol.
+ */
+declare function queryForegroundColor(write: (data: string) => void, read: (timeoutMs: number) => Promise<string | null>, timeoutMs?: number): Promise<string | null>;
+declare function queryBackgroundColor(write: (data: string) => void, read: (timeoutMs: number) => Promise<string | null>, timeoutMs?: number): Promise<string | null>;
+declare function queryCursorColor(write: (data: string) => void, read: (timeoutMs: number) => Promise<string | null>, timeoutMs?: number): Promise<string | null>;
+declare function setForegroundColor(write: (data: string) => void, color: string): void;
+declare function setBackgroundColor(write: (data: string) => void, color: string): void;
+declare function setCursorColor(write: (data: string) => void, color: string): void;
+declare function resetForegroundColor(write: (data: string) => void): void;
+declare function resetBackgroundColor(write: (data: string) => void): void;
+declare function resetCursorColor(write: (data: string) => void): void;
+declare function detectColorScheme(write: (data: string) => void, read: (timeoutMs: number) => Promise<string | null>, timeoutMs?: number): Promise<"light" | "dark" | null>;
+//#endregion
+//#region packages/ansi/src/theme/generate.d.ts
+/**
+ * Generate a complete ANSI 16 theme from a primary color + dark/light preference.
+ *
+ * All token values are ANSI color names (e.g. "yellow", "blueBright").
+ */
+declare function generateTheme$1(primary: AnsiPrimary, dark: boolean): Theme$1;
+//#endregion
+//#region packages/theme/src/generate.d.ts
+/**
+ * Generate a complete ANSI 16 theme from a primary color + dark/light preference.
+ *
+ * All token values are hex strings (e.g. "#808000" for yellow).
+ * Terminal rendering quantizes these to 4-bit ANSI codes at paint time
+ * when colorLevel === "basic".
+ */
+declare function generateTheme(primary: AnsiPrimary, dark: boolean): Theme$1;
+//#endregion
+//#region packages/theme/src/generators.d.ts
+/** Find which hue slot the primary color best matches by OKLCH hue angle proximity. */
+declare function assignPrimaryToSlot(primary: string): HueName;
+/**
+ * Generate a ColorScheme from a Base16 YAML scheme.
+ *
+ * Maps base00–base0F to ANSI palette colors, derives special colors.
+ */
+declare function fromBase16(yamlOrJson: string): ColorScheme;
+interface FromColorsOptions {
+  /** Background color (infers dark/light). */
+  background?: string;
+  /** Foreground/text color. Generated if omitted. */
+  foreground?: string;
+  /** Primary accent color. Generated if omitted. */
+  primary?: string;
+  /** Force dark mode. */
+  dark?: boolean;
+  /** Theme name. */
+  name?: string;
+}
+/**
+ * Generate a full ColorScheme from 1-3 hex colors.
+ *
+ * At minimum, provide `background` or `primary`. Missing colors are
+ * generated via surface ramp (from bg) and hue rotation (from primary).
+ */
+declare function fromColors(opts: FromColorsOptions): ColorScheme;
+/**
+ * Look up a built-in palette by name.
+ *
+ * @returns The ColorScheme, or undefined if not found.
+ */
+declare function fromPreset(name: string): ColorScheme | undefined;
+//#endregion
+//#region packages/theme/src/builder.d.ts
+interface ThemeBuilder {
+  /** Set background color. */
+  bg(color: string): ThemeBuilder;
+  /** Set foreground color. */
+  fg(color: string): ThemeBuilder;
+  /** Set primary accent color. */
+  primary(color: string): ThemeBuilder;
+  /** Alias for `.primary()`. */
+  accent(color: string): ThemeBuilder;
+  /** Force dark mode. */
+  dark(): ThemeBuilder;
+  /** Force light mode. */
+  light(): ThemeBuilder;
+  /** Set any palette color by name. */
+  color(name: keyof Omit<ColorScheme, "name" | "dark">, value: string): ThemeBuilder;
+  /** Set full palette at once. */
+  palette(p: ColorScheme): ThemeBuilder;
+  /** Load a built-in palette by name. */
+  preset(name: string): ThemeBuilder;
+  /** Derive the final Theme from accumulated state. */
+  build(): Theme$1;
+}
+/** Create a chainable theme builder. */
+declare function createTheme(): ThemeBuilder;
+/**
+ * Quick theme from a primary color or color name.
+ *
+ * @example
+ * ```typescript
+ * quickTheme('#EBCB8B', 'dark')  // yellow primary, dark mode
+ * quickTheme('blue')              // blue primary, default dark
+ * ```
+ */
+declare function quickTheme(primaryOrHex: string, mode?: "dark" | "light"): Theme$1;
+/**
+ * Create a theme from a built-in preset name.
+ *
+ * @example
+ * ```typescript
+ * presetTheme('catppuccin-mocha')
+ * presetTheme('nord')
+ * ```
+ */
+declare function presetTheme(name: string): Theme$1;
+//#endregion
+//#region packages/theme/src/auto-generate.d.ts
+/**
+ * Generate a complete Theme from a single primary color.
+ *
+ * Derives a full ColorScheme using OKLCH color manipulation:
+ * - Background/foreground from lightness endpoints using the primary's hue
+ * - Complementary and analogous accent colors from hue rotation
+ * - Surface ramp from bg lightness offsets
+ * - Status colors (error, warning, success, info) from standard hue positions
+ *
+ * @param primaryColor - A hex color string (e.g. "#5E81AC")
+ * @param mode - "dark" or "light" theme mode
+ * @returns A complete Theme with all 33 semantic tokens
+ *
+ * @example
+ * ```typescript
+ * const theme = autoGenerateTheme("#5E81AC", "dark")
+ * // Generates a full dark theme with blue as the primary accent
+ *
+ * const light = autoGenerateTheme("#E06C75", "light")
+ * // Generates a full light theme with red/rose as the primary accent
+ * ```
+ */
+declare function autoGenerateTheme(primaryColor: string, mode: "dark" | "light"): Theme$1;
+//#endregion
+//#region packages/theme/src/validate.d.ts
+/** Validation result from validateColorScheme(). */
+interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+/**
+ * Validate a ColorScheme.
+ *
+ * Checks:
+ * - All 22 color fields are present and non-empty hex strings
+ * - Warns on low-contrast foreground/background combinations
+ */
+declare function validateColorScheme(p: ColorScheme): ValidationResult;
+//#endregion
+//#region packages/theme/src/validate-theme.d.ts
+/**
+ * Theme validation — checks that all required semantic tokens are present.
+ *
+ * Complements validateColorScheme() which validates the lower-level
+ * ColorScheme. This validates the derived Theme object.
+ */
+/** All 33 required semantic token keys on Theme (excludes `name` and `palette`). */
+declare const THEME_TOKEN_KEYS: readonly string[];
+/** Result of theme validation. */
+interface ThemeValidationResult {
+  /** Whether the theme has all required tokens. */
+  valid: boolean;
+  /** Token keys that are required but missing or empty. */
+  missing: string[];
+  /** Token keys that exist on the object but are not recognized theme tokens. */
+  extra: string[];
+}
+/**
+ * Validate a Theme object — check that all required tokens are present.
+ *
+ * @param theme - The theme object to validate
+ * @returns Validation result with missing and extra token lists
+ *
+ * @example
+ * ```typescript
+ * const result = validateTheme(myTheme)
+ * if (!result.valid) {
+ *   console.log("Missing tokens:", result.missing)
+ * }
+ * ```
+ */
+declare function validateTheme(theme: Record<string, unknown>): ThemeValidationResult;
+//#endregion
+//#region packages/theme/src/alias.d.ts
+/**
+ * Resolve all token aliases in a theme.
+ *
+ * Token values that start with `$` are treated as references to other tokens.
+ * Alias chains are followed until a concrete (non-$) value is reached.
+ * Circular references are detected via a depth limit and left unresolved.
+ *
+ * @param theme - A theme-like object where values may reference other tokens via `$name`
+ * @returns A new object with all aliases resolved to concrete values
+ *
+ * @example
+ * ```typescript
+ * const themed = resolveAliases({
+ *   ...baseTheme,
+ *   button: "$primary",      // resolves to the value of 'primary'
+ *   buttonHover: "$button",  // chain: buttonHover -> button -> primary -> hex
+ * })
+ * ```
+ */
+declare function resolveAliases(theme: Record<string, string>): Record<string, string>;
+/**
+ * Resolve a single alias value against a Theme.
+ *
+ * Useful for resolving individual values without processing the entire theme.
+ *
+ * @param value - The value to resolve (may be "$tokenName" or a concrete value)
+ * @param theme - The theme to resolve against
+ * @returns The resolved concrete value
+ */
+declare function resolveTokenAlias(value: string, theme: Theme$1): string;
+//#endregion
+//#region packages/theme/src/css.d.ts
+/**
+ * Convert a Theme to CSS custom properties.
+ *
+ * Token names mirror Sterling's flat grammar with a `--` prefix:
+ *   - `bg-surface-default` → `--bg-surface-default`
+ *   - `fg-accent` → `--fg-accent`
+ *   - `border-focus` → `--border-focus`
+ *   - Palette entries: `--color0` through `--color15`
+ *
+ * @param theme - The theme to convert (Sterling flat tokens must be populated)
+ * @returns A record mapping CSS custom property names to color values
+ *
+ * @example
+ * ```typescript
+ * const vars = themeToCSSVars(myTheme)
+ * // { "--bg-surface-default": "#1E1E2E", "--fg-accent": "#F9E2AF", ... }
+ *
+ * // Apply to an element:
+ * Object.assign(element.style, vars)
+ * ```
+ */
+declare function themeToCSSVars(theme: Theme$1): Record<string, string>;
+//#endregion
+//#region packages/theme/src/import/types.d.ts
+/**
+ * Base16 scheme type — the 16-color format used by hundreds of community themes.
+ *
+ * @see https://github.com/chriskempson/base16
+ */
+/** A parsed Base16 color scheme. All hex values are WITHOUT `#` prefix. */
+interface Base16Scheme {
+  scheme: string;
+  author: string;
+  base00: string;
+  base01: string;
+  base02: string;
+  base03: string;
+  base04: string;
+  base05: string;
+  base06: string;
+  base07: string;
+  base08: string;
+  base09: string;
+  base0A: string;
+  base0B: string;
+  base0C: string;
+  base0D: string;
+  base0E: string;
+  base0F: string;
+}
+//#endregion
+//#region packages/theme/src/import/base16.d.ts
+/**
+ * Import a Base16 YAML (or JSON) scheme into a ColorScheme.
+ *
+ * Mapping:
+ *   base00 → background, base01 → brightBlack, base02 → selectionBackground,
+ *   base03 → white (muted fg), base05 → foreground/brightWhite,
+ *   base08 → red, base09 → brightRed, base0A → yellow,
+ *   base0B → green, base0C → cyan, base0D → blue, base0E → magenta,
+ *   base0F → brightMagenta.
+ *
+ * Bright color variants are derived by brightening normals.
+ * `dark` is inferred from base00 luminance.
+ */
+declare function importBase16(yamlOrJson: string): ColorScheme;
+//#endregion
+//#region packages/theme/src/export/base16.d.ts
+/**
+ * Export a ColorScheme to Base16 YAML format.
+ *
+ * Mapping:
+ *   background → base00, brightBlack → base01, selectionBackground → base02,
+ *   white → base03, (interpolated) → base04, foreground → base05,
+ *   (interpolated) → base06, (interpolated) → base07,
+ *   red → base08, brightRed → base09, yellow → base0A, green → base0B,
+ *   cyan → base0C, blue → base0D, magenta → base0E, brightMagenta → base0F.
+ */
+declare function exportBase16(palette: ColorScheme): string;
+//#endregion
+//#region packages/theme/src/schemes/catppuccin.d.ts
+/** Catppuccin Mocha — the classic dark variant. */
+declare const catppuccinMocha: ColorScheme;
+/** Catppuccin Frappe — muted dark variant. */
+declare const catppuccinFrappe: ColorScheme;
+/** Catppuccin Macchiato — warm dark variant. */
+declare const catppuccinMacchiato: ColorScheme;
+/** Catppuccin Latte — the light variant. */
+declare const catppuccinLatte: ColorScheme;
+//#endregion
+//#region packages/theme/src/schemes/nord.d.ts
+/** Nord — the classic dark arctic theme. */
+declare const nord: ColorScheme;
+//#endregion
+//#region packages/theme/src/schemes/dracula.d.ts
+/** Dracula — vibrant dark theme. */
+declare const dracula: ColorScheme;
+//#endregion
+//#region packages/theme/src/schemes/solarized.d.ts
+/** Solarized Dark — Ethan Schoonover's classic dark variant. */
+declare const solarizedDark: ColorScheme;
+/** Solarized Light — Ethan Schoonover's classic light variant. */
+declare const solarizedLight: ColorScheme;
+//#endregion
+//#region packages/theme/src/schemes/tokyo-night.d.ts
+/** Tokyo Night — the default dark variant. */
+declare const tokyoNight: ColorScheme;
+/** Tokyo Night Storm — slightly lighter background. */
+declare const tokyoNightStorm: ColorScheme;
+/** Tokyo Night Day — the light variant. */
+declare const tokyoNightDay: ColorScheme;
+//#endregion
+//#region packages/theme/src/schemes/one-dark.d.ts
+/** One Dark — the classic Atom editor theme. */
+declare const oneDark: ColorScheme;
+//#endregion
+//#region packages/theme/src/schemes/gruvbox.d.ts
+/** Gruvbox Dark — warm retro dark theme. */
+declare const gruvboxDark: ColorScheme;
+/** Gruvbox Light — warm retro light theme. */
+declare const gruvboxLight: ColorScheme;
+//#endregion
+//#region packages/theme/src/schemes/rose-pine.d.ts
+/** Rosé Pine — the main dark variant. */
+declare const rosePine: ColorScheme;
+/** Rosé Pine Moon — slightly lighter dark variant. */
+declare const rosePineMoon: ColorScheme;
+/** Rosé Pine Dawn — the light variant. */
+declare const rosePineDawn: ColorScheme;
+//#endregion
+//#region packages/theme/src/schemes/kanagawa.d.ts
+/** Kanagawa Wave — the default dark variant, inspired by "The Great Wave off Kanagawa". */
+declare const kanagawaWave: ColorScheme;
+/** Kanagawa Dragon — a muted, earthy dark variant. */
+declare const kanagawaDragon: ColorScheme;
+/** Kanagawa Lotus — the light variant, inspired by lotus flowers. */
+declare const kanagawaLotus: ColorScheme;
+//#endregion
+//#region packages/theme/src/schemes/everforest.d.ts
+/** Everforest Dark — warm green-based dark theme (medium background). */
+declare const everforestDark: ColorScheme;
+/** Everforest Light — warm green-based light theme (medium background). */
+declare const everforestLight: ColorScheme;
+//#endregion
+//#region packages/theme/src/schemes/monokai.d.ts
+/** Monokai Classic — the original Sublime Text Monokai colors. */
+declare const monokai: ColorScheme;
+/** Monokai Pro — the modern, refined Monokai with balanced colors. */
+declare const monokaiPro: ColorScheme;
+//#endregion
+//#region packages/theme/src/schemes/snazzy.d.ts
+/** Snazzy — clean dark theme by Sindre Sorhus. */
+declare const snazzy: ColorScheme;
+//#endregion
+//#region packages/theme/src/schemes/material.d.ts
+/** Material Darker — the deep dark Material variant. */
+declare const materialDark: ColorScheme;
+/** Material Lighter — the light Material variant. */
+declare const materialLight: ColorScheme;
+//#endregion
+//#region packages/theme/src/schemes/palenight.d.ts
+/** Palenight — the soft, purple-tinted Material dark variant. */
+declare const palenight: ColorScheme;
+//#endregion
+//#region packages/theme/src/schemes/ayu.d.ts
+/** Ayu Dark — deep dark variant with warm accents. */
+declare const ayuDark: ColorScheme;
+/** Ayu Mirage — balanced dark variant with softer contrast. */
+declare const ayuMirage: ColorScheme;
+/** Ayu Light — clean light variant. */
+declare const ayuLight: ColorScheme;
+//#endregion
+//#region packages/theme/src/schemes/nightfox.d.ts
+/** Nightfox — dark blue-toned variant. */
+declare const nightfox: ColorScheme;
+/** Dawnfox — warm light variant inspired by Rose Pine Dawn. */
+declare const dawnfox: ColorScheme;
+//#endregion
+//#region packages/theme/src/schemes/horizon.d.ts
+/** Horizon — warm dark variant with vivid accents. */
+declare const horizon: ColorScheme;
+//#endregion
+//#region packages/theme/src/schemes/moonfly.d.ts
+/** Moonfly — dark charcoal theme. */
+declare const moonfly: ColorScheme;
+//#endregion
+//#region packages/theme/src/schemes/nightfly.d.ts
+/** Nightfly — midnight-blue dark theme. */
+declare const nightfly: ColorScheme;
+//#endregion
+//#region packages/theme/src/schemes/oxocarbon.d.ts
+/** Oxocarbon Dark — IBM Carbon-inspired dark variant. */
+declare const oxocarbonDark: ColorScheme;
+/** Oxocarbon Light — IBM Carbon-inspired light variant. */
+declare const oxocarbonLight: ColorScheme;
+//#endregion
+//#region packages/theme/src/schemes/sonokai.d.ts
+/** Sonokai — vivid dark theme with Monokai-inspired accents. */
+declare const sonokai: ColorScheme;
+//#endregion
+//#region packages/theme/src/schemes/edge.d.ts
+/** Edge Dark — clean dark variant with balanced accents. */
+declare const edgeDark: ColorScheme;
+/** Edge Light — clean, readable light variant. */
+declare const edgeLight: ColorScheme;
+//#endregion
+//#region packages/theme/src/schemes/modus.d.ts
+/** Modus Vivendi — elegant dark theme with maximum legibility. */
+declare const modusVivendi: ColorScheme;
+/** Modus Operandi — elegant light theme with maximum legibility. */
+declare const modusOperandi: ColorScheme;
+//#endregion
+//#region packages/theme/src/schemes/index.d.ts
+/**
+ * Dark ANSI 16 theme — hex-valued, derived from the default dark scheme.
+ * All token values are hex strings (no ANSI slot names).
+ * Terminal rendering quantizes hex to 4-bit ANSI codes when colorLevel === "basic".
+ *
+ * Sterling flat tokens (`bg-surface-subtle`, `fg-on-accent`, `border-focus`, …)
+ * are baked in at construction — consumers can read either legacy fields or
+ * Sterling flat keys off the same Theme object.
+ */
+declare const ansi16DarkTheme: Theme$1;
+/**
+ * Light ANSI 16 theme — hex-valued, derived from the default light scheme.
+ * All token values are hex strings (no ANSI slot names).
+ * Terminal rendering quantizes hex to 4-bit ANSI codes when colorLevel === "basic".
+ *
+ * Sterling flat tokens baked in at construction.
+ */
+declare const ansi16LightTheme: Theme$1;
+/** Dark truecolor theme — derived from Nord. Sterling flat tokens baked in. */
+declare const defaultDarkTheme: Theme$1;
+/** Light truecolor theme — derived from Catppuccin Latte. Sterling flat tokens baked in. */
+declare const defaultLightTheme: Theme$1;
+/** All built-in ColorScheme definitions (70+ palettes). */
+declare const builtinPalettes: Record<string, ColorScheme>;
+/** All built-in themes, indexed by name (includes backward-compat aliases). */
+declare const builtinThemes: Record<string, Theme$1>;
+/** Resolve a theme by name. Defaults to dark-ansi16. */
+declare function getThemeByName(name?: string): Theme$1;
+/** Resolve a palette by name. Returns undefined if not found. */
+declare function getSchemeByName(name: string): ColorScheme | undefined;
+//#endregion
+//#region packages/theme/src/detect.d.ts
+/**
+ * Detect the terminal's palette and return a Sterling-aware Theme.
+ *
+ * Identical to `@silvery/ansi`'s `detectTheme` but every returned theme has
+ * Sterling flat tokens baked in via `inlineSterlingTokens`.
+ */
+declare function detectTheme(opts?: DetectThemeOptions): Promise<Theme$1>;
+//#endregion
+//#region packages/theme/src/sterling/types.d.ts
+/**
+ * Surface-only state pair: only `bg` varies by state. Used by the status
+ * roles (`info`, `success`, `warning`, `error`) where state variants are
+ * meaningful only for surfaces (filled bg), never for text.
+ *
+ * Text tokens on status roles don't hover — `fg-error` is a status color,
+ * not an interactive link. Keeping `fg.hover` / `fg.active` on those roles
+ * invited algorithmic over-generation that produced illegible results
+ * (e.g. catppuccin-frappe `warning.active.fg` collapsing to `#FFFFFF`).
+ */
+interface BgStatePair {
+  readonly bg: string;
+}
+/**
+ * Interactive (link-like) state pair: both `fg` and `bg` vary by state.
+ * Used by `accent` — the canonical interactive-text role.
+ */
+interface StatePair {
+  readonly fg: string;
+  readonly bg: string;
+}
+/**
+ * A status role — fg, bg, and `fgOn` (text color to draw when rendering ON
+ * a filled bg of this role). State variants apply to SURFACE (bg) only;
+ * text-color state variants are reserved for link-like roles (`accent`).
+ */
+interface InteractiveRole {
+  /** Foreground hex — use for text/icon in this role. */
+  readonly fg: string;
+  /** Background hex — use as fill for emphasis. */
+  readonly bg: string;
+  /** Foreground to use when drawing ON `bg` (contrast-picked). */
+  readonly fgOn: string;
+  /** Hover state — surface only (adaptive ±L shift on bg). */
+  readonly hover: BgStatePair;
+  /** Active (pressed) state — surface only (adaptive ±L shift on bg). */
+  readonly active: BgStatePair;
+}
+/**
+ * Accent — the canonical link-like interactive-text role. Has everything
+ * `InteractiveRole` does PLUS a focus-ring border AND `fg.hover` /
+ * `fg.active` text-color state variants (link hover treatments).
+ */
+interface AccentRole {
+  /** Foreground hex — use for text/icon in accent. */
+  readonly fg: string;
+  /** Background hex — use as fill for emphasis. */
+  readonly bg: string;
+  /** Foreground to use when drawing ON `bg` (contrast-picked). */
+  readonly fgOn: string;
+  /** Border color for focus rings using this accent. */
+  readonly border: string;
+  /** Hover state — both fg (link hover) and bg (surface hover). */
+  readonly hover: StatePair;
+  /** Active (pressed) state — both fg and bg. */
+  readonly active: StatePair;
+}
+/** Surface hierarchy — `default` is the canvas, subtle/raised/overlay stack upward. */
+interface SurfaceRole {
+  readonly default: string;
+  readonly subtle: string;
+  readonly raised: string;
+  readonly overlay: string;
+  readonly hover: string;
+}
+/** Border roles — `focus` is the focus-ring color; `default` is normal rule line. */
+interface BorderRole {
+  readonly default: string;
+  readonly focus: string;
+  readonly muted: string;
+}
+/** Cursor colors. */
+interface CursorRole {
+  readonly fg: string;
+  readonly bg: string;
+}
+/** Muted role — lower-emphasis text/bg for deemphasized content. */
+interface MutedRole {
+  readonly fg: string;
+  readonly bg: string;
+}
+/**
+ * The nested, programmatic form of a Theme. All leaf values are hex strings.
+ * Reached via `theme.accent.bg`, `theme.surface.raised`, etc.
+ */
+interface Roles {
+  readonly accent: AccentRole;
+  readonly info: InteractiveRole;
+  readonly success: InteractiveRole;
+  readonly warning: InteractiveRole;
+  readonly error: InteractiveRole;
+  readonly muted: MutedRole;
+  readonly surface: SurfaceRole;
+  readonly border: BorderRole;
+  readonly cursor: CursorRole;
+}
+/**
+ * Every flat hyphen-key that Sterling emits. String-literal union so that
+ * `theme["bg-accent"]` is type-checked and typos fail the compile.
+ *
+ * Grammar: `prefix-role[-state]` or `prefix-on-role` or `prefix-role-kind[-state]`.
+ * (See design-system.md §"Flattening rule".)
+ */
+type FlatToken = "bg-surface-default" | "bg-surface-subtle" | "bg-surface-raised" | "bg-surface-overlay" | "bg-surface-hover" | "border-default" | "border-focus" | "border-muted" | "fg-cursor" | "bg-cursor" | "fg-muted" | "bg-muted" | "fg-accent" | "bg-accent" | "fg-on-accent" | "fg-accent-hover" | "bg-accent-hover" | "fg-accent-active" | "bg-accent-active" | "border-accent" | "fg-info" | "bg-info" | "fg-on-info" | "bg-info-hover" | "bg-info-active" | "fg-success" | "bg-success" | "fg-on-success" | "bg-success-hover" | "bg-success-active" | "fg-warning" | "bg-warning" | "fg-on-warning" | "bg-warning-hover" | "bg-warning-active" | "fg-error" | "bg-error" | "fg-on-error" | "bg-error-hover" | "bg-error-active";
+/** The flat projection — every FlatToken maps to a hex string. */
+type FlatTokens = { readonly [K in FlatToken]: string };
+/**
+ * Per-token record of HOW a token was derived. Populated only when the
+ * derivation is called with `{ trace: true }`. Used by the Sterling
+ * storybook to visualize derivation rules.
+ */
+interface DerivationStep {
+  /** Token path (e.g. `"accent.hover.bg"` or flat `"bg-accent-hover"`). */
+  readonly token: string;
+  /** Human-readable rule name (e.g. `"OKLCH +0.04L on accent.bg"`). */
+  readonly rule: string;
+  /** Input hex(es) the rule operated on. */
+  readonly inputs: readonly string[];
+  /** Output hex. */
+  readonly output: string;
+  /** If auto-lift adjusted this token, the original value before adjustment. */
+  readonly liftedFrom?: string;
+  /** If pinned by scheme author, true. */
+  readonly pinned?: boolean;
+}
+type DerivationTrace = readonly DerivationStep[];
+/**
+ * Categorical color ring — 8 harmonious hues for tagging, chart series,
+ * calendar categories, priority levels — any CATEGORICAL color that isn't
+ * stateful. ensureContrast-adjusted against bg at derivation time. Consumers
+ * access these via `$red`, `$orange`, …, `$pink` or direct field access.
+ *
+ * Distinguish from:
+ *   - `$color0..$color15`         — raw terminal ANSI (user's theme verbatim)
+ *   - `$error/$warning/$success`  — semantic state (communicates meaning)
+ *   - `$brand`                    — app identity anchor (one color)
+ */
+interface CategoricalHues {
+  readonly red: string;
+  readonly orange: string;
+  readonly yellow: string;
+  readonly green: string;
+  readonly teal: string;
+  readonly blue: string;
+  readonly purple: string;
+  readonly pink: string;
+}
+/**
+ * The canonical Sterling Theme — Sterling flat tokens + nested roles on the
+ * same object, plus a small surface of non-token metadata and runtime
+ * convenience fields the framework depends on:
+ *
+ * Two access paths for every hex leaf:
+ *   - Nested:  `theme.accent.hover.bg`
+ *   - Flat:    `theme["bg-accent-hover"]`
+ *   Both paths reference the same string (not copies). The object is frozen
+ *   after derivation (see `flatten.ts`).
+ *
+ * Non-token metadata:
+ *   - `name` — scheme display name (if derived from a named scheme)
+ *   - `mode` — light/dark
+ *   - `derivationTrace` — optional; present only when `{ trace: true }` was passed
+ *   - `variants` — typography preset bundles (h1, body, code, …) resolved by
+ *     `<Text variant="…">`
+ *   - `palette` — 16-slot ANSI catalog used by `$color0` … `$color15`
+ *   - categorical hues (`red`, `orange`, `yellow`, `green`, `teal`, `blue`,
+ *     `purple`, `pink`) — hex strings for categorical UI
+ *
+ * The nested roles (`accent`, `muted`, `surface`, `border`, `cursor`, plus
+ * the status roles `info`/`success`/`warning`/`error`) are authoritative for
+ * stateful tokens. Legacy flat hex aliases for these roles (`theme.primary`,
+ * `theme.muted`, `theme.accent` as strings) are emitted as runtime
+ * conveniences via the scheme-builder but are not part of this type — they
+ * were deleted in silvery 0.19.0.
+ */
+type Theme = FlatTokens & Roles & {
+  readonly name?: string;
+  readonly mode: "light" | "dark";
+  readonly derivationTrace?: DerivationTrace;
+  readonly variants: Record<string, Variant>;
+  readonly palette: readonly string[];
+} & CategoricalHues;
+/**
+ * A typography variant — a named bundle of visual properties applied to a
+ * Text component via `variant="h1"`. The variant acts as a *default*: caller
+ * props always win over variant values.
+ *
+ * Color values follow the same syntax as `TextColor` — `$token` strings, hex
+ * values, ANSI names, or any string accepted by the color system.
+ */
+interface Variant {
+  readonly color?: string;
+  readonly backgroundColor?: string;
+  readonly bold?: boolean;
+  readonly italic?: boolean;
+  readonly dim?: boolean;
+  readonly underlineStyle?: "single" | "double" | "curly" | "dotted" | "dashed";
+}
+/**
+ * Metadata describing a DesignSystem's Theme shape — for tooling (docs,
+ * storybook, CSS export). Plain data, no functions.
+ */
+interface ThemeShape {
+  /** The list of FlatTokens this system emits. */
+  readonly flatTokens: readonly string[];
+  /** The list of role-object keys this system emits (e.g. `["accent", "info", ...]`). */
+  readonly roles: readonly string[];
+  /** The list of state variants used on interactive roles (e.g. `["hover", "active"]`). */
+  readonly states: readonly string[];
+}
+/** Contrast enforcement mode for derivation. See D3 in sterling-preflight.md. */
+type ContrastMode = /** Throw on WCAG AA failure on core role pairs. Used by catalog tests. */"strict" /** Auto-lift failing tokens via OKLCH L shifts. Used for user schemes. */ | "auto-lift";
+/** Options accepted by all derivation entry points. */
+interface DeriveOptions {
+  /** Default: `"auto-lift"`. */
+  readonly contrast?: ContrastMode;
+  /** If true, attach `derivationTrace` to the returned Theme. Default: false. */
+  readonly trace?: boolean;
+  /**
+   * Per-role token pins. A scheme author can pin specific tokens (e.g.
+   * `{ "error.fg": "#bf616a" }`) to skip auto-adjustment. The path syntax is
+   * nested-style: `"accent.hover.bg"`, `"error.fg"`. Flat-form pins are
+   * also accepted: `{ "bg-accent": "#...", "fg-on-error": "#..." }`.
+   */
+  readonly pins?: Readonly<Record<string, string>>;
+  /**
+   * Force light/dark inference. By default inferred from
+   * `scheme.dark` or WCAG luminance of `scheme.background`.
+   */
+  readonly mode?: "light" | "dark";
+}
+/**
+ * The `DesignSystem` contract. Sterling is the default implementation; other
+ * packages (e.g. `@silvery/design-material`) publish alternatives matching
+ * this shape.
+ */
+interface DesignSystem {
+  /** Display name for tooling (e.g. `"sterling"`). */
+  readonly name: string;
+  /** Metadata about this system's Theme shape. */
+  readonly shape: ThemeShape;
+  /**
+   * Whether the framework should auto-apply `bakeFlat` to each derivation's
+   * output — projecting hex leaves onto flat hyphen-keys on the same object.
+   *
+   * - `true` — use {@link defaultFlattenRule} (channel-role-state, Sterling style)
+   * - `FlattenRule` — system-specific rule (e.g. Material `onPrimary`)
+   * - `false` or omitted — no auto-flatten (system is responsible, or
+   *   consumer only uses nested form)
+   *
+   * Sterling and anything modelled on it should set `flatten: true` —
+   * flat-projection-on-same-object is a universal feature of nested
+   * hex-leaf POJOs and Sterling users expect `theme["bg-accent"]` access.
+   */
+  readonly flatten?: boolean | FlattenRule;
+  /** Return a raw default Theme, no input required. */
+  defaults(mode?: "light" | "dark"): Theme;
+  /**
+   * Fill partial theme values with defaults. Useful for hand-curated themes
+   * that override a few roles.
+   */
+  theme(partial?: DeepPartial<Theme>, opts?: DeriveOptions): Theme;
+  /** Derive from a 22-color terminal scheme — Sterling's primary path. */
+  deriveFromScheme(scheme: ColorScheme, opts?: DeriveOptions): Theme;
+  /** Derive from a single seed color — Material-style. */
+  deriveFromColor(color: string, opts?: DeriveOptions & {
+    mode?: "light" | "dark";
+  }): Theme;
+  /** Derive from a light/dark scheme pair. */
+  deriveFromPair(light: ColorScheme, dark: ColorScheme, opts?: DeriveOptions): {
+    light: Theme;
+    dark: Theme;
+  };
+  /** Derive from a scheme plus a brand-color overlay (F — brand discipline). */
+  deriveFromSchemeWithBrand(scheme: ColorScheme, brand: string, opts?: DeriveOptions): Theme;
+}
+/** Utility: recursive `Partial` for nested Theme overrides. */
+type DeepPartial<T> = T extends object ? T extends readonly unknown[] ? T : { [K in keyof T]?: DeepPartial<T[K]> } : T;
+//#endregion
+//#region packages/theme/src/sterling/sterling.d.ts
+/**
+ * Sterling — the user-facing DesignSystem. `defineDesignSystem` wraps
+ * `rawSterling` with auto-`bakeFlat` (per `flatten: true`), so every
+ * returned Theme has both nested roles AND flat hyphen keys populated.
+ */
+declare const sterling: DesignSystem;
+//#endregion
+//#region packages/theme/src/sterling/define.d.ts
+/**
+ * Wrap a DesignSystem so every derivation method auto-applies `bakeFlat`
+ * per the `flatten` flag. Pass your raw system (one that returns nested
+ * themes) and this returns a user-facing system whose outputs have flat
+ * keys populated.
+ */
+declare function defineDesignSystem(def: DesignSystem): DesignSystem;
+//#endregion
+//#region packages/theme/src/sterling/contrast.d.ts
+/**
+ * Sterling contrast guardrails — D3 from sterling-preflight.md.
+ *
+ * Two modes:
+ *   - `strict` — throw when a core role pair fails WCAG AA 4.5:1.
+ *     Used by the catalog test (all 84 shipped schemes must pass).
+ *   - `auto-lift` — adjust OKLCH lightness until AA passes (±0.04L increments
+ *     up to ~0.20L). Logs at debug; silent by default. Used for user schemes
+ *     at runtime.
+ *
+ * Pinned tokens (per-role overrides supplied by scheme authors) are excluded
+ * from auto-lift and from strict-mode enforcement — the author accepts the
+ * contrast consequence of pinning.
+ */
+/** WCAG AA threshold for normal text. */
+declare const WCAG_AA = 4.5;
+interface ContrastViolation {
+  readonly token: string;
+  readonly fg: string;
+  readonly bg: string;
+  readonly ratio: number;
+  readonly target: number;
+}
+declare class ContrastError extends Error {
+  readonly violations: readonly ContrastViolation[];
+  constructor(violations: readonly ContrastViolation[]);
+}
+/**
+ * Verify `fg` on `bg` meets `target` ratio. Returns `null` when already
+ * passing; otherwise returns a ContrastViolation.
+ */
+declare function checkAA(token: string, fg: string, bg: string, target?: number): ContrastViolation | null;
+/**
+ * Auto-lift `fg` against `bg` until the `target` contrast ratio is met,
+ * via OKLCH L shifts (hue + chroma preserved). Light bg → darken;
+ * dark bg → lighten.
+ *
+ * Implementation note: binary-searches the minimum L shift achieving the
+ * target. Falls back to a best-effort value if the target is unreachable
+ * (e.g., yellow against white can never hit 4.5:1 at any lightness while
+ * preserving yellow hue; the result is the darkest in-gamut yellow).
+ */
+declare function autoLift(fg: string, bg: string, target?: number): {
+  value: string;
+  lifted: boolean;
+};
+//#endregion
+//#region packages/theme/src/sterling/derive.d.ts
+/**
+ * Derive a Theme's nested roles from a ColorScheme. Guardrails applied.
+ */
+declare function deriveRoles(scheme: ColorScheme, opts: DeriveOptions): {
+  roles: Roles;
+  mode: "light" | "dark";
+  trace: DerivationStep[];
+  violations: ContrastViolation[];
+};
+/**
+ * Derive a full Theme (pre-flatten) from a ColorScheme. Throws `ContrastError`
+ * in strict mode if any role pair fails WCAG AA. Callers typically wrap this
+ * with `flatten()` (from `flatten.ts`) to get the user-facing Theme.
+ *
+ * Returned Theme is NOT frozen and DOES NOT contain flat keys yet.
+ */
+declare function deriveTheme(scheme: ColorScheme, opts?: DeriveOptions): Omit<Theme, keyof FlatTokens>;
+//#endregion
+//#region packages/theme/src/sterling/flat-tokens.d.ts
+declare const STERLING_FLAT_TOKENS: readonly FlatToken[];
+//#endregion
+//#region packages/theme/src/sterling/defaults.d.ts
+declare function defaultScheme(mode?: "light" | "dark"): ColorScheme;
+//#endregion
+export { ayuMirage as $, resetBackgroundColor as $t, detectTheme as A, pickColorLevel as An, Base16Scheme as At, modusVivendi as B, createTheme as Bt, InteractiveRole as C, disableMouse as Cn, nord as Ct, SurfaceRole as D, bakeFlat as Dn, catppuccinMocha as Dt, StatePair as E, FlattenRule as En, catppuccinMacchiato as Et, defaultDarkTheme as F, detectTerminalCaps as Fn, ThemeValidationResult as Ft, oxocarbonLight as G, fromColors as Gt, edgeLight as H, quickTheme as Ht, defaultLightTheme as I, validateTheme as It, horizon as J, generateTheme$1 as Jt, nightfly as K, fromPreset as Kt, getSchemeByName as L, ValidationResult as Lt, ansi16LightTheme as M, ColorLevel as Mn, resolveAliases as Mt, builtinPalettes as N, TerminalCaps as Nn, resolveTokenAlias as Nt, Theme as O, defaultFlattenRule as On, exportBase16 as Ot, builtinThemes as P, defaultCaps as Pn, THEME_TOKEN_KEYS as Pt, ayuLight as Q, queryForegroundColor as Qt, getThemeByName as R, validateColorScheme as Rt, FlatTokens as S, disableKittyKeyboard as Sn, dracula as St, Roles as T, enableMouse as Tn, catppuccinLatte as Tt, sonokai as U, assignPrimaryToSlot as Ut, edgeDark as V, presetTheme as Vt, oxocarbonDark as W, fromBase16 as Wt, nightfox as X, queryBackgroundColor as Xt, dawnfox as Y, detectColorScheme as Yt, ayuDark as Z, queryCursorColor as Zt, DerivationStep as _, AnsiPrimary as _n, tokyoNight as _t, ContrastError as a, parsePaletteResponse as an, monokaiPro as at, DesignSystem as b, Theme$1 as bn, solarizedDark as bt, autoLift as c, setPaletteColor as cn, kanagawaDragon as ct, sterling as d, detectTerminalScheme as dn, rosePine as dt, resetCursorColor as en, palenight as et, AccentRole as f, KnownVariant as fn, rosePineDawn as ft, DeepPartial as g, ActiveScheme as gn, oneDark as gt, CursorRole as h, deriveTheme$1 as hn, gruvboxLight as ht, deriveTheme as i, setForegroundColor as in, monokai as it, ansi16DarkTheme as j, quantizeHex as jn, themeToCSSVars as jt, ThemeShape as k, ColorTier as kn, importBase16 as kt, checkAA as l, DetectThemeOptions as ln, kanagawaLotus as lt, ContrastMode as m, DetectSchemeResult as mn, gruvboxDark as mt, STERLING_FLAT_TOKENS as n, setBackgroundColor as nn, materialLight as nt, ContrastViolation as o, queryMultiplePaletteColors as on, everforestDark as ot, BorderRole as p, DetectSchemeOptions as pn, rosePineMoon as pt, moonfly as q, generateTheme as qt, deriveRoles as r, setCursorColor as rn, snazzy as rt, WCAG_AA as s, queryPaletteColor as sn, everforestLight as st, defaultScheme as t, resetForegroundColor as tn, materialDark as tt, defineDesignSystem as u, DetectedScheme as un, kanagawaWave as ut, DerivationTrace as v, COLOR_SCHEME_FIELDS as vn, tokyoNightDay as vt, MutedRole as w, enableKittyKeyboard as wn, catppuccinFrappe as wt, FlatToken as x, resolveThemeColor as xn, solarizedLight as xt, DeriveOptions as y, ColorScheme as yn, tokyoNightStorm as yt, modusOperandi as z, autoGenerateTheme as zt };
+//# sourceMappingURL=index-D3saHouR.d.mts.map