silvery 0.19.2 → 0.21.0

package/dist/{index-D3saHouR.d.mts → index-CSQf13CI.d.mts}

@@ -1,136 +1,40 @@
-//#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";
+//#region packages/ansi/src/emulator.d.ts
 /**
- * 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.
+ * Terminal emulator identity — facts about *what terminal this IS*, as
+ * opposed to {@link ./caps#TerminalCaps} which describes what it can DO.
  *
- *   - `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`).
+ * Identity doesn't gate rendering; it's what tests, diagnostics, and
+ * probe-cache keys discriminate on (e.g. `program@version` is the cache key
+ * used by `@silvery/ag-term/text-sizing` per km-silvery.unicode-plateau
+ * Phase 2).
  *
- * Returns the input unchanged if it cannot be parsed as a hex color.
+ * Resolved once by {@link ./profile#createTerminalProfile} and exposed as
+ * `profile.emulator` — no other module reads TERM / TERM_PROGRAM.
  */
-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.
+ * Environment identity — facts about what terminal this IS. Separate from
+ * {@link ./caps#TerminalCaps} because identity doesn't gate rendering; it's
+ * what tests, diagnostics, and probe-cache keys discriminate on.
+ *
+ * Post km-silvery.plateau-naming-polish (2026-04-23): renamed from
+ * `TerminalIdentity` → `TerminalEmulator` (the thing IS a terminal emulator,
+ * matches `TERM_PROGRAM` provenance) and `termName` → `TERM` (matches the
+ * env var name and shell convention).
  */
-declare function pickColorLevel<T>(theme: T, tier: ColorTier): T;
+interface TerminalEmulator {
+  /** Terminal program name (from TERM_PROGRAM). */
+  readonly program: string;
+  /** Terminal program version string (from TERM_PROGRAM_VERSION). Empty when
+   * the host doesn't advertise a version. Together with `program`, forms the
+   * `program@version` fingerprint used as the probe-cache key in
+   * `@silvery/ag-term/text-sizing`. See km-silvery.unicode-plateau Phase 2. */
+  readonly version: string;
+  /** Value of the `TERM` env var (`"xterm-kitty"`, `"xterm-256color"`, …).
+   * Named `TERM` rather than `termName` to mirror the env-var name
+   * explicitly — the field's sole source is the `TERM` environment entry,
+   * resolved once by `createTerminalProfile`. */
+  readonly TERM: string;
+}
 //#endregion
 //#region packages/ansi/src/flatten.d.ts
 /**
@@ -219,190 +123,405 @@ declare const defaultFlattenRule: FlattenRule;
  */
 declare function bakeFlat<T extends object>(theme: T, rule?: FlattenRule): T;
 //#endregion
-//#region packages/ansi/src/terminal-control.d.ts
+//#region packages/ansi/src/sterling/types.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.
+ * 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.
  *
- * 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.
+ * 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`).
  */
-declare function enableMouse(): string;
+interface BgStatePair {
+  readonly bg: string;
+}
 /**
- * Disable mouse tracking. Disables in reverse order of enabling.
+ * Interactive (link-like) state pair: both `fg` and `bg` vary by state.
+ * Used by `accent` — the canonical interactive-text role.
  */
-declare function disableMouse(): string;
+interface StatePair {
+  readonly fg: string;
+  readonly bg: 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                    |
+ * 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`).
  *
- * @param flags Bitfield of Kitty keyboard flags
+ * Used for the four status families: `info`, `success`, `warning`, `error`.
  */
-declare function enableKittyKeyboard(flags?: number): string;
+interface StatusRole {
+  /** 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;
+}
 /**
- * Disable the Kitty keyboard protocol (pop mode stack).
- * Sends CSI < u to restore the previous keyboard mode.
+ * @deprecated Renamed to `StatusRole` for clarity (the family lacks the
+ * `fg.hover/active` interaction states the old name implied). The alias is
+ * retained for one cycle so external consumers don't break on rename.
  */
-declare function disableKittyKeyboard(): string;
-//#endregion
-//#region packages/ansi/src/style/style.d.ts
+type InteractiveRole = StatusRole;
 /**
- * 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).
+ * Accent — the canonical link-like interactive-text role. Has everything
+ * `StatusRole` does PLUS a focus-ring border AND `fg.hover` /
+ * `fg.active` text-color state variants (link hover treatments).
  */
-declare function resolveThemeColor(name: string | undefined, theme: object | undefined): string | undefined;
-//#endregion
-//#region packages/ansi/src/theme/types.d.ts
+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;
+}
 /**
- * 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)
+ * Selected role — the highlight surface for the cursor row, mouse selection,
+ * search-match highlight, and any "this is the active item" treatment.
+ * `fgOn` is the text color drawn on `bg`; `hover.bg` is the +0.04L shift used
+ * by SelectList row hover.
  */
-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;
+interface SelectedRole {
+  readonly bg: string;
+  readonly fgOn: string;
+  readonly hover: BgStatePair;
 }
