@stridge/noctis-theme-engine 1.0.0-beta.0

package/dist/generate/theme.js

@@ -0,0 +1,356 @@
+import { adjust, clamp, mix, parseColor, toCss } from "../color/oklch.js";
+import { getTextColor, isBright, solveOnBackground, solveTextColor } from "../color/contrast.js";
+import { ACCENT_ACTIVE, ACCENT_HOVER, AI_SELECTION_ALPHA, BG_C_STEPS, BG_L_STEPS, BG_L_STEPS_LIGHT, BORDER_L_STEPS, BORDER_SELECTED_MIX, CONTROL, CONTROL_C_STEP, ELEVATION_C_STEP, ELEVATION_STEP, ELEVATION_STEP_LIGHT, ENGINE_VAR_PREFIX, FIELD_HOVER_L, FOCUS_MIN_CHROMA, GHOST_CONTROL_SOFTEN, HEADER_LIFT, MUTED_MIX, ON_FILL_TINT, OVERLAY_ALPHA, PRIMARY_DIM, SELECTED_HOVER, SELECTED_MIX, SELECTION_ALPHA, SIDEBAR_ITEM_LIFT, SIDEBAR_ITEM_MIX, STATUSES, STATUS_BORDER_EXTRA_MIX, STATUS_HOVER, STATUS_SEEDS, STATUS_TINT_FACTOR, SUNKEN_L_STEP, SUNKEN_L_STEP_LIGHT, TEXT_LC_TARGETS, THEME_VARS, WHITE_RESERVE } from "./tokens.js";
+//#region src/generate/theme.ts
+/**
+* `generateTheme` — the seed → full token set core.
+*
+* A background seed walks contrast-scaled lightness steps to build the surface, border and
+* control ladders; every text and status tier is APCA-solved for guaranteed legibility; and
+* every emitted color is gamut-mapped to sRGB. Cross-surface elevation (menus, sidebar) is a
+* full re-generation at a shifted base — see {@link generateScopeTheme}.
+*
+* Every primitive resolves through `override ?? computed`: an entry in
+* {@link ThemeOverrides} replaces its primitive's computed value, and every dependent derives
+* against the resolved value — an overridden `"bg-1"` is the canvas the text tiers, borders,
+* controls, and status families solve against; an overridden `"accent"` feeds the accent set,
+* focus ring, and selection mixes; an overridden part is embedded by its composites.
+*/
+const BLACK = {
+	l: 0,
+	c: 0,
+	h: 0
+};
+const SCOPE_SEGMENTS = [
+	"el",
+	"su",
+	"mn"
+];
+/** Engine primitive ids — the {@link THEME_VARS} names with the namespace prefix stripped. */
+const PRIMITIVE_IDS = new Set(THEME_VARS.map((name) => name.slice(ENGINE_VAR_PREFIX.length)));
+/** Ids whose values are CSS shorthand composites — override values pass through verbatim, unparsed. */
+const COMPOSITE_IDS = new Set([
+	"shadow-border",
+	"focus-shadow",
+	"input-border"
+]);
+/** Split a possibly scope-qualified override key (`"el-bg-3"`) into its segment and primitive id. */
+function splitScope(key) {
+	for (const segment of SCOPE_SEGMENTS) if (key.startsWith(`${segment}-`)) return {
+		scope: segment,
+		id: key.slice(segment.length + 1)
+	};
+	return {
+		scope: null,
+		id: key
+	};
+}
+/**
+* Whether a string can be embedded verbatim as a single CSS declaration value. A legitimate
+* value never contains `{`, `}`, `<`, or a semicolon outside parentheses — any of those lets a
+* value close its declaration block and smuggle whole rules into the string-built engine
+* stylesheets (the runtime sheet and the SSR `<style>` text).
+*/
+function isSafeCssValue(value) {
+	let depth = 0;
+	for (const char of value) {
+		if (char === "{" || char === "}" || char === "<") return false;
+		if (char === "(") depth += 1;
+		else if (char === ")") depth = Math.max(0, depth - 1);
+		else if (char === ";" && depth === 0) return false;
+	}
+	return true;
+}
+/**
+* Reject unknown ids and invalid values up front, root and scope-qualified entries alike, so a
+* typo fails loudly instead of silently generating a default theme. Color values must parse;
+* composite values pass through verbatim, so they must be emission-safe ({@link isSafeCssValue})
+* — a rule-delimiting character in a composite would escape the declaration in the emitted CSS.
+*/
+function validateOverrides(overrides) {
+	for (const key of Object.keys(overrides)) {
+		const value = overrides[key];
+		if (value === void 0) continue;
+		const { id } = splitScope(key);
+		if (!PRIMITIVE_IDS.has(id)) throw new Error(`theme-engine: unknown theme override id "${key}"`);
+		if (!COMPOSITE_IDS.has(id)) parseColor(value);
+		else if (!isSafeCssValue(value)) throw new Error(`theme-engine: unsafe characters in theme override "${key}"`);
+	}
+}
+function resolveBright(bg, mode) {
+	if (mode === "light") return true;
+	if (mode === "dark") return false;
+	return isBright(bg);
+}
+/**
+* Reserve a sliver of white headroom in bright mode: pull the canvas to at most `1 − WHITE_RESERVE`
+* so elevated surfaces rise toward white without clamping. Dark canvases are returned unchanged.
+*/
+function reserveCanvas(c, bright) {
+	return bright ? {
+		...c,
+		l: Math.min(c.l, 1 - WHITE_RESERVE)
+	} : c;
+}
+/** On-fill text: auto white/black carrying at most a whisper of the surface's hue. */
+function onFillText(surface) {
+	return {
+		l: getTextColor(surface).l,
+		c: Math.min(surface.c, ON_FILL_TINT),
+		h: surface.h
+	};
+}
+/** A translucent white (dark) / black (light) border matching the opaque border's L-distance. */
+function alphaBorder(opaque, bg, bright) {
+	const alpha = bright ? clamp((bg.l - opaque.l) / Math.max(bg.l, .001), 0, 1) : clamp((opaque.l - bg.l) / Math.max(1 - bg.l, .001), 0, 1);
+	return {
+		l: bright ? 0 : 1,
+		c: 0,
+		h: 0,
+		a: alpha
+	};
+}
+/**
+* Turn `{ background, accent, contrast, mode? }` into the flat L1 primitive token map.
+* Pure and deterministic — no DOM, no globals.
+*
+* `options.overrides` entries replace their primitive's computed value (the override string is
+* emitted verbatim) and feed every dependent derivation; scope-qualified entries are validated
+* here but consumed only by the matching scope's run in {@link generateScopeTheme}.
+*/
+function generateTheme(input, options) {
+	const overrides = options?.overrides ?? {};
+	validateOverrides(overrides);
+	const css = (id, computed) => overrides[id] ?? toCss(computed);
+	const composite = (id, computed) => overrides[id] ?? computed;
+	const overrideColor = (id) => {
+		const value = overrides[id];
+		return value === void 0 ? void 0 : parseColor(value);
+	};
+	const background = parseColor(input.background);
+	const accentSeed = parseColor(input.accent);
+	const accent = overrideColor("accent") ?? accentSeed;
+	const seedCanvas = overrideColor("bg-1") ?? background;
+	const bright = resolveBright(seedCanvas, input.mode);
+	const canvas = overrides["bg-1"] === void 0 ? reserveCanvas(seedCanvas, bright) : seedCanvas;
+	const contrast = Number.isFinite(input.contrast) ? clamp(input.contrast, 0, 100) : 0;
+	const direction = bright ? -1 : 1;
+	const gain = contrast / 30 * direction;
+	const magnitude = Math.abs(gain);
+	const controlGain = (bright ? -.8 : 1) * (contrast / 70);
+	const mutedAmount = bright ? MUTED_MIX.light : MUTED_MIX.dark;
+	const bg = (bright ? BG_L_STEPS_LIGHT : BG_L_STEPS).map((lStep, i) => adjust(canvas, {
+		l: lStep * magnitude,
+		c: (BG_C_STEPS[i] ?? 0) * magnitude
+	}));
+	const bgSunken = adjust(canvas, { l: -(bright ? SUNKEN_L_STEP_LIGHT : SUNKEN_L_STEP) * magnitude });
+	const bgSelected = overrideColor("bg-selected") ?? mix(canvas, accent, bright ? SELECTED_MIX.light : SELECTED_MIX.dark);
+	const bgSelectedHover = adjust(bgSelected, {
+		l: SELECTED_HOVER.l * direction,
+		c: SELECTED_HOVER.c * magnitude
+	});
+	const bgFocus = overrideColor("bg-focus") ?? adjust(mix(canvas, accent, .05), { l: .04 * gain });
+	const fg1 = overrideColor("fg-1") ?? getTextColor(canvas);
+	const fg2 = solveTextColor(canvas, TEXT_LC_TARGETS.fg2);
+	const fg3 = overrideColor("fg-3") ?? solveTextColor(canvas, TEXT_LC_TARGETS.fg3);
+	const fg4 = solveTextColor(canvas, TEXT_LC_TARGETS.fg4);
+	const link = solveOnBackground({
+		...accent,
+		c: Math.max(accent.c, FOCUS_MIN_CHROMA)
+	}, canvas, 60);
+	const borderFaint = overrideColor("border-faint") ?? adjust(canvas, {
+		l: BORDER_L_STEPS.faint * gain,
+		c: .0026 * magnitude
+	});
+	const borderDefault = overrideColor("border-default") ?? adjust(canvas, {
+		l: BORDER_L_STEPS.default * gain,
+		c: .0026 * magnitude
+	});
+	const borderStrong = overrideColor("border-strong") ?? adjust(canvas, {
+		l: BORDER_L_STEPS.strong * gain,
+		c: .0026 * magnitude
+	});
+	const borderSelected = mix(canvas, accent, BORDER_SELECTED_MIX);
+	const accentHover = adjust(accent, {
+		l: ACCENT_HOVER.l * direction,
+		c: ACCENT_HOVER.c
+	});
+	const accentActive = adjust(accent, {
+		l: ACCENT_ACTIVE.l * direction,
+		c: ACCENT_ACTIVE.c
+	});
+	const accentMuted = mix(canvas, accent, mutedAmount * .7);
+	const primaryHover = adjust(fg1, { l: -PRIMARY_DIM.hover * direction });
+	const primaryActive = adjust(fg1, { l: -PRIMARY_DIM.active * direction });
+	const controlAt = (lStep, g) => adjust(canvas, {
+		l: lStep * g,
+		c: CONTROL_C_STEP * magnitude
+	});
+	const control = (lStep) => controlAt(lStep, controlGain);
+	const ghostGain = controlGain * (bright ? GHOST_CONTROL_SOFTEN : 1);
+	const ghost = (lStep) => controlAt(lStep, ghostGain);
+	const fieldHover = adjust(canvas, {
+		l: FIELD_HOVER_L * gain,
+		c: CONTROL_C_STEP * magnitude
+	});
+	const focusInBand = bright ? accent.l < .93 : accent.l > .45;
+	const focusRing = overrideColor("focus-ring") ?? (accent.c >= .06 && focusInBand ? accent : solveOnBackground({
+		...accent,
+		c: Math.max(accent.c, .06)
+	}, canvas, 45));
+	const scrollbar = mix(canvas, fg1, .35);
+	const bg1Css = css("bg-1", bg[0]);
+	const bgFocusCss = css("bg-focus", bgFocus);
+	const fg1Css = css("fg-1", fg1);
+	const borderDefaultCss = css("border-default", borderDefault);
+	const borderStrongCss = css("border-strong", borderStrong);
+	const focusRingCss = css("focus-ring", focusRing);
+	const map = {
+		"--noctis-engine-bg-1": bg1Css,
+		"--noctis-engine-bg-2": css("bg-2", bg[1]),
+		"--noctis-engine-bg-3": css("bg-3", bg[2]),
+		"--noctis-engine-bg-4": css("bg-4", bg[3]),
+		"--noctis-engine-bg-5": css("bg-5", bg[4]),
+		"--noctis-engine-bg-6": css("bg-6", bg[5]),
+		"--noctis-engine-bg-sunken": css("bg-sunken", bgSunken),
+		"--noctis-engine-bg-selected": css("bg-selected", bgSelected),
+		"--noctis-engine-bg-selected-hover": css("bg-selected-hover", bgSelectedHover),
+		"--noctis-engine-bg-focus": bgFocusCss,
+		"--noctis-engine-fg-1": fg1Css,
+		"--noctis-engine-fg-2": css("fg-2", fg2),
+		"--noctis-engine-fg-3": css("fg-3", fg3),
+		"--noctis-engine-fg-4": css("fg-4", fg4),
+		"--noctis-engine-link": css("link", link),
+		"--noctis-engine-border-faint": css("border-faint", borderFaint),
+		"--noctis-engine-border-default": borderDefaultCss,
+		"--noctis-engine-border-strong": borderStrongCss,
+		"--noctis-engine-border-faint-alpha": css("border-faint-alpha", alphaBorder(borderFaint, canvas, bright)),
+		"--noctis-engine-border-alpha": css("border-alpha", alphaBorder(borderDefault, canvas, bright)),
+		"--noctis-engine-border-strong-alpha": css("border-strong-alpha", alphaBorder(borderStrong, canvas, bright)),
+		"--noctis-engine-border-selected": css("border-selected", borderSelected),
+		"--noctis-engine-divider": overrides["divider"] ?? borderStrongCss,
+		"--noctis-engine-accent": css("accent", accent),
+		"--noctis-engine-accent-fg": css("accent-fg", onFillText(accent)),
+		"--noctis-engine-accent-hover": css("accent-hover", accentHover),
+		"--noctis-engine-accent-active": css("accent-active", accentActive),
+		"--noctis-engine-accent-muted": css("accent-muted", accentMuted),
+		"--noctis-engine-primary-hover": css("primary-hover", primaryHover),
+		"--noctis-engine-primary-active": css("primary-active", primaryActive),
+		"--noctis-engine-control-2": css("control-2", control(CONTROL.secondary.base)),
+		"--noctis-engine-control-2-hover": css("control-2-hover", control(CONTROL.secondary.hover)),
+		"--noctis-engine-control-2-selected": css("control-2-selected", control(CONTROL.secondary.selected)),
+		"--noctis-engine-control-2-selected-hover": css("control-2-selected-hover", control(CONTROL.secondary.selectedHover)),
+		"--noctis-engine-control-3": css("control-3", ghost(CONTROL.tertiary.base)),
+		"--noctis-engine-control-3-hover": css("control-3-hover", ghost(CONTROL.tertiary.hover)),
+		"--noctis-engine-control-3-selected": css("control-3-selected", ghost(CONTROL.tertiary.selected)),
+		"--noctis-engine-control-3-selected-hover": css("control-3-selected-hover", ghost(CONTROL.tertiary.selectedHover)),
+		"--noctis-engine-control-fg": overrides["control-fg"] ?? fg1Css,
+		"--noctis-engine-focus-ring": focusRingCss,
+		"--noctis-engine-selection-bg": css("selection-bg", {
+			...accent,
+			a: SELECTION_ALPHA
+		}),
+		"--noctis-engine-ai-selection-bg": css("ai-selection-bg", {
+			...fg3,
+			a: AI_SELECTION_ALPHA
+		}),
+		"--noctis-engine-overlay": css("overlay", {
+			...BLACK,
+			a: OVERLAY_ALPHA
+		}),
+		"--noctis-engine-shadow-color": css("shadow-color", BLACK),
+		"--noctis-engine-scrollbar": css("scrollbar", scrollbar),
+		"--noctis-engine-sidebar-item-bg": css("sidebar-item-bg", adjust(canvas, {
+			l: SIDEBAR_ITEM_LIFT * gain,
+			c: .002 * magnitude
+		})),
+		"--noctis-engine-sidebar-item-active": css("sidebar-item-active", mix(canvas, accent, SIDEBAR_ITEM_MIX)),
+		"--noctis-engine-header-bg": css("header-bg", adjust(canvas, {
+			l: HEADER_LIFT * gain,
+			c: .004 * magnitude
+		})),
+		"--noctis-engine-shadow-border": composite("shadow-border", `0 0 0 1px ${borderDefaultCss}`),
+		"--noctis-engine-focus-shadow": composite("focus-shadow", `0 0 0 1px ${focusRingCss}`),
+		"--noctis-engine-input-bg": overrides["input-bg"] ?? bg1Css,
+		"--noctis-engine-input-border": composite("input-border", `1px solid ${borderDefaultCss}`),
+		"--noctis-engine-field-hover": css("field-hover", fieldHover),
+		"--noctis-engine-field-focus": overrides["field-focus"] ?? bgFocusCss
+	};
+	for (const status of STATUSES) {
+		const color = overrideColor(status) ?? solveOnBackground(STATUS_SEEDS[status], canvas, 45);
+		const muted = overrideColor(`${status}-muted`) ?? mix(canvas, color, mutedAmount);
+		const border = mix(canvas, color, mutedAmount + STATUS_BORDER_EXTRA_MIX);
+		const tint = mix(canvas, color, mutedAmount * STATUS_TINT_FACTOR);
+		map[`${ENGINE_VAR_PREFIX}${status}`] = css(status, color);
+		map[`${ENGINE_VAR_PREFIX}${status}-hover`] = css(`${status}-hover`, adjust(color, {
+			l: STATUS_HOVER.l * direction,
+			c: STATUS_HOVER.c
+		}));
+		map[`${ENGINE_VAR_PREFIX}${status}-fg`] = css(`${status}-fg`, onFillText(color));
+		map[`${ENGINE_VAR_PREFIX}${status}-muted`] = css(`${status}-muted`, muted);
+		map[`${ENGINE_VAR_PREFIX}${status}-muted-fg`] = css(`${status}-muted-fg`, solveOnBackground(STATUS_SEEDS[status], muted, 45));
+		map[`${ENGINE_VAR_PREFIX}${status}-border`] = css(`${status}-border`, border);
+		map[`${ENGINE_VAR_PREFIX}${status}-tint`] = css(`${status}-tint`, tint);
+	}
+	return map;
+}
+/**
+* The canvas for an elevation scope: the root canvas shifted toward the scope's elevation.
+* Elevated/menu surfaces rise toward white (menu higher, reaching it in light mode) and sunken
+* recedes — both directions hold in light and dark. The shift base is the reserved root canvas
+* (or an explicit root `"bg-1"`), so a moved base re-derives every scope.
+*/
+function scopeCanvas(input, level, rootOverride) {
+	const seed = rootOverride ?? parseColor(input.background);
+	const bright = resolveBright(seed, input.mode);
+	const base = rootOverride ?? reserveCanvas(seed, bright);
+	const step = bright ? ELEVATION_STEP_LIGHT : ELEVATION_STEP;
+	return adjust(base, {
+		l: level === "sunken" ? -step.sunken : step[level],
+		c: ELEVATION_C_STEP
+	});
+}
+const SCOPE_SEGMENT = {
+	elevated: "el",
+	menu: "mn",
+	sunken: "su"
+};
+/** The override entries qualified for `segment`, with the qualifier stripped off the keys. */
+function scopeOverrides(overrides, segment) {
+	let scoped;
+	for (const key of Object.keys(overrides)) {
+		const value = overrides[key];
+		if (value === void 0 || !key.startsWith(`${segment}-`)) continue;
+		(scoped ??= {})[key.slice(segment.length + 1)] = value;
+	}
+	return scoped;
+}
+/**
+* Generate the full token map for an elevation scope. `root` is the base theme; `elevated`
+* (dialogs/sheets/popovers), `menu` (dropdowns/context menus/command palette — a higher float),
+* and `sunken` (sidebar/wells) re-run the whole generator at a shifted base, so every role —
+* surfaces, text, borders, status — stays internally consistent at that elevation. Apply the
+* result to a scope element with {@link applyTheme}.
+*
+* Overrides scope precisely: a root `"bg-1"` entry moves the base every scope shifts from, a
+* scope-qualified entry (`"el-bg-3"`) acts as that scope's own override map, and unqualified
+* entries otherwise stay at the root — they never leak into a scope's run.
+*/
+function generateScopeTheme(input, level, options) {
+	if (level === "root") return generateTheme(input, options);
+	const overrides = options?.overrides;
+	if (overrides) validateOverrides(overrides);
+	const scoped = overrides ? scopeOverrides(overrides, SCOPE_SEGMENT[level]) : void 0;
+	const bright = resolveBright(parseColor(overrides?.["bg-1"] ?? input.background), input.mode);
+	let bg1 = scoped?.["bg-1"];
+	if (bg1 === void 0) bg1 = toCss(scopeCanvas(input, level, overrides?.["bg-1"] === void 0 ? void 0 : parseColor(overrides["bg-1"])));
+	return generateTheme({
+		...input,
+		mode: bright ? "light" : "dark"
+	}, { overrides: {
+		...scoped,
+		"bg-1": bg1
+	} });
+}
+//#endregion
+export { generateScopeTheme, generateTheme, isSafeCssValue };

