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

package/dist/generate/tokens.js

@@ -0,0 +1,283 @@
+//#region src/generate/tokens.ts
+const STATUSES = [
+	"success",
+	"warning",
+	"danger",
+	"info"
+];
+const STATUS_SUFFIXES = [
+	"",
+	"-hover",
+	"-fg",
+	"-muted",
+	"-muted-fg",
+	"-border",
+	"-tint"
+];
+/**
+* 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.
+*/
+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).
+*/
+const ENGINE_LAYER = "noctis.engine";
+/** The flat set of generated L1 primitive CSS variables (names → CSS color/composite strings). */
+const THEME_VARS = [
+	"--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",
+	...STATUSES.flatMap((status) => STATUS_SUFFIXES.map((suffix) => `${ENGINE_VAR_PREFIX}${status}${suffix}`)),
+	"--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"
+];
+/**
+* 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.
+*/
+function scopedEngineVar(key, scope) {
+	return `${ENGINE_VAR_PREFIX}${scope}-${key.slice(16)}`;
+}
+/**
+* Surface elevation ramp: OKLCH-L offsets from the background canvas (1 = base → 6 = highest).
+* Surfaces always rise toward white; the magnitude is mode-specific because a dark canvas lifts
+* into ample headroom while a light canvas climbs the narrow band below white (see {@link WHITE_RESERVE}).
+*/
+const BG_L_STEPS = [
+	0,
+	.029,
+	.045,
+	.064,
+	.087,
+	.111
+];
+const BG_L_STEPS_LIGHT = [
+	0,
+	.005,
+	.009,
+	.014,
+	.02,
+	.028
+];
+/** Surface ramp chroma offsets — chroma rises slightly with elevation. */
+const BG_C_STEPS = [
+	0,
+	.001,
+	.0045,
+	.007,
+	.009,
+	.011
+];
+/** Sunken surface (sidebar/wells): one step below the canvas, receding in both modes. */
+const SUNKEN_L_STEP = .045;
+const SUNKEN_L_STEP_LIGHT = .03;
+/**
+* White headroom reserved below the canvas in bright mode: the base canvas is pulled to at most
+* `1 − WHITE_RESERVE` (OKLCH L) so elevated surfaces lift toward white without clamping. A `bg-1`
+* override is honored verbatim (no reserve); dark canvases need none.
+*/
+const WHITE_RESERVE = .035;
+/** Selected-row surface = base blended this far toward the accent. */
+const SELECTED_MIX = {
+	dark: .18,
+	light: .06
+};
+/** Selected-row hover lift off the selected surface. */
+const SELECTED_HOVER = {
+	l: .022,
+	c: .006
+};
+/** Focused-row surface: a faint accent tint over a slightly raised neutral. */
+const FOCUS_MIX = .05;
+const FOCUS_LIFT = .04;
+/** Border ladder: faint → default → strong, as OKLCH-L offsets from the background seed. */
+const BORDER_L_STEPS = {
+	faint: .043,
+	default: .081,
+	strong: .099
+};
+/** Borders carry a faint, constant tint off the surface hue. */
+const BORDER_C_STEP = .0026;
+/** Selected border = base blended this far toward the accent. */
+const BORDER_SELECTED_MIX = .32;
+/**
+* Bright-mode softening for ghost (tertiary) control washes. Ghost controls read only on
+* interaction; on a light page a full-strength wash lands as a heavy grey blob, so their gain is
+* scaled down in bright mode to a faint tint. Dark mode keeps full strength.
+*/
+const GHOST_CONTROL_SOFTEN = .45;
+/**
+* Neutral control surfaces: OKLCH-L offsets from the background seed, applied through the control
+* gain. Each tier walks rest → hover → selected → selected-hover. The L deltas are calibrated so
+* that — at the reference seed and contrast — the tiers reproduce the reference control ramp in
+* OKLCH (secondary base/hover/selected ≈ 0.230/0.270/0.297 L; tertiary ≈ 0.193/0.227/0.244 L).
+* Tiers stay neutral; chroma is the shared faint {@link CONTROL_C_STEP}.
+*/
+const CONTROL = {
+	secondary: {
+		base: .138,
+		hover: .231,
+		selected: .294,
+		selectedHover: .339
+	},
+	tertiary: {
+		base: .05,
+		hover: .13,
+		selected: .169,
+		selectedHover: .214
+	}
+};
+/** Control surfaces carry a faint tint. */
+const CONTROL_C_STEP = .001;
+/**
+* Primary (neutral white) hover/active: OKLCH-L dims of `--noctis-engine-fg-1` toward the seed (signed by mode
+* direction), sized to read like a deliberate press without compositing a translucent white.
+*/
+const PRIMARY_DIM = {
+	hover: .06,
+	active: .12
+};
+/** Field rest-hover lift off the canvas (OKLCH-L offset from the seed; focus reuses `--noctis-engine-bg-focus`). */
+const FIELD_HOVER_L = .03;
+/** APCA `Lc` targets for the secondary/muted/faint text tiers (fg-1 uses pure auto-contrast). */
+const TEXT_LC_TARGETS = {
+	fg2: 78,
+	fg3: 58,
+	fg4: 38
+};
+/** Accent hover/active lightness + chroma nudges (L signed by mode direction). */
+const ACCENT_HOVER = {
+	l: .04,
+	c: .005
+};
+const ACCENT_ACTIVE = {
+	l: .065,
+	c: .007
+};
+/** On-fill text picks up at most this much of the surface's hue (a whisper of tint). */
+const ON_FILL_TINT = .02;
+/** Amount the base surface is blended toward a hue for `*-muted` tinted surfaces. */
+const MUTED_MIX = {
+	dark: .18,
+	light: .08
+};
+/** Status hover lift and the extra/less mix for status border/tint surfaces. */
+const STATUS_HOVER = {
+	l: .04,
+	c: .005
+};
+const STATUS_BORDER_EXTRA_MIX = .12;
+const STATUS_TINT_FACTOR = .4;
+/** Canonical status hue seeds in OKLCH. */
+const STATUS_SEEDS = {
+	success: {
+		l: .706,
+		c: .176,
+		h: 146.5
+	},
+	warning: {
+		l: .824,
+		c: .179,
+		h: 91.3
+	},
+	danger: {
+		l: .656,
+		c: .201,
+		h: 23.3
+	},
+	info: {
+		l: .72,
+		c: .16,
+		h: 248
+	}
+};
+/** Selection highlight = muted text at this alpha; AI selection at the lower one. */
+const SELECTION_ALPHA = .2;
+const AI_SELECTION_ALPHA = .1;
+/** Modal/scrim overlay = black at this alpha. */
+const OVERLAY_ALPHA = .45;
+/** Sidebar/header neutral-surface lifts and tints. */
+const SIDEBAR_ITEM_MIX = .14;
+const SIDEBAR_ITEM_LIFT = .045;
+const HEADER_LIFT = .03;
+/** Minimum chroma/lightness band for the accent to serve directly as a focus ring. */
+const FOCUS_MIN_CHROMA = .06;
+/**
+* Re-generation base shift per elevation scope (OKLCH-L). `elevated` raises dialogs/sheets/
+* popovers; `menu` floats higher still (dropdowns, context menus, command palette); `sunken`
+* recedes sidebars/wells. Elevated/menu rise toward white and sunken recedes in both modes;
+* magnitudes are mode-specific — light lifts gently up the narrow band below white (menu reaches
+* it), dark lifts further into open headroom.
+*/
+const ELEVATION_STEP = {
+	elevated: .035,
+	menu: .055,
+	sunken: .045
+};
+const ELEVATION_STEP_LIGHT = {
+	elevated: .026,
+	menu: .04,
+	sunken: .03
+};
+/** Elevated/sunken scopes pick up a faint chroma off the surface hue. */
+const ELEVATION_C_STEP = .003;
+//#endregion
+export { ACCENT_ACTIVE, ACCENT_HOVER, AI_SELECTION_ALPHA, BG_C_STEPS, BG_L_STEPS, BG_L_STEPS_LIGHT, BORDER_C_STEP, BORDER_L_STEPS, BORDER_SELECTED_MIX, CONTROL, CONTROL_C_STEP, ELEVATION_C_STEP, ELEVATION_STEP, ELEVATION_STEP_LIGHT, ENGINE_LAYER, ENGINE_VAR_PREFIX, FIELD_HOVER_L, FOCUS_LIFT, FOCUS_MIN_CHROMA, FOCUS_MIX, 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, scopedEngineVar };

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import { ENGINE_LAYER, ENGINE_VAR_PREFIX, ElevationLevel, StatusName, THEME_VARS, ThemeInput, ThemeMap, ThemeMode, ThemeOverrides, ThemeVar, scopedEngineVar } from "./generate/tokens.js";
+import { GenerateThemeOptions, generateScopeTheme, generateTheme } from "./generate/theme.js";
+import { applyEngineVars, applyScopeTheme, applyTheme, clearEngineVars, hashInput, hashString } from "./apply/apply.js";
+import { Oklch, OklchDelta, adjust, adjustTo, clamp, clampOklch, mix, normalizeHue, parseColor, toCss, toSrgbGamut } from "./color/oklch.js";
+import { apcaContrast, getTextColor, isBright, luminance, solveOnBackground, solveTextColor, sufficientContrastForText, wcagContrast } from "./color/contrast.js";
+import { ThemePreset, defaultPreset, presets } from "./presets.js";
+import { THEME_COOKIE_NAME, THEME_STORAGE_KEY, ThemeCookieOptions, declarationsFor, decodeThemeInput, emitStaticCss, encodeThemeInput, persistTheme, readPersistedInput, readPersistedOverrides, readThemeCookie, serializeThemeCookie, themeBlockingScript, writeThemeCookie } from "./ssr/ssr.js";
+
+//#region src/index.d.ts
+/**
+ * `@stridge/noctis-theme-engine` — a framework-agnostic OKLCH theme generator.
+ *
+ * Turns `{ background, accent, contrast }` into a complete, APCA-legible token set and
+ * applies it as CSS variables in place. The React bindings live in `@stridge/noctis-theme-engine/react`.
+ *
+ * The emitted L1 primitives (`--noctis-engine-bg-*`, `--noctis-engine-fg-*`,
+ * `--noctis-engine-border-*`, …) are private to the design system: only the semantic layer should
+ * consume them, never components directly.
+ */
+/** Package identifier — the workspace-resolution marker consumed by the app scaffold. */
+declare const THEME_ENGINE_PACKAGE: "@stridge/noctis-theme-engine";
+//#endregion
+export { ENGINE_LAYER, ENGINE_VAR_PREFIX, type ElevationLevel, type GenerateThemeOptions, type Oklch, type OklchDelta, type StatusName, THEME_COOKIE_NAME, THEME_ENGINE_PACKAGE, THEME_STORAGE_KEY, THEME_VARS, type ThemeCookieOptions, type ThemeInput, type ThemeMap, type ThemeMode, type ThemeOverrides, type ThemePreset, type ThemeVar, adjust, adjustTo, apcaContrast, applyEngineVars, applyScopeTheme, applyTheme, clamp, clampOklch, clearEngineVars, declarationsFor, decodeThemeInput, defaultPreset, emitStaticCss, encodeThemeInput, generateScopeTheme, generateTheme, getTextColor, hashInput, hashString, isBright, luminance, mix, normalizeHue, parseColor, persistTheme, presets, readPersistedInput, readPersistedOverrides, readThemeCookie, scopedEngineVar, serializeThemeCookie, solveOnBackground, solveTextColor, sufficientContrastForText, themeBlockingScript, toCss, toSrgbGamut, wcagContrast, writeThemeCookie };