-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>;
+/**
+ * Inverse role — flipped surface used for status bars, modal chrome, the
+ * "you are here" inverse band. Subtle blend of fg into bg, with `fgOn`
+ * picked for AA contrast against the resulting surface.
+ */
+interface InverseRole {
+  readonly bg: string;
+  readonly fgOn: string;
 }
 /**
- * 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
+ * Link role — hyperlink text color. Distinct from `accent` so apps that want
+ * "link blue" (as opposed to the brand-derived accent) can opt in. Single
+ * `fg` slot — links are text, not surfaces; if a link surface is ever needed,
+ * extend with `bg` + `fgOn` then.
+ */
+interface LinkRole {
+  readonly fg: string;
+}
+/**
+ * Disabled role — neutral, deemphasized treatment for unavailable controls
+ * (read-only inputs, disabled buttons, inactive menu items). Composite-derived
+ * from the base interface tokens (`fg-default` / `border-default`) over
+ * `bg-surface-default`, NOT from accent/status families — disabled is meant
+ * to read as "absent / inactive", not as a muted error/success/etc.
+ *
+ * Derivation (per design-system.md §"Disabled derivation"):
+ *   - `fg-disabled    = composite(fg-default     @ 0.38, bg-surface-default)`
+ *     clamped to ≥3:1 contrast vs `bg-surface-default`
+ *   - `border-disabled = composite(border-default @ 0.24, bg-surface-default)`
+ *   - `bg-disabled    = composite(border-default @ 0.12, bg-surface-default)`
+ */
+interface DisabledRole {
+  readonly fg: string;
+  readonly bg: string;
+  readonly border: 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: StatusRole;
+  readonly success: StatusRole;
+  readonly warning: StatusRole;
+  readonly error: StatusRole;
+  readonly muted: MutedRole;
+  readonly surface: SurfaceRole;
+  readonly border: BorderRole;
+  readonly cursor: CursorRole;
+  readonly selected: SelectedRole;
+  readonly inverse: InverseRole;
+  readonly link: LinkRole;
+  readonly disabled: DisabledRole;
+}
+/**
+ * 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" | "bg-selected" | "fg-on-selected" | "bg-selected-hover" | "bg-inverse" | "fg-on-inverse" | "fg-link" | "fg-disabled" | "bg-disabled" | "border-disabled" | "bg-backdrop" | "fg-default" | "bg-default";
+/** 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
+ *
+ * Root pair:
+ *   - `fg` — default text color (= `scheme.foreground`)
+ *   - `bg` — default canvas color (= `scheme.background`; same value as
+ *            `bg-surface-default` but exposed at the root for `$fg` / `$bg`
+ *            JSX consumers and convenience access)
+ *
+ * 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[]; /** Default text color (= `scheme.foreground`). Heavily used as `$fg` in JSX. */
+  readonly fg: string;
+  /**
+   * Default canvas color (= `scheme.background`). Same value as
+   * `bg-surface-default`; exposed at the root for `$bg` JSX consumers and
+   * convenience access.
+   */
+  readonly bg: 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/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"];
+/**
+ * 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)}%`)
@@ -421,94 +540,74 @@ interface ActiveScheme {
 }
 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;
+//#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 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;
+/**
+ * Structural subset of `@silvery/ag-term/runtime` `InputOwner`. Defined
+ * locally so `@silvery/ansi` stays dependency-free — callers inside a silvery
+ * session can pass the real `InputOwner` and get nominal structural match;
+ * standalone callers who never heard of InputOwner are unaffected.
+ */
+interface ProbeInputOwner {
+  probe<T>(opts: {
+    query: string;
+    parse: (acc: string) => {
+      result: T;
+      consumed: number;
+    } | null;
+    timeoutMs: number;
+  }): Promise<T | null>;
 }
-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. */
+interface ProbeColorsOptions {
+  /** Per-OSC-query timeout in 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.
+   * Optional InputOwner (from `@silvery/ag-term/runtime`) that owns the stdin
+   * raw-mode + data listener for the enclosing session. When provided,
+   * probeColors routes OSC queries through `input.probe()` instead of
+   * touching `process.stdin` directly. This avoids the wasRaw race that kills
+   * host-TUI input when probeColors runs concurrently with a TUI session.
+   *
+   * When absent (e.g. CLI tool, non-TUI caller), probeColors falls back to
+   * the standalone race-safe `didSetRaw + listenerCount > 0` guard on
+   * `process.stdin`. The standalone path stays tested and supported.
    */
-  enforce?: "strict" | "lenient" | "off";
-  /** Add WCAG contrast check to the invariant validation. Default `false`. */
-  wcag?: boolean;
+  input?: ProbeInputOwner;
 }
