silvery 0.19.2 → 0.21.1

package/dist/src-Oe6x5PrS.mjs

@@ -0,0 +1,4621 @@
+import { blend, brighten, checkContrast, colorDistance, complement, contrastFg, darken, deltaE, ensureContrast, hexToOklch, hexToRgb as hexToRgb$1, oklchToHex, relativeLuminance } from "@silvery/color";
+import "string-width";
+//#region packages/ansi/src/constants.ts
+/**
+* ANSI escape code constants for extended terminal features.
+*
+* @see https://sw.kovidgoyal.net/kitty/underlines/
+* @see https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda
+*/
+/**
+* Extended underline style codes.
+* Uses colon-separated parameters (ISO 8613-6): \x1b[4:Nm
+*/
+const UNDERLINE_CODES = {
+	/** No underline */
+	none: "\x1B[4:0m",
+	/** Standard single underline */
+	single: "\x1B[4:1m",
+	/** Double underline (two parallel lines) */
+	double: "\x1B[4:2m",
+	/** Curly/wavy underline (spell check style) */
+	curly: "\x1B[4:3m",
+	/** Dotted underline */
+	dotted: "\x1B[4:4m",
+	/** Dashed underline */
+	dashed: "\x1B[4:5m",
+	/** Reset extended underline (same as none) */
+	reset: "\x1B[4:0m"
+};
+/** Standard underline on (SGR 4) - works on all terminals */
+const UNDERLINE_STANDARD = "\x1B[4m";
+/** Standard underline off (SGR 24) */
+const UNDERLINE_RESET_STANDARD = "\x1B[24m";
+/**
+* Reset underline color to default (SGR 59)
+*/
+const UNDERLINE_COLOR_RESET = "\x1B[59m";
+/**
+* Build underline color escape code for RGB values.
+* Format: \x1b[58:2::r:g:bm (SGR 58 with RGB color space)
+*/
+function buildUnderlineColorCode(r, g, b) {
+	return `\x1b[58:2::${r}:${g}:${b}m`;
+}
+//#endregion
+//#region packages/ansi/src/caps.ts
+/**
+* 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})`.
+*/
+function defaultCaps() {
+	return {
+		cursor: false,
+		input: false,
+		colorLevel: "truecolor",
+		colorForced: false,
+		colorProvenance: "auto",
+		unicode: true,
+		underlineStyles: [
+			"double",
+			"curly",
+			"dotted",
+			"dashed"
+		],
+		underlineColor: true,
+		overline: true,
+		textSizing: false,
+		kittyKeyboard: false,
+		bracketedPaste: true,
+		mouse: true,
+		kittyGraphics: false,
+		sixel: false,
+		osc52: false,
+		hyperlinks: false,
+		notifications: false,
+		syncOutput: false,
+		maybeDarkBackground: true,
+		maybeNerdFont: false,
+		maybeWideEmojis: true
+	};
+}
+//#endregion
+//#region packages/ansi/src/emulator.ts
+/**
+* Default emulator identity — unknown terminal, unversioned, no `TERM` set.
+* Matches what a non-TTY Node process sees when run from CI without env vars.
+*/
+function defaultEmulator() {
+	return {
+		program: "",
+		version: "",
+		TERM: ""
+	};
+}
+//#endregion
+//#region packages/ansi/src/theme/invariants.ts
+/**
+* Theme invariants — post-derivation visibility + optional WCAG checks.
+*
+* Two independent invariant groups:
+*
+* 1. **Visibility (always checked)** — selection and cursor must be
+*    distinguishable from bg. These fail silently because ensureContrast
+*    doesn't touch `bg-selected`/`bg-cursor`; you get "invisible selection"
+*    bugs that only surface via user complaints.
+*
+* 2. **WCAG contrast (opt-in)** — `deriveTheme()` already runs `ensureContrast`
+*    on every text/bg pair as it builds the Theme (lenient auto-adjust). A
+*    second validation pass is redundant for normal use. Enable it explicitly
+*    at build time to *verify* that shipped themes meet the targets, or when
+*    loading a hand-authored Theme object that skipped `deriveTheme`.
+*
+* This is why `validateThemeInvariants` defaults to `{ wcag: false }` — the
+* existing derivation already handles contrast. Callers opt in via
+* `validateThemeInvariants(theme, { wcag: true })` for strict pre-ship audits.
+*
+* All token access is Sterling-shaped — flat hyphen keys (`bg-accent`,
+* `fg-on-error`, `border-focus`) exist on every Theme via the derive +
+* bakeFlat pipeline. No concat-kebab legacy names (`primaryfg`, `mutedbg`, …)
+* — those were removed in silvery 0.19.0 (Sterling interior migration).
+*/
+const AA_RATIO = 4.5;
+const FAINT_RATIO = 1.5;
+const SELECTION_DELTA_L$1 = .08;
+const CURSOR_DELTA_E$1 = .15;
+/**
+* Contrast invariant pairs — all Sterling flat-token keys.
+*
+* These keys are populated on every Theme at derivation time via `bakeFlat`;
+* bracket access (`theme["bg-accent"]`) is the canonical lookup form and is
+* what `validateThemeInvariants` uses below.
+*/
+const CONTRAST_PAIRS = [
+	{
+		rule: "contrast:fg/bg",
+		fg: "fg",
+		bg: "bg",
+		min: AA_RATIO
+	},
+	{
+		rule: "contrast:fg/bg-surface-default",
+		fg: "fg",
+		bg: "bg-surface-default",
+		min: AA_RATIO
+	},
+	{
+		rule: "contrast:fg/bg-surface-subtle",
+		fg: "fg",
+		bg: "bg-surface-subtle",
+		min: AA_RATIO
+	},
+	{
+		rule: "contrast:fg/bg-surface-raised",
+		fg: "fg",
+		bg: "bg-surface-raised",
+		min: AA_RATIO
+	},
+	{
+		rule: "contrast:fg/bg-surface-hover",
+		fg: "fg",
+		bg: "bg-surface-hover",
+		min: AA_RATIO
+	},
+	{
+		rule: "contrast:fg/bg-surface-overlay",
+		fg: "fg",
+		bg: "bg-surface-overlay",
+		min: AA_RATIO
+	},
+	{
+		rule: "contrast:fg/bg-muted",
+		fg: "fg",
+		bg: "bg-muted",
+		min: AA_RATIO
+	},
+	{
+		rule: "contrast:fg-muted/bg",
+		fg: "fg-muted",
+		bg: "bg",
+		min: 3
+	},
+	{
+		rule: "contrast:fg-muted/bg-muted",
+		fg: "fg-muted",
+		bg: "bg-muted",
+		min: 3
+	},
+	{
+		rule: "contrast:fg-accent/bg",
+		fg: "fg-accent",
+		bg: "bg",
+		min: AA_RATIO
+	},
+	{
+		rule: "contrast:fg-error/bg",
+		fg: "fg-error",
+		bg: "bg",
+		min: AA_RATIO
+	},
+	{
+		rule: "contrast:fg-warning/bg",
+		fg: "fg-warning",
+		bg: "bg",
+		min: AA_RATIO
+	},
+	{
+		rule: "contrast:fg-success/bg",
+		fg: "fg-success",
+		bg: "bg",
+		min: AA_RATIO
+	},
+	{
+		rule: "contrast:fg-info/bg",
+		fg: "fg-info",
+		bg: "bg",
+		min: AA_RATIO
+	},
+	{
+		rule: "contrast:fg-on-accent/bg-accent",
+		fg: "fg-on-accent",
+		bg: "bg-accent",
+		min: AA_RATIO
+	},
+	{
+		rule: "contrast:fg-on-error/bg-error",
+		fg: "fg-on-error",
+		bg: "bg-error",
+		min: AA_RATIO
+	},
+	{
+		rule: "contrast:fg-on-warning/bg-warning",
+		fg: "fg-on-warning",
+		bg: "bg-warning",
+		min: AA_RATIO
+	},
+	{
+		rule: "contrast:fg-on-success/bg-success",
+		fg: "fg-on-success",
+		bg: "bg-success",
+		min: AA_RATIO
+	},
+	{
+		rule: "contrast:fg-on-info/bg-info",
+		fg: "fg-on-info",
+		bg: "bg-info",
+		min: AA_RATIO
+	},
+	{
+		rule: "contrast:fg-on-selected/bg-selected",
+		fg: "fg-on-selected",
+		bg: "bg-selected",
+		min: AA_RATIO
+	},
+	{
+		rule: "contrast:fg-cursor/bg-cursor",
+		fg: "fg-cursor",
+		bg: "bg-cursor",
+		min: AA_RATIO
+	},
+	{
+		rule: "contrast:border-default/bg",
+		fg: "border-default",
+		bg: "bg",
+		min: 3
+	},
+	{
+		rule: "contrast:border-focus/bg",
+		fg: "border-focus",
+		bg: "bg",
+		min: 3
+	},
+	{
+		rule: "contrast:border-muted/bg",
+		fg: "border-muted",
+		bg: "bg",
+		min: FAINT_RATIO
+	}
+];
+function lightness(hex) {
+	const o = hexToOklch(hex);
+	return o ? o.L : null;
+}
+/**
+* Validate post-derivation invariants on a Theme.
+*
+* Default: visibility checks only (selection ΔL, cursor ΔE). These are
+* invariants that `deriveTheme` doesn't enforce and that matter for every
+* theme regardless of authoring pedigree.
+*
+* Opt into WCAG contrast checks via `{ wcag: true }`. Use at build-time to
+* verify bundled themes, or when loading hand-authored Theme objects that
+* didn't flow through `deriveTheme`'s `ensureContrast` pass.
+*
+* Non-hex values (ANSI names from `ansi16` mode) are skipped with no
+* violation — ANSI 16 themes can't be contrast-checked in hex space.
+*
+* @example
+* ```ts
+* // Default — visibility only, fast
+* const { ok, violations } = validateThemeInvariants(theme)
+*
+* // Build-time audit — full WCAG check
+* const audit = validateThemeInvariants(theme, { wcag: true })
+* ```
+*/
+function validateThemeInvariants(theme, opts = {}) {
+	const checkWcag = opts.wcag ?? false;
+	const checkVisibility = opts.visibility ?? true;
+	const violations = [];
+	if (checkWcag) {
+		const themeRecord = theme;
+		for (const pair of CONTRAST_PAIRS) {
+			const fg = themeRecord[pair.fg];
+			const bg = themeRecord[pair.bg];
+			if (typeof fg !== "string" || typeof bg !== "string") continue;
+			const r = checkContrast(fg, bg);
+			if (r === null) continue;
+			if (r.ratio < pair.min) violations.push({
+				rule: pair.rule,
+				tokens: [pair.fg, pair.bg],
+				actual: r.ratio,
+				required: pair.min,
+				message: `${pair.fg} (${fg}) on ${pair.bg} (${bg}) is ${r.ratio.toFixed(2)}:1, needs ${pair.min.toFixed(1)}:1`
+			});
+		}
+	}
+	if (checkVisibility) {
+		const themeAny = theme;
+		const selectionBg = themeAny["bg-selected"] ?? "";
+		const cursorBg = themeAny["bg-cursor"] ?? themeAny["cursorbg"] ?? "";
+		const selectionKey = "bg-selected";
+		const cursorKey = themeAny["bg-cursor"] !== void 0 ? "bg-cursor" : "cursorbg";
+		const lBg = lightness(theme.bg);
+		const lSelBg = lightness(selectionBg);
+		if (lBg !== null && lSelBg !== null) {
+			const dL = Math.abs(lSelBg - lBg);
+			if (dL < .08) violations.push({
+				rule: "visibility:selection",
+				tokens: [selectionKey, "bg"],
+				actual: dL,
+				required: SELECTION_DELTA_L$1,
+				message: `${selectionKey} (${selectionBg}) differs from bg (${theme.bg}) by ΔL=${dL.toFixed(3)}, needs ≥ ${SELECTION_DELTA_L$1.toFixed(2)}`
+			});
+		}
+		const oBg = hexToOklch(theme.bg);
+		const oCursorBg = hexToOklch(cursorBg);
+		if (oBg && oCursorBg) {
+			const de = deltaE(oBg, oCursorBg);
+			if (de < .15) violations.push({
+				rule: "visibility:cursor",
+				tokens: [cursorKey, "bg"],
+				actual: de,
+				required: CURSOR_DELTA_E$1,
+				message: `${cursorKey} (${cursorBg}) differs from bg (${theme.bg}) by ΔE=${de.toFixed(3)}, needs ≥ ${CURSOR_DELTA_E$1.toFixed(2)}`
+			});
+		}
+	}
+	return {
+		ok: violations.length === 0,
+		violations
+	};
+}
+/**
+* Format violations as a multiline error message for throws/logs.
+*/
+function formatViolations(violations) {
+	if (violations.length === 0) return "";
+	return violations.map((v) => `  - [${v.rule}] ${v.message}`).join("\n");
+}
+/**
+* Thrown by `loadTheme({ mode: "strict" })` when invariants fail.
+* Carries the violations array for programmatic inspection.
+*/
+var ThemeInvariantError = class extends Error {
+	violations;
+	constructor(violations) {
+		super(`Theme invariants failed (${violations.length} violation${violations.length === 1 ? "" : "s"}):\n${formatViolations(violations)}`);
+		this.name = "ThemeInvariantError";
+		this.violations = violations;
+	}
+};
+//#endregion
+//#region packages/ansi/src/theme/derived.ts
+/**
+* deriveFields — single helper that fills all derived theme sections.
+*
+* Eliminates 4-way duplication of brand, categorical ring, state-variant, and
+* variants population across:
+*   - derive.ts   (deriveTruecolorTheme + deriveAnsi16Theme)
+*   - default-schemes.ts (ansi16DarkTheme + ansi16LightTheme)
+*   - @silvery/theme/generate.ts   (generateTheme)
+*   - @silvery/theme/schemes/index.ts (ansi16DarkTheme + ansi16LightTheme)
+*
+* Canonical authority: derive.ts truecolor path. ANSI16 paths are aligned to
+* deriveAnsi16Theme output (which is itself the canonical ANSI16 reference).
+*/
+/** Default typography variants — token-based, works across any theme. */
+const DEFAULT_VARIANTS$1 = {
+	h1: {
+		color: "$primary",
+		bold: true
+	},
+	h2: {
+		color: "$accent",
+		bold: true
+	},
+	h3: { bold: true },
+	body: {},
+	"body-muted": { color: "$muted" },
+	"fine-print": {
+		color: "$muted",
+		dim: true
+	},
+	strong: { bold: true },
+	em: { italic: true },
+	link: {
+		color: "$fg-link",
+		underlineStyle: "single"
+	},
+	key: {
+		color: "$accent",
+		bold: true
+	},
+	code: { backgroundColor: "$mutedbg" },
+	kbd: {
+		backgroundColor: "$mutedbg",
+		color: "$accent",
+		bold: true
+	}
+};
+/**
+* Derive the shared "delta" fields common to every theme object:
+* brand tokens, categorical ring, state variants, and typography variants.
+*
+* Pass a `shift` function for truecolor hover/active derivation (OKLCH
+* brighten/darken). Omit `shift` for ANSI16 — hover/active fall back to the
+* base color (no intermediate intensities available on 16-color terminals).
+*
+* @example
+* // Truecolor (dark theme)
+* import { brighten, darken } from "@silvery/color"
+* deriveFields({ shift: (hex, a) => brighten(hex, a), primary, ... })
+*
+* @example
+* // ANSI16 — no shift function
+* deriveFields({ primary, accent, fg, selectionbg, surfacebg, ring })
+*/
+function deriveFields(input) {
+	const { dark, shift, primary, accent, fg, selectionbg, surfacebg, ring } = input;
+	const applyShift = dark !== void 0 ? (color, amount) => dark ? brighten(color, amount) : darken(color, amount) : shift ?? ((color, _amount) => color);
+	return {
+		brand: primary,
+		"brand-hover": applyShift(primary, .04),
+		"brand-active": applyShift(primary, .08),
+		...ring,
+		"primary-hover": applyShift(primary, .04),
+		"primary-active": applyShift(primary, .08),
+		"accent-hover": applyShift(accent, .04),
+		"accent-active": applyShift(accent, .08),
+		"fg-hover": applyShift(fg, .04),
+		"fg-active": applyShift(fg, .08),
+		"bg-selected-hover": applyShift(selectionbg, .04),
+		"bg-surface-hover": applyShift(surfacebg, .04),
+		variants: DEFAULT_VARIANTS$1
+	};
+}
+//#endregion
+//#region packages/ansi/src/sterling/contrast.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. */
+const WCAG_AA = 4.5;
+var ContrastError = class extends Error {
+	violations;
+	constructor(violations) {
+		const summary = violations.slice(0, 5).map((v) => `${v.token}: ${v.ratio.toFixed(2)} < ${v.target} (fg=${v.fg}, bg=${v.bg})`).join("; ");
+		const extra = violations.length > 5 ? ` (+${violations.length - 5} more)` : "";
+		super(`Sterling contrast: ${violations.length} violation(s): ${summary}${extra}`);
+		this.name = "ContrastError";
+		this.violations = violations;
+	}
+};
+/**
+* Verify `fg` on `bg` meets `target` ratio. Returns `null` when already
+* passing; otherwise returns a ContrastViolation.
+*/
+function checkAA(token, fg, bg, target = WCAG_AA) {
+	const r = checkContrast(fg, bg);
+	if (!r) return null;
+	if (r.ratio >= target) return null;
+	return {
+		token,
+		fg,
+		bg,
+		ratio: r.ratio,
+		target
+	};
+}
+/**
+* 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).
+*/
+function autoLift(fg, bg, target = WCAG_AA) {
+	const current = checkContrast(fg, bg);
+	if (!current) return {
+		value: fg,
+		lifted: false
+	};
+	if (current.ratio >= target) return {
+		value: fg,
+		lifted: false
+	};
+	const adjusted = ensureContrast(fg, bg, target);
+	return {
+		value: adjusted,
+		lifted: adjusted !== fg
+	};
+}
+//#endregion
+//#region packages/ansi/src/sterling/derive.ts
+/**
+* Sterling derivation — preservative OKLCH rules over a 22-color ColorScheme.
+*
+* Implements design-system.md §"Derivation rules" with guardrails from D3.
+* Produces the nested `Roles` shape. `flatten.ts` projects the flat keys.
+*
+* Derivation is:
+*   1. `scheme.primary` (or fallback) → accent.fg / accent.bg / info.fg
+*   2. status roles from `scheme.red / yellow / green / primary`
+*   3. Adaptive OKLCH hover/active L-shift (direction = base-L, not scheme.dark):
+*        baseL > 0.6  → darken (hover −0.04L, active −0.08L)
+*        baseL ≤ 0.6  → brighten (hover +0.04L, active +0.08L)
+*      At L extremes (target L > 0.9 or < 0.1) chroma is proportionally
+*      reduced so the color pushes toward gray instead of collapsing to
+*      white/black — fixes the Frappe yellow/light-accent whiteout.
+*   4. `fgOn` picked for WCAG AA against role's `bg` (prefers scheme bg/fg)
+*   5. surface ramp via OKLCH blend
+*   6. contrast guardrail: strict throws, auto-lift adjusts
+*
+* Per-hue delta adaptation: yellows (H ∈ [80, 110]) get ±0.06L / ±0.10L,
+* low-chroma schemes (C < 0.05) get ±0.06L / ±0.10L. Everything else uses
+* the standard ±0.04L / ±0.08L.
+*
+* Pinned tokens (via `DeriveOptions.pins`) bypass both the rule and
+* auto-lift; they're written verbatim onto the Theme.
+*/
+/**
+* Default typography variants — token-based, works across any Sterling theme.
+* Consumed by `<Text variant="h1">` via the theme's `variants` record.
+*
+* Keys use Sterling flat-token names in their color slots (`$fg-accent`,
+* `$fg-muted`, `$bg-muted`) so the defaults resolve against every Sterling-
+* derived Theme without further wiring.
+*/
+const DEFAULT_VARIANTS = {
+	h1: {
+		color: "$fg-accent",
+		bold: true
+	},
+	h2: {
+		color: "$fg-accent",
+		bold: true
+	},
+	h3: { bold: true },
+	h4: {
+		color: "$fg-muted",
+		bold: true
+	},
+	h5: {
+		color: "$fg-muted",
+		italic: true
+	},
+	h6: {
+		color: "$fg-muted",
+		dim: true
+	},
+	body: {},
+	"body-muted": { color: "$fg-muted" },
+	"fine-print": {
+		color: "$fg-muted",
+		dim: true
+	},
+	strong: { bold: true },
+	em: { italic: true },
+	link: {
+		color: "$fg-accent",
+		underlineStyle: "single"
+	},
+	key: {
+		color: "$fg-accent",
+		bold: true
+	},
+	code: { backgroundColor: "$bg-muted" },
+	kbd: {
+		backgroundColor: "$bg-muted",
+		color: "$fg-accent",
+		bold: true
+	}
+};
+/**
+* Build the 16-slot ANSI palette from a ColorScheme. Indexed `$color0` …
+* `$color15` by the framework's token resolver.
+*/
+function buildPalette(scheme) {
+	return [
+		scheme.black,
+		scheme.red,
+		scheme.green,
+		scheme.yellow,
+		scheme.blue,
+		scheme.magenta,
+		scheme.cyan,
+		scheme.white,
+		scheme.brightBlack,
+		scheme.brightRed,
+		scheme.brightGreen,
+		scheme.brightYellow,
+		scheme.brightBlue,
+		scheme.brightMagenta,
+		scheme.brightCyan,
+		scheme.brightWhite
+	];
+}
+/**
+* Derive the 8-hue categorical ring from a ColorScheme. Mirrors the legacy
+* derive.ts logic — blends scheme hues for the missing Sterling slots
+* (orange from red+yellow, teal from green+cyan, pink from magenta+red).
+*/
+function buildCategoricalHues(scheme) {
+	const dark = scheme.dark ?? true;
+	return {
+		red: scheme.red,
+		orange: blend(scheme.red, scheme.yellow, .5),
+		yellow: scheme.yellow,
+		green: scheme.green,
+		teal: blend(scheme.green, scheme.cyan, .5),
+		blue: dark ? scheme.brightBlue : scheme.blue,
+		purple: scheme.magenta,
+		pink: blend(scheme.magenta, scheme.red, .5)
+	};
+}
+function isYellowish(hex) {
+	const o = hexToOklch(hex);
+	if (!o) return false;
+	return o.H >= 80 && o.H <= 120;
+}
+function isLowChroma(hex) {
+	const o = hexToOklch(hex);
+	if (!o) return false;
+	return o.C < .05;
+}
+/** Compute state-shift deltas for a given base color. Wider for yellows + low-chroma. */
+function stateDeltas(base) {
+	if (isYellowish(base) || isLowChroma(base)) return {
+		hover: .06,
+		active: .1
+	};
+	return {
+		hover: .04,
+		active: .08
+	};
+}
+/**
+* Adaptive L-shift: direction follows the token's own luminance, NOT
+* scheme.dark. High-L tokens (yellows, light accents) darken; low-L tokens
+* brighten. Uniform handling — yields a reliable "more active than hover"
+* relationship no matter what hue/lightness the base is.
+*
+* Chroma preservation at L extremes: when the target L pushes past 0.9
+* (approaching white) or below 0.1 (approaching black), chroma is scaled
+* down proportionally so the color drifts toward gray rather than
+* collapsing to #FFFFFF or #000000. This preserves perceptual differences
+* between the base / hover / active states even on intrinsically-bright
+* tokens (catppuccin-frappe yellow, light blue accents, etc.).
+*
+* Returns the original hex unchanged when OKLCH parsing fails.
+*/
+function shiftL(hex, amount) {
+	const o = hexToOklch(hex);
+	if (!o) return hex;
+	const direction = o.L > .6 ? -1 : 1;
+	const targetL = clamp01(o.L + direction * amount);
+	let nextC = o.C;
+	if (targetL > .9 || targetL < .1) {
+		const factor = clamp01(1 - Math.abs(targetL - .5) * 2);
+		nextC = o.C * factor;
+	}
+	return oklchToHex({
+		L: targetL,
+		C: nextC,
+		H: o.H
+	});
+}
+function clamp01(x) {
+	return x < 0 ? 0 : x > 1 ? 1 : x;
+}
+/** Label the direction the adaptive L-shift took, for trace rule strings. */
+function shiftLabel(hex) {
+	const o = hexToOklch(hex);
+	if (!o) return "brighten";
+	return o.L > .6 ? "darken" : "brighten";
+}
+function inferMode(scheme, explicit) {
+	if (explicit) return explicit;
+	if (typeof scheme.dark === "boolean") return scheme.dark ? "dark" : "light";
+	const lum = relativeLuminance(scheme.background);
+	return lum !== null && lum < .5 ? "dark" : "light";
+}
+/**
+* Pick a foreground color to draw on a filled `bg` of a role. Prefers
+* `scheme.background` if it beats AA against the role bg (i.e. the role bg
+* is bright enough that using dark text reads); otherwise `scheme.foreground`;
+* otherwise falls back to white/black by bg luminance.
+*/
+function pickFgOn(roleBg, scheme) {
+	const candidates = [
+		scheme.foreground,
+		scheme.background,
+		"#FFFFFF",
+		"#000000"
+	];
+	let best = candidates[0];
+	let bestRatio = 0;
+	for (const c of candidates) {
+		const r = checkAA("fgOn", c, roleBg);
+		if (r === null) return c;
+		if (r.ratio > bestRatio) {
+			best = c;
+			bestRatio = r.ratio;
+		}
+	}
+	return best;
+}
+/**
+* Resolve a pin for a token path. Accepts both nested (`"accent.hover.bg"`)
+* and flat (`"bg-accent-hover"`) forms. Returns the pinned hex or undefined.
+*/
+function pin(pins, nested, flat) {
+	if (!pins) return void 0;
+	return pins[nested] ?? pins[flat];
+}
+/**
+* Shared guard: handles pin → rule → contrast check → auto-lift → record.
+* `target` defaults to WCAG_AA (4.5); callers use 3.0 for "muted" tokens
+* that are deemphasized by design.
+*/
+function guardTarget(nestedPath, flatPath, rule, inputs, value, against, target, contrast, pins, trace, violations) {
+	const pinned = pin(pins, nestedPath, flatPath);
+	if (pinned !== void 0) {
+		trace.push({
+			token: nestedPath,
+			rule: "pinned by scheme author",
+			inputs: [pinned],
+			output: pinned,
+			pinned: true
+		});
+		return pinned;
+	}
+	if (against === void 0) {
+		trace.push({
+			token: nestedPath,
+			rule,
+			inputs,
+			output: value
+		});
+		return value;
+	}
+	if (checkAA(nestedPath, value, against, target) === null) {
+		trace.push({
+			token: nestedPath,
+			rule,
+			inputs,
+			output: value
+		});
+		return value;
+	}
+	const lifted = autoLift(value, against, target);
+	const finalValue = lifted.value;
+	const residual = checkAA(nestedPath, finalValue, against, target);
+	if (residual !== null) violations.push(residual);
+	trace.push({
+		token: nestedPath,
+		rule: lifted.lifted ? `${rule} + auto-lift` : rule,
+		inputs,
+		output: finalValue,
+		...lifted.lifted ? { liftedFrom: value } : {}
+	});
+	return finalValue;
+}
+/**
+* Derive a Theme's nested roles from a ColorScheme. Guardrails applied.
+*/
+function deriveRoles(scheme, opts) {
+	const mode = inferMode(scheme, opts.mode);
+	const contrast = opts.contrast ?? "auto-lift";
+	const pins = opts.pins;
+	const trace = [];
+	const violations = [];
+	const primary = scheme.primary ?? (mode === "dark" ? scheme.brightBlue : scheme.blue);
+	const bg = scheme.background;
+	const fg = scheme.foreground;
+	function guard(nestedPath, flatPath, rule, inputs, value, against, target = WCAG_AA) {
+		return guardTarget(nestedPath, flatPath, rule, inputs, value, against, target, contrast, pins, trace, violations);
+	}
+	const accentBase = guard("accent.fg", "fg-accent", "scheme.primary", [primary], primary, bg);
+	const accentBg = guard("accent.bg", "bg-accent", "scheme.primary", [primary], primary);
+	const deltaA = stateDeltas(accentBg);
+	const bgDir = shiftLabel(accentBg);
+	const accentHoverBg = guard("accent.hover.bg", "bg-accent-hover", `OKLCH ${bgDir} ${deltaA.hover}L on accent.bg`, [accentBg], shiftL(accentBg, deltaA.hover));
+	const accentActiveBg = guard("accent.active.bg", "bg-accent-active", `OKLCH ${bgDir} ${deltaA.active}L on accent.bg`, [accentBg], shiftL(accentBg, deltaA.active));
+	const accentFgOn = guard("accent.fgOn", "fg-on-accent", "contrast-pick(scheme.fg/bg/BW)", [accentBg], pickFgOn(accentBg, scheme), accentBg);
+	const accentBorder = guard("accent.border", "border-accent", "= accent.bg", [accentBg], accentBg);
+	const fgDir = shiftLabel(accentBase);
+	const accentHoverFg = guard("accent.hover.fg", "fg-accent-hover", `OKLCH ${fgDir} ${deltaA.hover}L on accent.fg`, [accentBase], shiftL(accentBase, deltaA.hover), bg);
+	const accentActiveFg = guard("accent.active.fg", "fg-accent-active", `OKLCH ${fgDir} ${deltaA.active}L on accent.fg`, [accentBase], shiftL(accentBase, deltaA.active), bg);
+	const accent = {
+		fg: accentBase,
+		bg: accentBg,
+		fgOn: accentFgOn,
+		border: accentBorder,
+		hover: {
+			fg: accentHoverFg,
+			bg: accentHoverBg
+		},
+		active: {
+			fg: accentActiveFg,
+			bg: accentActiveBg
+		}
+	};
+	const info = buildInteractive("info", primary, scheme, opts, trace, violations);
+	const success = buildInteractive("success", scheme.green, scheme, opts, trace, violations);
+	const warning = buildInteractive("warning", scheme.yellow, scheme, opts, trace, violations);
+	const error = buildInteractive("error", scheme.red, scheme, opts, trace, violations);
+	const mutedBg = guard("muted.bg", "bg-muted", "blend(bg, fg, 0.08)", [bg, fg], blend(bg, fg, .08));
+	const muted = {
+		fg: guard("muted.fg", "fg-muted", "blend(fg, bg, 0.4)", [fg, bg], blend(fg, bg, .4), mutedBg, 3),
+		bg: mutedBg
+	};
+	const fgForSurfaceLift = ensureContrast(fg, blend(bg, fg, .08), WCAG_AA);
+	const surfaceDefault = guard("surface.default", "bg-surface-default", "scheme.background", [bg], bg);
+	const surface = {
+		default: surfaceDefault,
+		subtle: guard("surface.subtle", "bg-surface-subtle", "blend(bg, fg, 0.03)", [bg, fg], blend(bg, fg, .03), fgForSurfaceLift, WCAG_AA),
+		raised: guard("surface.raised", "bg-surface-raised", "blend(bg, fg, 0.10)", [bg, fg], blend(bg, fg, .1), fgForSurfaceLift, WCAG_AA),
+		overlay: guard("surface.overlay", "bg-surface-overlay", "blend(bg, fg, 0.12)", [bg, fg], blend(bg, fg, .12), fgForSurfaceLift, WCAG_AA),
+		hover: guard("surface.hover", "bg-surface-hover", "blend(bg, fg, 0.10)", [bg, fg], blend(bg, fg, .1), fgForSurfaceLift, WCAG_AA)
+	};
+	const borderDefault = guard("border.default", "border-default", "blend(bg, fg, 0.18)", [bg, fg], blend(bg, fg, .18), bg, 3);
+	const border = {
+		default: borderDefault,
+		focus: guard("border.focus", "border-focus", "= accent.bg", [accentBg], accentBg, bg),
+		muted: guard("border.muted", "border-muted", "blend(bg, fg, 0.10)", [bg, fg], blend(bg, fg, .1), bg, 1.5)
+	};
+	const cursorBgRaw = guard("cursor.bg", "bg-cursor", "scheme.cursorColor (visibility-repaired ΔE ≥ 0.15 vs bg)", [scheme.cursorColor, bg], repairCursorBg$1(scheme.cursorColor, bg));
+	const cursor = {
+		fg: guard("cursor.fg", "fg-cursor", "scheme.cursorText", [scheme.cursorText], scheme.cursorText, cursorBgRaw),
+		bg: cursorBgRaw
+	};
+	const selectedBg = guard("selected.bg", "bg-selected", "scheme.selectionBackground (visibility-repaired ΔL ≥ 0.08 vs bg)", [scheme.selectionBackground, bg], repairSelectionBg$1(scheme.selectionBackground, bg));
+	const selectedFgOn = guard("selected.fgOn", "fg-on-selected", "scheme.selectionForeground", [scheme.selectionForeground], scheme.selectionForeground, selectedBg);
+	const selectedDeltaH = stateDeltas(selectedBg);
+	const selected = {
+		bg: selectedBg,
+		fgOn: selectedFgOn,
+		hover: { bg: guard("selected.hover.bg", "bg-selected-hover", `OKLCH ${shiftLabel(selectedBg)} ${selectedDeltaH.hover}L on selected.bg`, [selectedBg], shiftL(selectedBg, selectedDeltaH.hover)) }
+	};
+	const inverseBg = guard("inverse.bg", "bg-inverse", "blend(fg, bg, 0.1)", [fg, bg], blend(fg, bg, .1));
+	const inverse = {
+		bg: inverseBg,
+		fgOn: guard("inverse.fgOn", "fg-on-inverse", "contrast-pick(scheme.fg/bg/BW)", [inverseBg], pickFgOn(inverseBg, scheme), inverseBg)
+	};
+	const link = { fg: guard("link.fg", "fg-link", mode === "dark" ? "scheme.brightBlue" : "scheme.blue", [mode === "dark" ? scheme.brightBlue : scheme.blue], mode === "dark" ? scheme.brightBlue : scheme.blue, bg) };
+	const fgDisabledRaw = blend(surfaceDefault, fg, .38);
+	const fgDisabled = guard("disabled.fg", "fg-disabled", "composite(fg @ 0.38, surface.default), ≥3:1", [fg, surfaceDefault], fgDisabledRaw, surfaceDefault, 3);
+	const borderDisabled = guard("disabled.border", "border-disabled", "composite(border-default @ 0.24, surface.default)", [borderDefault, surfaceDefault], blend(surfaceDefault, borderDefault, .24));
+	return {
+		roles: {
+			accent,
+			info,
+			success,
+			warning,
+			error,
+			muted,
+			surface,
+			border,
+			cursor,
+			selected,
+			inverse,
+			link,
+			disabled: {
+				fg: fgDisabled,
+				bg: guard("disabled.bg", "bg-disabled", "composite(border-default @ 0.12, surface.default)", [borderDefault, surfaceDefault], blend(surfaceDefault, borderDefault, .12)),
+				border: borderDisabled
+			}
+		},
+		mode,
+		trace,
+		violations
+	};
+}
+const SELECTION_DELTA_L = .08;
+/**
+* Nudge selectionBg's OKLCH L until it differs from bg by ≥ SELECTION_DELTA_L.
+* Mirrors the legacy theme's repairSelectionBg behavior — preserves hue +
+* chroma but guarantees the highlight reads against any background. Non-hex
+* input returns unchanged.
+*/
+function repairSelectionBg$1(selectionBg, bg) {
+	const oSel = hexToOklch(selectionBg);
+	const oBg = hexToOklch(bg);
+	if (!oSel || !oBg) return selectionBg;
+	const dL = Math.abs(oSel.L - oBg.L);
+	if (dL >= SELECTION_DELTA_L) return selectionBg;
+	const needed = SELECTION_DELTA_L - dL + .005;
+	const direction = oSel.L >= oBg.L ? 1 : -1;
+	return oklchToHex({
+		L: clamp01(oSel.L + direction * needed),
+		C: oSel.C,
+		H: oSel.H
+	});
+}
+const CURSOR_DELTA_E = .15;
+/**
+* Nudge cursorBg's OKLCH L until it differs from bg by ≥ CURSOR_DELTA_E
+* (perceptual distance, not just lightness). Preserves hue + chroma but
+* guarantees the cursor reads against the surrounding bg.
+*
+* Uses ΔE (OKLCH perceptual distance) rather than ΔL because two colors at
+* the same lightness but different hue/chroma are still visibly distinct —
+* a yellow cursor on a blue bg of equal L is perfectly visible. Only when
+* ΔE falls below the visibility floor do we lift L to compensate.
+*
+* Mirrors `repairSelectionBg` in shape; the repair primitive is L because
+* shifting hue or chroma would change the author-intended cursor color
+* identity. L is the "size" knob — bigger ΔL → more visible without
+* recoloring.
+*
+* Non-hex input returns unchanged.
+*/
+function repairCursorBg$1(cursorBg, bg) {
+	const oCur = hexToOklch(cursorBg);
+	const oBg = hexToOklch(bg);
+	if (!oCur || !oBg) return cursorBg;
+	if (deltaE(oCur, oBg) >= CURSOR_DELTA_E) return cursorBg;
+	const direction = oCur.L >= oBg.L ? 1 : -1;
+	const TARGET = CURSOR_DELTA_E + .005;
+	let lo = 0;
+	let hi = direction > 0 ? 1 - oCur.L : oCur.L;
+	for (let i = 0; i < 24; i++) {
+		const mid = (lo + hi) / 2;
+		if (deltaE({
+			L: clamp01(oCur.L + direction * mid),
+			C: oCur.C,
+			H: oCur.H
+		}, oBg) >= TARGET) hi = mid;
+		else lo = mid;
+	}
+	return oklchToHex({
+		L: clamp01(oCur.L + direction * hi),
+		C: oCur.C,
+		H: oCur.H
+	});
+}
+function buildInteractive(name, seed, scheme, opts, trace, violations) {
+	const pins = opts.pins;
+	const contrast = opts.contrast ?? "auto-lift";
+	const bg = scheme.background;
+	const guard = (nestedPath, flatPath, rule, inputs, value, against, target = WCAG_AA) => guardTarget(nestedPath, flatPath, rule, inputs, value, against, target, contrast, pins, trace, violations);
+	const fg = guard(`${name}.fg`, `fg-${name}`, seedRule$1(name), [seed], seed, bg);
+	const roleBg = guard(`${name}.bg`, `bg-${name}`, seedRule$1(name), [seed], seed);
+	const delta = stateDeltas(roleBg);
+	const bgDir = shiftLabel(roleBg);
+	const fgOn = guard(`${name}.fgOn`, `fg-on-${name}`, "contrast-pick(scheme.fg/bg/BW)", [roleBg], pickFgOn(roleBg, scheme), roleBg);
+	const hoverBg = guard(`${name}.hover.bg`, `bg-${name}-hover`, `OKLCH ${bgDir} ${delta.hover}L`, [roleBg], shiftL(roleBg, delta.hover));
+	const activeBg = guard(`${name}.active.bg`, `bg-${name}-active`, `OKLCH ${bgDir} ${delta.active}L`, [roleBg], shiftL(roleBg, delta.active));
+	return {
+		fg,
+		bg: roleBg,
+		fgOn,
+		hover: { bg: hoverBg },
+		active: { bg: activeBg }
+	};
+}
+function seedRule$1(name) {
+	switch (name) {
+		case "info": return "scheme.primary (info mirrors accent's seed, derived independently)";
+		case "success": return "scheme.green";
+		case "warning": return "scheme.yellow";
+		case "error": return "scheme.red";
+		case "accent": return "scheme.primary";
+		default: return `scheme.${name}`;
+	}
+}
+/**
+* Derive a full Theme (pre-flatten) from a ColorScheme. Throws `ContrastError`
+* in strict mode if any role pair fails WCAG AA. Callers typically wrap this
+* with `flatten()` (from `flatten.ts`) to get the user-facing Theme.
+*
+* Returned Theme is NOT frozen and DOES NOT contain flat keys yet.
+*/
+function deriveTheme$1(scheme, opts = {}) {
+	const { roles, mode, trace, violations } = deriveRoles(scheme, opts);
+	if ((opts.contrast ?? "auto-lift") === "strict" && violations.length > 0) throw new ContrastError(violations);
+	return {
+		...roles,
+		...buildCategoricalHues(scheme),
+		name: scheme.name,
+		mode,
+		variants: DEFAULT_VARIANTS,
+		palette: buildPalette(scheme),
+		...opts.trace ? { derivationTrace: trace } : {}
+	};
+}
+/**
+* Merge a DeepPartial<Theme> onto an existing Theme (for `sterling.theme()`).
+* Nested role objects are spread deeply; flat keys are replaced if present.
+*/
+function mergePartial(base, patch) {
+	if (!patch) return base;
+	const out = { ...base };
+	for (const [k, v] of Object.entries(patch)) {
+		if (v === void 0) continue;
+		const cur = base[k];
+		if (cur && typeof cur === "object" && typeof v === "object" && !Array.isArray(v)) {
+			out[k] = {
+				...cur,
+				...v
+			};
+			for (const [k2, v2] of Object.entries(v)) if (v2 && typeof v2 === "object" && !Array.isArray(v2) && cur[k2] && typeof cur[k2] === "object") out[k][k2] = {
+				...cur[k2],
+				...v2
+			};
+		} else out[k] = v;
+	}
+	return out;
+}
+//#endregion
+//#region packages/ansi/src/sterling/inline.ts
+/**
+* Sterling flat-token inlining — merges Sterling flat tokens onto a Theme.
+*
+* Invoked implicitly by `deriveTheme`, `loadTheme`, and `deriveAnsi16Theme`
+* so every Theme `@silvery/ansi` produces has Sterling flat tokens baked in.
+* Callers do not need to call this directly.
+*
+* Behavior:
+*   - Preserves every existing Theme field unchanged
+*   - Writes Sterling flat tokens (`bg-accent`, `fg-on-accent`, `border-focus`, …)
+*     only when the key isn't already present as a string (so author pins /
+*     palette-provided values win)
+*   - Not frozen (theme overlays mutate in a few callers)
+*
+* A ColorScheme can be supplied for full fidelity. When omitted, Sterling
+* derives from a ColorScheme reconstructed from the theme's own palette —
+* lossy for ANSI slot colors but sufficient for Sterling's 6-slot surface.
+*
+* Exported from `@silvery/ansi` for advanced users who author Theme objects
+* by hand and want to ensure the flat tokens are populated; for scheme →
+* Theme construction `deriveTheme`/`loadTheme` handle this automatically.
+*/
+/**
+* Build a ColorScheme-shaped input from a Theme when the original
+* scheme isn't available (hand-crafted themes, picker round-trips).
+*
+* Reads legacy single-hex hints that the legacy `deriveTheme` path still
+* emits (`theme.primary`, `theme.accent`, `theme.cursorbg`, …) via bracket
+* access. Selection / inverse / link aliases were dropped in 0.21.0 — pulls
+* those from Sterling's nested role objects (`theme.selected.bg`,
+* `theme.inverse.bg`, `theme.link.fg`).
+*/
+function schemeFromTheme(theme) {
+	const palette = theme.palette ?? [];
+	const legacy = theme;
+	const primary = legacy["primary"];
+	const accent = legacy["accent"];
+	const errorHex = (typeof legacy["error"] === "string" ? legacy["error"] : theme.error?.fg) ?? "#000000";
+	const successHex = (typeof legacy["success"] === "string" ? legacy["success"] : theme.success?.fg) ?? "#000000";
+	const warningHex = (typeof legacy["warning"] === "string" ? legacy["warning"] : theme.warning?.fg) ?? "#000000";
+	const infoHex = (typeof legacy["info"] === "string" ? legacy["info"] : theme.info?.fg) ?? "#000000";
+	const accentHex = accent ?? theme.accent?.fg ?? primary ?? "#000000";
+	const primaryHex = primary ?? theme.accent?.fg ?? "#000000";
+	const mutedHex = (typeof legacy["muted"] === "string" ? legacy["muted"] : theme.muted?.fg) ?? "#888888";
+	const cursorBg = legacy["cursorbg"] ?? theme.cursor?.bg ?? theme.bg;
+	const cursorFg = legacy["cursor"] ?? theme.cursor?.fg ?? theme.fg;
+	const selectionBg = theme.selected?.bg ?? theme.bg;
+	const selectionFg = theme.selected?.fgOn ?? theme.fg;
+	return {
+		name: theme.name,
+		dark: isDark(theme.bg),
+		primary: primaryHex,
+		black: palette[0] ?? "#000000",
+		red: palette[1] ?? errorHex,
+		green: palette[2] ?? successHex,
+		yellow: palette[3] ?? warningHex,
+		blue: palette[4] ?? primaryHex,
+		magenta: palette[5] ?? accentHex,
+		cyan: palette[6] ?? infoHex,
+		white: palette[7] ?? theme.fg,
+		brightBlack: palette[8] ?? mutedHex,
+		brightRed: palette[9] ?? errorHex,
+		brightGreen: palette[10] ?? successHex,
+		brightYellow: palette[11] ?? warningHex,
+		brightBlue: palette[12] ?? primaryHex,
+		brightMagenta: palette[13] ?? accentHex,
+		brightCyan: palette[14] ?? infoHex,
+		brightWhite: palette[15] ?? theme.fg,
+		foreground: theme.fg,
+		background: theme.bg,
+		cursorColor: cursorBg,
+		cursorText: cursorFg,
+		selectionBackground: selectionBg,
+		selectionForeground: selectionFg
+	};
+}
+/**
+* Quick luminance check — matches relativeLuminance threshold (0.5). Avoids
+* pulling in @silvery/color for a single boolean.
+*/
+function isDark(hex) {
+	const m = /^#?([0-9a-f]{6})$/i.exec(hex);
+	if (!m?.[1]) return true;
+	const n = parseInt(m[1], 16);
+	const r = n >> 16 & 255;
+	const g = n >> 8 & 255;
+	const b = n & 255;
+	return (.2126 * r + .7152 * g + .0722 * b) / 255 < .5;
+}
+/**
+* Write Sterling flat tokens onto a Theme and return the augmented object.
+* Sets a key only when it's not already a string on the theme (so author
+* pins / palette-provided values win).
+*
+* When `scheme` is provided, Sterling derives directly from it (full fidelity).
+* Otherwise a scheme is reconstructed from the theme's palette (lossy on ANSI
+* slots but fine for Sterling's derivation surface).
+*/
+function inlineSterlingTokens(theme, scheme) {
+	const src = scheme ?? schemeFromTheme(theme);
+	const { roles } = deriveRoles(src, { contrast: "auto-lift" });
+	const out = { ...theme };
+	const setIfAbsent = (key, value) => {
+		if (!(key in out) || typeof out[key] !== "string") out[key] = value;
+	};
+	const accent = roles.accent;
+	if (accent) {
+		setIfAbsent("fg-accent", accent.fg);
+		setIfAbsent("bg-accent", accent.bg);
+		setIfAbsent("fg-on-accent", accent.fgOn);
+		for (const state of ["hover", "active"]) {
+			const s = accent[state];
+			if (!s) continue;
+			setIfAbsent(`fg-accent-${state}`, s.fg);
+			setIfAbsent(`bg-accent-${state}`, s.bg);
+		}
+	}
+	for (const role of [
+		"info",
+		"success",
+		"warning",
+		"error"
+	]) {
+		const r = roles[role];
+		if (!r) continue;
+		setIfAbsent(`fg-${role}`, r.fg);
+		setIfAbsent(`bg-${role}`, r.bg);
+		setIfAbsent(`fg-on-${role}`, r.fgOn);
+		for (const state of ["hover", "active"]) {
+			const s = r[state];
+			if (!s) continue;
+			setIfAbsent(`bg-${role}-${state}`, s.bg);
+		}
+	}
+	if (roles.accent && "border" in roles.accent) setIfAbsent("border-accent", roles.accent.border);
+	const surf = roles.surface;
+	if (surf) {
+		out["bg-surface-default"] = surf.default;
+		out["bg-surface-subtle"] = surf.subtle;
+		out["bg-surface-raised"] = surf.raised;
+		out["bg-surface-overlay"] = surf.overlay;
+		out["bg-surface-hover"] = surf.hover;
+	}
+	const b = roles.border;
+	if (b) {
+		setIfAbsent("border-default", b.default);
+		setIfAbsent("border-focus", b.focus);
+		setIfAbsent("border-muted", b.muted);
+	}
+	const c = roles.cursor;
+	if (c) {
+		setIfAbsent("fg-cursor", c.fg);
+		setIfAbsent("bg-cursor", c.bg);
+	}
+	const m = roles.muted;
+	if (m) {
+		setIfAbsent("fg-muted", m.fg);
+		setIfAbsent("bg-muted", m.bg);
+	}
+	const sel = roles.selected;
+	if (sel) {
+		setIfAbsent("bg-selected", sel.bg);
+		setIfAbsent("fg-on-selected", sel.fgOn);
+		setIfAbsent("bg-selected-hover", sel.hover.bg);
+	}
+	const inv = roles.inverse;
+	if (inv) {
+		setIfAbsent("bg-inverse", inv.bg);
+		setIfAbsent("fg-on-inverse", inv.fgOn);
+	}
+	const lnk = roles.link;
+	if (lnk) setIfAbsent("fg-link", lnk.fg);
+	const dis = roles.disabled;
+	if (dis) {
+		setIfAbsent("fg-disabled", dis.fg);
+		setIfAbsent("bg-disabled", dis.bg);
+		setIfAbsent("border-disabled", dis.border);
+	}
+	setIfAbsent("fg", src.foreground);
+	setIfAbsent("bg", src.background);
+	setIfAbsent("fg-default", src.foreground);
+	setIfAbsent("bg-default", src.background);
+	setIfAbsent("bg-backdrop", blend(src.background, "#000000", .4));
+	return out;
+}
+//#endregion
+//#region packages/ansi/src/theme/derive.ts
+/**
+* Theme derivation — transforms a ColorScheme into a Theme.
+*/
+/**
+* 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.
+*/
+function deriveTheme(palette, mode = "truecolor", adjustments) {
+	return inlineSterlingTokens(mode === "ansi16" ? deriveAnsi16ThemeRaw(palette) : deriveTruecolorTheme(palette, adjustments), palette);
+}
+/**
+* Load and validate a theme from a ColorScheme.
+*
+* Combines `deriveTheme()` (auto-adjust via ensureContrast with project-tuned
+* thresholds) with `validateThemeInvariants()` (post-derivation visibility +
+* optional WCAG).
+*
+* We don't re-impose WCAG on top of derive's tweaked thresholds — default
+* validation checks visibility invariants only (selection/cursor vs bg) that
+* derive doesn't handle.
+*
+* @example
+* ```ts
+* // Default: lenient + visibility-only (derive already handled contrast)
+* const theme = loadTheme(myScheme)
+*
+* // Build-time audit: strict + full WCAG
+* const theme = loadTheme(myScheme, { enforce: "strict", wcag: true })
+* ```
+*/
+function loadTheme(palette, opts = {}) {
+	const mode = opts.mode ?? "truecolor";
+	const enforce = opts.enforce ?? "lenient";
+	const theme = deriveTheme(palette, mode, opts.adjustments);
+	if (enforce === "off") return theme;
+	const { ok, violations } = validateThemeInvariants(theme, { wcag: opts.wcag });
+	if (!ok) {
+		if (enforce === "strict") throw new ThemeInvariantError(violations);
+		if (opts.violations) opts.violations.push(...violations);
+	}
+	return theme;
+}
+const AA$1 = 4.5;
+const DIM = 3;
+const FAINT$1 = 1.5;
+const CONTROL = 3;
+/**
+* Build a "raw" Theme with legacy single-hex role fields. The output is NOT a
+* complete Sterling Theme — Sterling roles + flat tokens are layered on by
+* `inlineSterlingTokens` at the end of `deriveTheme`. The cast at the bottom
+* (`as unknown as Theme`) acknowledges the staged construction; the contract
+* `deriveTheme()` returns a fully-shaped Sterling Theme is honored at the
+* `deriveTheme` boundary, not here.
+*
+* Legacy fields (`primary`, `primaryfg`, `accent`, `accentfg`, `errorfg`,
+* `successfg`, `warningfg`, `infofg`, `secondaryfg`, `focusborder`,
+* `inputborder`, `disabledfg`, `mutedbg`, `surfacebg`, `popoverbg`, `cursor`,
+* `cursorbg`, `secondary`, `border`) are still emitted at runtime so app code
+* that still uses `theme.primary` / `theme.errorfg` keeps working. The selection
+* / inverse / link aliases (`inverse`, `inversebg`, `selection`, `selectionbg`,
+* `link`) were dropped in 0.21.0 (sterling-purge-legacy-tokens) — consumers must
+* read Sterling's flat tokens (`bg-selected`, `fg-on-selected`, `bg-inverse`,
+* `fg-on-inverse`, `fg-link`).
+*/
+function deriveTruecolorTheme(p, adjustments) {
+	const dark = p.dark ?? true;
+	const bg = p.background;
+	function ensure(token, color, against, target) {
+		const result = ensureContrast(color, against, target);
+		if (adjustments && result !== color) {
+			const before = checkContrast(color, against);
+			const after = checkContrast(result, against);
+			adjustments.push({
+				token,
+				from: color,
+				to: result,
+				against,
+				target,
+				ratioBefore: before?.ratio ?? 0,
+				ratioAfter: after?.ratio ?? 0
+			});
+		}
+		return result;
+	}
+	const surfacebg = blend(bg, p.foreground, .03);
+	const popoverbg = blend(bg, p.foreground, .08);
+	const fg = ensure("fg", p.foreground, popoverbg, AA$1);
+	const primary = ensure("primary", p.primary ?? (dark ? p.yellow : p.blue), bg, AA$1);
+	const accent = ensure("accent", complement(primary), bg, AA$1);
+	const secondary = ensure("secondary", blend(primary, accent, .35), bg, AA$1);
+	const error = ensure("error", p.red, bg, AA$1);
+	const warning = ensure("warning", p.yellow, bg, AA$1);
+	const success = ensure("success", p.green, bg, AA$1);
+	const info = ensure("info", blend(fg, accent, .5), bg, AA$1);
+	const red = ensure("red", p.red, bg, AA$1);
+	const orange = ensure("orange", blend(p.red, p.yellow, .5), bg, AA$1);
+	const yellow = ensure("yellow", p.yellow, bg, AA$1);
+	const green = ensure("green", p.green, bg, AA$1);
+	const teal = ensure("teal", blend(p.green, p.cyan, .5), bg, AA$1);
+	const blue = ensure("blue", dark ? p.brightBlue : p.blue, bg, AA$1);
+	const purple = ensure("purple", p.magenta, bg, AA$1);
+	const pink = ensure("pink", blend(p.magenta, p.red, .5), bg, AA$1);
+	const mutedbg = blend(bg, p.foreground, .04);
+	const muted = ensure("muted", blend(fg, bg, .4), mutedbg, AA$1);
+	const disabledfg = ensure("disabledfg", blend(fg, bg, .5), bg, DIM);
+	const border = ensure("border", blend(bg, p.foreground, .15), bg, FAINT$1);
+	const inputborder = ensure("inputborder", blend(bg, p.foreground, .25), bg, CONTROL);
+	const selectionBg = repairSelectionBg(p.selectionBackground, bg);
+	const cursorBgRepaired = repairCursorBg(p.cursorColor, bg);
+	const cursor = ensure("cursor", p.cursorText, cursorBgRepaired, AA$1);
+	const derived = deriveFields({
+		dark,
+		primary,
+		accent,
+		fg,
+		selectionbg: selectionBg,
+		surfacebg,
+		ring: {
+			red,
+			orange,
+			yellow,
+			green,
+			teal,
+			blue,
+			purple,
+			pink
+		}
+	});
+	return {
+		name: p.name ?? (dark ? "derived-dark" : "derived-light"),
+		bg,
+		fg,
+		muted,
+		mutedbg,
+		surface: fg,
+		surfacebg,
+		popover: fg,
+		popoverbg,
+		cursor,
+		cursorbg: cursorBgRepaired,
+		primary,
+		primaryfg: contrastFg(primary),
+		secondary,
+		secondaryfg: contrastFg(secondary),
+		accent,
+		accentfg: contrastFg(accent),
+		error,
+		errorfg: contrastFg(error),
+		warning,
+		warningfg: contrastFg(warning),
+		success,
+		successfg: contrastFg(success),
+		info,
+		infofg: contrastFg(info),
+		border,
+		inputborder,
+		focusborder: ensure("focusborder", dark ? p.brightBlue : p.blue, bg, AA$1),
+		disabledfg,
+		palette: [
+			p.black,
+			p.red,
+			p.green,
+			p.yellow,
+			p.blue,
+			p.magenta,
+			p.cyan,
+			p.white,
+			p.brightBlack,
+			p.brightRed,
+			p.brightGreen,
+			p.brightYellow,
+			p.brightBlue,
+			p.brightMagenta,
+			p.brightCyan,
+			p.brightWhite
+		],
+		...derived
+	};
+}
+function deriveAnsi16Theme(p) {
+	return inlineSterlingTokens(deriveAnsi16ThemeRaw(p), p);
+}
+function deriveAnsi16ThemeRaw(p) {
+	const dark = p.dark ?? true;
+	const primaryColor = dark ? p.yellow : p.blue;
+	const accentColor = p.cyan;
+	const derived = deriveFields({
+		primary: primaryColor,
+		accent: accentColor,
+		fg: p.foreground,
+		selectionbg: p.selectionBackground,
+		surfacebg: p.black,
+		ring: {
+			red: dark ? p.brightRed : p.red,
+			orange: dark ? p.brightRed : p.red,
+			yellow: p.yellow,
+			green: dark ? p.brightGreen : p.green,
+			teal: p.cyan,
+			blue: dark ? p.brightBlue : p.blue,
+			purple: p.magenta,
+			pink: dark ? p.brightMagenta : p.magenta
+		}
+	});
+	return {
+		name: p.name ?? (dark ? "derived-ansi16-dark" : "derived-ansi16-light"),
+		bg: p.background,
+		fg: p.foreground,
+		muted: p.white,
+		mutedbg: p.black,
+		surface: p.foreground,
+		surfacebg: p.black,
+		popover: p.foreground,
+		popoverbg: p.black,
+		cursor: p.cursorText,
+		cursorbg: p.cursorColor,
+		primary: primaryColor,
+		primaryfg: p.black,
+		secondary: p.magenta,
+		secondaryfg: p.black,
+		accent: accentColor,
+		accentfg: p.black,
+		error: dark ? p.brightRed : p.red,
+		errorfg: p.black,
+		warning: p.yellow,
+		warningfg: p.black,
+		success: dark ? p.brightGreen : p.green,
+		successfg: p.black,
+		info: p.cyan,
+		infofg: p.black,
+		border: p.brightBlack,
+		inputborder: p.brightBlack,
+		focusborder: dark ? p.brightBlue : p.blue,
+		disabledfg: p.brightBlack,
+		palette: [
+			p.black,
+			p.red,
+			p.green,
+			p.yellow,
+			p.blue,
+			p.magenta,
+			p.cyan,
+			p.white,
+			p.brightBlack,
+			p.brightRed,
+			p.brightGreen,
+			p.brightYellow,
+			p.brightBlue,
+			p.brightMagenta,
+			p.brightCyan,
+			p.brightWhite
+		],
+		...derived
+	};
+}
+/**
+* Nudge `selectionBg`'s OKLCH lightness until it differs from `bg` by at least
+* `SELECTION_DELTA_L`. Preserves hue + chroma. Non-hex input returns unchanged.
+*
+* Direction: shift away from bg — if bg is dark, lift L; if bg is light, drop L.
+* If the input already meets the threshold, it's returned unchanged.
+*/
+function repairSelectionBg(selectionBg, bg) {
+	const oSel = hexToOklch(selectionBg);
+	const oBg = hexToOklch(bg);
+	if (!oSel || !oBg) return selectionBg;
+	const dL = Math.abs(oSel.L - oBg.L);
+	if (dL >= .08) return selectionBg;
+	const needed = SELECTION_DELTA_L$1 - dL + .005;
+	const direction = oSel.L >= oBg.L ? 1 : -1;
+	return oklchToHex({
+		L: Math.max(0, Math.min(1, oSel.L + direction * needed)),
+		C: oSel.C,
+		H: oSel.H
+	});
+}
+/**
+* Nudge `cursorBg`'s OKLCH values until it differs from `bg` by at least
+* `CURSOR_DELTA_E`. Shifts lightness first (preserves hue/chroma aesthetics).
+* Non-hex input returns unchanged.
+*/
+function repairCursorBg(cursorBg, bg) {
+	const d = colorDistance(cursorBg, bg);
+	if (d === null || d >= .15) return cursorBg;
+	const oCur = hexToOklch(cursorBg);
+	const oBg = hexToOklch(bg);
+	const lGap = SELECTION_DELTA_L$1 + .02;
+	const direction = oCur.L >= oBg.L ? 1 : -1;
+	const candidate = oklchToHex({
+		L: Math.max(0, Math.min(1, oCur.L + direction * lGap)),
+		C: oCur.C,
+		H: oCur.H
+	});
+	const d2 = colorDistance(candidate, bg);
+	if (d2 !== null && d2 >= .15) return candidate;
+	return oBg.L > .5 ? "#000000" : "#FFFFFF";
+}
+//#endregion
+//#region packages/ansi/src/theme/default-schemes.ts
+const defaultDarkScheme = {
+	name: "default-dark",
+	dark: true,
+	black: "#2e3440",
+	red: "#bf616a",
+	green: "#a3be8c",
+	yellow: "#ebcb8b",
+	blue: "#81a1c1",
+	magenta: "#b48ead",
+	cyan: "#88c0d0",
+	white: "#d8dee9",
+	brightBlack: "#4c566a",
+	brightRed: "#bf616a",
+	brightGreen: "#a3be8c",
+	brightYellow: "#ebcb8b",
+	brightBlue: "#81a1c1",
+	brightMagenta: "#b48ead",
+	brightCyan: "#8fbcbb",
+	brightWhite: "#eceff4",
+	foreground: "#d8dee9",
+	background: "#2e3440",
+	cursorColor: "#d8dee9",
+	cursorText: "#2e3440",
+	selectionBackground: "#434c5e",
+	selectionForeground: "#d8dee9"
+};
+const defaultLightScheme = {
+	name: "default-light",
+	dark: false,
+	black: "#5c6370",
+	red: "#d20f39",
+	green: "#40a02b",
+	yellow: "#df8e1d",
+	blue: "#1e66f5",
+	magenta: "#8839ef",
+	cyan: "#179299",
+	white: "#dce0e8",
+	brightBlack: "#6c7086",
+	brightRed: "#d20f39",
+	brightGreen: "#40a02b",
+	brightYellow: "#df8e1d",
+	brightBlue: "#1e66f5",
+	brightMagenta: "#8839ef",
+	brightCyan: "#179299",
+	brightWhite: "#eff1f5",
+	foreground: "#4c4f69",
+	background: "#eff1f5",
+	cursorColor: "#dc8a78",
+	cursorText: "#eff1f5",
+	selectionBackground: "#ccd0da",
+	selectionForeground: "#4c4f69"
+};
+/**
+* Dark ANSI 16 theme — hex-valued, derived from the default dark scheme.
+*
+* All token values are hex strings. Terminal rendering quantizes hex to
+* 4-bit ANSI codes at paint time when colorLevel === "ansi16".
+*/
+const ansi16DarkTheme = deriveAnsi16Theme(defaultDarkScheme);
+/**
+* Light ANSI 16 theme — hex-valued, derived from the default light scheme.
+*
+* All token values are hex strings. Terminal rendering quantizes hex to
+* 4-bit ANSI codes at paint time when colorLevel === "ansi16".
+*/
+const ansi16LightTheme = deriveAnsi16Theme(defaultLightScheme);
+//#endregion
+//#region packages/ansi/src/osc-palette.ts
+/**
+* OSC 4 Terminal Color Palette Query/Set — pure ANSI protocol.
+*/
+const ESC$4 = "\x1B";
+const BEL$2 = "\x07";
+function queryPaletteColor(index, write) {
+	if (index < 0 || index > 255) throw new RangeError(`Palette index must be 0-255, got ${index}`);
+	write(`${ESC$4}]4;${index};?${BEL$2}`);
+}
+function queryMultiplePaletteColors(indices, write) {
+	for (const index of indices) queryPaletteColor(index, write);
+}
+function setPaletteColor(index, color, write) {
+	if (index < 0 || index > 255) throw new RangeError(`Palette index must be 0-255, got ${index}`);
+	write(`${ESC$4}]4;${index};${color}${BEL$2}`);
+}
+const OSC4_PREFIX = `${ESC$4}]4;`;
+const OSC4_BODY_RE = /^(\d+);rgb:([0-9a-fA-F]{1,4})\/([0-9a-fA-F]{1,4})\/([0-9a-fA-F]{1,4})$/;
+function parsePaletteResponse(input) {
+	const prefixIdx = input.indexOf(OSC4_PREFIX);
+	if (prefixIdx === -1) return null;
+	const bodyStart = prefixIdx + OSC4_PREFIX.length;
+	let bodyEnd = input.indexOf(BEL$2, bodyStart);
+	if (bodyEnd === -1) bodyEnd = input.indexOf(`${ESC$4}\\`, bodyStart);
+	if (bodyEnd === -1) return null;
+	const body = input.slice(bodyStart, bodyEnd);
+	const match = OSC4_BODY_RE.exec(body);
+	if (!match) return null;
+	const index = Number.parseInt(match[1], 10);
+	if (index < 0 || index > 255) return null;
+	return {
+		index,
+		color: `#${normalizeHexChannel$1(match[2])}${normalizeHexChannel$1(match[3])}${normalizeHexChannel$1(match[4])}`
+	};
+}
+function normalizeHexChannel$1(hex) {
+	switch (hex.length) {
+		case 1: return hex + hex;
+		case 2: return hex;
+		default: return hex.slice(0, 2);
+	}
+}
+//#endregion
+//#region packages/ansi/src/protocol-error.ts
+/**
+* ProtocolError — structured error for terminal protocol parse failures.
+*
+* Used by parsers to signal that input WAS identified as belonging to this
+* protocol (prefix/marker matched) but is malformed in a way the parser
+* cannot recover from (missing terminator, invalid base64, missing required
+* field, etc.).
+*
+* Distinct from a `null` return:
+*
+* - `null` = "no input matched, but input was valid" — the parser does not
+*   recognize this input as belonging to its protocol family at all (no
+*   prefix, no marker). Used by discriminator chains to mean "next parser
+*   please."
+*
+* - `throw ProtocolError` = "this WAS for us but is broken" — the parser
+*   committed to the protocol (prefix matched), then the body failed
+*   validation. Callers should log and continue, NOT crash.
+*
+* Carries structured context so callers can route, dedupe, and log
+* without re-parsing the raw bytes:
+*
+* - `parser` — name of the parser that threw (e.g. "parseClipboardResponse")
+* - `input` — raw input bytes (truncated for safety; full length retained
+*   in `inputLength`)
+* - `reason` — short human-readable description of why-invalid
+*
+* Acceptance for bead `@km/silvery/15127-custom-protocol-implementation/
+* protocol-loud-errors`: parsers must fail loudly on protocol violation
+* instead of silently dropping malformed input.
+*
+* @module
+*/
+/** Maximum chars of raw input retained on the error (rest is truncated). */
+const INPUT_TRUNCATE_LENGTH = 256;
+/**
+* Thrown by protocol parsers when input is identified as belonging to the
+* protocol but is malformed.
+*
+* Callers (dispatch boundaries in `runtime/input-owner.ts`, `renderer.ts`,
+* and similar) should catch ProtocolError, log via the appropriate logger,
+* and continue — never let a protocol parse error crash the app.
+*/
+var ProtocolError = class extends Error {
+	name = "ProtocolError";
+	parser;
+	input;
+	inputLength;
+	reason;
+	constructor(opts) {
+		const inputLength = opts.input.length;
+		const truncated = inputLength > INPUT_TRUNCATE_LENGTH ? `${opts.input.slice(0, INPUT_TRUNCATE_LENGTH)}…<${inputLength - INPUT_TRUNCATE_LENGTH} more chars>` : opts.input;
+		super(`${opts.parser}: ${opts.reason} (input=${JSON.stringify(truncated)})`);
+		this.parser = opts.parser;
+		this.input = truncated;
+		this.inputLength = inputLength;
+		this.reason = opts.reason;
+	}
+};
+/** Narrowing helper — true if `err` is a ProtocolError. */
+function isProtocolError(err) {
+	return err instanceof ProtocolError;
+}
+//#endregion
+//#region packages/ansi/src/osc-colors.ts
+/**
+* OSC 10/11/12 Terminal Color Queries — pure ANSI protocol.
+*/
+const ESC$3 = "\x1B";
+const BEL$1 = "\x07";
+const RGB_BODY_RE$1 = /rgb:([0-9a-fA-F]{1,4})\/([0-9a-fA-F]{1,4})\/([0-9a-fA-F]{1,4})/;
+function normalizeHexChannel(hex) {
+	switch (hex.length) {
+		case 1: return hex + hex;
+		case 2: return hex;
+		default: return hex.slice(0, 2);
+	}
+}
+/**
+* Parse an OSC 10/11/12 color query response.
+*
+* Return semantics (see {@link ProtocolError} for the full contract):
+* - `null` — input does not contain the OSC `oscCode` prefix (not for us).
+* - `throw ProtocolError` — prefix matched (we committed to this protocol)
+*   but the response is malformed: missing terminator, body is not a valid
+*   `rgb:RRRR/GGGG/BBBB` spec, etc.
+*
+* Exported for testing and so callers in chained-discriminator pipelines
+* can dispatch raw input through the parser directly. Most users should
+* use {@link queryForegroundColor} / {@link queryBackgroundColor} /
+* {@link queryCursorColor} which wrap this with the write+read cycle.
+*/
+function parseOscColorResponse(input, oscCode) {
+	const prefix = `${ESC$3}]${oscCode};`;
+	const prefixIdx = input.indexOf(prefix);
+	if (prefixIdx === -1) return null;
+	const bodyStart = prefixIdx + prefix.length;
+	let bodyEnd = input.indexOf(BEL$1, bodyStart);
+	if (bodyEnd === -1) bodyEnd = input.indexOf(`${ESC$3}\\`, bodyStart);
+	if (bodyEnd === -1) throw new ProtocolError({
+		parser: "parseOscColorResponse",
+		input,
+		reason: `OSC ${oscCode} prefix present but missing terminator (expected BEL or ST)`
+	});
+	const body = input.slice(bodyStart, bodyEnd);
+	const match = RGB_BODY_RE$1.exec(body);
+	if (!match) throw new ProtocolError({
+		parser: "parseOscColorResponse",
+		input,
+		reason: `OSC ${oscCode} body is not a valid rgb:RRRR/GGGG/BBBB spec (body=${JSON.stringify(body)})`
+	});
+	return `#${normalizeHexChannel(match[1])}${normalizeHexChannel(match[2])}${normalizeHexChannel(match[3])}`;
+}
+async function queryOscColor(write, read, oscCode, timeoutMs) {
+	write(`${ESC$3}]${oscCode};?${BEL$1}`);
+	const data = await read(timeoutMs);
+	if (data == null) return null;
+	return parseOscColorResponse(data, oscCode);
+}
+async function queryForegroundColor(write, read, timeoutMs = 200) {
+	return queryOscColor(write, read, 10, timeoutMs);
+}
+async function queryBackgroundColor(write, read, timeoutMs = 200) {
+	return queryOscColor(write, read, 11, timeoutMs);
+}
+async function queryCursorColor(write, read, timeoutMs = 200) {
+	return queryOscColor(write, read, 12, timeoutMs);
+}
+function setForegroundColor(write, color) {
+	write(`${ESC$3}]10;${color}${BEL$1}`);
+}
+function setBackgroundColor(write, color) {
+	write(`${ESC$3}]11;${color}${BEL$1}`);
+}
+function setCursorColor(write, color) {
+	write(`${ESC$3}]12;${color}${BEL$1}`);
+}
+function resetForegroundColor(write) {
+	write(`${ESC$3}]110${BEL$1}`);
+}
+function resetBackgroundColor(write) {
+	write(`${ESC$3}]111${BEL$1}`);
+}
+function resetCursorColor(write) {
+	write(`${ESC$3}]112${BEL$1}`);
+}
+async function detectColorScheme(write, read, timeoutMs = 200) {
+	const bg = await queryBackgroundColor(write, read, timeoutMs);
+	if (bg == null) return null;
+	const r = parseInt(bg.slice(1, 3), 16) / 255;
+	const g = parseInt(bg.slice(3, 5), 16) / 255;
+	const b = parseInt(bg.slice(5, 7), 16) / 255;
+	return .2126 * r + .7152 * g + .0722 * b > .5 ? "light" : "dark";
+}
+//#endregion
+//#region packages/ansi/src/theme/detect.ts
+/**
+* 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
+*/
+async function probeColors(timeoutOrOpts) {
+	const opts = typeof timeoutOrOpts === "number" ? { timeoutMs: timeoutOrOpts } : timeoutOrOpts ?? {};
+	const timeoutMs = opts.timeoutMs ?? 150;
+	if (opts.input) return probeColorsViaOwner(opts.input, timeoutMs);
+	const stdin = process.stdin;
+	const stdout = process.stdout;
+	if (!stdin.isTTY || !stdout.isTTY) return null;
+	const otherListeners = stdin.listenerCount("data") > 0;
+	const wasRaw = stdin.isRaw;
+	let didSetRaw = false;
+	if (!wasRaw && !otherListeners) {
+		stdin.setRawMode(true);
+		didSetRaw = true;
+	}
+	let buffer = "";
+	const onData = (chunk) => {
+		buffer += chunk.toString();
+	};
+	stdin.on("data", onData);
+	try {
+		const write = (s) => {
+			stdout.write(s);
+		};
+		const read = (ms) => new Promise((resolve) => {
+			if (buffer.length > 0) {
+				const result = buffer;
+				buffer = "";
+				resolve(result);
+				return;
+			}
+			const timer = setTimeout(() => {
+				resolve(buffer.length > 0 ? buffer : null);
+				buffer = "";
+			}, ms);
+			const check = (_chunk) => {
+				clearTimeout(timer);
+				stdin.removeListener("data", check);
+				const result = buffer;
+				buffer = "";
+				resolve(result);
+			};
+			stdin.on("data", check);
+		});
+		const bg = await queryBackgroundColor(write, read, timeoutMs);
+		const fg = await queryForegroundColor(write, read, timeoutMs);
+		const ansi = new Array(16).fill(null);
+		queryMultiplePaletteColors(Array.from({ length: 16 }, (_, i) => i), write);
+		await new Promise((resolve) => setTimeout(resolve, timeoutMs));
+		const remaining = buffer;
+		buffer = "";
+		if (remaining) {
+			const oscPrefix = "\x1B]4;";
+			let pos = 0;
+			while (pos < remaining.length) {
+				const nextOsc = remaining.indexOf(oscPrefix, pos);
+				if (nextOsc === -1) break;
+				let end = remaining.indexOf("\x07", nextOsc);
+				if (end === -1) end = remaining.indexOf("\x1B\\", nextOsc);
+				if (end === -1) break;
+				const parsed = parsePaletteResponse(remaining.slice(nextOsc, end + 1));
+				if (parsed && parsed.index >= 0 && parsed.index < 16) ansi[parsed.index] = parsed.color;
+				pos = end + 1;
+			}
+		}
+		const dark = bg ? isDarkColor(bg) : true;
+		const palette = { dark };
+		if (bg) palette.background = bg;
+		if (fg) palette.foreground = fg;
+		const ansiFields = [
+			"black",
+			"red",
+			"green",
+			"yellow",
+			"blue",
+			"magenta",
+			"cyan",
+			"white",
+			"brightBlack",
+			"brightRed",
+			"brightGreen",
+			"brightYellow",
+			"brightBlue",
+			"brightMagenta",
+			"brightCyan",
+			"brightWhite"
+		];
+		for (let i = 0; i < 16; i++) if (ansi[i]) palette[ansiFields[i]] = ansi[i];
+		if (fg) palette.cursorColor = fg;
+		if (bg) palette.cursorText = bg;
+		return {
+			fg,
+			bg,
+			ansi,
+			dark,
+			palette
+		};
+	} finally {
+		stdin.removeListener("data", onData);
+		if (didSetRaw) stdin.setRawMode(false);
+	}
+}
+const ESC$2 = "\x1B";
+const BEL = "\x07";
+const RGB_BODY_RE = /rgb:([0-9a-fA-F]{1,4})\/([0-9a-fA-F]{1,4})\/([0-9a-fA-F]{1,4})/;
+/** OSC response parser for a specific OSC code (10 or 11). Returns the
+* first matching response in the buffer and the byte count to consume
+* (the end of that response, so leading garbage is cleared as well).
+*/
+function parseOscColor(acc, oscCode) {
+	const prefix = `${ESC$2}]${oscCode};`;
+	const prefixIdx = acc.indexOf(prefix);
+	if (prefixIdx === -1) return null;
+	const bodyStart = prefixIdx + prefix.length;
+	let bodyEnd = acc.indexOf(BEL, bodyStart);
+	let terminatorLen = 1;
+	if (bodyEnd === -1) {
+		bodyEnd = acc.indexOf(`${ESC$2}\\`, bodyStart);
+		terminatorLen = 2;
+		if (bodyEnd === -1) return null;
+	}
+	const body = acc.slice(bodyStart, bodyEnd);
+	const match = RGB_BODY_RE.exec(body);
+	if (!match) return null;
+	return {
+		result: `#${normalizeHex(match[1])}${normalizeHex(match[2])}${normalizeHex(match[3])}`,
+		consumed: bodyEnd + terminatorLen
+	};
+}
+function normalizeHex(channel) {
+	if (channel.length === 1) return channel + channel;
+	if (channel.length === 2) return channel;
+	return channel.slice(0, 2);
+}
+/**
+* Route OSC 10/11/4 queries through an InputOwner. Same semantics as the
+* standalone `probeColors` path (FG + BG sequentially, 16 palette slots in
+* one burst with a final drain), but all stdin access is owner-mediated —
+* no direct raw-mode toggles, no stdin.on("data").
+*/
+async function probeColorsViaOwner(input, timeoutMs) {
+	const fgQuery = `${ESC$2}]10;?${BEL}`;
+	const fg = await input.probe({
+		query: fgQuery,
+		parse: (acc) => parseOscColor(acc, 10),
+		timeoutMs
+	});
+	const bgQuery = `${ESC$2}]11;?${BEL}`;
+	const bg = await input.probe({
+		query: bgQuery,
+		parse: (acc) => parseOscColor(acc, 11),
+		timeoutMs
+	});
+	const ansi = new Array(16).fill(null);
+	let filled = 0;
+	const oscPrefix = `${ESC$2}]4;`;
+	let burstQuery = "";
+	for (let i = 0; i < 16; i++) burstQuery += `${ESC$2}]4;${i};?${BEL}`;
+	await input.probe({
+		query: burstQuery,
+		parse: (acc) => {
+			let pos = 0;
+			while (pos < acc.length) {
+				const next = acc.indexOf(oscPrefix, pos);
+				if (next === -1) break;
+				let end = acc.indexOf(BEL, next);
+				let termLen = 1;
+				if (end === -1) {
+					end = acc.indexOf(`${ESC$2}\\`, next);
+					termLen = 2;
+					if (end === -1) break;
+				}
+				const parsed = parsePaletteResponse(acc.slice(next, end + termLen));
+				if (parsed && parsed.index >= 0 && parsed.index < 16 && ansi[parsed.index] == null) {
+					ansi[parsed.index] = parsed.color;
+					filled++;
+				}
+				pos = end + termLen;
+			}
+			if (filled === 16) return {
+				result: true,
+				consumed: acc.length
+			};
+			return null;
+		},
+		timeoutMs
+	});
+	const dark = bg ? isDarkColor(bg) : true;
+	const palette = { dark };
+	if (bg) palette.background = bg;
+	if (fg) palette.foreground = fg;
+	const ansiFields = [
+		"black",
+		"red",
+		"green",
+		"yellow",
+		"blue",
+		"magenta",
+		"cyan",
+		"white",
+		"brightBlack",
+		"brightRed",
+		"brightGreen",
+		"brightYellow",
+		"brightBlue",
+		"brightMagenta",
+		"brightCyan",
+		"brightWhite"
+	];
+	for (let i = 0; i < 16; i++) if (ansi[i]) palette[ansiFields[i]] = ansi[i];
+	if (fg) palette.cursorColor = fg;
+	if (bg) palette.cursorText = bg;
+	if (fg == null && bg == null && filled === 0) return null;
+	return {
+		fg,
+		bg,
+		ansi,
+		dark,
+		palette
+	};
+}
+/**
+* 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.
+*/
+const detectTerminalScheme = probeColors;
+async function detectTheme(opts = {}) {
+	const colorLevel = opts.caps?.colorLevel;
+	if (colorLevel === "mono" || colorLevel === "ansi16") return opts.caps?.darkBackground ?? true ? ansi16DarkTheme : ansi16LightTheme;
+	const detected = await probeColors({
+		timeoutMs: opts.timeoutMs,
+		input: opts.input
+	});
+	const isDark = detected?.dark ?? opts.caps?.darkBackground ?? true;
+	const fallback = opts.fallback ?? (isDark ? opts.fallbackDark ?? defaultDarkScheme : opts.fallbackLight ?? defaultLightScheme);
+	if (!detected) return deriveTheme(fallback);
+	return deriveTheme({
+		...fallback,
+		...stripNulls$1(detected.palette)
+	});
+}
+function stripNulls$1(partial) {
+	const result = {};
+	for (const [k, v] of Object.entries(partial)) if (v != null) result[k] = v;
+	return result;
+}
+function isDarkColor(hex) {
+	const r = parseInt(hex.slice(1, 3), 16) / 255;
+	const g = parseInt(hex.slice(3, 5), 16) / 255;
+	const b = parseInt(hex.slice(5, 7), 16) / 255;
+	return .2126 * r + .7152 * g + .0722 * b <= .5;
+}
+//#endregion
+//#region packages/ansi/src/kitty-graphics-probe.ts
+const APC = "\x1B_G";
+const ST = "\x1B\\";
+/**
+* The image id used for the support query. Chosen well above the runtime image
+* id range (1..255) so a probe ack can never be confused with a real image's
+* response.
+*/
+const KITTY_PROBE_ID = 7777;
+/**
+* Parse a Kitty graphics query response for {@link KITTY_PROBE_ID}.
+*
+*   - `{ result: true }`  — `\x1b_Gi=<id>;OK\x1b\` → graphics supported.
+*   - `{ result: false }` — a well-formed response for our id that is NOT `OK`
+*                           (the terminal parsed the APC but rejected the query).
+*   - `null`              — no complete response for our id yet (the probe keeps
+*                           waiting; on timeout the caller treats this as
+*                           unsupported).
+*/
+function parseKittyGraphicsResponse(acc, id) {
+	const prefix = `${APC}i=${id};`;
+	const start = acc.indexOf(prefix);
+	if (start === -1) return null;
+	const bodyStart = start + prefix.length;
+	const end = acc.indexOf(ST, bodyStart);
+	if (end === -1) return null;
+	return {
+		result: acc.slice(bodyStart, end).trim() === "OK",
+		consumed: end + 2
+	};
+}
+/**
+* Probe the terminal at runtime for Kitty graphics support. Resolves:
+*   - `true`      — the terminal acknowledged it can paint Kitty graphics.
+*   - `false`     — a non-`OK` response (the protocol is understood but refused).
+*   - `undefined` — no response within `timeoutMs` (the terminal does not speak
+*                   the protocol, or a proxy/capture that cannot paint it).
+*
+* The query is a 1×1 RGB query-only command, harmless to a terminal that ignores
+* unknown APC sequences. Routed through the session's {@link ProbeInputOwner}
+* (never `process.stdin` directly) so it is safe inside a running TUI.
+*/
+async function probeKittyGraphics(input, timeoutMs = 150) {
+	const query = `${APC}i=${KITTY_PROBE_ID},s=1,v=1,a=q,t=d,f=24;AAAA${ST}`;
+	return await input.probe({
+		query,
+		timeoutMs,
+		parse: (acc) => parseKittyGraphicsResponse(acc, 7777)
+	}) ?? void 0;
+}
+//#endregion
+//#region packages/ansi/src/color-maps.ts
+/** Modifier SGR codes: open -> close */
+const MODIFIERS = {
+	reset: [0, 0],
+	bold: [1, 22],
+	dim: [2, 22],
+	italic: [3, 23],
+	underline: [4, 24],
+	inverse: [7, 27],
+	hidden: [8, 28],
+	strikethrough: [9, 29],
+	overline: [53, 55]
+};
+/** Foreground color name -> ANSI SGR code */
+const FG_COLORS = {
+	black: 30,
+	red: 31,
+	green: 32,
+	yellow: 33,
+	blue: 34,
+	magenta: 35,
+	cyan: 36,
+	white: 37,
+	blackBright: 90,
+	gray: 90,
+	grey: 90,
+	redBright: 91,
+	greenBright: 92,
+	yellowBright: 93,
+	blueBright: 94,
+	magentaBright: 95,
+	cyanBright: 96,
+	whiteBright: 97
+};
+/** Background color name -> ANSI SGR code */
+const BG_COLORS = {
+	bgBlack: 40,
+	bgRed: 41,
+	bgGreen: 42,
+	bgYellow: 43,
+	bgBlue: 44,
+	bgMagenta: 45,
+	bgCyan: 46,
+	bgWhite: 47,
+	bgBlackBright: 100,
+	bgGray: 100,
+	bgGrey: 100,
+	bgRedBright: 101,
+	bgGreenBright: 102,
+	bgYellowBright: 103,
+	bgBlueBright: 104,
+	bgMagentaBright: 105,
+	bgCyanBright: 106,
+	bgWhiteBright: 107
+};
+/** Standard ANSI 16 color RGB values for nearest-color matching.
+* Uses xterm-256 standard values for consistent mapping (matches chalk/ansi-styles). */
+const ANSI_16_COLORS = [
+	[
+		0,
+		0,
+		0
+	],
+	[
+		128,
+		0,
+		0
+	],
+	[
+		0,
+		128,
+		0
+	],
+	[
+		128,
+		128,
+		0
+	],
+	[
+		0,
+		0,
+		128
+	],
+	[
+		128,
+		0,
+		128
+	],
+	[
+		0,
+		128,
+		128
+	],
+	[
+		192,
+		192,
+		192
+	],
+	[
+		128,
+		128,
+		128
+	],
+	[
+		255,
+		0,
+		0
+	],
+	[
+		0,
+		255,
+		0
+	],
+	[
+		255,
+		255,
+		0
+	],
+	[
+		0,
+		0,
+		255
+	],
+	[
+		255,
+		0,
+		255
+	],
+	[
+		0,
+		255,
+		255
+	],
+	[
+		255,
+		255,
+		255
+	]
+];
+/**
+* Canonical hex values for the 16 standard ANSI color slots.
+*
+* These are the xterm-256 reference values — the same RGB values used by
+* `nearestAnsi16` for quantization. Used to convert ANSI16 slot-name themes
+* (e.g., "yellow") into hex-valued themes (e.g., "#808000") so Theme objects
+* are pure hex across all tiers.
+*
+* Terminal-rendering behavior is unchanged: the output phase reads `colorLevel`
+* and emits 4-bit ANSI codes when `colorLevel === "basic"` — the hex value is
+* only carried in the Theme object itself, not emitted verbatim.
+*/
+const ANSI16_SLOT_HEX = {
+	black: "#000000",
+	red: "#800000",
+	green: "#008000",
+	yellow: "#808000",
+	blue: "#000080",
+	magenta: "#800080",
+	cyan: "#008080",
+	white: "#c0c0c0",
+	blackBright: "#808080",
+	gray: "#808080",
+	grey: "#808080",
+	redBright: "#ff0000",
+	greenBright: "#00ff00",
+	yellowBright: "#ffff00",
+	blueBright: "#0000ff",
+	magentaBright: "#ff00ff",
+	cyanBright: "#00ffff",
+	whiteBright: "#ffffff"
+};
+/** Find nearest ANSI 16 color index for an RGB value. */
+function nearestAnsi16(r, g, b) {
+	let bestIdx = 0;
+	let bestDist = Infinity;
+	for (let i = 0; i < 16; i++) {
+		const [cr, cg, cb] = ANSI_16_COLORS[i];
+		const dist = (r - cr) ** 2 + (g - cg) ** 2 + (b - cb) ** 2;
+		if (dist < bestDist) {
+			bestDist = dist;
+			bestIdx = i;
+		}
+	}
+	return bestIdx;
+}
+/** Convert RGB to 256-color index (using the 6x6x6 color cube). */
+function rgbToAnsi256(r, g, b) {
+	if (r === g && g === b) {
+		if (r < 8) return 16;
+		if (r > 248) return 231;
+		return Math.round((r - 8) / 247 * 24) + 232;
+	}
+	const ri = Math.round(r / 255 * 5);
+	const gi = Math.round(g / 255 * 5);
+	const bi = Math.round(b / 255 * 5);
+	return 16 + 36 * ri + 6 * gi + bi;
+}
+/**
+* Generate SGR foreground code for an RGB color at the given color tier.
+* Returns the SGR parameter string (e.g., "31" or "38;5;196" or "38;2;255;0;0").
+*
+* Tiers `"truecolor"`, `"256"`, and `"ansi16"` emit color codes. `"mono"`
+* is handled by the caller (no SGR code is emitted for color at the mono tier)
+* — this function coerces `"mono"` to the `"ansi16"` code path rather than
+* throwing, since callers that get here with `"mono"` have already bypassed
+* the mono short-circuit.
+*/
+function fgFromRgb(r, g, b, tier) {
+	if (tier === "truecolor") return `38;2;${r};${g};${b}`;
+	if (tier === "256") return `38;5;${rgbToAnsi256(r, g, b)}`;
+	const idx = nearestAnsi16(r, g, b);
+	return idx < 8 ? `${30 + idx}` : `${82 + idx}`;
+}
+/**
+* Generate SGR background code for an RGB color at the given color tier.
+* See {@link fgFromRgb} for tier handling.
+*/
+function bgFromRgb(r, g, b, tier) {
+	if (tier === "truecolor") return `48;2;${r};${g};${b}`;
+	if (tier === "256") return `48;5;${rgbToAnsi256(r, g, b)}`;
+	const idx = nearestAnsi16(r, g, b);
+	return idx < 8 ? `${40 + idx}` : `${92 + idx}`;
+}
+/**
+* Convert a 256-palette index back to its canonical xterm hex value.
+*
+* Mirrors `rgbToAnsi256`:
+*   - 16–231: 6×6×6 color cube. Index = 16 + 36·r + 6·g + b (each channel 0..5).
+*   - 232–255: 24-step grayscale ramp.
+*   - 0–15: ANSI 16 slots (reuses ANSI16_SLOT_HEX for exact parity with
+*     `nearestAnsi16`).
+*/
+function ansi256ToHex(idx) {
+	if (idx < 0 || idx > 255 || !Number.isInteger(idx)) return "#000000";
+	if (idx < 16) {
+		const [r, g, b] = ANSI_16_COLORS[idx];
+		return rgbToHexHash(r, g, b);
+	}
+	if (idx < 232) {
+		const levels = [
+			0,
+			95,
+			135,
+			175,
+			215,
+			255
+		];
+		const i = idx - 16;
+		const r = levels[Math.floor(i / 36)];
+		const g = levels[Math.floor(i % 36 / 6)];
+		const b = levels[i % 6];
+		return rgbToHexHash(r, g, b);
+	}
+	const gray = 8 + (idx - 232) * 10;
+	return rgbToHexHash(gray, gray, gray);
+}
+function rgbToHexHash(r, g, b) {
+	const h = (n) => n.toString(16).padStart(2, "0");
+	return `#${h(r)}${h(g)}${h(b)}`;
+}
+function parseHexLocal(hex) {
+	if (typeof hex !== "string") return null;
+	let s = hex.trim();
+	if (s.startsWith("#")) s = s.slice(1);
+	if (s.length === 3) s = s.split("").map((c) => c + c).join("");
+	if (s.length !== 6) return null;
+	const r = parseInt(s.slice(0, 2), 16);
+	const g = parseInt(s.slice(2, 4), 16);
+	const b = parseInt(s.slice(4, 6), 16);
+	if (Number.isNaN(r) || Number.isNaN(g) || Number.isNaN(b)) return null;
+	return [
+		r,
+		g,
+		b
+	];
+}
+/**
+* Hex-in / hex-out quantization for previews.
+*
+* Takes any hex color and returns the hex a real terminal at that tier would
+* actually emit. Used by the Sterling storybook to make the `1/2/3/4` tier
+* toggle visibly different in-process — the output phase already does this
+* when writing to a real TTY, but preview surfaces (theme swatches, rendered
+* components inside a storybook app) bypass output-phase quantization. Apply
+* `quantizeHex` at render time to mimic tier-specific terminal output.
+*
+*   - `truecolor`: returns the input unchanged (normalized to `#rrggbb`).
+*   - `256`: snaps to the nearest xterm-256 slot, then returns that slot's hex.
+*   - `ansi16`: snaps to one of the 16 standard slots (canonical xterm RGB).
+*   - `mono`: luminance threshold (>= 0.5 → `#ffffff`, else `#000000`).
+*
+* Returns the input unchanged if it cannot be parsed as a hex color.
+*/
+function quantizeHex(hex, tier) {
+	const rgb = parseHexLocal(hex);
+	if (!rgb) return hex;
+	const [r, g, b] = rgb;
+	if (tier === "truecolor") return rgbToHexHash(r, g, b);
+	if (tier === "256") return ansi256ToHex(rgbToAnsi256(r, g, b));
+	if (tier === "ansi16") {
+		const [cr, cg, cb] = ANSI_16_COLORS[nearestAnsi16(r, g, b)];
+		return rgbToHexHash(cr, cg, cb);
+	}
+	return (.2126 * r + .7152 * g + .0722 * b) / 255 >= .5 ? "#ffffff" : "#000000";
+}
+/**
+* Hex-regex used to detect hex leaves during tier quantization walks.
+* Matches `#rgb` and `#rrggbb` (case-insensitive).
+*/
+const HEX_LEAF_RE$1 = /^#[0-9a-fA-F]{3}([0-9a-fA-F]{3})?$/;
+function isHexLeaf$1(value) {
+	return typeof value === "string" && HEX_LEAF_RE$1.test(value);
+}
+/**
+* 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.
+*/
+function pickColorLevel(theme, tier) {
+	if (tier === "truecolor") return theme;
+	return pickColorLevelWalk(theme, tier);
+}
+function pickColorLevelWalk(obj, tier) {
+	if (obj == null) return obj;
+	if (isHexLeaf$1(obj)) return quantizeHex(obj, tier);
+	if (Array.isArray(obj)) return obj.map((v) => pickColorLevelWalk(v, tier));
+	if (typeof obj === "object") {
+		const out = {};
+		for (const [k, v] of Object.entries(obj)) out[k] = pickColorLevelWalk(v, tier);
+		return out;
+	}
+	return obj;
+}
+//#endregion
+//#region packages/ansi/src/profile.ts
+/**
+* Terminal profile — single source of truth for terminal detection.
+*
+* One function, one profile. Collapses the previously redundant trio of
+* `detectColor()`, `detectTerminalCaps()`, and `resolveColorTier()` into a
+* single entry point: {@link createTerminalProfile}.
+*
+* Phase 3 of `km-silvery.terminal-profile-plateau`. Phase 4 (unify entry
+* points) will thread the profile through `run()`, `createApp().run()`, and
+* `render()` so every Term instance is populated from one detection pass.
+*
+* Post km-silvery.plateau-naming-polish (2026-04-23): 2-layer shape —
+* `profile.caps` (protocol flags + `maybe*` heuristics) and `profile.emulator`
+* (program/version/TERM). The former `profile.heuristics` namespace was
+* absorbed into caps with a `maybe` prefix per-field.
+*
+* Phase 7 of `km-silvery.caps-restructure` (Pro verdict 2026-04-23) originally
+* split the flat `TerminalCaps` into three layers; the heuristics layer proved
+* too small to earn its own namespace and was collapsed in the naming polish.
+*/
+/**
+* Build a {@link TerminalProfile} from the current environment.
+*
+* 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, …)
+*
+* 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`.
+*
+* 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.
+*
+* No I/O beyond whatever `detectTerminalCaps()` already does (a `defaults read`
+* call on macOS for Apple Terminal dark-mode heuristics — cached).
+*
+* @example
+* ```ts
+* // Auto-detect from process.env + process.stdout
+* const profile = createTerminalProfile()
+* console.log(profile.colorLevel) // "truecolor" on Ghostty
+*
+* // Force a tier (still honors NO_COLOR / FORCE_COLOR env precedence)
+* const forced = createTerminalProfile({ colorLevel: "256" })
+*
+* // Term path — base caps already detected, just resolve color tier.
+* const termProfile = createTerminalProfile({
+*   colorLevel: userColorLevel,
+*   caps: term.caps,
+* })
+*
+* // Headless/test fixture — zero env influence
+* const fake = createTerminalProfile({
+*   env: {},
+*   stdout: { isTTY: true },
+*   colorLevel: "truecolor",
+* })
+* ```
+*/
+function createTerminalProfile(options = {}) {
+	const env = options.env ?? process.env;
+	const stdout = options.stdout ?? process.stdout;
+	const stdin = "stdin" in options ? options.stdin : process.stdin;
+	const envTier = envColorTier(env);
+	const overrideTier = options.colorLevel === null ? "mono" : options.colorLevel ?? void 0;
+	const baseCapsTier = options.caps?.colorLevel;
+	let resolvedTier;
+	let colorProvenance;
+	if (envTier !== void 0) {
+		resolvedTier = envTier;
+		colorProvenance = "env";
+	} else if (overrideTier !== void 0) {
+		resolvedTier = overrideTier;
+		colorProvenance = "override";
+	} else if (baseCapsTier !== void 0) {
+		resolvedTier = baseCapsTier;
+		colorProvenance = "caller-caps";
+	} else {
+		resolvedTier = detectColorFromEnv(env, stdout);
+		colorProvenance = "auto";
+	}
+	const detected = options.caps ? void 0 : detectTerminalProfileFromEnv(env, stdout);
+	const baseCaps = options.caps ? {
+		...defaultCaps(),
+		...options.caps
+	} : detected.caps;
+	const baseEmulator = options.emulator ? {
+		...defaultEmulator(),
+		...options.emulator
+	} : detected?.emulator ?? defaultEmulator();
+	const inputResolved = options.caps?.input ?? (stdin?.isTTY === true && typeof stdin.setRawMode === "function");
+	return freezeProfileInDev({
+		emulator: baseEmulator,
+		caps: {
+			...baseCaps,
+			colorLevel: resolvedTier,
+			colorForced: colorProvenance === "env" || colorProvenance === "override",
+			colorProvenance,
+			input: inputResolved
+		},
+		colorLevel: resolvedTier
+	});
+}
+/**
+* Freeze a profile (plus its nested caps / emulator) in dev builds so
+* `profile.colorLevel === profile.caps.colorLevel` and every other invariant
+* can't silently drift via direct mutation. Production builds skip the
+* freeze to keep the allocation cheap; the type-level `readonly` fields
+* already block TS-side writes.
+*
+* Per km-silvery.profile-immutable (/pro review 2026-04-23): profiles are
+* snapshot values by contract. Any caller that needs to "change" a profile
+* must build a new one — the plateau-era single-source-of-truth guarantee
+* leans on this.
+*/
+function freezeProfileInDev(profile) {
+	if (process.env.NODE_ENV === "production") return profile;
+	Object.freeze(profile.caps);
+	Object.freeze(profile.emulator);
+	Object.freeze(profile);
+	return profile;
+}
+/**
+* Build a {@link TerminalProfile} with an OSC-detected `theme` bundled in.
+*
+* 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:
+*
+* 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().
+*
+* 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.
+*
+* 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
+* ```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
+*/
+async function probeTerminalProfile(options = {}) {
+	const profile = createTerminalProfile(options);
+	if (options.probeTheme === false) return profile;
+	let kittyGraphics = profile.caps.kittyGraphics;
+	if (kittyGraphics && options.input) kittyGraphics = await probeKittyGraphics(options.input, options.timeoutMs ?? 150) === true;
+	const theme = await detectTheme({
+		caps: profile.caps,
+		fallbackDark: options.fallbackDark,
+		fallbackLight: options.fallbackLight,
+		timeoutMs: options.timeoutMs,
+		input: options.input
+	});
+	const resolvedTheme = profile.caps.colorForced ? pickColorLevel(theme, profile.colorLevel) : theme;
+	const caps = kittyGraphics === profile.caps.kittyGraphics ? profile.caps : {
+		...profile.caps,
+		kittyGraphics
+	};
+	return freezeProfileInDev({
+		...profile,
+		caps,
+		theme: resolvedTheme
+	});
+}
+/**
+* Deterministic variant of {@link detectColor} that takes env+stdout as args.
+* Exported-internal so the shim `detectColor()` can delegate without reading
+* `process.env` twice.
+*/
+function detectColorFromEnv(env, stdout) {
+	if (env.NO_COLOR !== void 0) return "mono";
+	const forceColor = env.FORCE_COLOR;
+	if (forceColor !== void 0) {
+		if (forceColor === "0" || forceColor === "false") return "mono";
+		if (forceColor === "1") return "ansi16";
+		if (forceColor === "2") return "256";
+		if (forceColor === "3") return "truecolor";
+		return "ansi16";
+	}
+	if (!stdout.isTTY) return "mono";
+	if (env.TERM === "dumb") return "mono";
+	const colorTerm = env.COLORTERM;
+	if (colorTerm === "truecolor" || colorTerm === "24bit") return "truecolor";
+	const term = env.TERM ?? "";
+	if (term.includes("truecolor") || term.includes("24bit") || term.includes("xterm-ghostty") || term.includes("xterm-kitty") || term.includes("wezterm")) return "truecolor";
+	if (term.includes("256color") || term.includes("256")) return "256";
+	const termProgram = env.TERM_PROGRAM;
+	if (termProgram === "iTerm.app" || termProgram === "Apple_Terminal") return termProgram === "iTerm.app" ? "truecolor" : "256";
+	if (termProgram === "Ghostty" || termProgram === "WezTerm") return "truecolor";
+	if (env.KITTY_WINDOW_ID) return "truecolor";
+	if (term.includes("xterm") || term.includes("color") || term.includes("ansi")) return "ansi16";
+	if (CI_ENVS.some((name) => env[name] !== void 0)) return "ansi16";
+	if (env.WT_SESSION) return "truecolor";
+	return "ansi16";
+}
+/**
+* Env-only FORCE_COLOR / NO_COLOR tier probe. Returns `undefined` when no
+* env override applies. Used by {@link createTerminalProfile} to enforce that
+* env always beats caller-supplied overrides.
+*/
+function envColorTier(env) {
+	if (env.NO_COLOR !== void 0) return "mono";
+	const force = env.FORCE_COLOR;
+	if (force !== void 0) {
+		if (force === "0" || force === "false") return "mono";
+		if (force === "1") return "ansi16";
+		if (force === "2") return "256";
+		if (force === "3") return "truecolor";
+		return "ansi16";
+	}
+}
+/**
+* Deterministic env-based detection of the full two-layer profile
+* ({@link TerminalCaps} + {@link TerminalEmulator}). Reads env explicitly
+* (no `process.env` access) so callers can inject custom environments in
+* tests. Color tier is derived via {@link detectColorFromEnv} and therefore
+* honors FORCE_COLOR / NO_COLOR.
+*/
+function detectTerminalProfileFromEnv(env, stdout) {
+	const program = env.TERM_PROGRAM ?? "";
+	const programLower = program.toLowerCase();
+	const version = env.TERM_PROGRAM_VERSION ?? "";
+	const TERM = env.TERM ?? "";
+	const noColor = env.NO_COLOR !== void 0;
+	const isAppleTerminal = programLower === "apple_terminal";
+	const colorLevel = noColor ? "mono" : detectColorFromEnv(env, stdout);
+	const isKitty = TERM === "xterm-kitty";
+	const isITerm = programLower === "iterm.app";
+	const isGhostty = programLower === "ghostty";
+	const isWezTerm = programLower === "wezterm";
+	const isAlacritty = programLower === "alacritty";
+	const isFoot = TERM === "foot" || TERM === "foot-extra";
+	const isDumb = TERM === "dumb";
+	const isModern = !isDumb && (isKitty || isITerm || isGhostty || isWezTerm || isFoot);
+	let isKittyWithTextSizing = false;
+	if (isKitty) {
+		const parts = version.split(".");
+		const major = Number(parts[0]) || 0;
+		const minor = Number(parts[1]) || 0;
+		isKittyWithTextSizing = major > 0 || major === 0 && minor >= 40;
+	}
+	let maybeDarkBackground = !isAppleTerminal;
+	const colorFgBg = env.COLORFGBG;
+	if (colorFgBg) {
+		const parts = colorFgBg.split(";");
+		const bg = parseInt(parts[parts.length - 1] ?? "", 10);
+		if (!isNaN(bg)) maybeDarkBackground = bg < 7;
+	} else if (isAppleTerminal) maybeDarkBackground = detectMacOSDarkMode();
+	let maybeNerdFont = isModern || isAlacritty;
+	const nfEnv = env.NERDFONT;
+	if (nfEnv === "0" || nfEnv === "false") maybeNerdFont = false;
+	else if (nfEnv === "1" || nfEnv === "true") maybeNerdFont = true;
+	const underlineExtensions = isModern || !isDumb && isAlacritty;
+	const underlineStyles = underlineExtensions ? [
+		"double",
+		"curly",
+		"dotted",
+		"dashed"
+	] : [];
+	const unicode = isModern || !isDumb && env.WT_SESSION !== void 0 || env.KITTY_WINDOW_ID !== void 0 || utf8Locale(env) || !isDumb && termImpliesUnicode(TERM) || env.CI !== void 0 && env.GITHUB_ACTIONS !== void 0;
+	const cursor = stdout.isTTY === true && TERM !== "dumb";
+	return {
+		emulator: {
+			program,
+			version,
+			TERM
+		},
+		caps: {
+			cursor,
+			input: false,
+			colorLevel,
+			colorForced: noColor || env.FORCE_COLOR !== void 0,
+			colorProvenance: noColor || env.FORCE_COLOR !== void 0 ? "env" : "auto",
+			unicode,
+			underlineStyles,
+			underlineColor: underlineExtensions,
+			overline: underlineExtensions,
+			textSizing: isKittyWithTextSizing,
+			kittyKeyboard: !isDumb && (isKitty || isGhostty || isWezTerm || isFoot),
+			bracketedPaste: true,
+			mouse: true,
+			kittyGraphics: !isDumb && (isKitty || isGhostty),
+			sixel: !isDumb && (isFoot || isWezTerm),
+			osc52: isModern || !isDumb && isAlacritty,
+			hyperlinks: isModern || !isDumb && isAlacritty,
+			notifications: isITerm || isKitty,
+			syncOutput: isModern || !isDumb && isAlacritty,
+			maybeDarkBackground,
+			maybeNerdFont,
+			maybeWideEmojis: !isAppleTerminal
+		},
+		colorLevel
+	};
+}
+/**
+* Does `env.LANG` / `LC_ALL` / `LC_CTYPE` name a UTF-8 locale? Absorbed from
+* the retired `detectUnicode()` helper.
+*/
+function utf8Locale(env) {
+	const lang = (env.LANG ?? env.LC_ALL ?? env.LC_CTYPE ?? "").toLowerCase();
+	return lang.includes("utf-8") || lang.includes("utf8");
+}
+/**
+* Does the `TERM` value imply a multiplexer / terminal family we know renders
+* unicode correctly? Absorbed from the retired `detectUnicode()` helper.
+*/
+function termImpliesUnicode(term) {
+	return term.includes("xterm") || term.includes("rxvt") || term.includes("screen") || term.includes("tmux");
+}
+const CI_ENVS = [
+	"CI",
+	"GITHUB_ACTIONS",
+	"GITLAB_CI",
+	"JENKINS_URL",
+	"BUILDKITE",
+	"CIRCLECI",
+	"TRAVIS"
+];
+let cachedMacOSDarkMode;
+function detectMacOSDarkMode() {
+	if (cachedMacOSDarkMode !== void 0) return cachedMacOSDarkMode;
+	try {
+		const { spawnSync } = process.getBuiltinModule("node:child_process");
+		cachedMacOSDarkMode = spawnSync("defaults", [
+			"read",
+			"-g",
+			"AppleInterfaceStyle"
+		], {
+			encoding: "utf-8",
+			timeout: 500
+		}).stdout?.trim() === "Dark";
+	} catch {
+		cachedMacOSDarkMode = false;
+	}
+	return cachedMacOSDarkMode;
+}
+//#endregion
+//#region packages/ansi/src/sgr-codes.ts
+/**
+* Marker bit for the PACKED numeric truecolor form: `0x1000000 | r<<16 | g<<8 | b`.
+* ag-term's ANSI parser (unicode.ts) tracks inline truecolor SGR in this compact
+* form, and those numbers reach fg/bgColorCode via styleToAnsiCodes when wrapped
+* text re-emits carried styles (fixSgrAcrossWrappedLines).
+*/
+const PACKED_TRUECOLOR = 16777216;
+/** The palette slot for a color, or `undefined` for a genuine truecolor. */
+function paletteSlot(color) {
+	const idx = typeof color === "number" ? color : color.index;
+	return typeof idx === "number" && idx >= 0 && idx <= 255 ? idx : void 0;
+}
+/** Resolve a non-palette color to truecolor components, unpacking the packed numeric form. */
+function truecolorRgb(color) {
+	if (typeof color === "number") {
+		if (color >= PACKED_TRUECOLOR && color <= 33554431) return {
+			r: color >> 16 & 255,
+			g: color >> 8 & 255,
+			b: color & 255
+		};
+		throw new Error(`sgr-codes: number ${color} is neither a palette slot (0-255) nor a packed truecolor (0x1000000|rgb)`);
+	}
+	return color;
+}
+/**
+* Emit the shortest SGR code string for a foreground color.
+* - Basic 0-7: 4-bit code (30+N)
+* - Extended 8-255: 256-color (38;5;N)
+* - RGB (no palette index): true color (38;2;R;G;B)
+*/
+function fgColorCode(color) {
+	const slot = paletteSlot(color);
+	if (slot !== void 0) {
+		if (slot <= 7) return `${30 + slot}`;
+		return `38;5;${slot}`;
+	}
+	const { r, g, b } = truecolorRgb(color);
+	return `38;2;${r};${g};${b}`;
+}
+/**
+* Emit the shortest SGR code string for a background color.
+* - Basic 0-7: 4-bit code (40+N)
+* - Extended 8-255: 256-color (48;5;N)
+* - RGB (no palette index): true color (48;2;R;G;B)
+*/
+function bgColorCode(color) {
+	const slot = paletteSlot(color);
+	if (slot !== void 0) {
+		if (slot <= 7) return `${40 + slot}`;
+		return `48;5;${slot}`;
+	}
+	const { r, g, b } = truecolorRgb(color);
+	return `48;2;${r};${g};${b}`;
+}
+//#endregion
+//#region packages/ansi/src/utils.ts
+/**
+* Process-lifetime set of warning IDs that have already fired. Used by
+* {@link warnOnce} to avoid console spam on every re-render / every paste /
+* every parse. Shared across packages — one latch per warning ID, regardless
+* of which module emits it.
+*
+* Intentionally process-global (not scoped per {@link Term}) because the
+* warnings gated here describe developer-mistake conditions that are
+* semantically "once per process": spam is worse than missed repeats.
+*/
+const _firedWarnings = /* @__PURE__ */ new Set();
+/**
+* Emit a warning exactly once per process, keyed by `id`.
+*
+* The first call with a given `id` invokes `emit(message)`; subsequent calls
+* with the same `id` are no-ops. Use for dev-mode checks that would otherwise
+* spam the console on every render pass / every keystroke / every reconcile.
+*
+* Consolidates what used to be three parallel `let hasWarned*` latches
+* scattered across silvery packages (`test/index.tsx`,
+* `ag-react/reconciler/host-config.ts`, `ag/keys.ts`). See
+* km-silvery.latch-consolidation.
+*
+* @param id - Unique warning identifier (stable across restarts). Convention:
+*   `<package>:<short-slug>`, e.g. `"silvery/test:termless-leak"`,
+*   `"silvery/ag-react:box-in-text"`.
+* @param emit - Callback that actually produces the warning. Called once.
+*   Omit to use `console.warn` with no message (rarely useful — prefer an
+*   explicit emit).
+*
+* @example
+* ```ts
+* import { warnOnce } from "@silvery/ansi"
+*
+* function validateBoxInText() {
+*   if (!isValid) {
+*     warnOnce("silvery/ag-react:box-in-text", () =>
+*       console.warn("<Box> cannot be nested inside <Text>.")
+*     )
+*   }
+* }
+* ```
+*/
+function warnOnce(id, emit) {
+	if (_firedWarnings.has(id)) return;
+	_firedWarnings.add(id);
+	emit();
+}
+//#endregion
+//#region packages/ansi/src/flatten.ts
+/**
+* Channel-role-state default rule. Matches Sterling / Primer / CSS-var
+* conventions: `{kind}-{role}[-{state}]`, with `fg-on-{role}` for `fgOn`,
+* and implicit-kind collapse for the `surface` / `border` roles.
+*
+* Mapping examples:
+* | Path                         | Flat key                    |
+* | ---------------------------- | --------------------------- |
+* | `accent.fg`                  | `fg-accent`                 |
+* | `accent.bg`                  | `bg-accent`                 |
+* | `accent.fgOn`                | `fg-on-accent`              |
+* | `accent.border`              | `border-accent`             |
+* | `accent.hover.bg`            | `bg-accent-hover`           |
+* | `accent.active.fg`           | `fg-accent-active`          |
+* | `info.hover.bg`              | `bg-info-hover`             |
+* | `cursor.fg`                  | `fg-cursor`                 |
+* | `muted.bg`                   | `bg-muted`                  |
+* | `surface.default`            | `bg-surface-default`        |
+* | `surface.subtle`             | `bg-surface-subtle`         |
+* | `surface.hover`              | `bg-surface-hover`          |
+* | `border.default`             | `border-default`            |
+* | `border.focus`               | `border-focus`              |
+* | `border.muted`               | `border-muted`              |
+*
+* Returns `null` for depth-1 leaves (e.g. `mode`, `name` — not role-scoped)
+* so metadata doesn't get flattened. The caller (`bakeFlat`) already filters
+* non-hex leaves, but the rule also guards paths shorter than 2 segments.
+*/
+const defaultFlattenRule = (path) => {
+	if (path.length < 2) return null;
+	const role = path[0];
+	const last = path[path.length - 1];
+	const mid = path.slice(1, -1);
+	if (last === "fgOn") return `fg-on-${role}`;
+	if (last === "fg" || last === "bg" || last === "border") {
+		const state = mid.length > 0 ? mid.join("-") : void 0;
+		return state ? `${last}-${role}-${state}` : `${last}-${role}`;
+	}
+	if (role === "surface") return `bg-surface-${last}`;
+	if (role === "border") return `border-${last}`;
+	return null;
+};
+/** Matches `#rgb`, `#rrggbb`, and `#rrggbbaa` (case-insensitive). */
+const HEX_LEAF_RE = /^#[0-9a-fA-F]{3}([0-9a-fA-F]{3})?([0-9a-fA-F]{2})?$/;
+function isHexLeaf(value) {
+	return typeof value === "string" && HEX_LEAF_RE.test(value);
+}
+/**
+* Populate flat hyphen-keys onto `theme` in-place by walking hex leaves and
+* asking `rule` where each leaf should also live at the root.
+*
+* Both the nested and flat forms reference the SAME string (not copies) —
+* `bakeFlat({...}).accent.bg === bakeFlat({...})["bg-accent"]`.
+*
+* `rule` defaults to {@link defaultFlattenRule} (channel-role-state).
+* Rules returning `null` for a path skip that leaf — useful for suppressing
+* metadata or implementing partial projections.
+*
+* The returned object is deep-frozen. The input object is mutated in place
+* and returned; callers that want an unfrozen copy should `structuredClone`
+* before calling.
+*
+* @param theme  nested POJO of hex-string leaves (plus optional metadata)
+* @param rule   how to compute flat keys from nested paths
+* @returns      the same object, with flat keys added and frozen
+*/
+function bakeFlat(theme, rule = defaultFlattenRule) {
+	const root = theme;
+	if (Object.isFrozen(root)) return theme;
+	walk(root, [], root, rule);
+	freezeDeep(root);
+	return theme;
+}
+function walk(node, path, root, rule) {
+	for (const key of Object.keys(node)) {
+		if (node === root && key.includes("-")) continue;
+		const value = node[key];
+		const subpath = [...path, key];
+		if (isHexLeaf(value)) {
+			const flatKey = rule(subpath);
+			if (flatKey !== null) root[flatKey] = value;
+			continue;
+		}
+		if (value && typeof value === "object" && !Array.isArray(value)) walk(value, subpath, root, rule);
+	}
+}
+function freezeDeep(o) {
+	if (o === null || typeof o !== "object") return;
+	if (Object.isFrozen(o)) return;
+	Object.freeze(o);
+	for (const k of Object.keys(o)) freezeDeep(o[k]);
+}
+//#endregion
+//#region packages/ansi/src/terminal-control.ts
+/**
+* ANSI terminal control helpers.
+*
+* Pure string-returning functions for terminal control sequences.
+* No side effects, no stdout writes -- consumers compose and write.
+*
+* Covers: screen management, cursor control, scroll regions,
+* mouse tracking, keyboard protocols, and bracketed paste.
+*
+* @see https://invisible-island.net/xterm/ctlseqs/ctlseqs.html
+* @see https://sw.kovidgoyal.net/kitty/keyboard-protocol/
+*/
+/** Escape character (0x1B) */
+const ESC$1 = "\x1B";
+/** Control Sequence Introducer: ESC [ */
+const CSI$1 = `${ESC$1}[`;
+`${ESC$1}`;
+function enableMouse(options = {}) {
+	return `${CSI$1}?1003h${CSI$1}?1006h${options.pixels ? `${CSI$1}?1016h` : ""}`;
+}
+/**
+* Disable mouse tracking. Disables in reverse order of enabling.
+*/
+function disableMouse() {
+	return `${CSI$1}?1016l${CSI$1}?1006l${CSI$1}?1003l`;
+}
+/**
+* Enable bracketed paste mode (DEC private mode 2004).
+* Terminal wraps pasted text with markers so the app can distinguish
+* paste from typed input.
+*/
+function enableBracketedPaste() {
+	return `${CSI$1}?2004h`;
+}
+/**
+* Disable bracketed paste mode.
+*/
+function disableBracketedPaste() {
+	return `${CSI$1}?2004l`;
+}
+/**
+* Enable the Kitty keyboard protocol (push mode).
+*
+* Sends CSI > flags u to opt into the specified modes.
+* Supported by: Ghostty, Kitty, WezTerm, foot. Ignored by unsupported terminals.
+*
+* Flags are a bitfield:
+*
+* | Flag | Bit | Description                               |
+* | ---- | --- | ----------------------------------------- |
+* | 1    | 0   | Disambiguate escape codes                 |
+* | 2    | 1   | Report event types (press/repeat/release)  |
+* | 4    | 2   | Report alternate keys                     |
+* | 8    | 3   | Report all keys as escape codes           |
+* | 16   | 4   | Report associated text                    |
+*
+* @param flags Bitfield of Kitty keyboard flags
+*/
+function enableKittyKeyboard(flags = 1) {
+	return `${CSI$1}>${flags}u`;
+}
+/**
+* Disable the Kitty keyboard protocol (pop mode stack).
+* Sends CSI < u to restore the previous keyboard mode.
+*/
+function disableKittyKeyboard() {
+	return `${CSI$1}<u`;
+}
+//#endregion
+//#region packages/ansi/src/kitty-graphics.ts
+/**
+* Kitty graphics protocol — minimal encoder for cell-sized overlay placements.
+*
+* Used by the backdrop-fade pass to fade emoji/wide-char glyphs (SGR 2 "dim"
+* is a no-op on bitmap emoji in most terminals). We upload a single tiny
+* translucent RGBA image once, then emit `a=p` placements over specific cells
+* with `z=1` so the overlay sits on top of the already-rendered emoji glyph.
+*
+* ## Protocol summary
+*
+* The Kitty graphics protocol uses APC escapes: `\x1b_G<control>;<payload>\x1b\\`.
+* Control parameters are key=value pairs separated by commas. Payload is
+* base64-encoded image data (only on upload).
+*
+* Key commands we use:
+*
+* | Command     | Meaning                                                       |
+* | ----------- | ------------------------------------------------------------- |
+* | `a=t`       | Transmit (upload) image data                                  |
+* | `a=p`       | Place a previously-uploaded image                             |
+* | `a=d`       | Delete (remove placements and/or free images)                 |
+* | `f=32`      | RGBA pixel format (4 bytes per pixel)                         |
+* | `s=W,v=H`   | Source image dimensions in pixels                             |
+* | `i=<id>`    | Image ID (stable across frames)                               |
+* | `p=<id>`    | Placement ID (stable per cell)                                |
+* | `C=1`       | Disable cursor movement after placement (crucial for overlay) |
+* | `c=<cols>`  | Cell column extent                                            |
+* | `r=<rows>`  | Cell row extent                                               |
+* | `z=<zidx>`  | Z-index (0 = below text, 1 = above text)                      |
+* | `q=2`       | Quiet mode (suppress OK/error responses from terminal)        |
+*
+* Because the image is tiled into a single cell, `c=1,r=1,C=1` keeps the
+* placement local — it doesn't shift the rendered text layout.
+*
+* @see https://sw.kovidgoyal.net/kitty/graphics-protocol/
+*/
+/**
+* Stable image ID for the backdrop scrim overlay. Uploaded once per terminal
+* session; placements reuse this ID. Value is arbitrary — just needs to be
+* unique within the process. 0xBEEF picked for grep-ability.
+*/
+const BACKDROP_SCRIM_IMAGE_ID = 48879;
+/**
+* Placement ID base for backdrop scrim placements. Each cell gets a unique
+* placement ID derived from `x * OFFSET + y`. This lets us target individual
+* placements for deletion while leaving others alive. `i=<id>,p=<pid>` refers
+* to a single placement.
+*/
+const BACKDROP_PLACEMENT_X_STRIDE = 1e4;
+/**
+* Derive a stable placement ID for a given (x, y) cell. Max column = 9999,
+* which comfortably exceeds any realistic terminal width.
+*/
+function backdropPlacementId(x, y) {
+	return x * BACKDROP_PLACEMENT_X_STRIDE + y + 1;
+}
+/**
+* Encode a Uint8Array as base64. Kitty expects standard base64 (with `+`/`/`
+* and `=` padding). We use Buffer when available (Node/Bun), fall back to
+* btoa for browser/canvas adapters (the canvas target may never actually
+* need to emit Kitty escapes — this is just defensive).
+*/
+function base64Encode(bytes) {
+	if (typeof Buffer !== "undefined") return Buffer.from(bytes).toString("base64");
+	let binary = "";
+	for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+	const g = globalThis;
+	if (typeof g.btoa === "function") return g.btoa(binary);
+	throw new Error("base64 encoding unavailable in this environment");
+}
+/**
+* Build a tiny RGBA pixel grid for the scrim overlay.
+*
+* Kitty's graphics protocol paints images at native pixel resolution scaled
+* to `c` x `r` cells. A 2x2 RGBA image scaled to a single cell (~10x20 px
+* depending on font) gives us a smooth fill. We intentionally keep the
+* image tiny to minimize base64 payload size on the upload frame.
+*
+* Pixel color: `(r, g, b, a)` where `r/g/b` is the scrim tint and `a` is the
+* alpha (0-255). For a dark backdrop we use near-black at ~50% alpha, which
+* darkens the emoji underneath without completely hiding it.
+*
+* Width/height = 2 pixels — 16 bytes total, ~24 bytes base64. Upload is ~60
+* bytes including control chars. One-time cost per modal session.
+*/
+function buildScrimPixels(tint, alpha) {
+	const a = Math.max(0, Math.min(255, Math.round(alpha)));
+	const r = Math.max(0, Math.min(255, Math.round(tint.r)));
+	const g = Math.max(0, Math.min(255, Math.round(tint.g)));
+	const b = Math.max(0, Math.min(255, Math.round(tint.b)));
+	const bytes = new Uint8Array(16);
+	for (let i = 0; i < 4; i++) {
+		bytes[i * 4 + 0] = r;
+		bytes[i * 4 + 1] = g;
+		bytes[i * 4 + 2] = b;
+		bytes[i * 4 + 3] = a;
+	}
+	return bytes;
+}
+/**
+* APC wrapper: `\x1b_G<control>[;<payload>]\x1b\\`.
+*
+* The protocol allows chunking large payloads via `m=1` but our scrim is
+* tiny — always fits in one chunk.
+*/
+function apc(control, payload) {
+	if (payload === void 0 || payload === "") return `\x1b_G${control}\x1b\\`;
+	return `\x1b_G${control};${payload}\x1b\\`;
+}
+/**
+* Emit a one-shot image upload. Terminal stores the RGBA pixels under
+* `i=<imageId>` and keeps them until explicitly freed. Subsequent placements
+* reference the image by ID without re-sending pixel data.
+*
+* `q=2` suppresses the terminal's OK/error reply — otherwise we'd see stray
+* APC sequences back on stdin.
+*/
+function kittyUploadScrimImage(pixels, width, height, imageId = BACKDROP_SCRIM_IMAGE_ID) {
+	const payload = base64Encode(pixels);
+	return apc(`a=t,f=32,s=${width},v=${height},i=${imageId},q=2`, payload);
+}
+/**
+* Emit a cell placement. Places `imageId` at the current cursor position
+* covering `c` cols and `r` rows with z-index `z`. `C=1` prevents the cursor
+* from advancing after placement (critical — otherwise every placement
+* shifts the cursor, breaking the caller's positioning).
+*
+* Placement ID (`p=<pid>`) is stable per cell so incremental frames can
+* replace placements without accumulating duplicates.
+*/
+function kittyPlaceAt(opts) {
+	const imageId = opts.imageId ?? 48879;
+	const cols = opts.cols ?? 1;
+	const rows = opts.rows ?? 1;
+	const z = opts.z ?? 1;
+	return apc(`a=p,i=${imageId},p=${opts.placementId},c=${cols},r=${rows},z=${z},C=1,q=2`);
+}
+/**
+* Delete ALL placements of our scrim image without freeing the image.
+* Used when the modal closes — we leave the image cached in case another
+* modal opens, but remove every overlay cell at once.
+*/
+function kittyDeleteAllScrimPlacements(imageId = BACKDROP_SCRIM_IMAGE_ID) {
+	return apc(`a=d,d=i,i=${imageId},q=2`);
+}
+/**
+* Absolute cursor position (CUP). 1-based row/col per VT100.
+*
+* Used to position the cursor before emitting a placement so the placement
+* lands in the right cell. Kept small and local — the rest of the pipeline
+* uses more elaborate cursor tracking, but for out-of-band overlay emission
+* we just want a deterministic "jump here, place, done."
+*/
+function cupTo(col, row) {
+	return `\x1b[${row + 1};${col + 1}H`;
+}
+//#endregion
+//#region packages/ansi/src/style/colors.ts
+/** Default ANSI codes for theme tokens when no theme object is given. */
+const THEME_TOKEN_DEFAULTS = {
+	primary: 33,
+	secondary: 36,
+	accent: 35,
+	error: 31,
+	warning: 33,
+	success: 32,
+	info: 36,
+	muted: 2,
+	link: 34,
+	border: 90,
+	surface: 37
+};
+//#endregion
+//#region packages/ansi/src/style/style.ts
+/**
+* createStyle() — theme-aware chalk replacement.
+*
+* Returns a chainable Proxy-based style object. Access properties to
+* accumulate styles, call with a string to apply them.
+*
+* @example
+* ```ts
+* const s = createStyle()
+* s.bold.red("error")           // "\x1b[1;31merror\x1b[22;39m"
+* s.hex("#ff0000")("text")      // truecolor foreground
+*
+* const s = createStyle({ theme })
+* s.primary("deploy")           // resolves $primary from theme
+* ```
+*/
+/**
+* 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).
+*/
+function resolveThemeColor(name, theme) {
+	if (!name) return void 0;
+	if (!name.startsWith("$")) return name;
+	if (!theme) return void 0;
+	return resolveToken(name, theme);
+}
+/** Internal: resolve a token name (with or without $ prefix) against a theme.
+*
+* Resolution order:
+*   1. Direct key lookup — finds Sterling flat keys (`bg-accent`,
+*      `fg-on-error`, `border-focus`, …) and legacy kebab keys
+*      (`primary-hover`, `fg-hover`, `bg-surface-hover`) and plain names
+*      (`bg`, `primary`, `muted`).
+*   2. No-hyphen fallback — `$surface-bg` → `theme.surfacebg`,
+*      `$focus-border` → `theme.focusborder`.
+*
+* The old `LEGACY_ALIASES` table (e.g. `fgmuted` → `muted`, `bgsurface` →
+* `surfacebg`) was removed in 0.18.1 once every shipped default Theme ships
+* with Sterling flat tokens baked in — `theme["fg-muted"]` and
+* `theme["bg-surface-subtle"]` are direct fields now, so no alias fallback
+* is required for canonical Sterling tokens. Tokens that existed only as
+* aliases (e.g. `$bg-surface`, `$fg-on-primary`, `$border-input`,
+* `$fg-disabled`) no longer resolve — callers should use the canonical
+* Sterling equivalents (`$bg-surface-default`, `$fg-on-accent`,
+* `$border-default`, `$fg-muted`).
+*/
+function resolveToken(name, theme) {
+	if (!theme) return void 0;
+	const token = name.startsWith("$") ? name.slice(1) : name;
+	if (token.startsWith("color")) {
+		const idx = parseInt(token.slice(5), 10);
+		if (idx >= 0 && idx < 16 && theme.palette && idx < theme.palette.length) return theme.palette[idx];
+	}
+	const themeObj = theme;
+	const direct = themeObj[token];
+	if (typeof direct === "string") return direct;
+	const noHyphen = token.replace(/-/g, "");
+	if (noHyphen !== token) {
+		const stripped = themeObj[noHyphen];
+		if (typeof stripped === "string") return stripped;
+	}
+}
+const ESC = "\x1B[";
+const KNOWN_METHODS = new Set([
+	"hex",
+	"rgb",
+	"bgHex",
+	"bgRgb",
+	"ansi256",
+	"bgAnsi256",
+	"resolve",
+	"curlyUnderline",
+	"dottedUnderline",
+	"dashedUnderline",
+	"doubleUnderline",
+	"underlineColor",
+	"styledUnderline"
+]);
+const THEME_TOKENS = new Set([
+	"primary",
+	"secondary",
+	"accent",
+	"error",
+	"warning",
+	"success",
+	"info",
+	"muted",
+	"link",
+	"border",
+	"surface"
+]);
+/** Convert chalk numeric level (0-3) to {@link ColorLevel}. */
+function fromChalkLevel(n) {
+	if (n <= 0) return "mono";
+	if (n === 1) return "ansi16";
+	if (n === 2) return "256";
+	return "truecolor";
+}
+/** Convert {@link ColorLevel} to chalk numeric level (0-3). */
+function toChalkLevel(cl) {
+	if (cl === "mono") return 0;
+	if (cl === "ansi16") return 1;
+	if (cl === "256") return 2;
+	return 3;
+}
+/**
+* Create a style object for terminal output.
+*
+* @param options - Color level and optional theme
+* @returns A chainable style object (chalk-compatible API)
+*
+* @example
+* ```ts
+* import { createStyle } from "@silvery/ansi"
+*
+* const s = createStyle()
+* console.log(s.bold.red("Error!"))
+* console.log(s.hex("#818cf8")("Indigo"))
+*
+* // With theme
+* const s = createStyle({ theme })
+* console.log(s.primary("Deploy"))
+* console.log(s.success("Done"))
+* ```
+*/
+function createStyle(options) {
+	const ref = {
+		level: "mono",
+		theme: options?.theme,
+		caps: {
+			underlineStyles: false,
+			underlineColor: false
+		}
+	};
+	if (options?.level !== void 0 && options.level !== null) {
+		ref.level = options.level;
+		ref.caps = options.caps ?? ref.caps;
+	} else if (options?.level === null) {
+		ref.level = "mono";
+		ref.caps = options.caps ?? ref.caps;
+	} else try {
+		const profile = createTerminalProfile({ stdout: process.stdout });
+		ref.level = profile.colorLevel;
+		ref.caps = options?.caps ?? {
+			underlineStyles: profile.caps.underlineStyles.length > 0,
+			underlineColor: profile.caps.underlineColor
+		};
+	} catch {
+		ref.level = "mono";
+		ref.caps = options?.caps ?? ref.caps;
+	}
+	return createChainWithRef({
+		opens: [],
+		closes: []
+	}, ref);
+}
+createStyle();
+/**
+* Create a chain that reads level from a mutable ref.
+* This allows `style.level = 3` to affect all subsequent calls.
+*/
+function createChainWithRef(state, ref) {
+	const proxyRef = { proxy: null };
+	const handler = {
+		apply(_target, _thisArg, args) {
+			const level = ref.level;
+			if (state.visible && level === "mono") return "";
+			let text;
+			if (args.length === 0) text = "";
+			else if (Array.isArray(args[0]) && "raw" in args[0]) text = String.raw(args[0], ...args.slice(1));
+			else if (args.length > 1) text = args.map((a) => String(a ?? "")).join(" ");
+			else text = String(args[0] ?? "");
+			if (text === "") return "";
+			if (level === "mono" || state.opens.length === 0) return text;
+			const open = `${ESC}${state.opens.join(";")}m`;
+			const close = `${ESC}${state.closes.join(";")}m`;
+			for (const closeCode of state.closes) {
+				const closeSeq = `${ESC}${closeCode}m`;
+				const parts = text.split(closeSeq);
+				if (parts.length > 1) text = parts.join(`${closeSeq}${open}`);
+			}
+			if (text.includes("\n")) text = text.replace(/\r?\n/g, `${close}$&${open}`);
+			return `${open}${text}${close}`;
+		},
+		get(_target, prop) {
+			if (typeof prop === "symbol") return void 0;
+			if (prop === "level") return toChalkLevel(ref.level);
+			if (prop === "resolve") return (token) => resolveToken(token, ref.theme);
+			if (prop === "visible") return createChainWithRef({
+				...state,
+				visible: true
+			}, ref);
+			if (prop === "call" || prop === "apply" || prop === "bind") return Function.prototype[prop].bind(proxyRef.proxy);
+			const level = ref.level;
+			if (prop === "hex" || prop === "bgHex") return (color) => {
+				if (level === "mono") return createChainWithRef(state, ref);
+				const rgb = hexToRgb$1(color);
+				if (!rgb) return createChainWithRef(state, ref);
+				const code = prop === "hex" ? fgFromRgb(rgb[0], rgb[1], rgb[2], level) : bgFromRgb(rgb[0], rgb[1], rgb[2], level);
+				const close = prop === "hex" ? "39" : "49";
+				return createChainWithRef({
+					opens: [...state.opens, code],
+					closes: [...state.closes, close]
+				}, ref);
+			};
+			if (prop === "rgb" || prop === "bgRgb") return (r, g, b) => {
+				if (level === "mono") return createChainWithRef(state, ref);
+				const code = prop === "rgb" ? fgFromRgb(r, g, b, level) : bgFromRgb(r, g, b, level);
+				const close = prop === "rgb" ? "39" : "49";
+				return createChainWithRef({
+					opens: [...state.opens, code],
+					closes: [...state.closes, close]
+				}, ref);
+			};
+			if (prop === "ansi256") return (code) => {
+				if (level === "mono") return createChainWithRef(state, ref);
+				return createChainWithRef({
+					opens: [...state.opens, `38;5;${code}`],
+					closes: [...state.closes, "39"]
+				}, ref);
+			};
+			if (prop === "bgAnsi256") return (code) => {
+				if (level === "mono") return createChainWithRef(state, ref);
+				return createChainWithRef({
+					opens: [...state.opens, `48;5;${code}`],
+					closes: [...state.closes, "49"]
+				}, ref);
+			};
+			if (prop === "curlyUnderline" || prop === "dottedUnderline" || prop === "dashedUnderline" || prop === "doubleUnderline") {
+				const styleName = prop.slice(0, prop.length - 9);
+				return (text) => applyExtendedUnderline(text, styleName, ref);
+			}
+			if (prop === "underlineColor") return (r, g, b, text) => applyUnderlineColor(text, r, g, b, ref);
+			if (prop === "styledUnderline") return (styleName, rgb, text) => applyStyledUnderline(text, styleName, rgb, ref);
+			if (prop in MODIFIERS) {
+				if (level === "mono") return createChainWithRef(state, ref);
+				const [open, close] = MODIFIERS[prop];
+				return createChainWithRef({
+					opens: [...state.opens, String(open)],
+					closes: [...state.closes, String(close)]
+				}, ref);
+			}
+			if (prop in FG_COLORS) {
+				if (level === "mono") return createChainWithRef(state, ref);
+				return createChainWithRef({
+					opens: [...state.opens, String(FG_COLORS[prop])],
+					closes: [...state.closes, "39"]
+				}, ref);
+			}
+			if (prop in BG_COLORS) {
+				if (level === "mono") return createChainWithRef(state, ref);
+				return createChainWithRef({
+					opens: [...state.opens, String(BG_COLORS[prop])],
+					closes: [...state.closes, "49"]
+				}, ref);
+			}
+			if (THEME_TOKENS.has(prop)) {
+				if (level === "mono") return createChainWithRef(state, ref);
+				const hex = resolveToken(prop, ref.theme);
+				if (hex) {
+					const rgb = hexToRgb$1(hex);
+					if (rgb) {
+						const code = fgFromRgb(rgb[0], rgb[1], rgb[2], level);
+						if (prop === "link") return createChainWithRef({
+							opens: [
+								...state.opens,
+								code,
+								"4"
+							],
+							closes: [
+								...state.closes,
+								"39",
+								"24"
+							]
+						}, ref);
+						return createChainWithRef({
+							opens: [...state.opens, code],
+							closes: [...state.closes, "39"]
+						}, ref);
+					}
+				}
+				const fallback = THEME_TOKEN_DEFAULTS[prop];
+				if (fallback !== void 0) {
+					if (prop === "muted") return createChainWithRef({
+						opens: [...state.opens, String(fallback)],
+						closes: [...state.closes, "22"]
+					}, ref);
+					if (prop === "link") return createChainWithRef({
+						opens: [
+							...state.opens,
+							String(fallback),
+							"4"
+						],
+						closes: [
+							...state.closes,
+							"39",
+							"24"
+						]
+					}, ref);
+					return createChainWithRef({
+						opens: [...state.opens, String(fallback)],
+						closes: [...state.closes, "39"]
+					}, ref);
+				}
+			}
+		},
+		set(_target, prop, value) {
+			if (prop === "level") {
+				ref.level = fromChalkLevel(value);
+				return true;
+			}
+			return false;
+		},
+		has(_target, prop) {
+			if (prop === "level") return true;
+			if (typeof prop === "symbol") return false;
+			return prop in MODIFIERS || prop in FG_COLORS || prop in BG_COLORS || THEME_TOKENS.has(prop) || KNOWN_METHODS.has(prop);
+		}
+	};
+	const target = function() {};
+	const proxy = new Proxy(target, handler);
+	proxyRef.proxy = proxy;
+	return proxy;
+}
+const UNDERLINE_OPEN = "\x1B[4m";
+const UNDERLINE_CLOSE = "\x1B[24m";
+/** `style.curlyUnderline(text)` / `.dotted` / `.dashed` / `.double`. */
+function applyExtendedUnderline(text, name, ref) {
+	if (ref.level === "mono") return text;
+	if (!ref.caps.underlineStyles) return `${UNDERLINE_OPEN}${text}${UNDERLINE_CLOSE}`;
+	return `${UNDERLINE_CODES[name]}${text}${UNDERLINE_CODES.reset}`;
+}
+/** `style.underlineColor(r, g, b, text)`. */
+function applyUnderlineColor(text, r, g, b, ref) {
+	if (ref.level === "mono") return text;
+	if (!ref.caps.underlineColor) return `${UNDERLINE_OPEN}${text}${UNDERLINE_CLOSE}`;
+	return `${UNDERLINE_STANDARD}${buildUnderlineColorCode(r, g, b)}${text}${UNDERLINE_COLOR_RESET}${UNDERLINE_RESET_STANDARD}`;
+}
+/** `style.styledUnderline(name, [r,g,b], text)`. */
+function applyStyledUnderline(text, name, rgb, ref) {
+	if (ref.level === "mono") return text;
+	if (!ref.caps.underlineStyles) return `${UNDERLINE_OPEN}${text}${UNDERLINE_CLOSE}`;
+	const [r, g, b] = rgb;
+	const styleCode = UNDERLINE_CODES[name];
+	if (!ref.caps.underlineColor) return `${styleCode}${text}${UNDERLINE_CODES.reset}`;
+	return `${styleCode}${buildUnderlineColorCode(r, g, b)}${text}${UNDERLINE_CODES.reset}${UNDERLINE_COLOR_RESET}`;
+}
+//#endregion
+//#region packages/ansi/src/style/mixed-proxy.ts
+/** Methods on Style that take arguments and return a new Style chain. */
+const STYLE_METHODS = new Set([
+	"hex",
+	"bgHex",
+	"rgb",
+	"bgRgb",
+	"ansi256",
+	"bgAnsi256"
+]);
+/**
+* Create a proxy that wraps a style instance with additional properties.
+*
+* The proxy makes the result:
+* - Callable: result('text') applies current styles
+* - Chainable: result.bold.red('text') chains styles
+* - Extended: result.anyExtraProp accesses extra properties
+*
+* Extra properties take priority over style properties on name collision.
+*/
+function createMixedStyle(style, extra) {
+	return createChainProxy(style, extra);
+}
+/**
+* Internal recursive proxy builder for style chain + extra properties.
+*/
+function createChainProxy(currentStyle, extra) {
+	const handler = {
+		apply(_target, _thisArg, args) {
+			return currentStyle(...args);
+		},
+		get(_target, prop) {
+			if (prop in extra) {
+				const value = extra[prop];
+				if (typeof value === "function") return value;
+				return value;
+			}
+			if (typeof prop === "symbol") return extra[prop];
+			if (STYLE_METHODS.has(prop)) {
+				const method = currentStyle[prop];
+				if (typeof method === "function") return (...args) => {
+					return createChainProxy(method.apply(currentStyle, args), extra);
+				};
+			}
+			const styleProp = currentStyle[prop];
+			if (styleProp !== void 0) {
+				if (typeof styleProp === "function" || typeof styleProp === "object") return createChainProxy(styleProp, extra);
+				return styleProp;
+			}
+		},
+		set(_target, prop, value) {
+			extra[prop] = value;
+			return true;
+		},
+		defineProperty(_target, prop, descriptor) {
+			Object.defineProperty(extra, prop, descriptor);
+			return true;
+		},
+		has(_target, prop) {
+			if (prop in extra) return true;
+			if (typeof prop === "string" && prop in currentStyle) return true;
+			return false;
+		}
+	};
+	const proxyTarget = function() {};
+	return new Proxy(proxyTarget, handler);
+}
+//#endregion
+//#region packages/ansi/src/theme/monochrome.ts
+/**
+* Default monochrome attrs — Polaris-aligned mapping from the design spec.
+*
+* The philosophy: every *semantic* token that would normally carry color gets an
+* attrs set that preserves its hierarchy rank and state semantics. Example:
+* error (danger) is bold+inverse so it *grabs* attention even without red;
+* warning is bold to stand out but not as aggressively; info is italic to
+* indicate auxiliary information.
+*
+* Structural surfaces (bg/mutedbg/surfacebg/popoverbg) have no attrs — they
+* represent background planes that monochrome terminals can't vary anyway.
+*/
+const DEFAULT_MONO_ATTRS = {
+	bg: [],
+	mutedbg: [],
+	surfacebg: [],
+	popoverbg: [],
+	border: [],
+	cursorbg: [],
+	fg: [],
+	muted: ["dim"],
+	disabledfg: ["dim"],
+	surface: [],
+	popover: [],
+	primary: ["bold"],
+	secondary: ["bold"],
+	accent: ["italic", "bold"],
+	error: ["bold", "inverse"],
+	warning: ["bold"],
+	success: ["bold"],
+	info: ["italic"],
+	primaryfg: [],
+	secondaryfg: [],
+	accentfg: [],
+	errorfg: ["inverse"],
+	warningfg: [],
+	successfg: [],
+	infofg: [],
+	focusborder: ["bold"],
+	inputborder: [],
+	cursor: [],
+	"fg-muted": ["dim"],
+	"bg-muted": [],
+	"fg-accent": ["italic", "bold"],
+	"bg-accent": [],
+	"fg-on-accent": [],
+	"border-accent": [],
+	"fg-accent-hover": ["italic", "bold"],
+	"bg-accent-hover": [],
+	"fg-accent-active": ["italic", "bold"],
+	"bg-accent-active": [],
+	"fg-info": ["italic"],
+	"bg-info": [],
+	"fg-on-info": [],
+	"bg-info-hover": [],
+	"bg-info-active": [],
+	"fg-success": ["bold"],
+	"bg-success": [],
+	"fg-on-success": [],
+	"bg-success-hover": [],
+	"bg-success-active": [],
+	"fg-warning": ["bold"],
+	"bg-warning": [],
+	"fg-on-warning": [],
+	"bg-warning-hover": [],
+	"bg-warning-active": [],
+	"fg-error": ["bold", "inverse"],
+	"bg-error": [],
+	"fg-on-error": ["inverse"],
+	"bg-error-hover": [],
+	"bg-error-active": [],
+	"bg-surface-default": [],
+	"bg-surface-subtle": [],
+	"bg-surface-raised": [],
+	"bg-surface-overlay": [],
+	"bg-surface-hover": [],
+	"border-default": [],
+	"border-focus": ["bold"],
+	"border-muted": [],
+	"fg-cursor": [],
+	"bg-cursor": [],
+	"bg-selected": ["inverse"],
+	"fg-on-selected": [],
+	"bg-selected-hover": ["inverse"],
+	"bg-inverse": ["inverse"],
+	"fg-on-inverse": [],
+	"fg-link": ["underline"]
+};
+/**
+* Produce per-token monochrome attrs from a base Theme.
+*
+* Currently returns `DEFAULT_MONO_ATTRS` — a canonical mapping. Passed the
+* theme to allow per-theme overrides in the future (e.g., a palette that
+* prefers `underline` for accents over `italic`). The argument is reserved.
+*/
+function deriveMonochromeTheme(theme) {
+	return DEFAULT_MONO_ATTRS;
+}
+/**
+* Resolve mono-attrs from a color *string* — the high-level entry point
+* consumed by the render pipeline.
+*
+* Accepts strings like `"$primary"`, `"$fg-muted"`, `"$border-focus"`. Strips
+* the `$` prefix and looks the name up directly against `DEFAULT_MONO_ATTRS`,
+* which carries both legacy keys (`muted`, `surfacebg`, `focusborder`, …) AND
+* Sterling flat tokens (`fg-muted`, `bg-surface-default`, `border-focus`, …)
+* as first-class entries. Returns `undefined` for non-token strings (hex,
+* rgb(), named ANSI colors) — callers should treat this as "no attrs".
+*
+* A secondary no-hyphen fallback (`$surface-bg` → `surfacebg`) keeps the
+* legacy hyphenated-compound form working for callers that still emit that
+* shape.
+*
+* @param color    The color string (e.g. `"$primary"`, `"#ff0000"`, `"red"`)
+* @param theme    Active theme (reserved for per-theme overrides)
+* @returns        Array of mono-attrs for the token, or `undefined` if not a
+*                 recognized token.
+*/
+function monoAttrsForColorString(color, theme) {
+	if (!color.startsWith("$")) return void 0;
+	const name = color.slice(1);
+	const attrs = deriveMonochromeTheme(theme);
+	const direct = attrs[name];
+	if (direct !== void 0) return direct;
+	const noHyphen = name.replace(/-/g, "");
+	if (noHyphen !== name) {
+		const stripped = attrs[noHyphen];
+		if (stripped !== void 0) return stripped;
+	}
+}
+//#endregion
+//#region packages/ansi/src/theme/fingerprint.ts
+/** Fields that are always probed and used for fingerprinting. */
+const FINGERPRINT_FIELDS = [
+	"foreground",
+	"background",
+	"black",
+	"red",
+	"green",
+	"yellow",
+	"blue",
+	"magenta",
+	"cyan",
+	"white",
+	"brightBlack",
+	"brightRed",
+	"brightGreen",
+	"brightYellow",
+	"brightBlue",
+	"brightMagenta",
+	"brightCyan",
+	"brightWhite"
+];
+/**
+* Map ΔE thresholds into a 0–1 confidence.
+*
+* sumΔE=0 + maxΔE=0 → 1.0 (perfect match)
+* sumΔE=30 (threshold)  → ~0.5
+* sumΔE≥60 → ~0.0
+*/
+function computeConfidence(sumDE, maxDE, sumThreshold) {
+	const sumScore = Math.max(0, 1 - sumDE / (sumThreshold * 2));
+	const maxScore = Math.max(0, 1 - maxDE / 16);
+	return Math.max(0, Math.min(1, .7 * sumScore + .3 * maxScore));
+}
+/**
+* Match probed slots against a catalog, returning the best candidate if it
+* satisfies both sum and per-slot thresholds. Returns `null` if nothing matches.
+*
+* `probed` is a partial ColorScheme — whatever slots OSC queries returned. Missing
+* slots are skipped (still counted as "not compared"). Non-hex values are
+* ignored (ΔE can't be computed).
+*/
+function fingerprintMatch(probed, catalog, opts = {}) {
+	const sumThreshold = opts.sumThreshold ?? 30;
+	const perSlotThreshold = opts.perSlotThreshold ?? 8;
+	let best = null;
+	for (const scheme of catalog) {
+		let sumDE = 0;
+		let maxDE = 0;
+		let slotsCompared = 0;
+		for (const field of FINGERPRINT_FIELDS) {
+			const probedVal = probed[field];
+			const catalogVal = scheme[field];
+			if (typeof probedVal !== "string" || typeof catalogVal !== "string") continue;
+			const de = colorDistance(probedVal, catalogVal);
+			if (de === null) continue;
+			const scaled = de * 100;
+			sumDE += scaled;
+			if (scaled > maxDE) maxDE = scaled;
+			slotsCompared++;
+		}
+		if (slotsCompared === 0) continue;
+		if (maxDE > perSlotThreshold) continue;
+		if (sumDE > sumThreshold) continue;
+		if (best === null || sumDE < best.sumDeltaE) best = {
+			scheme,
+			sumDeltaE: sumDE,
+			maxDeltaE: maxDE,
+			slotsCompared,
+			confidence: computeConfidence(sumDE, maxDE, sumThreshold)
+		};
+	}
+	return best;
+}
+//#endregion
+//#region packages/ansi/src/theme/types.ts
+const COLOR_SCHEME_FIELDS = [
+	"black",
+	"red",
+	"green",
+	"yellow",
+	"blue",
+	"magenta",
+	"cyan",
+	"white",
+	"brightBlack",
+	"brightRed",
+	"brightGreen",
+	"brightYellow",
+	"brightBlue",
+	"brightMagenta",
+	"brightCyan",
+	"brightWhite",
+	"foreground",
+	"background",
+	"cursorColor",
+	"cursorText",
+	"selectionBackground",
+	"selectionForeground"
+];
+//#endregion
+//#region packages/ansi/src/theme/orchestrator.ts
+function envOverride() {
+	const v = process.env.SILVERY_COLOR;
+	if (!v) return null;
+	if (v === "truecolor" || v === "256" || v === "ansi16" || v === "scheme" || v === "mono" || v === "auto") return v;
+	return null;
+}
+/**
+* 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)}%)`)
+* ```
+*/
+async function detectScheme(opts = {}) {
+	const enforce = opts.enforce ?? "lenient";
+	const wcag = opts.wcag ?? false;
+	if (opts.override) {
+		const theme = loadTheme(opts.override, {
+			enforce,
+			wcag
+		});
+		return {
+			scheme: opts.override,
+			theme,
+			source: "override",
+			confidence: 1,
+			slotSources: allSlotsFrom("fallback"),
+			matchedName: opts.override.name
+		};
+	}
+	const envMode = envOverride();
+	if (envMode === "mono" || envMode === "ansi16") {
+		const fallback = opts.darkFallback !== false ? defaultDarkScheme : defaultLightScheme;
+		return {
+			scheme: fallback,
+			theme: loadTheme(fallback, {
+				enforce,
+				wcag
+			}),
+			source: "override",
+			confidence: 1,
+			slotSources: allSlotsFrom("fallback"),
+			matchedName: fallback.name
+		};
+	}
+	const detected = await probeColors({
+		timeoutMs: opts.timeoutMs,
+		input: opts.input
+	});
+	if (!detected) {
+		const fallback = opts.darkFallback !== false ? defaultDarkScheme : defaultLightScheme;
+		return {
+			scheme: fallback,
+			theme: loadTheme(fallback, {
+				enforce,
+				wcag
+			}),
+			source: "fallback",
+			confidence: 0,
+			slotSources: allSlotsFrom("fallback"),
+			matchedName: fallback.name
+		};
+	}
+	const catalog = opts.catalog ?? [];
+	if (catalog.length > 0) {
+		const match = fingerprintMatch(detected.palette, catalog);
+		if (match) {
+			const theme = loadTheme(match.scheme, {
+				enforce,
+				wcag
+			});
+			return {
+				scheme: match.scheme,
+				theme,
+				source: "fingerprint",
+				confidence: match.confidence,
+				slotSources: allSlotsFrom("catalog"),
+				matchedName: match.scheme.name
+			};
+		}
+	}
+	const fallback = detected.dark ? defaultDarkScheme : defaultLightScheme;
+	const probedSlots = stripNulls(detected.palette);
+	const derivedSlots = deriveMissingSlotsFromProbe(probedSlots);
+	const merged = {
+		...fallback,
+		...derivedSlots,
+		...probedSlots
+	};
+	const theme = loadTheme(merged, {
+		enforce,
+		wcag
+	});
+	const slotSources = {};
+	for (const field of COLOR_SCHEME_FIELDS) slotSources[field] = typeof detected.palette[field] === "string" ? "probed" : field in derivedSlots ? "derived" : "fallback";
+	const probedCount = Object.values(slotSources).filter((s) => s === "probed").length;
+	return {
+		scheme: merged,
+		theme,
+		source: "probed",
+		confidence: Math.min(1, probedCount / 18),
+		slotSources,
+		matchedName: void 0
+	};
+}
+function stripNulls(partial) {
+	const result = {};
+	for (const [k, v] of Object.entries(partial)) if (v != null) result[k] = v;
+	return result;
+}
+function deriveMissingSlotsFromProbe(probed) {
+	const out = {};
+	if (typeof probed.background === "string" && typeof probed.foreground === "string" && typeof probed.selectionBackground !== "string") out.selectionBackground = blend(probed.background, probed.foreground, .16);
+	if (typeof probed.foreground === "string" && typeof probed.selectionForeground !== "string") out.selectionForeground = probed.foreground;
+	return out;
+}
+function allSlotsFrom(src) {
+	const out = {};
+	for (const field of COLOR_SCHEME_FIELDS) out[field] = src;
+	return out;
+}
+/**
+* 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>)
+* ```
+*/
+async function detectSchemeTheme(opts = {}) {
+	const { theme } = await detectScheme(opts);
+	return theme;
+}
+//#endregion
+//#region packages/ansi/src/theme/tokens.ts
+/**
+* Runtime constant — the 12 built-in variant names shipped by silvery.
+*
+* Used in dev warnings when an unknown variant is looked up in Text.tsx:
+* ```
+* Warning: Unknown variant "h11". Known variants: h1, h2, h3, …
+* ```
+*
+* Mirrors `VariantName` exactly — update both when variants change.
+*/
+const KNOWN_VARIANTS = [
+	"h1",
+	"h2",
+	"h3",
+	"body",
+	"body-muted",
+	"fine-print",
+	"strong",
+	"em",
+	"link",
+	"key",
+	"code",
+	"kbd"
+];
+//#endregion
+//#region packages/ansi/src/color-scheme.ts
+const CSI = `[`;
+`${CSI}`;
+`${CSI}`;
+//#endregion
+//#region packages/ansi/src/theme/generate.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").
+*/
+function generateTheme(primary, dark) {
+	const fg = dark ? "whiteBright" : "black";
+	const accent = primary;
+	const selectionbg = primary;
+	const surfacebg = dark ? "black" : "white";
+	const derived = deriveFields({
+		primary,
+		accent,
+		fg,
+		selectionbg,
+		surfacebg,
+		ring: {
+			red: dark ? "redBright" : "red",
+			orange: dark ? "redBright" : "red",
+			yellow: "yellow",
+			green: dark ? "greenBright" : "green",
+			teal: "cyan",
+			blue: dark ? "blueBright" : "blue",
+			purple: "magenta",
+			pink: dark ? "magentaBright" : "magenta"
+		}
+	});
+	return {
+		name: `${dark ? "dark" : "light"}-${primary}`,
+		bg: "",
+		fg,
+		muted: dark ? "white" : "blackBright",
+		mutedbg: dark ? "black" : "white",
+		surface: dark ? "whiteBright" : "black",
+		surfacebg,
+		popover: dark ? "whiteBright" : "black",
+		popoverbg: dark ? "blackBright" : "white",
+		inverse: dark ? "black" : "whiteBright",
+		inversebg: dark ? "whiteBright" : "black",
+		cursor: "black",
+		cursorbg: primary,
+		selection: "black",
+		selectionbg: primary,
+		primary,
+		primaryfg: "black",
+		secondary: primary,
+		secondaryfg: "black",
+		accent: primary,
+		accentfg: "black",
+		error: dark ? "redBright" : "red",
+		errorfg: "black",
+		warning: primary,
+		warningfg: "black",
+		success: dark ? "greenBright" : "green",
+		successfg: "black",
+		info: dark ? "cyanBright" : "cyan",
+		infofg: "black",
+		border: "gray",
+		inputborder: "gray",
+		focusborder: dark ? "blueBright" : "blue",
+		link: "blueBright",
+		disabledfg: "gray",
+		palette: [
+			"black",
+			"red",
+			"green",
+			"yellow",
+			"blue",
+			"magenta",
+			"cyan",
+			"white",
+			"blackBright",
+			"redBright",
+			"greenBright",
+			"yellowBright",
+			"blueBright",
+			"magentaBright",
+			"cyanBright",
+			"whiteBright"
+		],
+		...derived
+	};
+}
+//#endregion
+//#region packages/ansi/src/sterling/flat-tokens.ts
+const STERLING_FLAT_TOKENS = [
+	"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"
+];
+//#endregion
+//#region packages/ansi/src/sterling/defaults.ts
+/**
+* A hand-tuned neutral dark scheme — not a copy of any catalog palette, but
+* close to Nord/Dracula territory. Used only when the caller asks for a
+* "raw default" (no scheme at all).
+*/
+const darkBaseline = {
+	name: "sterling-dark",
+	dark: true,
+	primary: "#7FB4CA",
+	black: "#1E1E2E",
+	red: "#E06C75",
+	green: "#98C379",
+	yellow: "#E5C07B",
+	blue: "#61AFEF",
+	magenta: "#C678DD",
+	cyan: "#56B6C2",
+	white: "#ABB2BF",
+	brightBlack: "#5C6370",
+	brightRed: "#E06C75",
+	brightGreen: "#98C379",
+	brightYellow: "#E5C07B",
+	brightBlue: "#61AFEF",
+	brightMagenta: "#C678DD",
+	brightCyan: "#56B6C2",
+	brightWhite: "#FFFFFF",
+	foreground: "#E4E4E7",
+	background: "#16181D",
+	cursorColor: "#E4E4E7",
+	cursorText: "#16181D",
+	selectionBackground: "#3E4452",
+	selectionForeground: "#E4E4E7"
+};
+const lightBaseline = {
+	name: "sterling-light",
+	dark: false,
+	primary: "#1F6FEB",
+	black: "#24292F",
+	red: "#CF222E",
+	green: "#1A7F37",
+	yellow: "#9A6700",
+	blue: "#0969DA",
+	magenta: "#8250DF",
+	cyan: "#1B7C83",
+	white: "#6E7781",
+	brightBlack: "#57606A",
+	brightRed: "#A40E26",
+	brightGreen: "#2DA44E",
+	brightYellow: "#BF8700",
+	brightBlue: "#218BFF",
+	brightMagenta: "#A475F9",
+	brightCyan: "#3192AA",
+	brightWhite: "#8C959F",
+	foreground: "#1F2328",
+	background: "#FFFFFF",
+	cursorColor: "#1F2328",
+	cursorText: "#FFFFFF",
+	selectionBackground: "#DDF4FF",
+	selectionForeground: "#1F2328"
+};
+function defaultScheme(mode = "dark") {
+	return mode === "dark" ? darkBaseline : lightBaseline;
+}
+//#endregion
+//#region packages/ansi/src/sterling/define.ts
+/**
+* `defineDesignSystem` — wrap a DesignSystem so its derivations auto-apply
+* `bakeFlat` per the `flatten` flag.
+*
+* This makes flat-projection-on-same-object a FRAMEWORK feature, not a
+* Sterling-specific one. Any `DesignSystem` whose Theme is a nested POJO of
+* hex-string leaves gets `theme.accent.bg` AND `theme["bg-accent"]` access
+* without reimplementing the walk.
+*
+* ```ts
+* export const sterling = defineDesignSystem({
+*   name: "sterling",
+*   shape: STERLING_SHAPE,
+*   flatten: true,                      // ← opt in to default channel-role-state rule
+*   defaults(mode) { return derive(...) },
+*   theme(partial) { return derive(...) },
+*   deriveFromScheme(scheme) { return derive(...) },
+*   // … etc. Return VALUES without flat keys; defineDesignSystem bakes them.
+* })
+* ```
+*
+* Contract:
+* - `flatten: true` → apply `bakeFlat(theme)` with `defaultFlattenRule`
+* - `flatten: <fn>` → apply `bakeFlat(theme, <fn>)`
+* - `flatten: false` / omitted → pass-through (identity)
+*
+* All derivation methods (`defaults`, `theme`, `deriveFromScheme`,
+* `deriveFromColor`, `deriveFromPair`, `deriveFromSchemeWithBrand`) are
+* wrapped; their return values go through the flatten filter before
+* reaching the caller. `deriveFromPair` returns `{ light, dark }` —
+* both are flattened.
+*/
+function resolveFlatten(flatten) {
+	if (flatten === false || flatten === void 0) return (t) => t;
+	if (typeof flatten === "function") {
+		const rule = flatten;
+		return (t) => bakeFlat(t, rule);
+	}
+	return (t) => bakeFlat(t);
+}
+/**
+* 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.
+*/
+function defineDesignSystem(def) {
+	const flatten = resolveFlatten(def.flatten);
+	return {
+		name: def.name,
+		shape: def.shape,
+		flatten: def.flatten,
+		defaults: (mode) => flatten(def.defaults(mode)),
+		theme: (partial, opts) => flatten(def.theme(partial, opts)),
+		deriveFromScheme: (scheme, opts) => flatten(def.deriveFromScheme(scheme, opts)),
+		deriveFromColor: (color, opts) => flatten(def.deriveFromColor(color, opts)),
+		deriveFromPair: (light, dark, opts) => {
+			const pair = def.deriveFromPair(light, dark, opts);
+			return {
+				light: flatten(pair.light),
+				dark: flatten(pair.dark)
+			};
+		},
+		deriveFromSchemeWithBrand: (scheme, brand, opts) => flatten(def.deriveFromSchemeWithBrand(scheme, brand, opts))
+	};
+}
+//#endregion
+//#region packages/ansi/src/sterling/sterling.ts
+/**
+* Sterling — silvery's canonical DesignSystem.
+*
+* This is the default system shipped from `@silvery/theme`. It implements
+* the `DesignSystem` contract from `types.ts` and serves as the reference
+* for alternative systems (`@silvery/design-material`, `-primer`, etc.).
+*
+* The flat-projection (`theme["bg-accent"]` as a sibling of `theme.accent.bg`
+* on the same object) is NOT Sterling-specific — it's a framework feature.
+* Sterling opts in via `flatten: true` in {@link defineDesignSystem}, which
+* auto-applies `bakeFlat` (from `@silvery/ansi`) to every derivation's
+* output. The default rule is channel-role-state (`fg-accent`, `bg-accent-hover`,
+* `fg-on-error`, `bg-surface-subtle`, `border-focus`, …) — exactly what
+* Sterling's pre-generalization `populateFlat` produced.
+*
+* All derivation functions return a frozen Theme with both nested roles
+* AND flat hyphen keys populated — the user-facing `$fg-accent` syntax
+* resolves against the flat keys, while programmatic access uses nested.
+*/
+const STERLING_SHAPE = {
+	flatTokens: STERLING_FLAT_TOKENS,
+	roles: [
+		"accent",
+		"info",
+		"success",
+		"warning",
+		"error",
+		"muted",
+		"surface",
+		"border",
+		"cursor",
+		"selected",
+		"inverse",
+		"link",
+		"disabled"
+	],
+	states: ["hover", "active"]
+};
+/**
+* Internal: build a nested Theme (no flat keys). `defineDesignSystem` applies
+* `bakeFlat` afterwards — the inner derivation stays flat-agnostic.
+*
+* Also pre-populates the standalone flat tokens that don't come from a role
+* walk: `bg-backdrop` (modal scrim), and `fg-default`/`bg-default` (explicit
+* aliases for canvas fg/bg). bakeFlat preserves pre-existing root-level
+* hyphen keys, so writing these here is the simplest seam.
+*/
+function buildRawTheme(scheme, opts = {}) {
+	const base = deriveTheme$1(scheme, opts);
+	const out = base;
+	if (typeof out["bg-backdrop"] !== "string") out["bg-backdrop"] = blend(scheme.background, "#000000", .4);
+	if (typeof out["fg-default"] !== "string") out["fg-default"] = scheme.foreground;
+	if (typeof out["bg-default"] !== "string") out["bg-default"] = scheme.background;
+	return base;
+}
+/**
+* Apply a brand overlay to a ColorScheme — overrides `primary` and relevant
+* ANSI hue slots with the brand color. Keeps the rest of the scheme intact.
+* Per Appendix F: brand is a theme INPUT, not a public token sibling of accent.
+*/
+function applyBrand(scheme, brand) {
+	return {
+		...scheme,
+		primary: brand
+	};
+}
+/**
+* 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.
+*/
+const sterling = defineDesignSystem({
+	name: "sterling",
+	shape: STERLING_SHAPE,
+	flatten: true,
+	defaults(mode = "dark") {
+		return buildRawTheme(defaultScheme(mode), { contrast: "auto-lift" });
+	},
+	theme(partial, opts = {}) {
+		const base = buildRawTheme(defaultScheme(opts.mode ?? "dark"), {
+			...opts,
+			contrast: opts.contrast ?? "auto-lift"
+		});
+		if (!partial) return base;
+		return mergePartial(base, partial);
+	},
+	deriveFromScheme(scheme, opts = {}) {
+		return buildRawTheme(scheme, opts);
+	},
+	deriveFromColor(color, opts = {}) {
+		return buildRawTheme({
+			...defaultScheme(opts.mode ?? "dark"),
+			name: `seed:${color}`,
+			primary: color,
+			blue: color,
+			brightBlue: blend(color, "#ffffff", .15)
+		}, opts);
+	},
+	deriveFromPair(light, dark, opts = {}) {
+		return {
+			light: buildRawTheme(light, {
+				...opts,
+				mode: "light"
+			}),
+			dark: buildRawTheme(dark, {
+				...opts,
+				mode: "dark"
+			})
+		};
+	},
+	deriveFromSchemeWithBrand(scheme, brand, opts = {}) {
+		return buildRawTheme(applyBrand(scheme, brand), opts);
+	}
+});
+//#endregion
+//#region packages/ansi/src/sterling/token-manifest.ts
+const AA = "AA 4.5:1";
+const NA = "—";
+[...[
+	"info",
+	"success",
+	"warning",
+	"error"
+].flatMap((role) => [
+	{
+		flat: `fg-${role}`,
+		path: `${role}.fg`,
+		family: role,
+		axis: "fg",
+		purpose: `${capitalize(role)} status text.`,
+		derivation: seedRule(role),
+		contrast: AA,
+		tierNotes: "Seeds from the matching ANSI palette slot."
+	},
+	{
+		flat: `bg-${role}`,
+		path: `${role}.bg`,
+		family: role,
+		axis: "bg",
+		purpose: `${capitalize(role)} fill — alerts, badges.`,
+		derivation: seedRule(role),
+		contrast: NA,
+		tierNotes: "Distinct from siblings in ALL 84 palettes (collision test)."
+	},
+	{
+		flat: `fg-on-${role}`,
+		path: `${role}.fgOn`,
+		family: role,
+		axis: "fg-on",
+		purpose: `Foreground when drawing text ON \`bg-${role}\`.`,
+		derivation: "contrast-pick(scheme.fg / scheme.bg / black / white) for AA on bg.",
+		contrast: AA,
+		tierNotes: "Pre-quantization pick."
+	},
+	{
+		flat: `bg-${role}-hover`,
+		path: `${role}.hover.bg`,
+		family: role,
+		axis: "bg-hover",
+		purpose: `Hover fill for ${role} surfaces.`,
+		derivation: `OKLCH ±0.04L on bg-${role}.`,
+		contrast: NA,
+		tierNotes: "Often collapses with bg in ansi16."
+	},
+	{
+		flat: `bg-${role}-active`,
+		path: `${role}.active.bg`,
+		family: role,
+		axis: "bg-active",
+		purpose: `Pressed/active fill for ${role} surfaces.`,
+		derivation: `OKLCH ±0.08L on bg-${role}.`,
+		contrast: NA,
+		tierNotes: "Collapses to bg in low tiers."
+	}
+])];
+function capitalize(s) {
+	return s.charAt(0).toUpperCase() + s.slice(1);
+}
+function seedRule(role) {
+	switch (role) {
+		case "info": return "scheme.primary (info mirrors accent's seed).";
+		case "success": return "scheme.green.";
+		case "warning": return "scheme.yellow.";
+		case "error": return "scheme.red.";
+	}
+}
+//#endregion
+export { queryMultiplePaletteColors as $, fgColorCode as A, detectColorScheme as B, enableBracketedPaste as C, defaultFlattenRule as D, bakeFlat as E, pickColorLevel as F, resetCursorColor as G, queryCursorColor as H, quantizeHex as I, setCursorColor as J, resetForegroundColor as K, detectTerminalScheme as L, detectColorFromEnv as M, probeTerminalProfile as N, warnOnce as O, ANSI16_SLOT_HEX as P, parsePaletteResponse as Q, detectTheme as R, disableMouse as S, enableMouse as T, queryForegroundColor as U, queryBackgroundColor as V, resetBackgroundColor as W, ProtocolError as X, setForegroundColor as Y, isProtocolError as Z, kittyDeleteAllScrimPlacements as _, generateTheme as a, deriveRoles as at, disableBracketedPaste as b, detectSchemeTheme as c, WCAG_AA as ct, createMixedStyle as d, deriveFields as dt, queryPaletteColor as et, createStyle as f, defaultCaps as ft, cupTo as g, buildScrimPixels as h, STERLING_FLAT_TOKENS as i, deriveTheme as it, createTerminalProfile as j, bgColorCode as k, COLOR_SCHEME_FIELDS as l, autoLift as lt, backdropPlacementId as m, defineDesignSystem as n, ansi16DarkTheme as nt, KNOWN_VARIANTS as o, deriveTheme$1 as ot, resolveThemeColor as p, setBackgroundColor as q, defaultScheme as r, ansi16LightTheme as rt, detectScheme as s, ContrastError as st, sterling as t, setPaletteColor as tt, monoAttrsForColorString as u, checkAA as ut, kittyPlaceAt as v, enableKittyKeyboard as w, disableKittyKeyboard as x, kittyUploadScrimImage as y, probeColors as z };
+
+//# sourceMappingURL=src-Oe6x5PrS.mjs.map