@clhaas/palette-kit 0.1.7 → 0.3.0

package/dist/engine/gamut.js

@@ -0,0 +1,101 @@
+import { clampChroma, converter } from "culori";
+import { clamp } from "../utils/clamp.js";
+const toRgb = converter("rgb");
+const toP3 = converter("p3");
+const toOklch = converter("oklch");
+const normalizeHue = (hue) => ((hue % 360) + 360) % 360;
+const toCuloriOklch = (color) => ({
+    mode: "oklch",
+    l: clamp(color.l, 0, 100) / 100,
+    c: Math.max(0, color.c),
+    h: color.h,
+    alpha: color.alpha ?? 1,
+});
+const fromCuloriOklch = (color) => ({
+    l: clamp(typeof color.l === "number" && Number.isFinite(color.l) ? color.l * 100 : 0, 0, 100),
+    c: Math.max(0, typeof color.c === "number" && Number.isFinite(color.c) ? color.c : 0),
+    h: normalizeHue(typeof color.h === "number" && Number.isFinite(color.h) ? color.h : 0),
+    ...(typeof color.alpha === "number" ? { alpha: color.alpha } : {}),
+});
+const clamp01 = (value) => Math.min(1, Math.max(0, value));
+const toTargetRgb = (color, target) => {
+    const source = toCuloriOklch(color);
+    const rgb = target === "p3" ? toP3(source) : toRgb(source);
+    if (!rgb) {
+        return null;
+    }
+    const r = typeof rgb.r === "number" && Number.isFinite(rgb.r) ? rgb.r : Number.NaN;
+    const g = typeof rgb.g === "number" && Number.isFinite(rgb.g) ? rgb.g : Number.NaN;
+    const b = typeof rgb.b === "number" && Number.isFinite(rgb.b) ? rgb.b : Number.NaN;
+    if (!Number.isFinite(r) || !Number.isFinite(g) || !Number.isFinite(b)) {
+        return null;
+    }
+    return { r, g, b };
+};
+const toOklchFromRgb = (rgb, target) => {
+    const converted = toOklch({
+        mode: (target === "p3" ? "p3" : "rgb"),
+        r: clamp01(rgb.r),
+        g: clamp01(rgb.g),
+        b: clamp01(rgb.b),
+    });
+    if (!converted) {
+        return null;
+    }
+    return fromCuloriOklch(converted);
+};
+const GAMUT_EPSILON = 1e-6;
+const inGamut = (rgb) => !!rgb &&
+    Number.isFinite(rgb.r) &&
+    Number.isFinite(rgb.g) &&
+    Number.isFinite(rgb.b) &&
+    rgb.r >= -GAMUT_EPSILON &&
+    rgb.r <= 1 + GAMUT_EPSILON &&
+    rgb.g >= -GAMUT_EPSILON &&
+    rgb.g <= 1 + GAMUT_EPSILON &&
+    rgb.b >= -GAMUT_EPSILON &&
+    rgb.b <= 1 + GAMUT_EPSILON;
+const fallbackColor = (color) => ({
+    l: 0,
+    c: 0,
+    h: 0,
+    alpha: color.alpha ?? 1,
+});
+export const isInGamut = (color, target) => inGamut(toTargetRgb(color, target));
+export const mapToGamut = (color, target, mapping, strict) => {
+    // Note:
+    // `preferP3ThenCompress` is primarily a caller-level strategy (e.g. serializeColor prefers P3 when possible).
+    // Inside this mapper, any non-clip mapping uses chroma compression (via clampChroma) when mapping is needed.
+    const rgb = toTargetRgb(color, target);
+    if (!rgb) {
+        if (strict) {
+            throw new Error(`Unable to convert color to ${target}`);
+        }
+        return fallbackColor(color);
+    }
+    if (mapping === "clip") {
+        if (inGamut(rgb)) {
+            return color;
+        }
+        const clipped = { r: clamp01(rgb.r), g: clamp01(rgb.g), b: clamp01(rgb.b) };
+        const clippedOklch = toOklchFromRgb(clipped, target);
+        return clippedOklch
+            ? {
+                ...clippedOklch,
+                ...(typeof color.alpha === "number" ? { alpha: color.alpha } : {}),
+            }
+            : fallbackColor(color);
+    }
+    if (inGamut(rgb)) {
+        return color;
+    }
+    const clamped = clampChroma(toCuloriOklch(color), "oklch", target === "p3" ? "p3" : "rgb");
+    if (!clamped) {
+        if (strict) {
+            throw new Error(`Unable to clamp chroma for ${target}`);
+        }
+        return fallbackColor(color);
+    }
+    return fromCuloriOklch(clamped);
+};
+export const toGamutRgb = (color, target) => toTargetRgb(color, target);