-//#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`.
+ * Probe the terminal for its 22-slot color scheme via OSC 4/10/11 queries.
+ *
+ * Pure terminal primitive — no fingerprinting, no theme derivation. Returns the
+ * raw probed slots (or `null` if probing isn't available, e.g. non-TTY).
+ *
+ * For the full detection cascade (override → probe → fingerprint → fallback +
+ * theme derivation), use `detectScheme` from `@silvery/ansi` or
+ * `detectTheme` from `@silvery/theme`.
+ *
+ * `probeColors` is the canonical name; `detectTerminalScheme` is the legacy
+ * alias kept for backward compatibility.
+ *
+ * Call styles:
+ *   await probeColors()                                    // default timeout, standalone
+ *   await probeColors(150)                                 // legacy positional timeout
+ *   await probeColors({ timeoutMs: 150 })                  // options form
+ *   await probeColors({ input: inputOwner, timeoutMs: 150 }) // routed through InputOwner
  */
-type VariantName = "h1" | "h2" | "h3" | "body" | "body-muted" | "fine-print" | "strong" | "em" | "link" | "key" | "code" | "kbd";
+declare function probeColors(timeoutOrOpts?: number | ProbeColorsOptions): Promise<DetectedScheme | null>;
 /**
- * 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.
+ * Legacy alias for {@link probeColors}. Prefer `probeColors` in new code —
+ * the name says what it does (probes terminal color slots), and "detect" is
+ * reserved for the full cascade (`detectScheme`, `detectTheme`). Retained
+ * as a stable alias — no deprecation schedule.
  */
-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>;
+declare const detectTerminalScheme: typeof probeColors;
 interface DetectThemeOptions {
   /** Fallback ColorScheme when detection fails or returns partial data.
    * Detected colors override matching fallback fields.
@@ -523,870 +622,695 @@ interface DetectThemeOptions {
   /** 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
+   * - colorLevel `"mono"` / `"ansi16"` skips OSC detection and returns ANSI 16 theme
    * - darkBackground informs fallback selection when detection fails */
   caps?: {
     colorLevel?: string;
     darkBackground?: boolean;
   };
+  /** Optional InputOwner — routes OSC queries through the session's stdin
+   * owner instead of directly mutating process.stdin raw mode. See
+   * {@link ProbeColorsOptions.input}. */
+  input?: ProbeInputOwner;
 }
+declare function detectTheme(opts?: DetectThemeOptions): Promise<Theme>;
 //#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
+//#region packages/ansi/src/profile.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").
+ * Which rung of the precedence chain resolved the profile's color tier.
+ *
+ * Scoped specifically to **color tier** — not whole-profile provenance. Other
+ * caps fields (unicode, kittyKeyboard, …) come from `detectTerminalProfileFromEnv`
+ * or a caller-supplied caps object; their provenance is not tracked here.
+ *
+ * - `"env"` — `NO_COLOR` or `FORCE_COLOR` env var won.
+ * - `"override"` — caller-supplied `colorLevel` won.
+ * - `"caller-caps"` — `options.caps.colorLevel` fallback won. Note this
+ *   conflates "pre-detected real caps the Term committed to" with
+ *   "synthetically forced caps from a test fixture / user config"; callers
+ *   that need to tell those apart pass `colorLevel` explicitly instead.
+ * - `"auto"` — env-based auto-detection (TERM/COLORTERM/TERM_PROGRAM) won.
+ *
+ * Consumers that only need "was the tier forced?" should read
+ * {@link TerminalCaps.colorForced} instead of comparing against this enum.
+ * Phase 5 of `km-silvery.terminal-profile-plateau` (per /pro review 2026-04-23):
+ * the flat `source` field was retired because it read like whole-profile
+ * provenance but only described color tier.
  */
-declare function generateTheme$1(primary: AnsiPrimary, dark: boolean): Theme$1;
-//#endregion
-//#region packages/theme/src/generate.d.ts
+type ColorProvenance = "env" | "override" | "caller-caps" | "auto";
 /**
- * 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".
+ * A fully-resolved view of the current terminal.
+ *
+ * Bundled intentionally — callers shouldn't mix and match detection sources.
+ * `colorLevel` mirrors `caps.colorLevel`; it's exposed as a top-level field so
+ * callers that only need the tier (e.g. `createStyle({ level })`) don't have
+ * to reach into the caps object.
+ *
+ * **Immutability**: profiles are snapshot values — the whole plateau depends
+ * on `colorLevel === caps.colorLevel` never drifting. Every field is
+ * `readonly` at the type level, and `createTerminalProfile` freezes the
+ * returned object (and its nested `caps`) in dev builds so accidental
+ * mutation crashes loudly. Production builds skip the freeze to keep the
+ * allocation cheap; the type-level `readonly` already blocks TS writers.
+ *
+ * Post km-silvery.plateau-naming-polish (2026-04-23): 2-layer shape — `emulator`
+ * (what terminal IS this) and `caps` (what can it do, including `maybe*`
+ * heuristics). The original Phase 7 3-layer shape collapsed because the
+ * 3-field heuristics namespace was pulling its weight.
+ *
+ * @see createTerminalProfile
  */
-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;
+interface TerminalProfile {
+  /** Environment identity — what terminal IS this (program, version, TERM). */
+  readonly emulator: TerminalEmulator;
+  /** Protocol-capability flags + low-confidence `maybe*` heuristics. Also
+   * carries `colorLevel` / `colorForced` / `colorProvenance`. */
+  readonly caps: TerminalCaps;
+  /** Convenience alias for `caps.colorLevel`. Exposed as a top-level field
+   * because callers that only need the tier (e.g. `createStyle({ level })`)
+   * shouldn't have to reach into the caps object. */
+  readonly colorLevel: ColorLevel;
+  /**
+   * OSC-detected terminal theme, populated only when the profile was built via
+   * {@link probeTerminalProfile}. Pre-quantized to {@link colorLevel} when the
+   * tier was {@link TerminalCaps.colorForced} so token hex values match what
+   * the pipeline will actually emit.
+   *
+   * Absent on sync {@link createTerminalProfile} — theme detection is an async
+   * OSC probe and can't run inside a sync call. Entry points that need a
+   * theme (run, createApp) should use `probeTerminalProfile` instead.
+   *
+   * Post km-silvery.plateau-profile-theme (H2 of the /big review 2026-04-23).
+   */
+  readonly theme?: Theme;
+}
 /**
- * Generate a ColorScheme from a Base16 YAML scheme.
+ * Minimal stdout shape needed for detection.
  *
- * Maps base00–base0F to ANSI palette colors, derives special colors.
+ * Using a structural type (not `NodeJS.WriteStream`) keeps `@silvery/ansi`
+ * browser-safe — the canvas/DOM backends can pass `{ isTTY: false }` without
+ * pulling in Node's tty types.
  */
-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;
+interface TerminalProfileStdout {
+  isTTY?: boolean;
+  columns?: number;
+  rows?: number;
 }
 /**
- * Generate a full ColorScheme from 1-3 hex colors.
+ * Minimal stdin shape needed for input capability detection.
  *
- * At minimum, provide `background` or `primary`. Missing colors are
- * generated via surface ramp (from bg) and hue rotation (from primary).
+ * Structural like {@link TerminalProfileStdout} — browser/canvas backends
+ * that have no stdin pass `undefined` and `caps.input` resolves to `false`
+ * via the default. Absorbed from the retired `detectInput(stdin)` helper
+ * in unicode-plateau Phase 4.
  */
-declare function fromColors(opts: FromColorsOptions): ColorScheme;
+interface TerminalProfileStdin {
+  isTTY?: boolean;
+  setRawMode?: (mode: boolean) => unknown;
+}
 /**
- * Look up a built-in palette by name.
- *
- * @returns The ColorScheme, or undefined if not found.
+ * Options for {@link createTerminalProfile}.
  */
-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;
+interface CreateTerminalProfileOptions {
+  /** Environment (default: `process.env`). */
+  env?: Record<string, string | undefined>;
+  /** Output stream (default: `process.stdout`). */
+  stdout?: TerminalProfileStdout;
+  /**
+   * Input stream (default: `process.stdin`). Used to derive `caps.input` —
+   * whether the host can read raw keystrokes. Pass `undefined` explicitly
+   * (or omit on non-Node targets) to force `caps.input = false`.
+   */
+  stdin?: TerminalProfileStdin;
+  /**
+   * Explicit color tier override. Wins over `caps.colorLevel` but NOT over
+   * NO_COLOR / FORCE_COLOR env vars. `null` is accepted as an alias for
+   * `"mono"` (pre-plateau no-color spelling).
+   */
+  colorLevel?: ColorLevel | null;
+  /**
+   * Base capabilities. When provided, skips the env-based caps detection —
+   * the profile uses these as the starting point. `caps.colorLevel` acts as
+   * the fallback tier (used only if env+override both decline to set one).
+   *
+   * Typical uses:
+   * - Term constructors already computed full caps → pass them here to avoid
+   *   a redundant detection pass.
+   * - Tests want a known-good caps fixture → pass a fully-populated object.
+   */
+  caps?: Partial<TerminalCaps>;
+  /**
+   * Base emulator identity. When provided, skips identity detection and uses
+   * these values. Typical use: Term constructors that already resolved
+   * TERM_PROGRAM from their stdin/stdout context.
+   */
+  emulator?: Partial<TerminalEmulator>;
 }
-/** Create a chainable theme builder. */
-declare function createTheme(): ThemeBuilder;
 /**
- * Quick theme from a primary color or color name.
+ * Build a {@link TerminalProfile} from the current environment.
  *
- * @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.
+ * Priority for the final `colorLevel` (highest wins):
+ *   1. `NO_COLOR` env var → `"mono"`
+ *   2. `FORCE_COLOR` env var → `0/false → mono, 1 → ansi16, 2 → 256, 3 → truecolor`
+ *   3. `options.colorLevel` (caller-supplied explicit tier)
+ *   4. `options.caps.colorLevel` (base caps' pre-detected tier)
+ *   5. Auto-detected tier from env (TERM, COLORTERM, TERM_PROGRAM, …)
  *
- * @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.
+ * The env-var precedence (1 & 2) matches the existing `detectColor()` semantics
+ * and is observed on every silvery entry point — tests pass with explicit
+ * env vars even when a caller forces a tier via `colorLevel`.
  *
- * 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
+ * When `options.caps` is provided, the profile treats those as the base
+ * capabilities and skips the env-based caps detection — only the color tier
+ * is resolved through the precedence chain above. When `options.caps` is
+ * absent, the full `detectTerminalProfileFromEnv` pass runs.
  *
- * @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
+ * No I/O beyond whatever `detectTerminalCaps()` already does (a `defaults read`
+ * call on macOS for Apple Terminal dark-mode heuristics — cached).
  *
  * @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.
+ * ```ts
+ * // Auto-detect from process.env + process.stdout
+ * const profile = createTerminalProfile()
+ * console.log(profile.colorLevel) // "truecolor" on Ghostty
  *
- * 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.
+ * // Force a tier (still honors NO_COLOR / FORCE_COLOR env precedence)
+ * const forced = createTerminalProfile({ colorLevel: "256" })
  *
- * @param theme - The theme object to validate
- * @returns Validation result with missing and extra token lists
+ * // Term path — base caps already detected, just resolve color tier.
+ * const termProfile = createTerminalProfile({
+ *   colorLevel: userColorLevel,
+ *   caps: term.caps,
+ * })
  *
- * @example
- * ```typescript
- * const result = validateTheme(myTheme)
- * if (!result.valid) {
- *   console.log("Missing tokens:", result.missing)
- * }
+ * // Headless/test fixture — zero env influence
+ * const fake = createTerminalProfile({
+ *   env: {},
+ *   stdout: { isTTY: true },
+ *   colorLevel: "truecolor",
+ * })
  * ```
  */
-declare function validateTheme(theme: Record<string, unknown>): ThemeValidationResult;
-//#endregion
-//#region packages/theme/src/alias.d.ts
+declare function createTerminalProfile(options?: CreateTerminalProfileOptions): TerminalProfile;
 /**
- * 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
- * })
- * ```
+ * Options for {@link probeTerminalProfile}. Extends the sync factory options
+ * with the async-only fields a theme probe needs.
  */
-declare function resolveAliases(theme: Record<string, string>): Record<string, string>;
+interface ProbeTerminalProfileOptions extends CreateTerminalProfileOptions {
+  /**
+   * Probe the terminal's theme via OSC 10/11/4 and bundle the result as
+   * `profile.theme`. Default `true` — the whole point of using the async
+   * variant is to get the theme alongside caps. Set `false` to skip the
+   * probe (no OSC writes) while still resolving a {@link TerminalProfile}
+   * identical to the sync path.
+   */
+  probeTheme?: boolean;
+  /**
+   * Fallback scheme when the OSC probe returns partial / no data. Matches
+   * {@link DetectThemeOptions.fallbackDark}.
+   */
+  fallbackDark?: DetectThemeOptions["fallbackDark"];
+  /** Fallback for light terminals (overrides `fallbackDark`). */
+  fallbackLight?: DetectThemeOptions["fallbackLight"];
+  /** Per-OSC-query timeout in ms (default 150 — matches `detectTheme`). */
+  timeoutMs?: number;
+  /**
+   * Optional {@link ProbeInputOwner} (the structural type `detectTheme`
+   * accepts). When provided, the probe routes OSC queries through the
+   * owner's `probe()` method instead of touching `process.stdin` directly —
+   * required inside a running TUI session. Callers in `@silvery/ag-term`
+   * construct a transient `InputOwner` around this call; standalone callers
+   * can omit it.
+   */
+  input?: ProbeInputOwner;
+}
 /**
- * Resolve a single alias value against a Theme.
+ * Build a {@link TerminalProfile} with an OSC-detected `theme` bundled in.
  *
- * Useful for resolving individual values without processing the entire theme.
+ * Async because the theme probe writes OSC queries to stdout and waits for
+ * responses on stdin. This is the Phase-H2 variant of
+ * {@link createTerminalProfile} — everything the sync factory does, plus:
  *
- * @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.
+ * 1. Run `detectTheme` (OSC 4/10/11 probe with fallback) once.
+ * 2. Pre-quantize the resulting theme via {@link pickColorLevel} when the
+ *    tier was forced ({@link TerminalCaps.colorForced} is `true`) so
+ *    token hex values match what the pipeline will actually emit.
+ * 3. Return the profile with `theme` populated — one detection, one profile
+ *    flowing end-to-end through run() / createApp().
  *
- * 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`
+ * Call sites previously ran `createTerminalProfile(...)` + `detectTheme(...)`
+ * + `pickColorLevel(...)` as three separate steps on both the Term-path and
+ * options-path branches. Collapsing that into one function removes the
+ * duplication and the possibility of the three views disagreeing about
+ * what was forced.
  *
- * @param theme - The theme to convert (Sterling flat tokens must be populated)
- * @returns A record mapping CSS custom property names to color values
+ * When `probeTheme` is `false`, behaves like the sync {@link createTerminalProfile}
+ * but wrapped in a Promise — useful for call sites that want uniform async
+ * treatment regardless of whether a probe is needed.
  *
  * @example
- * ```typescript
- * const vars = themeToCSSVars(myTheme)
- * // { "--bg-surface-default": "#1E1E2E", "--fg-accent": "#F9E2AF", ... }
- *
- * // Apply to an element:
- * Object.assign(element.style, vars)
+ * ```ts
+ * // Node entry point with TUI-safe probing.
+ * const profile = await probeTerminalProfile({
+ *   colorLevel: options.colorLevel,
+ *   caps: term.profile.caps,
+ *   fallbackDark: nord,
+ *   fallbackLight: catppuccinLatte,
+ *   input: probeOwner, // structural InputOwner from @silvery/ag-term
+ * })
+ * // profile.caps, profile.colorLevel, profile.caps.colorForced, profile.theme
  * ```
+ *
+ * @see createTerminalProfile — sync variant, no theme probe
+ * @see DetectThemeOptions — the underlying probe options this wraps
  */
-declare function themeToCSSVars(theme: Theme$1): Record<string, string>;
+declare function probeTerminalProfile(options?: ProbeTerminalProfileOptions): Promise<TerminalProfile>;
 //#endregion
-//#region packages/theme/src/import/types.d.ts
+//#region packages/ansi/src/caps.d.ts
 /**
- * Base16 scheme type — the 16-color format used by hundreds of community themes.
- *
- * @see https://github.com/chriskempson/base16
+ * Pure protocol capability flags plus low-confidence environment heuristics —
+ * what the terminal *can* do at the wire level, plus what the system guesses
+ * about theme/font/emoji rendering. Used by renderers / measurer for
+ * pre-flight branching.
+ *
+ * Post km-silvery.plateau-naming-polish (2026-04-23):
+ * - `TerminalHeuristics` was absorbed into this type. Guesses live alongside
+ *   hard facts but carry a `maybe` prefix so the uncertainty is loud at every
+ *   read site (`caps.maybeDarkBackground` vs `caps.cursor`).
+ *
+ * Post km-silvery.caps-restructure (Phase 7, 2026-04-23): the original flat
+ * 22-field shape was split into {@link TerminalCaps} (this type) and
+ * {@link TerminalEmulator} (environment identity — program/version/TERM).
+ * Both live on `profile.{caps,emulator}`.
+ *
+ * Renames from the old flat shape:
+ * - `textSizingSupported` → `textSizing` (drops the verbose suffix)
+ * - `underlineStyles: boolean` → `underlineStyles: readonly UnderlineStyle[]`
+ *   so a terminal that supports curly but not dotted can report that precisely
+ * - `colorForced` + `colorProvenance` moved INTO caps (they describe color
+ *   resolution, which is caps-adjacent)
+ *
+ * Phase 7 briefly renamed `colorLevel` → `colorTier` on caps, then reverted
+ * in plateau-naming-polish (2026-04-23) because `level` was already the
+ * canonical vocabulary across the stack (Style.level, createStyle({ level }),
+ * pickColorLevel, Pipeline.ColorLevel, run({ colorLevel })). Alignment won.
  */
-/** 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;
+interface TerminalCaps {
+  /** Can the host reposition the cursor? True when the output stream is a
+   * TTY and `TERM` is not `"dumb"`. Absorbed from the standalone
+   * `detectCursor()` helper in unicode-plateau Phase 3. */
+  readonly cursor: boolean;
+  /** Can the host read raw keystrokes? True when the input stream is a TTY
+   * and supports `setRawMode`. Absorbed from the standalone
+   * `detectInput()` helper in unicode-plateau Phase 4. */
+  readonly input: boolean;
+  /** Color support level. See {@link ColorLevel}. */
+  readonly colorLevel: ColorLevel;
+  /**
+   * Was the color tier forced by env vars (NO_COLOR / FORCE_COLOR) or a
+   * caller-supplied `colorLevel`? Equivalent to
+   * `colorProvenance === "env" || colorProvenance === "override"` — exposed
+   * as a precomputed boolean because that's the question every pre-quantize
+   * gate in run.tsx / create-app.tsx actually asks.
+   *
+   * Moved from {@link ./profile#TerminalProfile} into caps in Phase 7 — it
+   * describes *color* resolution, which is caps-adjacent, so grouping it here
+   * means all color-tier metadata travels as one unit.
+   */
+  readonly colorForced: boolean;
+  /**
+   * Which rung of the precedence chain resolved {@link colorLevel}. Use
+   * {@link colorForced} for the common "was the tier forced?" check; use this
+   * enum only when the specific rung matters (e.g. diagnostics, theme
+   * detection, debug output).
+   */
+  readonly colorProvenance: ColorProvenance;
+  /** Unicode/emoji support */
+  readonly unicode: boolean;
+  /**
+   * Extended SGR 4:x underline styles this terminal advertises. Empty array
+   * means "only the standard SGR 4 single underline is known to work" and
+   * consumers should fall back accordingly.
+   *
+   * Phase 7 upgrade: was a single `boolean` (all-or-nothing). With the array
+   * a terminal that supports curly but not dotted can report that precisely;
+   * style.ts now checks `caps.underlineStyles.includes("curly")` per style.
+   */
+  readonly underlineStyles: readonly UnderlineStyle[];
+  /** SGR 58 underline color */
+  readonly underlineColor: boolean;
+  /**
+   * SGR 53/55 overline support. SGR 53 draws a line ABOVE the character cell,
+   * complementing the underline (SGR 4) below. Most modern terminals support
+   * it (Ghostty, iTerm2, xterm with extended attrs); the output phase skips
+   * emit when this is false so older terminals don't render the literal
+   * escape as text. See {@link BoxProps#overline} for the UI-facing prop.
+   */
+  readonly overline: boolean;
+  /** OSC 66 text sizing protocol likely supported (Kitty 0.40+, Ghostty).
+   * Phase 7 rename: dropped the verbose `Supported` suffix. */
+  readonly textSizing: boolean;
+  /** Kitty keyboard protocol supported */
+  readonly kittyKeyboard: boolean;
+  /** Bracketed paste mode */
+  readonly bracketedPaste: boolean;
+  /** SGR mouse tracking */
+  readonly mouse: boolean;
+  /** Kitty graphics protocol (inline images) */
+  readonly kittyGraphics: boolean;
+  /** Sixel graphics supported */
+  readonly sixel: boolean;
+  /** OSC 52 clipboard */
+  readonly osc52: boolean;
+  /** OSC 8 hyperlinks */
+  readonly hyperlinks: boolean;
+  /** OSC 9/99 notifications */
+  readonly notifications: boolean;
+  /** Synchronized output (DEC 2026) */
+  readonly syncOutput: boolean;
+  /** Heuristic: likely dark background (for theme selection). Use
+   * {@link probeTerminalProfile} with OSC 11 to resolve definitively. */
+  readonly maybeDarkBackground: boolean;
+  /** Heuristic: likely has Nerd Font installed (for icon selection).
+   * Sniffed from TERM / LC_TERMINAL / known-modern terminal programs. */
+  readonly maybeNerdFont: boolean;
+  /** Heuristic: text-presentation emoji (`⚠` `☑` `⭐` — `Extended_Pictographic`
+   * without default `Emoji_Presentation`) rendered as 2 cells. Modern terminals
+   * (Ghostty, iTerm, Kitty) render these at emoji width (2 cells); Terminal.app
+   * renders them at text width (1 cell). Affects measurer + layout. */
+  readonly maybeWideEmojis: boolean;
 }