package/dist/index.js

@@ -0,0 +1,22 @@
+import { adjust, adjustTo, clamp, clampOklch, mix, normalizeHue, parseColor, toCss, toSrgbGamut } from "./color/oklch.js";
+import { apcaContrast, getTextColor, isBright, luminance, solveOnBackground, solveTextColor, sufficientContrastForText, wcagContrast } from "./color/contrast.js";
+import { ENGINE_LAYER, ENGINE_VAR_PREFIX, THEME_VARS, scopedEngineVar } from "./generate/tokens.js";
+import { generateScopeTheme, generateTheme } from "./generate/theme.js";
+import { applyEngineVars, applyScopeTheme, applyTheme, clearEngineVars, hashInput, hashString } from "./apply/apply.js";
+import { defaultPreset, presets } from "./presets.js";
+import { THEME_COOKIE_NAME, THEME_STORAGE_KEY, declarationsFor, decodeThemeInput, emitStaticCss, encodeThemeInput, persistTheme, readPersistedInput, readPersistedOverrides, readThemeCookie, serializeThemeCookie, themeBlockingScript, writeThemeCookie } from "./ssr/ssr.js";
+//#region src/index.ts
+/**
+* `@stridge/noctis-theme-engine` — a framework-agnostic OKLCH theme generator.
+*
+* Turns `{ background, accent, contrast }` into a complete, APCA-legible token set and
+* applies it as CSS variables in place. The React bindings live in `@stridge/noctis-theme-engine/react`.
+*
+* The emitted L1 primitives (`--noctis-engine-bg-*`, `--noctis-engine-fg-*`,
+* `--noctis-engine-border-*`, …) are private to the design system: only the semantic layer should
+* consume them, never components directly.
+*/
+/** Package identifier — the workspace-resolution marker consumed by the app scaffold. */
+const THEME_ENGINE_PACKAGE = "@stridge/noctis-theme-engine";
+//#endregion
+export { ENGINE_LAYER, ENGINE_VAR_PREFIX, THEME_COOKIE_NAME, THEME_ENGINE_PACKAGE, THEME_STORAGE_KEY, THEME_VARS, adjust, adjustTo, apcaContrast, applyEngineVars, applyScopeTheme, applyTheme, clamp, clampOklch, clearEngineVars, declarationsFor, decodeThemeInput, defaultPreset, emitStaticCss, encodeThemeInput, generateScopeTheme, generateTheme, getTextColor, hashInput, hashString, isBright, luminance, mix, normalizeHue, parseColor, persistTheme, presets, readPersistedInput, readPersistedOverrides, readThemeCookie, scopedEngineVar, serializeThemeCookie, solveOnBackground, solveTextColor, sufficientContrastForText, themeBlockingScript, toCss, toSrgbGamut, wcagContrast, writeThemeCookie };