package/dist/engine/gamut.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/engine/gamut.test.js

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+import { isInGamut, mapToGamut } from "./gamut.js";
+describe("gamut mapping", () => {
+    const outOfSrgbInP3 = { l: 60, c: 0.2, h: 40 };
+    it("detects out-of-gamut sRGB colors", () => {
+        expect(isInGamut(outOfSrgbInP3, "srgb")).toBe(false);
+        expect(isInGamut(outOfSrgbInP3, "p3")).toBe(true);
+    });
+    it("clips to sRGB gamut", () => {
+        const clipped = mapToGamut(outOfSrgbInP3, "srgb", "clip", false);
+        expect(isInGamut(clipped, "srgb")).toBe(true);
+    });
+    it("compresses chroma to sRGB gamut", () => {
+        const compressed = mapToGamut(outOfSrgbInP3, "srgb", "compressChroma", false);
+        expect(isInGamut(compressed, "srgb")).toBe(true);
+        expect(compressed.c).toBeLessThanOrEqual(outOfSrgbInP3.c);
+    });
+    it("keeps chroma when already in P3", () => {
+        const mapped = mapToGamut(outOfSrgbInP3, "p3", "preferP3ThenCompress", false);
+        expect(isInGamut(mapped, "p3")).toBe(true);
+        expect(mapped.c).toBeCloseTo(outOfSrgbInP3.c, 4);
+    });
+});

package/dist/engine/generateScale.d.ts

@@ -0,0 +1,15 @@
+import type { CurvePresetName } from "../presets/index.js";
+import type { SurfaceIntent } from "../types/index.js";
+export type OkLchColor = {
+    l: number;
+    c: number;
+    h: number;
+    alpha?: number;
+};
+type GenerateScaleOptions = {
+    context: "light" | "dark";
+    surface: SurfaceIntent;
+    preset?: CurvePresetName;
+};
+export declare function generateScale(seed: OkLchColor, options: GenerateScaleOptions): OkLchColor[];
+export {};

package/dist/engine/generateScale.js

@@ -0,0 +1,29 @@
+import { curvePresets } from "../presets/index.js";
+import { clamp } from "../utils/clamp.js";
+import { lerp } from "../utils/lerp.js";
+const STEPS = 12;
+const OKLCH_L_MIN = 0;
+const OKLCH_L_MAX = 100;
+export function generateScale(seed, options) {
+    const presetName = options.preset ?? "modern";
+    const preset = curvePresets[presetName];
+    const surfaceCurve = preset.surfaces[options.surface];
+    const range = surfaceCurve.ranges[options.context];
+    return Array.from({ length: STEPS }, (_, index) => {
+        const t = index / (STEPS - 1);
+        const lightnessT = surfaceCurve.l(t);
+        const chromaT = surfaceCurve.c(lightnessT);
+        const l = clamp(lerp(range.l[0], range.l[1], lightnessT), OKLCH_L_MIN, OKLCH_L_MAX);
+        // Allow select surfaces to exceed seed chroma slightly while staying within range caps.
+        const chromaBoost = range.chromaBoost ?? 1;
+        const boostedSeed = (seed.c ?? range.cMax) * chromaBoost;
+        const maxChroma = Math.min(range.cMax, Math.max(0, boostedSeed));
+        const c = clamp(lerp(range.cMin, maxChroma, chromaT), 0, range.cMax);
+        return {
+            l,
+            c,
+            h: seed.h,
+            alpha: seed.alpha,
+        };
+    });
+}