-//#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.
+ * Default capabilities — modern-terminal-ish defaults for headless / emulator /
+ * unknown contexts. Heuristic fields (`maybe*`) bake in "probably dark, no
+ * nerd font, wide emojis like Ghostty/iTerm" — callers override via
+ * `createTerminalProfile({caps})`.
  */
-declare function importBase16(yamlOrJson: string): ColorScheme;
+declare function defaultCaps(): TerminalCaps;
 //#endregion
-//#region packages/theme/src/export/base16.d.ts
+//#region packages/ansi/src/types.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.
+ * Type definitions for @silvery/ansi
  */
-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".
+ * The canonical 4-state color tier supported by a terminal.
  *
- * 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.
+ * One enum, one spelling — used everywhere a color capability is described
+ * (caps, style level, chalk compat, tier quantization, etc.).
+ *
+ * - `"mono"` — no color (OSC queries disabled, monochrome attribute fallback).
+ * - `"ansi16"` — 16-slot palette (SGR 30-37, 90-97 / 40-47, 100-107).
+ * - `"256"` — xterm-256 palette (SGR 38;5;n).
+ * - `"truecolor"` — 24-bit RGB (SGR 38;2;r;g;b).
+ *
+ * Prior to km-silvery.terminal-profile-plateau this type went by three
+ * different names with three different spellings for the no-color case
+ * (`null`, `"none"`, `"mono"`). Canonicalized to `ColorLevel` + `"mono"`.
  */