package/dist/presets.d.ts

@@ -0,0 +1,23 @@
+import { ThemeInput } from "./generate/tokens.js";
+
+//#region src/presets.d.ts
+/** A named theme seed. */
+interface ThemePreset extends ThemeInput {
+  name: string;
+}
+/**
+ * The Noctis default — first paint and the build-time static CSS use this. A near-black foundation
+ * carrying a trace of the accent hue: the canvas reads neutral, but as the engine lifts chroma with
+ * elevation, surfaces lean a touch indigo. The seed is a near-black base under an indigo accent
+ * (canvas `lch(4.52 0.3 272)`, accent `lch(47.92 59.30 288)`), converted into OKLCH so the derived
+ * ramp, controls, and elevation land exactly on the engine's calibration targets (see
+ * `calibration.test.ts`). Authored in OKLCH — the engine's working space.
+ */
+declare const defaultPreset: ThemePreset;
+/**
+ * The shipped presets. Dark is the Noctis default; Midnight is a deeper violet, Light the inverse,
+ * Forest a deliberately distinct green. Seeds are authored in OKLCH so the calibration is exact.
+ */
+declare const presets: readonly ThemePreset[];
+//#endregion
+export { ThemePreset, defaultPreset, presets };

package/dist/presets.js

@@ -0,0 +1,42 @@
+//#region src/presets.ts
+/**
+* The Noctis default — first paint and the build-time static CSS use this. A near-black foundation
+* carrying a trace of the accent hue: the canvas reads neutral, but as the engine lifts chroma with
+* elevation, surfaces lean a touch indigo. The seed is a near-black base under an indigo accent
+* (canvas `lch(4.52 0.3 272)`, accent `lch(47.92 59.30 288)`), converted into OKLCH so the derived
+* ramp, controls, and elevation land exactly on the engine's calibration targets (see
+* `calibration.test.ts`). Authored in OKLCH — the engine's working space.
+*/
+const defaultPreset = {
+	name: "Dark",
+	background: "oklch(0.1711 0.0011 271)",
+	accent: "oklch(0.5674 0.1585 275)",
+	contrast: 30
+};
+/**
+* The shipped presets. Dark is the Noctis default; Midnight is a deeper violet, Light the inverse,
+* Forest a deliberately distinct green. Seeds are authored in OKLCH so the calibration is exact.
+*/
+const presets = [
+	defaultPreset,
+	{
+		name: "Light",
+		background: "oklch(0.991 0.002 271)",
+		accent: "oklch(0.5674 0.1585 275)",
+		contrast: 30
+	},
+	{
+		name: "Midnight",
+		background: "oklch(0.18 0.03 268)",
+		accent: "oklch(0.62 0.19 285)",
+		contrast: 36
+	},
+	{
+		name: "Forest",
+		background: "oklch(0.19 0.018 158)",
+		accent: "oklch(0.65 0.15 152)",
+		contrast: 32
+	}
+];
+//#endregion
+export { defaultPreset, presets };