package/dist/engine/generateScale.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/engine/generateScale.test.js

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { generateScale } from "./generateScale.js";
+const seed = { l: 49.5, c: 0.19, h: 264.0 };
+const isMonotonic = (values) => values.every((value, index) => index === 0 || value >= values[index - 1] - 1e-6);
+describe("generateScale", () => {
+    it("returns 12 steps", () => {
+        const result = generateScale(seed, { context: "light", surface: "surface" });
+        expect(result).toHaveLength(12);
+    });
+    it("keeps lightness monotonic in light context", () => {
+        const result = generateScale(seed, { context: "light", surface: "surface" });
+        const lightness = result.map((step) => step.l);
+        expect(isMonotonic(lightness)).toBe(true);
+    });
+    it("keeps lightness monotonic in dark context", () => {
+        const result = generateScale(seed, { context: "dark", surface: "surface" });
+        const lightness = result.map((step) => step.l);
+        expect(isMonotonic(lightness)).toBe(true);
+    });
+    it("keeps hue constant across steps", () => {
+        const result = generateScale(seed, { context: "light", surface: "surface" });
+        result.forEach((step) => {
+            expect(step.h).toBeCloseTo(seed.h, 6);
+        });
+    });
+    it("never produces negative chroma", () => {
+        const result = generateScale(seed, { context: "light", surface: "surface" });
+        result.forEach((step) => {
+            expect(step.c).toBeGreaterThanOrEqual(0);
+        });
+    });
+});

package/dist/engine/index.d.ts

@@ -0,0 +1,8 @@
+export type { EngineContext } from "./context.js";
+export { mapColorContextToEngine } from "./context.js";
+export type { OkLchColor } from "./generateScale.js";
+export { generateScale } from "./generateScale.js";
+export type { NormalizedOnSolidQuery, NormalizedQuery } from "./normalize.js";
+export { normalizeOnSolidQuery, normalizeQuery } from "./normalize.js";
+export type { BaseResolvedColor, ThemeConfig } from "./resolveBaseColor.js";
+export { resolveBaseColor } from "./resolveBaseColor.js";

package/dist/engine/index.js

@@ -0,0 +1,4 @@
+export { mapColorContextToEngine } from "./context.js";
+export { generateScale } from "./generateScale.js";
+export { normalizeOnSolidQuery, normalizeQuery } from "./normalize.js";
+export { resolveBaseColor } from "./resolveBaseColor.js";

package/dist/engine/normalize.d.ts

@@ -0,0 +1,43 @@
+import type { ColorQuery, ColorState, OnSolidQuery, OutputOptions } from "../types/index.js";
+export type NormalizedQuery = Required<Pick<ColorQuery, "role" | "usage" | "context" | "surface" | "state" | "emphasis">> & {
+    variant?: ColorQuery["variant"];
+    on?: ColorQuery["on"];
+    contrast?: ColorQuery["contrast"];
+    alpha?: ColorQuery["alpha"];
+    output: Required<Omit<OutputOptions, "format">>;
+};
+export type NormalizedOnSolidQuery = Required<Pick<OnSolidQuery, "bgRole" | "usage" | "context" | "state" | "emphasis">> & {
+    alpha?: OnSolidQuery["alpha"];
+    contrast?: OnSolidQuery["contrast"];
+    output: Required<Omit<OutputOptions, "format">>;
+};
+export declare const COLOR_STATES: readonly ColorState[];
+/**
+ * Normalize a user-facing ColorQuery into a fully populated, validated structure.
+ *
+ * - Applies defaults for missing fields (context, surface, state, emphasis, output).
+ * - Infers usage and surface from role naming patterns when not provided.
+ * - In strict mode, missing required fields throw actionable errors.
+ * - In non-strict mode, safe defaults are applied with explicit warnings.
+ * - Validates nested objects (background hints, contrast requirements, alpha strategies).
+ * - Trims string inputs and enforces allowed enum values.
+ *
+ * @example
+ * normalizeQuery({ role: "text.primary" });
+ * @example
+ * normalizeQuery({
+ *   role: "bg.canvas",
+ *   on: { kind: "color", value: "#fff" },
+ *   contrast: { model: "apca", targetLc: 60 },
+ *   output: { strict: true },
+ * });
+ */
+export declare function normalizeQuery(q: ColorQuery): NormalizedQuery;
+/**
+ * Normalize a user-facing OnSolidQuery into a fully populated, validated structure.
+ *
+ * - Applies defaults for missing fields (context, state, emphasis, output).
+ * - Validates usage ("text" | "icon") and required background role.
+ * - Validates nested objects (contrast requirements, alpha strategies).
+ */
+export declare function normalizeOnSolidQuery(q: OnSolidQuery): NormalizedOnSolidQuery;