-declare const ansi16DarkTheme: Theme$1;
+type ColorLevel = "mono" | "ansi16" | "256" | "truecolor";
 /**
- * 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.
+ * RGB color tuple for underline color.
+ * Each component is 0-255.
  */
-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
+type RGB = [r: number, g: number, b: number];
 /**
- * Detect the terminal's palette and return a Sterling-aware Theme.
+ * Extended underline styles supported by modern terminals.
  *
- * Identical to `@silvery/ansi`'s `detectTheme` but every returned theme has
- * Sterling flat tokens baked in via `inlineSterlingTokens`.
+ * - `single`: Standard underline (SGR 4:1)
+ * - `double`: Two parallel lines (SGR 4:2)
+ * - `curly`: Wavy/squiggly line (SGR 4:3) - commonly used for spell check
+ * - `dotted`: Dotted line (SGR 4:4)
+ * - `dashed`: Dashed line (SGR 4:5)
  */
-declare function detectTheme(opts?: DetectThemeOptions): Promise<Theme$1>;
+type UnderlineStyle = "single" | "double" | "curly" | "dotted" | "dashed";
 //#endregion
-//#region packages/theme/src/sterling/types.d.ts
+//#region packages/ansi/src/color-maps.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.
+ * Hex-in / hex-out quantization for previews.
  *
