@ciridae/ui 0.6.1 → 0.7.0

package/dist/components/ui/ciridae-ui-provider.d.ts

@@ -3,6 +3,6 @@ import { type ThemeProviderProps } from "./color-theme";
 export type CiridaeUiProviderProps = {
     children: ReactNode;
     agentation?: boolean;
-} & Pick<ThemeProviderProps, "defaultMode">;
-declare function CiridaeUiProvider({ agentation, children, defaultMode }: CiridaeUiProviderProps): import("@types/react").JSX.Element;
+} & Pick<ThemeProviderProps, "defaultMode" | "defaultPalette">;
+declare function CiridaeUiProvider({ agentation, children, defaultMode, defaultPalette, }: CiridaeUiProviderProps): import("@types/react").JSX.Element;
 export { CiridaeUiProvider };

package/dist/components/ui/ciridae-ui-provider.js

@@ -8,7 +8,7 @@ function CiridaeUiToaster() {
     const { mode } = useTheme();
     return _jsx(Toaster, { richColors: true, closeButton: true, theme: mode });
 }
-function CiridaeUiProvider({ agentation = false, children, defaultMode }) {
-    return (_jsx(ThemeProvider, { defaultMode: defaultMode, children: _jsxs(TooltipProvider, { children: [children, _jsx(CiridaeUiToaster, {}), agentation ? (_jsx(Suspense, { fallback: null, children: _jsx(LazyAgentation, {}) })) : null] }) }));
+function CiridaeUiProvider({ agentation = false, children, defaultMode, defaultPalette, }) {
+    return (_jsx(ThemeProvider, { defaultMode: defaultMode, defaultPalette: defaultPalette, children: _jsxs(TooltipProvider, { children: [children, _jsx(CiridaeUiToaster, {}), agentation ? (_jsx(Suspense, { fallback: null, children: _jsx(LazyAgentation, {}) })) : null] }) }));
 }
 export { CiridaeUiProvider };

package/dist/components/ui/color-theme-context.d.ts

@@ -1,4 +1,5 @@
 import * as React from "react";
+import type { PaletteSelection } from "../../lib/palette";
 type ThemeMode = "light" | "dark" | "system";
 type ResolvedTheme = "light" | "dark";
 type ThemeContextValue = {
@@ -6,11 +7,22 @@ type ThemeContextValue = {
     resolvedTheme: ResolvedTheme;
     setMode: (mode: ThemeMode) => void;
     toggleTheme: () => void;
+    /** `null` means the app has not opted into palettes; the stylesheet's tokens stand. */
+    palette: PaletteSelection | null;
+    setPalette: (palette: PaletteSelection) => void;
+    /** Drops the user's override and returns to the app's `defaultPalette`. */
+    resetPalette: () => void;
 };
 type ThemeProviderProps = {
     children: React.ReactNode;
     defaultMode?: ThemeMode;
+    /**
+     * The app's own identity. Omit to leave every color token to the
+     * stylesheet, which is what keeps an app that has not opted in unchanged.
+     */
+    defaultPalette?: PaletteSelection;
     storageKey?: string;
+    paletteStorageKey?: string;
 };
 declare const ThemeContext: React.Context<ThemeContextValue | undefined>;
 export { ThemeContext, type ResolvedTheme, type ThemeContextValue, type ThemeMode, type ThemeProviderProps, };

package/dist/components/ui/color-theme.d.ts

@@ -1,5 +1,5 @@
 import * as React from "react";
 import { type ResolvedTheme, type ThemeMode, type ThemeProviderProps } from "./color-theme-context";
-declare function ThemeProvider({ children, defaultMode, storageKey, }: ThemeProviderProps): React.JSX.Element;
+declare function ThemeProvider({ children, defaultMode, defaultPalette, storageKey, paletteStorageKey, }: ThemeProviderProps): React.JSX.Element;
 export { ThemeProvider, type ResolvedTheme, type ThemeMode, type ThemeProviderProps };
 export { useTheme } from "./use-color-theme";

package/dist/components/ui/color-theme.js

@@ -1,16 +1,35 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import * as React from "react";
+import { PALETTE_TOKEN_NAMES, canonicalPaletteSelection, derivePaletteTokens, paletteSelectionKey, resolvePaletteSelection, } from "../../lib/palette";
 import { ThemeContext, } from "./color-theme-context";
 const defaultStorageKey = "ciridae-ui-theme";
-function ThemeProvider({ children, defaultMode = "system", storageKey = defaultStorageKey, }) {
+const defaultPaletteStorageKey = "ciridae-ui-palette";
+function ThemeProvider({ children, defaultMode = "system", defaultPalette, storageKey = defaultStorageKey, paletteStorageKey = defaultPaletteStorageKey, }) {
     const [mode, setModeState] = React.useState(() => readStoredMode(storageKey, defaultMode));
+    const [storedPalette, setStoredPalette] = React.useState(() => readStoredPalette(paletteStorageKey));
     const [systemTheme, setSystemTheme] = React.useState(() => getSystemTheme());
     const resolvedTheme = mode === "system" ? systemTheme : mode;
+    const selected = storedPalette ?? defaultPalette ?? null;
+    // `defaultPalette` is documented as an inline object literal, so it is a new
+    // reference on every render. Keyed by identity instead, the token effect and
+    // the context memo below stop firing on renders that changed no palette.
+    const paletteKey = paletteSelectionKey(selected);
+    // Publish the canonical selection, not the caller's object. Memoising the raw
+    // one would hand back a stale copy whenever two inputs share a key: setting
+    // hue 10.4 after 10.1 changes storage but not the key, so `palette.hue` would
+    // keep reporting 10.1 for the session and a control bound to it would snap
+    // back on any sub-degree move.
+    //
+    // Depending on `selected` is the other half: it is a new object every render,
+    // while `paletteKey` changes exactly when the palette does.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    const palette = React.useMemo(() => canonicalPaletteSelection(selected), [paletteKey]);
     React.useEffect(() => {
         const root = document.documentElement;
         root.classList.remove("light", "dark");
         root.classList.add(resolvedTheme);
     }, [resolvedTheme]);
+    usePaletteTokens(palette, resolvedTheme);
     React.useEffect(() => {
         const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
         const updateSystemTheme = () => {
@@ -27,9 +46,63 @@ function ThemeProvider({ children, defaultMode = "system", storageKey = defaultS
     const toggleTheme = React.useCallback(() => {
         setMode(resolvedTheme === "dark" ? "light" : "dark");
     }, [resolvedTheme, setMode]);
-    const contextValue = React.useMemo(() => ({ mode, resolvedTheme, setMode, toggleTheme }), [mode, resolvedTheme, setMode, toggleTheme]);
+    const setPalette = React.useCallback((nextPalette) => {
+        setStoredPalette(nextPalette);
+        localStorage.setItem(paletteStorageKey, JSON.stringify(nextPalette));
+    }, [paletteStorageKey]);
+    const resetPalette = React.useCallback(() => {
+        setStoredPalette(null);
+        localStorage.removeItem(paletteStorageKey);
+    }, [paletteStorageKey]);
+    const contextValue = React.useMemo(() => ({
+        mode,
+        resolvedTheme,
+        setMode,
+        toggleTheme,
+        palette,
+        setPalette,
+        resetPalette,
+    }), [mode, resolvedTheme, setMode, toggleTheme, palette, setPalette, resetPalette]);
     return _jsx(ThemeContext.Provider, { value: contextValue, children: children });
 }
+/**
+ * Writes a palette onto the document element as inline custom properties.
+ *
+ * Inline values outrank both the `:root` and `.dark` rules, so they have to be
+ * recomputed for the resolved mode rather than only when the palette changes.
+ * With no palette the properties are removed outright and the stylesheet
+ * governs again.
+ */
+function usePaletteTokens(palette, mode) {
+    // Only clear what this hook wrote. An app that sets a custom property on the
+    // document element itself, and never opts into palettes, would otherwise have
+    // it stripped on mount and on every mode change by a provider it is only
+    // using for light and dark.
+    const hasWritten = React.useRef(false);
+    React.useEffect(() => {
+        const root = document.documentElement;
+        const clear = () => {
+            if (!hasWritten.current)
+                return;
+            for (const token of PALETTE_TOKEN_NAMES)
+                root.style.removeProperty(`--${token}`);
+            hasWritten.current = false;
+        };
+        const spec = palette ? resolvePaletteSelection(palette) : null;
+        if (!spec) {
+            clear();
+            return;
+        }
+        for (const [token, value] of Object.entries(derivePaletteTokens(spec, mode))) {
+            root.style.setProperty(`--${token}`, value);
+        }
+        hasWritten.current = true;
+        // The properties live on an element this hook does not own, so it has to
+        // hand them back. Without this an unmounted provider leaves a palette on
+        // the document for whatever renders next.
+        return clear;
+    }, [palette, mode]);
+}
 function readStoredMode(storageKey, defaultMode) {
     if (typeof window === "undefined")
         return defaultMode;
@@ -39,6 +112,35 @@ function readStoredMode(storageKey, defaultMode) {
     }
     return defaultMode;
 }
+/**
+ * Anything unrecognised is discarded rather than trusted: this value survives
+ * deploys, so it outlives renamed presets and older shapes of the type.
+ */
+function readStoredPalette(storageKey) {
+    if (typeof window === "undefined")
+        return null;
+    const raw = localStorage.getItem(storageKey);
+    if (!raw)
+        return null;
+    try {
+        return parseStoredPalette(JSON.parse(raw));
+    }
+    catch {
+        // Corrupt JSON is treated the same as no preference.
+        return null;
+    }
+}
+function parseStoredPalette(value) {
+    if (typeof value !== "object" || value === null || !("kind" in value))
+        return null;
+    if (value.kind === "preset" && "id" in value && typeof value.id === "string") {
+        return canonicalPaletteSelection({ kind: "preset", id: value.id });
+    }
+    if (value.kind === "custom" && "hue" in value && typeof value.hue === "number") {
+        return canonicalPaletteSelection({ kind: "custom", hue: value.hue });
+    }
+    return null;
+}
 function getSystemTheme() {
     if (typeof window === "undefined")
         return "light";

package/dist/entries/palette.d.ts

@@ -0,0 +1,2 @@
+export * from "../lib/palette";
+export * from "../lib/palette-presets";

package/dist/entries/palette.js

@@ -0,0 +1,2 @@
+export * from "../lib/palette";
+export * from "../lib/palette-presets";

package/dist/lib/palette-presets.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The palettes an app can name.
+ *
+ * Five, chosen to be visibly distinct from one another: below about 0.02 in
+ * OKLab two swatches read as the same color, and every pair here clears that by
+ * at least fivefold. That rules out a second neutral -- a warm ground differs
+ * from a cool one by roughly 0.006, real across a whole page but invisible in a
+ * swatch -- so Slate is the only one without a brand hue of its own.
+ *
+ * Anything else is a hue away: `customPaletteSpec` in ./palette builds a palette
+ * from a single number, and `scripts/check-palette-contrast.mjs` proves every
+ * one of those is readable too.
+ */
+import type { PalettePreset } from "./palette";
+declare const PALETTE_PRESETS: readonly PalettePreset[];
+declare const PALETTE_PRESETS_BY_ID: ReadonlyMap<string, PalettePreset>;
+export { PALETTE_PRESETS, PALETTE_PRESETS_BY_ID };

package/dist/lib/palette-presets.js

@@ -0,0 +1,42 @@
+const PALETTE_PRESETS = Object.freeze([
+    // The theme the template shipped before palettes existed, and the way back to it.
+    { id: "slate", label: "Slate", spec: { groundHue: 260, groundChroma: 0.002 } },
+    {
+        id: "clay",
+        label: "Clay",
+        spec: {
+            groundHue: 55,
+            groundChroma: 0.008,
+            brand: { hue: 50, chroma: 0.11, lightness: 0.44 },
+        },
+    },
+    {
+        id: "iris",
+        label: "Iris",
+        spec: {
+            groundHue: 275,
+            groundChroma: 0.005,
+            brand: { hue: 285, chroma: 0.13, lightness: 0.42 },
+        },
+    },
+    {
+        id: "teal",
+        label: "Teal",
+        spec: {
+            groundHue: 200,
+            groundChroma: 0.005,
+            brand: { hue: 195, chroma: 0.1, lightness: 0.44 },
+        },
+    },
+    {
+        id: "plum",
+        label: "Plum",
+        spec: {
+            groundHue: 320,
+            groundChroma: 0.005,
+            brand: { hue: 330, chroma: 0.12, lightness: 0.42 },
+        },
+    },
+]);
+const PALETTE_PRESETS_BY_ID = new Map(PALETTE_PRESETS.map((preset) => [preset.id, preset]));
+export { PALETTE_PRESETS, PALETTE_PRESETS_BY_ID };

package/dist/lib/palette-tokens.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The fixed parts of the theme: the lightness ladder every palette is built on,
+ * and the status colors no palette is allowed to move.
+ *
+ * Kept apart from ./palette so the derivation reads as logic rather than data.
+ */
+type PaletteMode = "light" | "dark";
+type LadderEntry = {
+    l: number;
+    /** Multiplier on the palette's ground chroma. */
+    c: number;
+    /** Alpha, for the tokens that carry one. */
+    a?: number;
+    /** Takes the brand hue and chroma, but only when the palette declares a brand. */
+    brand?: true;
+};
+/**
+ * Every color token, as lightness plus a multiplier on the palette's ground
+ * chroma. Read straight out of ciridae.css against its 0.002 chroma, so the
+ * Slate preset reproduces the stylesheet exactly -- `check-palette-contrast.mjs`
+ * asserts that, and will fail if the two ever drift.
+ *
+ * A palette moves hue and chroma but never the lightness, which is what keeps
+ * the contrast gates cleared: WCAG contrast is dominated by lightness.
+ */
+declare const LADDER: Record<PaletteMode, Record<string, LadderEntry>>;
+/**
+ * Status stays semantic across every palette: an error is the same red whatever
+ * brand the app wears, so "failed" never has to be relearned per theme. The last
+ * two chart series sit here for the same reason -- they keep a five-series chart
+ * readable when the brand-led three are close together.
+ */
+declare const STATUS_TOKENS: Record<PaletteMode, Record<string, string>>;
+/** Tokens whose fill carries the brand rather than a surface step. */
+declare const BRAND_FILLS: Set<string>;
+/** Hover surfaces take a fraction of the brand chroma so they read as tinted, not saturated. */
+declare const ACCENT_SURFACES: Set<string>;
+declare const ACCENT_FOREGROUNDS: Set<string>;
+export { ACCENT_FOREGROUNDS, ACCENT_SURFACES, BRAND_FILLS, LADDER, STATUS_TOKENS, type LadderEntry, type PaletteMode, };

package/dist/lib/palette-tokens.js

@@ -0,0 +1,133 @@
+/**
+ * The fixed parts of the theme: the lightness ladder every palette is built on,
+ * and the status colors no palette is allowed to move.
+ *
+ * Kept apart from ./palette so the derivation reads as logic rather than data.
+ */
+/**
+ * Every color token, as lightness plus a multiplier on the palette's ground
+ * chroma. Read straight out of ciridae.css against its 0.002 chroma, so the
+ * Slate preset reproduces the stylesheet exactly -- `check-palette-contrast.mjs`
+ * asserts that, and will fail if the two ever drift.
+ *
+ * A palette moves hue and chroma but never the lightness, which is what keeps
+ * the contrast gates cleared: WCAG contrast is dominated by lightness.
+ */
+const LADDER = {
+    light: {
+        background: { l: 0.985, c: 0.5 },
+        foreground: { l: 0.145, c: 1 },
+        card: { l: 1, c: 0 },
+        "card-foreground": { l: 0.145, c: 1 },
+        popover: { l: 1, c: 0 },
+        "popover-foreground": { l: 0.145, c: 1 },
+        primary: { l: 0.145, c: 1, brand: true },
+        "primary-foreground": { l: 0.99, c: 0 },
+        secondary: { l: 0.955, c: 1 },
+        "secondary-foreground": { l: 0.2, c: 1 },
+        muted: { l: 0.955, c: 1 },
+        "muted-foreground": { l: 0.46, c: 1.5 },
+        accent: { l: 0.935, c: 1, brand: true },
+        "accent-foreground": { l: 0.18, c: 1, brand: true },
+        border: { l: 0.865, c: 1 },
+        input: { l: 0.835, c: 1 },
+        ring: { l: 0.145, c: 1, brand: true },
+        overlay: { l: 0.145, c: 1, a: 0.58 },
+        surface: { l: 1, c: 0 },
+        "surface-foreground": { l: 0.145, c: 1 },
+        "surface-inverse": { l: 0.145, c: 1 },
+        "surface-inverse-foreground": { l: 0.99, c: 0 },
+        "chart-1": { l: 0.22, c: 1, brand: true },
+        "chart-2": { l: 0.5, c: 1, brand: true },
+        "chart-3": { l: 0.72, c: 1, brand: true },
+        sidebar: { l: 0.965, c: 0.5 },
+        "sidebar-foreground": { l: 0.23, c: 1 },
+        "sidebar-primary": { l: 0.145, c: 1, brand: true },
+        "sidebar-primary-foreground": { l: 0.99, c: 0 },
+        "sidebar-accent": { l: 0.935, c: 1, brand: true },
+        "sidebar-accent-foreground": { l: 0.18, c: 1, brand: true },
+        "sidebar-border": { l: 0.865, c: 1 },
+        "sidebar-ring": { l: 0.145, c: 1, brand: true },
+        "table-header-foreground": { l: 0.42, c: 1.5 },
+    },
+    dark: {
+        background: { l: 0.145, c: 1 },
+        foreground: { l: 0.935, c: 0.5 },
+        card: { l: 0.185, c: 1 },
+        "card-foreground": { l: 0.935, c: 0.5 },
+        popover: { l: 0.205, c: 1 },
+        "popover-foreground": { l: 0.935, c: 0.5 },
+        primary: { l: 0.965, c: 0.5, brand: true },
+        "primary-foreground": { l: 0.145, c: 1 },
+        secondary: { l: 0.255, c: 1 },
+        "secondary-foreground": { l: 0.94, c: 0.5 },
+        muted: { l: 0.255, c: 1 },
+        "muted-foreground": { l: 0.7, c: 1 },
+        accent: { l: 0.275, c: 1, brand: true },
+        "accent-foreground": { l: 0.94, c: 0.5, brand: true },
+        border: { l: 0.32, c: 1 },
+        input: { l: 0.36, c: 1 },
+        ring: { l: 0.88, c: 0.5, brand: true },
+        overlay: { l: 0.08, c: 0.5, a: 0.72 },
+        surface: { l: 0.205, c: 1 },
+        "surface-foreground": { l: 0.935, c: 0.5 },
+        "surface-inverse": { l: 0.935, c: 0.5 },
+        "surface-inverse-foreground": { l: 0.145, c: 1 },
+        "chart-1": { l: 0.9, c: 0.5, brand: true },
+        "chart-2": { l: 0.68, c: 1, brand: true },
+        "chart-3": { l: 0.48, c: 1, brand: true },
+        sidebar: { l: 0.18, c: 1 },
+        "sidebar-foreground": { l: 0.88, c: 0.5 },
+        "sidebar-primary": { l: 0.965, c: 0.5, brand: true },
+        "sidebar-primary-foreground": { l: 0.145, c: 1 },
+        "sidebar-accent": { l: 0.235, c: 1, brand: true },
+        "sidebar-accent-foreground": { l: 0.94, c: 0.5, brand: true },
+        "sidebar-border": { l: 0.32, c: 1 },
+        "sidebar-ring": { l: 0.88, c: 0.5, brand: true },
+        "table-header-foreground": { l: 0.78, c: 1 },
+    },
+};
+/**
+ * Status stays semantic across every palette: an error is the same red whatever
+ * brand the app wears, so "failed" never has to be relearned per theme. The last
+ * two chart series sit here for the same reason -- they keep a five-series chart
+ * readable when the brand-led three are close together.
+ */
+const STATUS_TOKENS = {
+    light: {
+        destructive: "oklch(0.48 0.13 27)",
+        "destructive-foreground": "oklch(0.99 0 0)",
+        success: "oklch(0.44 0.075 150)",
+        "success-foreground": "oklch(0.99 0 0)",
+        "success-muted": "oklch(0.94 0.03 150)",
+        info: "oklch(0.43 0.045 245)",
+        "info-foreground": "oklch(0.99 0 0)",
+        "info-muted": "oklch(0.94 0.018 245)",
+        warning: "oklch(0.52 0.075 85)",
+        "warning-foreground": "oklch(0.99 0 0)",
+        "warning-muted": "oklch(0.95 0.035 85)",
+        "chart-4": "oklch(0.5 0.055 245)",
+        "chart-5": "oklch(0.5 0.07 150)",
+    },
+    dark: {
+        destructive: "oklch(0.65 0.12 27)",
+        "destructive-foreground": "oklch(0.12 0.002 260)",
+        success: "oklch(0.68 0.075 150)",
+        "success-foreground": "oklch(0.12 0.002 260)",
+        "success-muted": "oklch(0.25 0.035 150)",
+        info: "oklch(0.7 0.05 245)",
+        "info-foreground": "oklch(0.12 0.002 260)",
+        "info-muted": "oklch(0.25 0.028 245)",
+        warning: "oklch(0.76 0.075 85)",
+        "warning-foreground": "oklch(0.12 0.002 260)",
+        "warning-muted": "oklch(0.27 0.04 85)",
+        "chart-4": "oklch(0.72 0.065 245)",
+        "chart-5": "oklch(0.7 0.1 150)",
+    },
+};
+/** Tokens whose fill carries the brand rather than a surface step. */
+const BRAND_FILLS = new Set(["primary", "sidebar-primary", "ring", "sidebar-ring"]);
+/** Hover surfaces take a fraction of the brand chroma so they read as tinted, not saturated. */
+const ACCENT_SURFACES = new Set(["accent", "sidebar-accent"]);
+const ACCENT_FOREGROUNDS = new Set(["accent-foreground", "sidebar-accent-foreground"]);
+export { ACCENT_FOREGROUNDS, ACCENT_SURFACES, BRAND_FILLS, LADDER, STATUS_TOKENS, };

package/dist/lib/palette.d.ts

@@ -0,0 +1,83 @@
+import { type PaletteMode } from "./palette-tokens";
+/**
+ * A palette's brand, supplied whole.
+ *
+ * One object rather than three optional fields so the two states -- ground-only
+ * and branded -- are the only ones a caller can express. Separately optional
+ * hue, chroma, and lightness let a type-valid spec colour the primary while the
+ * charts took the ground-only path.
+ */
+type PaletteBrand = {
+    hue: number;
+    chroma: number;
+    /** Light-mode lightness of primary. Dark mode lifts it to stay legible. */
+    lightness: number;
+};
+type PaletteSpec = {
+    /** Hue for surfaces, borders, and text. */
+    groundHue: number;
+    /** Chroma for those neutrals. Tiny values (< 0.015) read as a tint, not a color. */
+    groundChroma: number;
+    /** Omit for a palette that is only a tinted ground, keeping a near-black primary. */
+    brand?: PaletteBrand;
+};
+type PalettePreset = {
+    id: string;
+    label: string;
+    spec: PaletteSpec;
+};
+/**
+ * Full token map for one palette in one mode, as `--name` -> oklch string.
+ * Applied as inline custom properties on the document element, which is why the
+ * caller must recompute when the light/dark mode changes: an inline value wins
+ * over both the `:root` and `.dark` rules.
+ *
+ * The readability guarantee covers the specs `check-palette-contrast.mjs`
+ * sweeps: the named presets and anything `customPaletteSpec` returns. A spec
+ * assembled by hand with its own chroma and lightness is derived faithfully but
+ * has never been graded.
+ */
+declare function derivePaletteTokens(spec: PaletteSpec, mode: PaletteMode): Record<string, string>;
+/** Every token a palette writes. Used to clear stale properties when switching. */
+declare const PALETTE_TOKEN_NAMES: readonly string[];
+/**
+ * A palette from a hue alone, for an app whose brand is not in the preset list.
+ * Ground hue follows the brand, so there is no combination that clashes with
+ * itself and only the hue has to be chosen.
+ *
+ * Throws on a hue that is not finite: `oklch(0.43 0.12 NaN)` is not an error any
+ * browser reports, it silently voids every declaration that uses the token.
+ *
+ * The hue is normalised to a whole degree, which is what makes the contrast
+ * gate's sweep total rather than a sample: a fraction of a degree is invisible,
+ * but an unrounded hue would be a reachable palette the sweep never graded.
+ */
+declare function customPaletteSpec(hue: number): PaletteSpec;
+/** What an app or a user has chosen. `null` elsewhere means "use the stylesheet". */
+type PaletteSelection = {
+    kind: "preset";
+    id: string;
+} | {
+    kind: "custom";
+    hue: number;
+};
+/**
+ * The selection as the derivation reads it: a hue normalised to the whole degree
+ * the tokens come from, and `null` for anything that resolves to nothing -- a
+ * preset id that no longer exists, a hue that is not finite.
+ *
+ * This is the single validating boundary for a selection from anywhere
+ * untrusted: a stored value, a URL, an app's own config. Publishing it rather
+ * than the caller's own object also keeps `useTheme().palette` equal to what is
+ * on the document, so a control bound to `palette.hue` reads back the palette it
+ * is looking at.
+ */
+declare function canonicalPaletteSelection(selection: PaletteSelection | null): PaletteSelection | null;
+/** The spec a selection derives, or `null` if it does not resolve to one. */
+declare function resolvePaletteSelection(selection: PaletteSelection): PaletteSpec | null;
+/**
+ * Stable identity for a selection, so a caller holding an inline
+ * `defaultPalette` object literal does not look like a new palette every render.
+ */
+declare function paletteSelectionKey(selection: PaletteSelection | null): string;
+export { PALETTE_TOKEN_NAMES, canonicalPaletteSelection, customPaletteSpec, derivePaletteTokens, paletteSelectionKey, resolvePaletteSelection, type PaletteBrand, type PaletteMode, type PalettePreset, type PaletteSelection, type PaletteSpec, };

package/dist/lib/palette.js

@@ -0,0 +1,151 @@
+/**
+ * Palette derivation for the Ciridae theme.
+ *
+ * A palette is a ground plus an optional brand, not a hand-authored token set:
+ * ./palette-tokens owns the lightness ladder, and a palette moves only hue and
+ * chroma over it. Holding lightness fixed is what keeps every palette clearing
+ * the contrast gates, because WCAG contrast is dominated by lightness;
+ * `scripts/check-palette-contrast.mjs` proves that across both the presets and
+ * every whole-degree hue `customPaletteSpec` can produce.
+ *
+ * Named presets and custom hues run through `derivePaletteTokens` alike, so
+ * there is no second code path that could drift from the validated one.
+ */
+import { PALETTE_PRESETS_BY_ID } from "./palette-presets";
+import { ACCENT_FOREGROUNDS, ACCENT_SURFACES, BRAND_FILLS, LADDER, STATUS_TOKENS, } from "./palette-tokens";
+function round(value, places) {
+    return Number.parseFloat(value.toFixed(places));
+}
+/** Hue is dropped at zero chroma, where it says nothing and `oklch(1 0 0)` is the idiom. */
+function formatOklch(lightness, chroma, hue, alpha) {
+    const c = round(chroma, 4);
+    const channels = `${round(lightness, 3)} ${c} ${c === 0 ? 0 : hue}`;
+    return alpha === undefined ? `oklch(${channels})` : `oklch(${channels} / ${alpha})`;
+}
+function brandChroma(token, brand, mode) {
+    if (ACCENT_SURFACES.has(token))
+        return brand.chroma * (mode === "light" ? 0.22 : 0.3);
+    if (ACCENT_FOREGROUNDS.has(token))
+        return brand.chroma * 0.35;
+    return brand.chroma;
+}
+function brandLightness(token, entry, brand, mode) {
+    if (!BRAND_FILLS.has(token))
+        return entry.l;
+    if (mode === "light")
+        return brand.lightness;
+    // A saturated brand at its light-mode lightness disappears into a dark
+    // ground, so the fill lifts rather than inverting to near-white.
+    return Math.min(0.82, brand.lightness + 0.32);
+}
+/**
+ * Full token map for one palette in one mode, as `--name` -> oklch string.
+ * Applied as inline custom properties on the document element, which is why the
+ * caller must recompute when the light/dark mode changes: an inline value wins
+ * over both the `:root` and `.dark` rules.
+ *
+ * The readability guarantee covers the specs `check-palette-contrast.mjs`
+ * sweeps: the named presets and anything `customPaletteSpec` returns. A spec
+ * assembled by hand with its own chroma and lightness is derived faithfully but
+ * has never been graded.
+ */
+function derivePaletteTokens(spec, mode) {
+    const tokens = {};
+    for (const [token, entry] of Object.entries(LADDER[mode])) {
+        // A palette with no brand is entirely its ground, so the brand-marked
+        // tokens fall back to the ladder untouched. That is what lets Slate come
+        // out byte-identical to ciridae.css rather than as a near-copy.
+        const brand = entry.brand === true ? spec.brand : undefined;
+        const hue = brand ? brand.hue : spec.groundHue;
+        const chroma = brand ? brandChroma(token, brand, mode) : spec.groundChroma * entry.c;
+        const lightness = brand ? brandLightness(token, entry, brand, mode) : entry.l;
+        tokens[token] = formatOklch(lightness, chroma, hue, entry.a);
+    }
+    return { ...tokens, ...STATUS_TOKENS[mode] };
+}
+/** Every token a palette writes. Used to clear stale properties when switching. */
+const PALETTE_TOKEN_NAMES = Object.freeze([
+    ...new Set([
+        ...Object.keys(LADDER.light),
+        ...Object.keys(LADDER.dark),
+        ...Object.keys(STATUS_TOKENS.light),
+        ...Object.keys(STATUS_TOKENS.dark),
+    ]),
+]);
+/** Chroma for a hue-only palette: the middle of the range the presets use. */
+const CUSTOM_BRAND_CHROMA = 0.12;
+/**
+ * Whole degrees in [0, 360) -- the space `check-palette-contrast.mjs` sweeps.
+ *
+ * Shared so a hue and its identity cannot normalise differently: 360, 0, and
+ * 359.6 all derive the same palette, so they must all name it the same way.
+ */
+function normalizeHue(hue) {
+    return Math.round(((hue % 360) + 360) % 360) % 360;
+}
+/**
+ * A palette from a hue alone, for an app whose brand is not in the preset list.
+ * Ground hue follows the brand, so there is no combination that clashes with
+ * itself and only the hue has to be chosen.
+ *
+ * Throws on a hue that is not finite: `oklch(0.43 0.12 NaN)` is not an error any
+ * browser reports, it silently voids every declaration that uses the token.
+ *
+ * The hue is normalised to a whole degree, which is what makes the contrast
+ * gate's sweep total rather than a sample: a fraction of a degree is invisible,
+ * but an unrounded hue would be a reachable palette the sweep never graded.
+ */
+function customPaletteSpec(hue) {
+    if (!Number.isFinite(hue))
+        throw new Error(`Custom palette hue must be finite, got ${hue}`);
+    const normalizedHue = normalizeHue(hue);
+    return {
+        groundHue: normalizedHue,
+        groundChroma: 0.005,
+        brand: { hue: normalizedHue, chroma: CUSTOM_BRAND_CHROMA, lightness: 0.43 },
+    };
+}
+/**
+ * The selection as the derivation reads it: a hue normalised to the whole degree
+ * the tokens come from, and `null` for anything that resolves to nothing -- a
+ * preset id that no longer exists, a hue that is not finite.
+ *
+ * This is the single validating boundary for a selection from anywhere
+ * untrusted: a stored value, a URL, an app's own config. Publishing it rather
+ * than the caller's own object also keeps `useTheme().palette` equal to what is
+ * on the document, so a control bound to `palette.hue` reads back the palette it
+ * is looking at.
+ */
+function canonicalPaletteSelection(selection) {
+    if (!selection)
+        return null;
+    if (selection.kind === "preset") {
+        return PALETTE_PRESETS_BY_ID.has(selection.id) ? selection : null;
+    }
+    return Number.isFinite(selection.hue)
+        ? { kind: "custom", hue: normalizeHue(selection.hue) }
+        : null;
+}
+/** The spec a selection derives, or `null` if it does not resolve to one. */
+function resolvePaletteSelection(selection) {
+    const canonical = canonicalPaletteSelection(selection);
+    if (!canonical)
+        return null;
+    return canonical.kind === "preset"
+        ? (PALETTE_PRESETS_BY_ID.get(canonical.id)?.spec ?? null)
+        : customPaletteSpec(canonical.hue);
+}
+/**
+ * Stable identity for a selection, so a caller holding an inline
+ * `defaultPalette` object literal does not look like a new palette every render.
+ */
+function paletteSelectionKey(selection) {
+    if (!selection)
+        return "none";
+    if (selection.kind === "preset")
+        return `preset:${selection.id}`;
+    // Normalised exactly as `customPaletteSpec` does, so two hues that derive the
+    // same palette cannot read as two different selections.
+    return `custom:${normalizeHue(selection.hue)}`;
+}
+export { PALETTE_TOKEN_NAMES, canonicalPaletteSelection, customPaletteSpec, derivePaletteTokens, paletteSelectionKey, resolvePaletteSelection, };

package/package.json

@@ -1,8 +1,11 @@
 {
 	"name": "@ciridae/ui",
-	"version": "0.6.1",
+	"version": "0.7.0",
 	"type": "module",
 	"private": false,
+	"engines": {
+		"node": ">=22.18"
+	},
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/ciridae-ai/ciridae.git",