package/dist/react/context.d.ts

@@ -0,0 +1,16 @@
+import { ThemeInput, ThemeOverrides } from "../generate/tokens.js";
+import { ThemePreset } from "../presets.js";
+//#region src/react/context.d.ts
+/**
+ * What `useTheme()` returns: the live input and generation-time overrides, their setters, and
+ * the available presets.
+ */
+interface ThemeContextValue {
+  input: ThemeInput;
+  setTheme: (input: ThemeInput) => void;
+  overrides: ThemeOverrides | undefined;
+  setOverrides: (overrides: ThemeOverrides | undefined) => void;
+  presets: readonly ThemePreset[];
+}
+//#endregion
+export { ThemeContextValue };

package/dist/react/context.js

@@ -0,0 +1,6 @@
+"use client";
+import { createContext } from "react";
+//#region src/react/context.ts
+const ThemeContext = createContext(null);
+//#endregion
+export { ThemeContext };

package/dist/react/provider.d.ts

@@ -0,0 +1,28 @@
+import { ThemeInput, ThemeOverrides } from "../generate/tokens.js";
+import { ReactNode } from "react";
+
+//#region src/react/provider.d.ts
+interface ThemeProviderProps {
+  /** Server-resolved seed (from the persisted cookie) — falls back to the default preset. */
+  initialInput?: ThemeInput;
+  /**
+   * Generation-time primitive overrides. Controlled: while present it is the active override
+   * set, and a new identity regenerates and re-applies the theme; `setOverrides` drives the
+   * uncontrolled case. Overrides participate in derivation — see `ThemeOverrides`.
+   */
+  overrides?: ThemeOverrides;
+  children: ReactNode;
+}
+/**
+ * Mounts the theme at the root of the app: regenerates the token map whenever the input or the
+ * overrides change and emits it through the engine sheet, then persists it (cookie +
+ * localStorage) so the next load's SSR seed and blocking script repaint correctly. Exposes
+ * {@link useTheme}.
+ */
+declare function ThemeProvider({
+  initialInput,
+  overrides: overridesProp,
+  children
+}: ThemeProviderProps): ReactNode;
+//#endregion
+export { ThemeProvider, ThemeProviderProps };