- * 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.
+ * 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.
  *
- * Grammar: `prefix-role[-state]` or `prefix-on-role` or `prefix-role-kind[-state]`.
- * (See design-system.md §"Flattening rule".)
+ *   - `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.
  */
-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 };
+declare function quantizeHex(hex: string, tier: ColorLevel): 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.
+ * 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.
  */
-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[];
+declare function pickColorLevel<T>(theme: T, tier: ColorLevel): T;
+//#endregion
+//#region packages/ansi/src/terminal-control.d.ts
 /**
- * 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.
+ * Enable mouse tracking with full hover support.
  *
- * Distinguish from:
- *   - `$color0..$color15`         — raw terminal ANSI (user's theme verbatim)
- *   - `$error/$warning/$success`  — semantic state (communicates meaning)
- *   - `$brand`                    — app identity anchor (one color)
+ * 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.
+ * - **1016** (SGR-Pixels): Optional pixel coordinates in the same SGR shape.
+ *
+ * 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.
  */
-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;
+interface MouseModeOptions {
+  /** Enable xterm SGR-Pixels mode 1016 in addition to 1003/1006. */
+  pixels?: boolean;
 }
+declare function enableMouse(options?: MouseModeOptions): 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:
+ * Disable mouse tracking. Disables in reverse order of enabling.
+ */
+declare function disableMouse(): string;
+/**
+ * Enable the Kitty keyboard protocol (push mode).
  *
- * 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`).
+ * Sends CSI > flags u to opt into the specified modes.
+ * Supported by: Ghostty, Kitty, WezTerm, foot. Ignored by unsupported terminals.
  *