package/dist/engine/normalize.js

@@ -0,0 +1,403 @@
+const usages = ["bg", "border", "text", "icon", "ring", "shadow", "stroke", "fill"];
+const onSolidUsages = ["text", "icon"];
+const contexts = ["light", "dark", "highContrast", "dimmed"];
+const surfaces = [
+    "app",
+    "surface",
+    "subtle",
+    "solid",
+    "overlay",
+    "data",
+    "transparent",
+];
+export const COLOR_STATES = [
+    "default",
+    "hover",
+    "active",
+    "selected",
+    "focus",
+    "disabled",
+];
+const emphases = ["muted", "subtle", "default", "strong", "inverted"];
+const semanticVariants = [
+    "neutral",
+    "accent",
+    "success",
+    "warning",
+    "danger",
+    "info",
+    "highlight",
+    "premium",
+];
+const colorSpaces = ["srgb", "p3", "oklch"];
+const gamutMappings = [
+    "clip",
+    "compressChroma",
+    "preferP3ThenCompress",
+];
+const srgbFormats = ["hex", "rgb", "rgba"];
+const formatString = (value) => (value ? value.trim() : undefined);
+const assertOneOf = (value, options, label) => {
+    if (!options.includes(value)) {
+        throw new Error(`Invalid ${label}: "${value}"`);
+    }
+    return value;
+};
+const normalizeRole = (role) => {
+    if (role === undefined) {
+        throw new Error("Color role is required");
+    }
+    const trimmed = role.trim();
+    if (!trimmed) {
+        throw new Error("Color role is required");
+    }
+    return trimmed;
+};
+const normalizeBgRole = (role) => {
+    if (role === undefined) {
+        throw new Error("Background role (bgRole) is required");
+    }
+    const trimmed = role.trim();
+    if (!trimmed) {
+        throw new Error("Background role (bgRole) is required");
+    }
+    return trimmed;
+};
+const hexColorPattern = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+const inferUsageFromRole = (role) => {
+    const normalizedRole = role.trim().toLowerCase();
+    if (normalizedRole.startsWith("text.")) {
+        return "text";
+    }
+    if (normalizedRole.startsWith("icon.")) {
+        return "icon";
+    }
+    if (normalizedRole.startsWith("border.")) {
+        return "border";
+    }
+    if (normalizedRole.startsWith("bg.") ||
+        normalizedRole.startsWith("surface.") ||
+        normalizedRole.startsWith("overlay.")) {
+        return "bg";
+    }
+    if (normalizedRole.startsWith("focus.") || normalizedRole.startsWith("ring.")) {
+        return "ring";
+    }
+    if (normalizedRole.startsWith("chart.")) {
+        const tokens = normalizedRole.split(".");
+        if (tokens.includes("stroke")) {
+            return "stroke";
+        }
+        if (tokens.includes("fill")) {
+            return "fill";
+        }
+        if (tokens.includes("grid")) {
+            return "border";
+        }
+        if (tokens.includes("label") || tokens.includes("text")) {
+            return "text";
+        }
+    }
+    return undefined;
+};
+/**
+ * Infer surface intent from role naming patterns.
+ *
+ * Recognizes:
+ * - Direct surface token prefixes: `"app.*"`, `"surface.*"`, `"solid.*"`, etc.
+ * - Background patterns: `"bg.app"`, `"bg.surface"`, `"bg.solid"`, etc.
+ *
+ * @example
+ * inferSurfaceFromRole("bg.app") // "app"
+ * @example
+ * inferSurfaceFromRole("app.bg") // "app"
+ */
+const inferSurfaceFromRole = (role) => {
+    const normalizedRole = role.trim().toLowerCase();
+    const tokens = normalizedRole.split(".");
+    const [first, second] = tokens;
+    if (first && surfaces.includes(first)) {
+        return first;
+    }
+    if (first === "bg" && second && surfaces.includes(second)) {
+        return second;
+    }
+    return undefined;
+};
+/**
+ * Infer semantic variant from role token.
+ *
+ * Recognizes:
+ * - Semantic variants: `"neutral"`, `"accent"`, `"success"`, `"warning"`, etc.
+ * - Custom categories: `"category:*"`
+ * - Chart variants: `"chart:*"`
+ *
+ * @example
+ * inferVariantFromRole("success.bg") // "success"
+ * @example
+ * inferVariantFromRole("category:sales.fill") // "category:sales"
+ */
+const inferVariantFromRole = (role) => {
+    const token = role.trim().split(".")[0];
+    const normalized = token?.toLowerCase();
+    if (!normalized) {
+        return undefined;
+    }
+    if (semanticVariants.includes(normalized)) {
+        return normalized;
+    }
+    if (/^(category|chart):.+/.test(normalized)) {
+        return normalized;
+    }
+    return undefined;
+};
+const normalizeVariant = (variant) => {
+    if (!variant) {
+        return undefined;
+    }
+    const trimmed = variant.trim();
+    if (semanticVariants.includes(trimmed)) {
+        return trimmed;
+    }
+    if (/^(category|chart):.+/.test(trimmed)) {
+        return trimmed;
+    }
+    throw new Error(`Invalid variant: "${variant}"`);
+};
+const warn = (message) => {
+    console.warn(message);
+};
+/**
+ * Cache used to deduplicate inference warnings.
+ *
+ * Notes:
+ * - This is intentionally module-scoped so repeated calls don't spam logs.
+ * - To avoid unbounded growth in long-running processes, this cache is capped
+ *   and clears itself when the cap is reached.
+ */
+const inferenceWarnings = new Set();
+const MAX_INFERENCE_WARNINGS = 1000;
+const warnInferenceOnce = (key, message) => {
+    if (inferenceWarnings.has(key))
+        return;
+    if (inferenceWarnings.size >= MAX_INFERENCE_WARNINGS) {
+        inferenceWarnings.clear();
+    }
+    inferenceWarnings.add(key);
+    console.warn(message);
+};
+const missingUsageMessage = (role) => `Usage is required for role: "${role}". Provide usage explicitly (e.g. { usage: "text" }) or use a role prefix like "text.", "icon.", "bg.", "border.", "ring."`;
+const missingSurfaceMessage = (role) => `Surface is required for role: "${role}". Provide surface explicitly (e.g. { surface: "surface" }) or use a role pattern like "bg.app", "bg.surface", "app.*"`;
+const normalizeBackgroundHint = (hint, strict) => {
+    if (!hint) {
+        return undefined;
+    }
+    if (hint.kind === "auto") {
+        return hint;
+    }
+    if (hint.kind === "role") {
+        const trimmedRole = normalizeRole(hint.role);
+        return { kind: "role", role: trimmedRole };
+    }
+    if (hint.kind === "color") {
+        const value = hint.value.trim();
+        if (!value) {
+            throw new Error("Background hint color value is required");
+        }
+        if (!hexColorPattern.test(value)) {
+            if (strict) {
+                throw new Error(`Invalid background hint color value: "${hint.value}"`);
+            }
+            warn(`Unvalidated background hint color value: "${hint.value}"`);
+        }
+        return { kind: "color", value };
+    }
+    throw new Error(`Invalid background hint kind: "${hint.kind}"`);
+};
+const normalizeContrast = (contrast) => {
+    if (!contrast) {
+        return undefined;
+    }
+    if (contrast.model === "apca") {
+        if (!Number.isFinite(contrast.targetLc)) {
+            throw new Error("APCA targetLc must be a number");
+        }
+        if (contrast.minLc !== undefined && !Number.isFinite(contrast.minLc)) {
+            throw new Error("APCA minLc must be a number");
+        }
+        if (contrast.maxLc !== undefined && !Number.isFinite(contrast.maxLc)) {
+            throw new Error("APCA maxLc must be a number");
+        }
+        // Validate logical relationships between APCA contrast bounds
+        if (contrast.minLc !== undefined && contrast.maxLc !== undefined) {
+            if (contrast.minLc > contrast.maxLc) {
+                throw new Error("APCA minLc cannot be greater than maxLc");
+            }
+        }
+        if (contrast.minLc !== undefined && contrast.minLc > contrast.targetLc) {
+            throw new Error("APCA minLc cannot be greater than targetLc");
+        }
+        if (contrast.maxLc !== undefined && contrast.targetLc > contrast.maxLc) {
+            throw new Error("APCA targetLc cannot be greater than maxLc");
+        }
+        return contrast;
+    }
+    if (contrast.model === "wcag2") {
+        const minRatio = "minRatio" in contrast ? contrast.minRatio : contrast.ratio;
+        if (minRatio === undefined) {
+            throw new Error("WCAG2 contrast requires either 'minRatio' or legacy 'ratio' property");
+        }
+        if (!Number.isFinite(minRatio)) {
+            throw new Error("WCAG2 minRatio must be a number");
+        }
+        return { model: "wcag2", minRatio };
+    }
+    if (contrast.model === "none") {
+        return contrast;
+    }
+    throw new Error(`Invalid contrast model: "${contrast.model}"`);
+};
+const validateIncludeSpaces = (includeSpaces) => {
+    const value = includeSpaces ?? [];
+    value.forEach((space) => {
+        assertOneOf(space, colorSpaces, "output includeSpaces");
+    });
+    return value;
+};
+const normalizeAlpha = (alpha) => {
+    if (!alpha) {
+        return undefined;
+    }
+    if (alpha.mode === "none") {
+        return alpha;
+    }
+    if (alpha.mode === "fixed") {
+        if (!Number.isFinite(alpha.alpha)) {
+            throw new Error("Fixed alpha must be a number");
+        }
+        return alpha;
+    }
+    if (alpha.mode === "solveOnBackground") {
+        return alpha;
+    }
+    throw new Error(`Invalid alpha strategy mode: "${alpha.mode}"`);
+};
+const normalizeOutput = (output) => {
+    const preferSpaceValue = formatString(output?.preferSpace);
+    const gamutMappingValue = formatString(output?.gamutMapping);
+    const srgbFormatValue = formatString(output?.srgbFormat);
+    const includeSpaces = validateIncludeSpaces(output?.includeSpaces);
+    const preferSpace = preferSpaceValue
+        ? assertOneOf(preferSpaceValue, colorSpaces, "output preferSpace")
+        : "oklch";
+    const gamutMapping = gamutMappingValue
+        ? assertOneOf(gamutMappingValue, gamutMappings, "output gamutMapping")
+        : "preferP3ThenCompress";
+    const srgbFormat = srgbFormatValue
+        ? assertOneOf(srgbFormatValue, srgbFormats, "output srgbFormat")
+        : "hex";
+    if (output?.strict !== undefined && typeof output.strict !== "boolean") {
+        throw new Error("Output strict must be a boolean");
+    }
+    if (output?.includeMeta !== undefined && typeof output.includeMeta !== "boolean") {
+        throw new Error("Output includeMeta must be a boolean");
+    }
+    return {
+        preferSpace,
+        includeSpaces,
+        gamutMapping,
+        strict: output?.strict ?? false,
+        precision: {
+            l: 1,
+            c: 3,
+            h: 1,
+            ...output?.precision,
+        },
+        includeMeta: output?.includeMeta ?? false,
+        srgbFormat,
+    };
+};
+/**
+ * Normalize a user-facing ColorQuery into a fully populated, validated structure.
+ *
+ * - Applies defaults for missing fields (context, surface, state, emphasis, output).
+ * - Infers usage and surface from role naming patterns when not provided.
+ * - In strict mode, missing required fields throw actionable errors.
+ * - In non-strict mode, safe defaults are applied with explicit warnings.
+ * - Validates nested objects (background hints, contrast requirements, alpha strategies).
+ * - Trims string inputs and enforces allowed enum values.
+ *
+ * @example
+ * normalizeQuery({ role: "text.primary" });
+ * @example
+ * normalizeQuery({
+ *   role: "bg.canvas",
+ *   on: { kind: "color", value: "#fff" },
+ *   contrast: { model: "apca", targetLc: 60 },
+ *   output: { strict: true },
+ * });
+ */
+export function normalizeQuery(q) {
+    const role = normalizeRole(formatString(q.role));
+    const contextValue = formatString(q.context) ?? "light";
+    const inferredSurface = inferSurfaceFromRole(role);
+    const surfaceValue = formatString(q.surface) ?? inferredSurface ?? "surface";
+    const stateValue = formatString(q.state) ?? "default";
+    const emphasisValue = formatString(q.emphasis) ?? "default";
+    const output = normalizeOutput(q.output);
+    const usageValue = formatString(q.usage) ?? inferUsageFromRole(role);
+    const variantValue = formatString(q.variant) ?? inferVariantFromRole(role);
+    if (!usageValue) {
+        if (output.strict) {
+            throw new Error(missingUsageMessage(role));
+        }
+        warnInferenceOnce(`usage:${role}`, `Defaulting usage to "bg" for role: "${role}". ${missingUsageMessage(role)}`);
+    }
+    if (!formatString(q.surface) && !inferredSurface) {
+        if (output.strict) {
+            throw new Error(missingSurfaceMessage(role));
+        }
+        warnInferenceOnce(`surface:${role}`, `Defaulting surface to "surface" for role: "${role}". ${missingSurfaceMessage(role)}`);
+    }
+    return {
+        role,
+        usage: assertOneOf(usageValue ?? "bg", usages, "usage"),
+        context: assertOneOf(contextValue, contexts, "context"),
+        surface: assertOneOf(surfaceValue, surfaces, "surface"),
+        state: assertOneOf(stateValue, COLOR_STATES, "state"),
+        emphasis: assertOneOf(emphasisValue, emphases, "emphasis"),
+        variant: normalizeVariant(variantValue),
+        on: normalizeBackgroundHint(q.on, output.strict),
+        contrast: normalizeContrast(q.contrast),
+        alpha: normalizeAlpha(q.alpha),
+        output,
+    };
+}
+/**
+ * Normalize a user-facing OnSolidQuery into a fully populated, validated structure.
+ *
+ * - Applies defaults for missing fields (context, state, emphasis, output).
+ * - Validates usage ("text" | "icon") and required background role.
+ * - Validates nested objects (contrast requirements, alpha strategies).
+ */
+export function normalizeOnSolidQuery(q) {
+    const bgRole = normalizeBgRole(formatString(q.bgRole));
+    const usageValue = formatString(q.usage);
+    const contextValue = formatString(q.context) ?? "light";
+    const stateValue = formatString(q.state) ?? "default";
+    const emphasisValue = formatString(q.emphasis) ?? "default";
+    const output = normalizeOutput(q.output);
+    if (!usageValue) {
+        throw new Error("On-solid usage is required (text or icon)");
+    }
+    return {
+        bgRole,
+        usage: assertOneOf(usageValue, onSolidUsages, "onSolid usage"),
+        context: assertOneOf(contextValue, contexts, "context"),
+        state: assertOneOf(stateValue, COLOR_STATES, "state"),
+        emphasis: assertOneOf(emphasisValue, emphases, "emphasis"),
+        contrast: normalizeContrast(q.contrast),
+        alpha: normalizeAlpha(q.alpha),
+        output,
+    };
+}

package/dist/engine/normalize.test.d.ts

@@ -0,0 +1 @@
+export {};