package/dist/react/provider.js

@@ -0,0 +1,51 @@
+"use client";
+import { generateTheme } from "../generate/theme.js";
+import { applyTheme } from "../apply/apply.js";
+import { defaultPreset, presets } from "../presets.js";
+import { persistTheme, readPersistedInput, readPersistedOverrides, writeThemeCookie } from "../ssr/ssr.js";
+import { ThemeContext } from "./context.js";
+import { useCallback, useEffect, useInsertionEffect, useMemo, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/react/provider.tsx
+/**
+* Mounts the theme at the root of the app: regenerates the token map whenever the input or the
+* overrides change and emits it through the engine sheet, then persists it (cookie +
+* localStorage) so the next load's SSR seed and blocking script repaint correctly. Exposes
+* {@link useTheme}.
+*/
+function ThemeProvider({ initialInput, overrides: overridesProp, children }) {
+	const [input, setInput] = useState(() => initialInput ?? readPersistedInput() ?? defaultPreset);
+	const [localOverrides, setLocalOverrides] = useState(() => initialInput ? void 0 : readPersistedOverrides() ?? void 0);
+	const overrides = overridesProp ?? localOverrides;
+	const vars = useMemo(() => generateTheme(input, { overrides }), [input, overrides]);
+	useInsertionEffect(() => {
+		applyTheme(vars);
+	}, [vars]);
+	useEffect(() => {
+		persistTheme(input, vars, overrides);
+		writeThemeCookie(input, { overrides });
+	}, [
+		input,
+		vars,
+		overrides
+	]);
+	const setTheme = useCallback((next) => setInput(next), []);
+	const setOverrides = useCallback((next) => setLocalOverrides(next), []);
+	return /* @__PURE__ */ jsx(ThemeContext, {
+		value: useMemo(() => ({
+			input,
+			setTheme,
+			overrides,
+			setOverrides,
+			presets
+		}), [
+			input,
+			setTheme,
+			overrides,
+			setOverrides
+		]),
+		children
+	});
+}
+//#endregion
+export { ThemeProvider };

package/dist/react/use-theme.d.ts

@@ -0,0 +1,7 @@
+import { ThemeContextValue } from "./context.js";
+
+//#region src/react/use-theme.d.ts
+/** Access the active theme input, the `setTheme` setter, and the presets. Must be under a `ThemeProvider`. */
+declare function useTheme(): ThemeContextValue;
+//#endregion
+export { useTheme };

package/dist/react/use-theme.js

@@ -0,0 +1,12 @@
+"use client";
+import { ThemeContext } from "./context.js";
+import { useContext } from "react";
+//#region src/react/use-theme.ts
+/** Access the active theme input, the `setTheme` setter, and the presets. Must be under a `ThemeProvider`. */
+function useTheme() {
+	const ctx = useContext(ThemeContext);
+	if (!ctx) throw new Error("theme-engine: useTheme must be used within a <ThemeProvider>");
+	return ctx;
+}
+//#endregion
+export { useTheme };

package/dist/react.d.ts

@@ -0,0 +1,4 @@
+import { ThemeProvider, ThemeProviderProps } from "./react/provider.js";
+import { ThemeContextValue } from "./react/context.js";
+import { useTheme } from "./react/use-theme.js";
+export { type ThemeContextValue, ThemeProvider, type ThemeProviderProps, useTheme };

package/dist/react.js

@@ -0,0 +1,3 @@
+import { ThemeProvider } from "./react/provider.js";
+import { useTheme } from "./react/use-theme.js";
+export { ThemeProvider, useTheme };

package/dist/ssr/ssr.d.ts

@@ -0,0 +1,71 @@
+import { ThemeInput, ThemeMap, ThemeOverrides } from "../generate/tokens.js";
+import { GenerateThemeOptions } from "../generate/theme.js";
+
+//#region src/ssr/ssr.d.ts
+/** Cookie + localStorage key under which the active theme is persisted. */
+declare const THEME_COOKIE_NAME = "stridge-theme";
+declare const THEME_STORAGE_KEY = "stridge-theme";
+/** Serialize a theme map into a CSS declaration body (`--k:v;…`). */
+declare function declarationsFor(map: ThemeMap): string;
+/**
+ * Build-time static CSS for a theme — the default brand theme shipped on `:root` so the first
+ * paint is correct without any JavaScript. The rule is wrapped in `@layer noctis.engine`, the
+ * same layer the runtime sheet declares into, so SSR and CSR emission carry identical names,
+ * values, and cascade position — and any unlayered author rule beats both.
+ */
+declare function emitStaticCss(input: ThemeInput, selector?: string, options?: GenerateThemeOptions): string;
+/** Encode an input (plus any generation-time overrides) for cookie/storage transport (compact, URL-safe). */
+declare function encodeThemeInput(input: ThemeInput, overrides?: ThemeOverrides): string;
+/** Decode a cookie/storage value back into an input (with its overrides), or `null` if malformed. */
+declare function decodeThemeInput(value: string): (ThemeInput & {
+  overrides?: ThemeOverrides;
+}) | null;
+/** Read the persisted theme input (with its overrides) from a raw `Cookie` header string (server-side). */
+declare function readThemeCookie(cookieHeader: string | null | undefined, name?: string): (ThemeInput & {
+  overrides?: ThemeOverrides;
+}) | null;
+/** Options for the persisted theme cookie. */
+interface ThemeCookieOptions {
+  name?: string;
+  maxAge?: number;
+  path?: string;
+  sameSite?: "Lax" | "Strict" | "None";
+  /** Generation-time overrides persisted alongside the seed; round-tripped by {@link readThemeCookie}. */
+  overrides?: ThemeOverrides;
+}
+/**
+ * Build a `Set-Cookie` value for the persisted theme (for server responses). The cookie carries
+ * the seed plus the override delta, not the generated vars — but a large enough override set can
+ * still exceed the ~4096-byte cookie cap, where browsers silently drop the write and SSR falls
+ * back to the default theme; a dev-time warning fires as the encoded value approaches it.
+ */
+declare function serializeThemeCookie(input: ThemeInput, options?: ThemeCookieOptions): string;
+/** Write the theme cookie from the browser (`document.cookie`). */
+declare function writeThemeCookie(input: ThemeInput, options?: ThemeCookieOptions): void;
+/**
+ * Persist the active theme (input + computed vars + any generation-time overrides) to
+ * localStorage for instant pre-paint apply. The vars are the resolved output, so the blocking
+ * script replays an overridden theme without engine code. Storage access can throw (privacy
+ * settings, quota, opaque origins), so failures are swallowed.
+ */
+declare function persistTheme(input: ThemeInput, vars: ThemeMap, overrides?: ThemeOverrides, key?: string): void;
+/** Read the persisted input back (for the React layer's initial state). Validated; never throws. */
+declare function readPersistedInput(key?: string): ThemeInput | null;
+/** Read the persisted generation-time overrides back, or `null` when none were stored. Never throws. */
+declare function readPersistedOverrides(key?: string): ThemeOverrides | null;
+/**
+ * Generate the body of a blocking inline `<script>` for `<head>`: it reads the persisted
+ * variables from localStorage and replays them in a `<style>` rule — `@layer noctis.engine`,
+ * `:root` — before first paint, killing the flash for client-persisted custom themes. Ships no
+ * engine code — it only replays stored vars.
+ *
+ * The replay lands in the SAME layer the runtime sheet declares into, so the provider's
+ * hydration emission (later in the layer by source order) supersedes it and post-hydration theme
+ * changes paint normally. The persisted payload carries the ROOT var map only, so the
+ * `el`/`su`/`mn` scope sets keep the build-time default until hydration — a custom-scope theme
+ * shows default scope surfaces for that window. localStorage is same-origin: the replayed values
+ * are the ones {@link persistTheme} wrote, validated at generation time.
+ */
+declare function themeBlockingScript(key?: string): string;
+//#endregion
+export { THEME_COOKIE_NAME, THEME_STORAGE_KEY, ThemeCookieOptions, declarationsFor, decodeThemeInput, emitStaticCss, encodeThemeInput, persistTheme, readPersistedInput, readPersistedOverrides, readThemeCookie, serializeThemeCookie, themeBlockingScript, writeThemeCookie };