- * 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
+ * Flags are a bitfield:
  *
- * 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.
+ * | 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
  */
-type Theme = FlatTokens & Roles & {
-  readonly name?: string;
-  readonly mode: "light" | "dark";
-  readonly derivationTrace?: DerivationTrace;
-  readonly variants: Record<string, Variant>;
-  readonly palette: readonly string[];
-} & CategoricalHues;
+declare function enableKittyKeyboard(flags?: number): string;
 /**
- * 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.
+ * Disable the Kitty keyboard protocol (pop mode stack).
+ * Sends CSI < u to restore the previous keyboard mode.
  */
-interface Variant {
-  readonly color?: string;
-  readonly backgroundColor?: string;
-  readonly bold?: boolean;
-  readonly italic?: boolean;
-  readonly dim?: boolean;
-  readonly underlineStyle?: "single" | "double" | "curly" | "dotted" | "dashed";
-}
+declare function disableKittyKeyboard(): string;
+//#endregion
+//#region packages/ansi/src/style/style.d.ts
 /**
- * Metadata describing a DesignSystem's Theme shape — for tooling (docs,
- * storybook, CSS export). Plain data, no functions.
+ * 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).
  */
-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";
+declare function resolveThemeColor(name: string | undefined, theme: object | undefined): string | undefined;
+//#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;
 }
 /**
- * The `DesignSystem` contract. Sterling is the default implementation; other
- * packages (e.g. `@silvery/design-material`) publish alternatives matching
- * this shape.
+ * Derive a Theme from a ColorScheme, with Sterling flat tokens baked in.
+ *
+ * Every Theme `@silvery/ansi` produces passes through `inlineSterlingTokens`
+ * so consumers can read `$bg-accent`, `$bg-surface-overlay`, `$border-default`,
+ * `$fg-muted`, etc. directly off the returned object. This is the one
+ * canonical Theme shape in silvery — there is no separate "partial" Theme.
  */