package/dist/generate/tokens.d.ts

@@ -0,0 +1,88 @@
+//#region src/generate/tokens.d.ts
+/**
+ * The engine's public input shape and its private L1 primitive token set.
+ *
+ * The set is deep: a neutral surface ramp with sunken + interaction-state surfaces, a
+ * weight × alpha border family, control surfaces, status ramps with seven sub-roles each,
+ * utility/state colors, and the border/focus/input composites. Elevation is a full
+ * re-generation at a shifted base (see `generateScopeTheme`), not extra tiers.
+ *
+ * The numeric constants are calibrated against a reference dark ramp converted into OKLCH.
+ * They are OKLCH offsets from the background seed, scaled by the contrast knob at runtime —
+ * a single parametric curve, not a lookup table.
+ */
+/** Forced light/dark, or modeless (`auto` — background lightness decides). */
+type ThemeMode = "auto" | "light" | "dark";
+/** The three-input seed. `background`/`accent` accept any CSS color; `contrast` ∈ [0,100]. */
+interface ThemeInput {
+  background: string;
+  accent: string;
+  contrast: number;
+  mode?: ThemeMode;
+}
+/**
+ * Generation-time primitive overrides, keyed by engine primitive id — the variable name without
+ * the `--noctis-engine-` prefix (`"bg-3"`, `"accent"`, `"border-default"`). Values are CSS color
+ * strings in any `parseColor`-accepted form; the shadow/input composites (`"shadow-border"`,
+ * `"input-border"`, …) take full composite strings verbatim. Scope-qualified ids (`"el-bg-3"`,
+ * `"su-…"`, `"mn-…"`) apply only inside that elevation scope's generation.
+ *
+ * Unlike a cascade override of the emitted variable, an override participates in derivation:
+ * every dependent primitive derives against the overridden value — text re-solves its APCA
+ * target on an overridden canvas, composites embed an overridden part, and the elevation scopes
+ * shift off an overridden `"bg-1"`. Unknown ids, unparseable color values, and composite values
+ * carrying rule-delimiting characters (`{`, `}`, `<`, a top-level `;`) throw.
+ *
+ * Gotcha: bracket-assigning a literal `"__proto__"` key (`overrides["__proto__"] = …`) is a
+ * silent no-op — JavaScript treats it as a prototype set, so the entry never becomes an own key
+ * and is never read. A JSON-sourced own `"__proto__"` key is rejected as an unknown id.
+ */
+type ThemeOverrides = Readonly<Partial<Record<string, string>>>;
+/**
+ * A surface's elevation scope — the vertical layer it sits on relative to the canvas. Each scope
+ * is a full re-generation of the theme at a base lightness shifted off the seed (see
+ * {@link ELEVATION_STEP}), so every role re-derives consistently for that layer. Ordered low → high:
+ *
+ * - `sunken` — recedes below the canvas. Sidebars, content wells, the scrollbar track, inset code
+ *   blocks. The quietest layer; surfaces here read as carved into the page.
+ * - `root` — the canvas itself: the base page background and everything that sits directly on it.
+ *   The default; most of the app lives here.
+ * - `elevated` — a raised surface that floats just above the canvas. Dialogs, sheets, drawers,
+ *   popovers, cards lifted for emphasis — anything that should read as "on top of" the page.
+ * - `menu` — the highest float, lifted a touch more than `elevated`. Transient list overlays that
+ *   open above everything else: dropdown and context menus, select listboxes, the command palette.
+ */
+type ElevationLevel = "root" | "elevated" | "menu" | "sunken";
+declare const STATUSES: readonly ["success", "warning", "danger", "info"];
+/** Status family name. */
+type StatusName = (typeof STATUSES)[number];
+/**
+ * The reserved namespace prefix every engine primitive carries. The engine owns this stratum:
+ * no graph token of any tier ever serializes into a `--noctis-engine-*` name, so downstream
+ * lint can ban the whole namespace by prefix. Every primitive name and scope-set composition is
+ * derived from this single constant — there are no other literal copies of the prefix.
+ */
+declare const ENGINE_VAR_PREFIX: "--noctis-engine-";
+/**
+ * The cascade layer every engine emission lives in — the SSR emitters and the runtime sheet all
+ * declare into it, so an unlayered author rule on any engine variable outranks the engine by
+ * cascade. A cascade override replaces that one variable's value only; dependents do not
+ * re-derive (use {@link ThemeOverrides} for that).
+ */
+declare const ENGINE_LAYER: "noctis.engine";
+/** The flat set of generated L1 primitive CSS variables (names → CSS color/composite strings). */
+declare const THEME_VARS: readonly ["--noctis-engine-bg-1", "--noctis-engine-bg-2", "--noctis-engine-bg-3", "--noctis-engine-bg-4", "--noctis-engine-bg-5", "--noctis-engine-bg-6", "--noctis-engine-bg-sunken", "--noctis-engine-bg-selected", "--noctis-engine-bg-selected-hover", "--noctis-engine-bg-focus", "--noctis-engine-fg-1", "--noctis-engine-fg-2", "--noctis-engine-fg-3", "--noctis-engine-fg-4", "--noctis-engine-link", "--noctis-engine-border-faint", "--noctis-engine-border-default", "--noctis-engine-border-strong", "--noctis-engine-border-faint-alpha", "--noctis-engine-border-alpha", "--noctis-engine-border-strong-alpha", "--noctis-engine-border-selected", "--noctis-engine-divider", "--noctis-engine-accent", "--noctis-engine-accent-fg", "--noctis-engine-accent-hover", "--noctis-engine-accent-active", "--noctis-engine-accent-muted", "--noctis-engine-primary-hover", "--noctis-engine-primary-active", "--noctis-engine-control-2", "--noctis-engine-control-2-hover", "--noctis-engine-control-2-selected", "--noctis-engine-control-2-selected-hover", "--noctis-engine-control-3", "--noctis-engine-control-3-hover", "--noctis-engine-control-3-selected", "--noctis-engine-control-3-selected-hover", "--noctis-engine-control-fg", "--noctis-engine-field-hover", "--noctis-engine-field-focus", ...("--noctis-engine-success" | "--noctis-engine-success-hover" | "--noctis-engine-success-fg" | "--noctis-engine-success-muted" | "--noctis-engine-success-muted-fg" | "--noctis-engine-success-border" | "--noctis-engine-success-tint" | "--noctis-engine-warning" | "--noctis-engine-warning-hover" | "--noctis-engine-warning-fg" | "--noctis-engine-warning-muted" | "--noctis-engine-warning-muted-fg" | "--noctis-engine-warning-border" | "--noctis-engine-warning-tint" | "--noctis-engine-danger" | "--noctis-engine-danger-hover" | "--noctis-engine-danger-fg" | "--noctis-engine-danger-muted" | "--noctis-engine-danger-muted-fg" | "--noctis-engine-danger-border" | "--noctis-engine-danger-tint" | "--noctis-engine-info" | "--noctis-engine-info-hover" | "--noctis-engine-info-fg" | "--noctis-engine-info-muted" | "--noctis-engine-info-muted-fg" | "--noctis-engine-info-border" | "--noctis-engine-info-tint")[], "--noctis-engine-focus-ring", "--noctis-engine-selection-bg", "--noctis-engine-ai-selection-bg", "--noctis-engine-overlay", "--noctis-engine-shadow-color", "--noctis-engine-scrollbar", "--noctis-engine-sidebar-item-bg", "--noctis-engine-sidebar-item-active", "--noctis-engine-header-bg", "--noctis-engine-shadow-border", "--noctis-engine-focus-shadow", "--noctis-engine-input-bg", "--noctis-engine-input-border"];
+/** A generated primitive variable name. */
+type ThemeVar = (typeof THEME_VARS)[number];
+/**
+ * Compose the elevation-scope variant of an engine primitive: the scope segment (`el`/`su`/`mn`)
+ * is inserted *inside* the engine namespace, so `--noctis-engine-bg-1` at the `el` scope becomes
+ * `--noctis-engine-el-bg-1`. The single source of the scope-set spelling — the static `tokens.css`
+ * scope blocks, the SSR emitter, and the runtime writer all route through it so their names cannot
+ * drift apart.
+ */
+declare function scopedEngineVar(key: ThemeVar, scope: "el" | "su" | "mn"): string;
+/** A complete generated theme: every {@link ThemeVar} mapped to a CSS color/composite string. */
+type ThemeMap = Record<ThemeVar, string>;
+//#endregion
+export { ENGINE_LAYER, ENGINE_VAR_PREFIX, ElevationLevel, StatusName, THEME_VARS, ThemeInput, ThemeMap, ThemeMode, ThemeOverrides, ThemeVar, scopedEngineVar };