-interface DesignSystem {
-  /** Display name for tooling (e.g. `"sterling"`). */
-  readonly name: string;
-  /** Metadata about this system's Theme shape. */
-  readonly shape: ThemeShape;
+declare function deriveTheme(palette: ColorScheme, mode?: "ansi16" | "truecolor", adjustments?: ThemeAdjustment[]): Theme;
+//#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" | "derived" | "fallback";
+interface DetectSchemeResult {
+  /** The resolved 22-slot color scheme. */
+  scheme: ColorScheme;
+  /** The derived, validated Theme (via loadTheme). */
+  theme: Theme;
+  /** 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;
   /**
-   * 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.
+   * Apply strict invariant validation to the loaded Theme. Default `lenient`.
+   * See `loadTheme`'s `enforce` parameter.
    */
-  readonly flatten?: boolean | FlattenRule;
-  /** Return a raw default Theme, no input required. */
-  defaults(mode?: "light" | "dark"): Theme;
+  enforce?: "strict" | "lenient" | "off";
+  /** Add WCAG contrast check to the invariant validation. Default `false`. */
+  wcag?: boolean;
   /**
-   * Fill partial theme values with defaults. Useful for hand-curated themes
-   * that override a few roles.
+   * Optional InputOwner (from `@silvery/ag-term/runtime`). When provided,
+   * OSC queries route through it instead of touching process.stdin directly.
+   * See `probeColors` for the ownership rationale.
    */
-  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;
+  input?: ProbeInputOwner;
 }
-/** 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.
+ * Detect the terminal's color scheme + derive a theme in one call.
+ *
+ * Runs the 4-layer detection cascade (override → probe → fingerprint →
+ * fallback) and returns a fully-resolved Theme along with provenance metadata
+ * so callers can log how the scheme was determined.
+ *
+ * This is the recommended entry point for apps — it handles all the gotchas
+ * (non-TTY environments, failed probes, partial OSC responses, catalog matches,
+ * bg-mode inference) and returns something you can hand to `ThemeProvider`.
+ *
+ * @example
+ * ```ts
+ * import { detectScheme } from "@silvery/ansi"
+ * import { builtinPalettes } from "@silvery/theme/schemes"
+ *
+ * const { scheme, theme, source, matchedName, confidence } = await detectScheme({
+ *   catalog: Object.values(builtinPalettes),
+ *   enforce: "lenient",
+ * })
+ * console.log(`${source === "fingerprint" ? `detected ${matchedName}` : source} (${(confidence * 100).toFixed(0)}%)`)
+ * ```
  */
-declare const sterling: DesignSystem;
-//#endregion
-//#region packages/theme/src/sterling/define.d.ts
+declare function detectScheme(opts?: DetectSchemeOptions): Promise<DetectSchemeResult>;
 /**
- * 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.
+ * Shortcut: detect scheme + return the Theme only. For apps that don't care
+ * about provenance. Same defaults as `detectScheme`.
+ *
+ * @example
+ * ```ts
+ * const theme = await detectSchemeTheme({ catalog: Object.values(builtinPalettes) })
+ * render(<ThemeProvider theme={theme}>…</ThemeProvider>)
+ * ```
  */
-declare function defineDesignSystem(def: DesignSystem): DesignSystem;
+declare function detectSchemeTheme(opts?: DetectSchemeOptions): Promise<Theme>;
 //#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[]);
-}
+//#region packages/ansi/src/theme/tokens.d.ts
 /**
- * Verify `fg` on `bg` meets `target` ratio. Returns `null` when already
- * passing; otherwise returns a ContrastViolation.
+ * Built-in variant names — the standard typography presets shipped by silvery.
+ * These are the default keys in `Theme.variants`.
  */
-declare function checkAA(token: string, fg: string, bg: string, target?: number): ContrastViolation | null;
+type VariantName = "h1" | "h2" | "h3" | "body" | "body-muted" | "fine-print" | "strong" | "em" | "link" | "key" | "code" | "kbd";
 /**
- * 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).
+ * 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.
  */
-declare function autoLift(fg: string, bg: string, target?: number): {
-  value: string;
-  lifted: boolean;
-};
+type KnownVariant = VariantName | (string & {});
 //#endregion
-//#region packages/theme/src/sterling/derive.d.ts
+//#region packages/ansi/src/osc-palette.d.ts
 /**
- * Derive a Theme's nested roles from a ColorScheme. Guardrails applied.
+ * OSC 4 Terminal Color Palette Query/Set — pure ANSI protocol.
  */
-declare function deriveRoles(scheme: ColorScheme, opts: DeriveOptions): {
-  roles: Roles;
-  mode: "light" | "dark";
-  trace: DerivationStep[];
-  violations: ContrastViolation[];
-};
+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
+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
 /**
- * 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.
+ * Generate a complete ANSI 16 theme from a primary color + dark/light preference.
  *
- * Returned Theme is NOT frozen and DOES NOT contain flat keys yet.
+ * All token values are ANSI color names (e.g. "yellow", "blueBright").
  */
-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;
+declare function generateTheme(primary: AnsiPrimary, dark: boolean): Theme;
 //#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
+export { BorderRole as $, quantizeHex as A, createTerminalProfile as B, deriveTheme as C, enableKittyKeyboard as D, disableMouse as E, defaultCaps as F, detectTheme as G, DetectThemeOptions as H, ColorProvenance as I, AnsiPrimary as J, probeColors as K, CreateTerminalProfileOptions as L, RGB as M, UnderlineStyle as N, enableMouse as O, TerminalCaps as P, AccentRole as Q, ProbeTerminalProfileOptions as R, detectSchemeTheme as S, disableKittyKeyboard as T, DetectedScheme as U, probeTerminalProfile as V, detectTerminalScheme as W, ColorScheme as X, COLOR_SCHEME_FIELDS as Y, HueName as Z, DetectSchemeOptions as _, bakeFlat as _t, queryForegroundColor as a, DeriveOptions as at, SlotSource as b, resetForegroundColor as c, FlatTokens as ct, setForegroundColor as d, Roles as dt, ContrastMode as et, parsePaletteResponse as f, StatePair as ft, KnownVariant as g, FlattenRule as gt, setPaletteColor as h, ThemeShape as ht, queryCursorColor as i, DerivationTrace as it, ColorLevel as j, pickColorLevel as k, setBackgroundColor as l, InteractiveRole as lt, queryPaletteColor as m, Theme as mt, detectColorScheme as n, DeepPartial as nt, resetBackgroundColor as o, DesignSystem as ot, queryMultiplePaletteColors as p, SurfaceRole as pt, ActiveScheme as q, queryBackgroundColor as r, DerivationStep as rt, resetCursorColor as s, FlatToken as st, generateTheme as t, CursorRole as tt, setCursorColor as u, MutedRole as ut, DetectSchemeResult as v, defaultFlattenRule as vt, resolveThemeColor as w, detectScheme as x, DetectSource as y, TerminalEmulator as yt, TerminalProfile as z };
+//# sourceMappingURL=index-CSQf13CI.d.mts.map