@clhaas/palette-kit 0.1.7 → 0.3.0

package/dist/contrast/scoring.test.js

@@ -0,0 +1,148 @@
+import { describe, expect, it } from "vitest";
+import { scoreApca, scoreContrast } from "./scoring.js";
+describe("scoreApca", () => {
+    it("prefers values closer to target within range", () => {
+        const target = 60;
+        const min = 50;
+        const max = 80;
+        const hasMax = true;
+        expect(scoreApca(60, target, min, max, hasMax)).toBeGreaterThan(scoreApca(80, target, min, max, hasMax));
+    });
+    it("penalizes values outside the range", () => {
+        const target = 60;
+        const min = 50;
+        const max = 80;
+        const hasMax = true;
+        expect(scoreApca(40, target, min, max, hasMax)).toBeLessThan(0);
+        expect(scoreApca(90, target, min, max, hasMax)).toBeLessThan(0);
+    });
+    it("penalizes below min and prefers target when no max", () => {
+        const target = 60;
+        const min = 50;
+        const max = Number.POSITIVE_INFINITY;
+        const hasMax = false;
+        expect(scoreApca(40, target, min, max, hasMax)).toBeLessThan(scoreApca(55, target, min, max, hasMax));
+        expect(scoreApca(60, target, min, max, hasMax)).toBeGreaterThan(scoreApca(70, target, min, max, hasMax));
+    });
+    it("returns NEGATIVE_INFINITY for NaN values", () => {
+        const target = 60;
+        const min = 50;
+        const max = 80;
+        const hasMax = true;
+        expect(scoreApca(Number.NaN, target, min, max, hasMax)).toBe(Number.NEGATIVE_INFINITY);
+    });
+});
+describe("scoreContrast", () => {
+    describe("with APCA contrast model", () => {
+        it("delegates to scoreApca with correct parameters when maxLc is defined", () => {
+            const result = {
+                model: "apca",
+                target: 60,
+                value: 65,
+                pass: true,
+            };
+            const req = {
+                model: "apca",
+                targetLc: 60,
+                minLc: 50,
+                maxLc: 80,
+            };
+            const score = scoreContrast(result, req);
+            const expectedScore = scoreApca(65, 60, 50, 80, true);
+            expect(score).toBe(expectedScore);
+        });
+        it("delegates to scoreApca without max when maxLc is undefined", () => {
+            const result = {
+                model: "apca",
+                target: 60,
+                value: 65,
+                pass: true,
+            };
+            const req = {
+                model: "apca",
+                targetLc: 60,
+                minLc: 50,
+            };
+            const score = scoreContrast(result, req);
+            const expectedScore = scoreApca(65, 60, 50, Number.POSITIVE_INFINITY, false);
+            expect(score).toBe(expectedScore);
+        });
+        it("uses targetLc as min when minLc is undefined", () => {
+            const result = {
+                model: "apca",
+                target: 60,
+                value: 65,
+                pass: true,
+            };
+            const req = {
+                model: "apca",
+                targetLc: 60,
+            };
+            const score = scoreContrast(result, req);
+            const expectedScore = scoreApca(65, 60, 60, Number.POSITIVE_INFINITY, false);
+            expect(score).toBe(expectedScore);
+        });
+    });
+    describe("with WCAG2 contrast model", () => {
+        it("returns the raw contrast value", () => {
+            const result = {
+                model: "wcag2",
+                target: 4.5,
+                value: 7.2,
+                pass: true,
+            };
+            const req = {
+                model: "wcag2",
+                minRatio: 4.5,
+            };
+            const score = scoreContrast(result, req);
+            expect(score).toBe(7.2);
+        });
+    });
+    describe("with NaN or non-finite values", () => {
+        it("returns NEGATIVE_INFINITY for NaN", () => {
+            const result = {
+                model: "apca",
+                target: 60,
+                value: Number.NaN,
+                pass: false,
+            };
+            const req = {
+                model: "apca",
+                targetLc: 60,
+                minLc: 50,
+            };
+            const score = scoreContrast(result, req);
+            expect(score).toBe(Number.NEGATIVE_INFINITY);
+        });
+        it("returns NEGATIVE_INFINITY for positive infinity", () => {
+            const result = {
+                model: "apca",
+                target: 60,
+                value: Number.POSITIVE_INFINITY,
+                pass: false,
+            };
+            const req = {
+                model: "apca",
+                targetLc: 60,
+                minLc: 50,
+            };
+            const score = scoreContrast(result, req);
+            expect(score).toBe(Number.NEGATIVE_INFINITY);
+        });
+        it("returns NEGATIVE_INFINITY for negative infinity", () => {
+            const result = {
+                model: "wcag2",
+                target: 4.5,
+                value: Number.NEGATIVE_INFINITY,
+                pass: false,
+            };
+            const req = {
+                model: "wcag2",
+                minRatio: 4.5,
+            };
+            const score = scoreContrast(result, req);
+            expect(score).toBe(Number.NEGATIVE_INFINITY);
+        });
+    });
+});

package/dist/contrast/solver.d.ts

@@ -0,0 +1,13 @@
+import type { OkLchColor } from "../engine/generateScale.js";
+import type { CurvePresetName } from "../presets/index.js";
+import type { ContrastRequirement, SurfaceIntent } from "../types/index.js";
+import type { ContrastCheckResult, SolveOptions } from "./types.js";
+export declare function solveContrast(fg: OkLchColor, bg: OkLchColor | undefined, req: ContrastRequirement, ctx: {
+    preset?: CurvePresetName;
+    surface: SurfaceIntent;
+    context: "light" | "dark";
+}, opts?: SolveOptions): {
+    color: OkLchColor;
+    result: ContrastCheckResult;
+    iterations: number;
+};

package/dist/contrast/solver.js

@@ -0,0 +1,170 @@
+import { converter } from "culori";
+import { getSurfaceRange } from "../operators/utils.js";
+import { computeApcaLc } from "./apca.js";
+import { scoreContrast } from "./scoring.js";
+import { contrastRatio } from "./wcag2.js";
+const toSrgb = converter("rgb");
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+const clampOkLch = (color, cMax) => ({
+    l: clamp(color.l, 0, 100),
+    c: clamp(color.c, 0, cMax),
+    h: color.h,
+    alpha: color.alpha,
+});
+const clampOkLchLoose = (color) => ({
+    l: clamp(color.l, 0, 100),
+    c: Math.max(0, color.c),
+    h: color.h,
+    alpha: color.alpha,
+});
+const toSrgbColor = (color) => {
+    const rgb = toSrgb({ mode: "oklch", l: clamp(color.l, 0, 100) / 100, c: color.c, h: color.h });
+    if (!rgb) {
+        return null;
+    }
+    const r = typeof rgb.r === "number" && Number.isFinite(rgb.r) ? clamp(rgb.r, 0, 1) : 0;
+    const g = typeof rgb.g === "number" && Number.isFinite(rgb.g) ? clamp(rgb.g, 0, 1) : 0;
+    const b = typeof rgb.b === "number" && Number.isFinite(rgb.b) ? clamp(rgb.b, 0, 1) : 0;
+    return { r, g, b };
+};
+const getTarget = (req) => {
+    if (req.model === "apca") {
+        return req.targetLc;
+    }
+    if (req.model === "wcag2") {
+        return req.minRatio;
+    }
+    return 0;
+};
+const checkContrast = (fg, bg, req, epsilon) => {
+    if (req.model === "none") {
+        return { model: "none", target: 0, value: 0, pass: true };
+    }
+    const fgSrgb = toSrgbColor(fg);
+    const bgSrgb = toSrgbColor(bg);
+    const target = getTarget(req);
+    if (!fgSrgb || !bgSrgb) {
+        return { model: req.model, target, value: Number.NaN, pass: false };
+    }
+    if (req.model === "apca") {
+        const value = Math.abs(computeApcaLc(fgSrgb, bgSrgb));
+        const minTarget = req.minLc ?? req.targetLc;
+        const maxTarget = req.maxLc ?? Number.POSITIVE_INFINITY;
+        const pass = Number.isFinite(value) && value >= minTarget - epsilon && value <= maxTarget + epsilon;
+        return { model: "apca", target, value, pass };
+    }
+    const value = contrastRatio(fgSrgb, bgSrgb);
+    const pass = Number.isFinite(value) && value + epsilon >= target;
+    return { model: "wcag2", target, value, pass };
+};
+const pickBetter = (current, candidate, req) => {
+    const currentScore = scoreContrast(current.result, req);
+    const candidateScore = scoreContrast(candidate.result, req);
+    return candidateScore > currentScore ? candidate : current;
+};
+export function solveContrast(fg, bg, req, ctx, opts) {
+    const options = {
+        strict: false,
+        maxIterations: 24,
+        epsilon: 0.01,
+        ...opts,
+    };
+    if (req.model === "none") {
+        return {
+            color: fg,
+            result: { model: "none", target: 0, value: 0, pass: true },
+            iterations: 0,
+        };
+    }
+    if (!bg) {
+        if (options.strict) {
+            throw new Error("Contrast solver requires background");
+        }
+        return {
+            color: fg,
+            result: { model: req.model, target: getTarget(req), value: Number.NaN, pass: false },
+            iterations: 0,
+        };
+    }
+    const range = getSurfaceRange(ctx.preset, ctx.surface, ctx.context);
+    const clamped = clampOkLch(fg, range.cMax);
+    const background = clampOkLchLoose(bg);
+    let iterations = 0;
+    const evaluate = (color) => {
+        const result = checkContrast(color, background, req, options.epsilon);
+        iterations += 1;
+        return result;
+    };
+    let best = { color: clamped, result: evaluate(clamped) };
+    if (best.result.pass) {
+        return { ...best, iterations };
+    }
+    const lMin = 0;
+    const lMax = 100;
+    const sampleT = 0.25;
+    const sampleDown = clamp(clamped.l + (lMin - clamped.l) * sampleT, lMin, lMax);
+    const sampleUp = clamp(clamped.l + (lMax - clamped.l) * sampleT, lMin, lMax);
+    let preferredBound = lMin;
+    if (iterations < options.maxIterations) {
+        const downCandidate = {
+            color: { ...clamped, l: sampleDown },
+            result: evaluate({ ...clamped, l: sampleDown }),
+        };
+        best = pickBetter(best, downCandidate, req);
+        if (best.result.pass) {
+            return { ...best, iterations };
+        }
+        if (iterations < options.maxIterations) {
+            const upCandidate = {
+                color: { ...clamped, l: sampleUp },
+                result: evaluate({ ...clamped, l: sampleUp }),
+            };
+            best = pickBetter(best, upCandidate, req);
+            if (best.result.pass) {
+                return { ...best, iterations };
+            }
+            preferredBound =
+                scoreContrast(upCandidate.result, req) > scoreContrast(downCandidate.result, req)
+                    ? lMax
+                    : lMin;
+        }
+    }
+    const remainingAfterSamples = Math.max(0, options.maxIterations - iterations);
+    const lSteps = Math.max(4, remainingAfterSamples);
+    for (let step = 1; step <= lSteps && iterations < options.maxIterations; step += 1) {
+        const t = step / lSteps;
+        const l = clamp(clamped.l + (preferredBound - clamped.l) * t, lMin, lMax);
+        const candidateColor = { ...clamped, l };
+        const result = evaluate(candidateColor);
+        const candidate = { color: candidateColor, result };
+        best = pickBetter(best, candidate, req);
+        if (result.pass) {
+            return { color: candidateColor, result, iterations };
+        }
+    }
+    let current = { ...best.color };
+    while (iterations < options.maxIterations && current.c > 0) {
+        const nextC = clamp(current.c * 0.9, 0, range.cMax);
+        current = { ...current, c: nextC };
+        const result = evaluate(current);
+        best = pickBetter(best, { color: current, result }, req);
+        if (result.pass) {
+            return { color: current, result, iterations };
+        }
+        const sweepSteps = Math.min(3, options.maxIterations - iterations);
+        for (let step = 1; step <= sweepSteps && iterations < options.maxIterations; step += 1) {
+            const t = step / sweepSteps;
+            const l = clamp(current.l + (preferredBound - current.l) * t, lMin, lMax);
+            const candidateColor = { ...current, l };
+            const candidateResult = evaluate(candidateColor);
+            best = pickBetter(best, { color: candidateColor, result: candidateResult }, req);
+            if (candidateResult.pass) {
+                return { color: candidateColor, result: candidateResult, iterations };
+            }
+        }
+    }
+    if (options.strict) {
+        throw new Error(`Contrast solver failed (${best.result.model}) target=${best.result.target} value=${best.result.value} iterations=${iterations}`);
+    }
+    return { color: best.color, result: best.result, iterations };
+}

package/dist/contrast/solver.test.d.ts

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

package/dist/contrast/solver.test.js

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+import { parseColor } from "../utils/parseColor.js";
+import { solveContrast } from "./solver.js";
+const toOkLch = (hex) => {
+    const parsed = parseColor(hex);
+    return {
+        l: parsed.okLch.channels[0] * 100,
+        c: parsed.okLch.channels[1],
+        h: parsed.okLch.channels[2],
+        alpha: parsed.okLch.alpha,
+    };
+};
+describe("solveContrast", () => {
+    it("raises contrast on light backgrounds", () => {
+        const fg = toOkLch("#777777");
+        const bg = toOkLch("#ffffff");
+        const result = solveContrast(fg, bg, { model: "wcag2", minRatio: 4.5 }, { surface: "surface", context: "light" });
+        expect(result.result.pass).toBe(true);
+        expect(result.result.value).toBeGreaterThanOrEqual(4.5);
+        expect(result.color.l).toBeGreaterThanOrEqual(0);
+        expect(result.color.l).toBeLessThanOrEqual(100);
+        expect(result.color.c).toBeGreaterThanOrEqual(0);
+    });
+    it("returns original color when contrast model is none", () => {
+        const fg = toOkLch("#777777");
+        const bg = toOkLch("#ffffff");
+        const result = solveContrast(fg, bg, { model: "none" }, { surface: "surface", context: "light" });
+        expect(result.result.pass).toBe(true);
+        expect(result.iterations).toBe(0);
+        expect(result.color).toEqual(fg);
+    });
+    it("skips when background is missing and strict is false", () => {
+        const fg = toOkLch("#777777");
+        const result = solveContrast(fg, undefined, { model: "wcag2", minRatio: 4.5 }, { surface: "surface", context: "light" }, { strict: false });
+        expect(result.result.pass).toBe(false);
+        expect(Number.isNaN(result.result.value)).toBe(true);
+    });
+    it("throws when background is missing and strict is true", () => {
+        const fg = toOkLch("#777777");
+        expect(() => solveContrast(fg, undefined, { model: "wcag2", minRatio: 4.5 }, { surface: "surface", context: "light" }, { strict: true })).toThrowError(/requires background/i);
+    });
+    it("raises contrast on dark backgrounds", () => {
+        const fg = toOkLch("#777777");
+        const bg = toOkLch("#111111");
+        const result = solveContrast(fg, bg, { model: "wcag2", minRatio: 4.5 }, { surface: "surface", context: "dark" });
+        expect(result.result.pass).toBe(true);
+        expect(result.result.value).toBeGreaterThanOrEqual(4.5);
+    });
+    it("keeps hue stable", () => {
+        const fg = toOkLch("#3366ff");
+        const bg = toOkLch("#ffffff");
+        const result = solveContrast(fg, bg, { model: "wcag2", minRatio: 4.5 }, { surface: "surface", context: "light" });
+        expect(result.color.h).toBeCloseTo(fg.h, 6);
+    });
+    it("throws in strict mode when target is unattainable", () => {
+        const fg = toOkLch("#ffffff");
+        const bg = toOkLch("#ffffff");
+        expect(() => solveContrast(fg, bg, { model: "wcag2", minRatio: 30 }, { surface: "surface", context: "light" }, { strict: true })).toThrowError(/contrast solver failed/i);
+    });
+    it("prefers APCA values closer to target within the allowed range", () => {
+        const fg = toOkLch("#777777");
+        const bg = toOkLch("#ffffff");
+        const minLc = 50;
+        const maxLc = 80;
+        const targetLc = 60;
+        const result = solveContrast(fg, bg, { model: "apca", targetLc, minLc, maxLc }, { surface: "surface", context: "light" });
+        const value = result.result.value;
+        const targetDistance = Math.abs(value - targetLc);
+        const maxDistance = Math.abs(maxLc - targetLc);
+        expect(result.result.pass).toBe(true);
+        expect(value).toBeGreaterThanOrEqual(minLc);
+        expect(value).toBeLessThanOrEqual(maxLc);
+        expect(targetDistance).toBeLessThanOrEqual(maxDistance);
+    });
+});

package/dist/contrast/types.d.ts

@@ -0,0 +1,17 @@
+export type ContrastModel = "apca" | "wcag2" | "none";
+export type ContrastCheckResult = {
+    model: ContrastModel;
+    target: number;
+    value: number;
+    pass: boolean;
+};
+export type SolveOptions = {
+    strict?: boolean;
+    maxIterations?: number;
+    epsilon?: number;
+};
+export type SrgbColor = {
+    r: number;
+    g: number;
+    b: number;
+};

package/dist/contrast/types.js

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

package/dist/contrast/utils.d.ts

@@ -0,0 +1,4 @@
+import type { OkLchColor } from "../engine/generateScale.js";
+import type { SrgbColor } from "./types.js";
+export declare const toSrgbColor: (color: OkLchColor) => SrgbColor | null;
+export declare const blendSrgb: (fg: SrgbColor, bg: SrgbColor, alpha: number) => SrgbColor;

package/dist/contrast/utils.js

@@ -0,0 +1,18 @@
+import { converter } from "culori";
+const toSrgb = converter("rgb");
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+export const toSrgbColor = (color) => {
+    const rgb = toSrgb({ mode: "oklch", l: clamp(color.l, 0, 100) / 100, c: color.c, h: color.h });
+    if (!rgb) {
+        return null;
+    }
+    const r = typeof rgb.r === "number" && Number.isFinite(rgb.r) ? clamp(rgb.r, 0, 1) : 0;
+    const g = typeof rgb.g === "number" && Number.isFinite(rgb.g) ? clamp(rgb.g, 0, 1) : 0;
+    const b = typeof rgb.b === "number" && Number.isFinite(rgb.b) ? clamp(rgb.b, 0, 1) : 0;
+    return { r, g, b };
+};
+export const blendSrgb = (fg, bg, alpha) => ({
+    r: fg.r * alpha + bg.r * (1 - alpha),
+    g: fg.g * alpha + bg.g * (1 - alpha),
+    b: fg.b * alpha + bg.b * (1 - alpha),
+});

package/dist/contrast/wcag2.d.ts

@@ -0,0 +1,3 @@
+import type { SrgbColor } from "./types.js";
+export declare const relativeLuminance: (color: SrgbColor) => number;
+export declare const contrastRatio: (fg: SrgbColor, bg: SrgbColor) => number;

package/dist/contrast/wcag2.js

@@ -0,0 +1,19 @@
+const clamp01 = (value) => Math.min(1, Math.max(0, value));
+const toLinear = (channel) => {
+    const value = clamp01(channel);
+    return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+};
+export const relativeLuminance = (color) => {
+    const r = toLinear(color.r);
+    const g = toLinear(color.g);
+    const b = toLinear(color.b);
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+};
+export const contrastRatio = (fg, bg) => {
+    const fgLum = relativeLuminance(fg);
+    const bgLum = relativeLuminance(bg);
+    const lighter = Math.max(fgLum, bgLum);
+    const darker = Math.min(fgLum, bgLum);
+    const ratio = (lighter + 0.05) / (darker + 0.05);
+    return Number.isFinite(ratio) ? ratio : Number.NaN;
+};

package/dist/contrast/wcag2.test.d.ts

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

package/dist/contrast/wcag2.test.js

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+import { contrastRatio } from "./wcag2.js";
+describe("wcag2 contrastRatio", () => {
+    it("returns high contrast for black on white", () => {
+        const ratio = contrastRatio({ r: 0, g: 0, b: 0 }, { r: 1, g: 1, b: 1 });
+        expect(ratio).toBeGreaterThan(10);
+    });
+    it("returns lower contrast for mid gray on white", () => {
+        const gray = 0x77 / 255;
+        const ratio = contrastRatio({ r: gray, g: gray, b: gray }, { r: 1, g: 1, b: 1 });
+        expect(ratio).toBeLessThan(4.5);
+    });
+    it("does not return NaN", () => {
+        const ratio = contrastRatio({ r: 0.2, g: 0.4, b: 0.6 }, { r: 0.8, g: 0.7, b: 0.1 });
+        expect(Number.isNaN(ratio)).toBe(false);
+    });
+});

package/dist/core/createTheme.d.ts

@@ -0,0 +1,35 @@
+import type { BaseResolvedColor, ThemeConfig } from "../engine/resolveBaseColor.js";
+import type { ColorContext, ColorQuery, ColorRole, OnSolidQuery, OutputOptions, ResolvedColor } from "../types/index.js";
+export type PaletteTheme = {
+    /**
+     * Resolve a single color query to the core OKLCH output shape.
+     */
+    resolve: (query: ColorQuery) => BaseResolvedColor;
+    /**
+     * Resolve a batch of color queries while preserving input order.
+     */
+    resolveMany: (queries: ColorQuery[]) => BaseResolvedColor[];
+    /**
+     * Resolve a color role with inference and DX validation.
+     *
+     * Inference and strict/non-strict behavior is shared with `theme.resolve(...)` and is
+     * implemented inside query normalization.
+     *
+     * When `output.strict` is true, missing inference throws an error; otherwise
+     * safe defaults are used.
+     */
+    color: (role: ColorRole, options?: Omit<ColorQuery, "role">) => BaseResolvedColor;
+    /**
+     * Resolve a foreground color against a solid background (APCA/WCAG aware).
+     */
+    onSolid: (query: OnSolidQuery) => BaseResolvedColor;
+    /**
+     * Serialize a resolved color query for external outputs (CSS, RN, JSON, etc.).
+     */
+    serialize: (query: ColorQuery, options?: OutputOptions) => ResolvedColor;
+    /**
+     * Return a new theme instance with a bound context.
+     */
+    withContext: (context: ColorContext) => PaletteTheme;
+};
+export declare function createTheme(config: ThemeConfig): PaletteTheme;

package/dist/core/createTheme.js

@@ -0,0 +1,24 @@
+import { onSolid } from "../engine/onSolid.js";
+import { serializeResolved } from "../serialize/serializeColor.js";
+import { resolve } from "./resolve.js";
+import { resolveMany } from "./resolveMany.js";
+export function createTheme(config) {
+    const themeConfig = {
+        ...config,
+        preset: config.preset ?? "modern",
+        variants: config.variants ?? {},
+    };
+    const applyBoundContext = (query, boundContext) => (boundContext ? { context: boundContext, ...query } : query);
+    const buildTheme = (boundContext) => ({
+        resolve: (query) => resolve(applyBoundContext(query, boundContext), themeConfig),
+        resolveMany: (queries) => resolveMany(queries.map((query) => applyBoundContext(query, boundContext)), themeConfig),
+        color: (role, options) => resolve(applyBoundContext({ role, ...(options ?? {}) }, boundContext), themeConfig),
+        onSolid: (query) => onSolid(applyBoundContext(query, boundContext), themeConfig),
+        serialize: (query, options) => {
+            const resolved = resolve(applyBoundContext(query, boundContext), themeConfig);
+            return serializeResolved(resolved, options);
+        },
+        withContext: (context) => buildTheme(context),
+    });
+    return buildTheme();
+}

package/dist/core/dx-helpers.test.d.ts

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

package/dist/core/dx-helpers.test.js

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import { createTheme } from "./createTheme.js";
+describe("Phase 2 helpers", () => {
+    const theme = createTheme({
+        seeds: {
+            light: { neutral: "#8B8D98", accent: "#3D63DD" },
+            dark: { neutral: "#8B8D98", accent: "#3D63DD" },
+        },
+        preset: "modern",
+    });
+    it("resolveMany preserves input order", () => {
+        const queries = [
+            { role: "bg.app", usage: "bg", surface: "app", context: "light" },
+            { role: "text.primary", usage: "text", surface: "surface", context: "light" },
+        ];
+        const expected = queries.map((query) => theme.resolve(query));
+        const results = theme.resolveMany(queries);
+        expect(results.map((result) => result.step)).toEqual(expected.map((result) => result.step));
+        expect(results.map((result) => result.seedUsed)).toEqual(expected.map((result) => result.seedUsed));
+    });
+    it("withContext applies bound context and allows overrides", () => {
+        const darkTheme = theme.withContext("dark");
+        const bound = darkTheme.resolve({ role: "bg.app", usage: "bg", surface: "app" });
+        const explicit = {
+            role: "bg.app",
+            usage: "bg",
+            surface: "app",
+            context: "dark",
+        };
+        const explicitResolved = theme.resolve(explicit);
+        expect(bound.step).toBe(explicitResolved.step);
+        const override = darkTheme.resolve({
+            role: "bg.app",
+            usage: "bg",
+            surface: "app",
+            context: "light",
+        });
+        const light = {
+            role: "bg.app",
+            usage: "bg",
+            surface: "app",
+            context: "light",
+        };
+        const lightResolved = theme.resolve(light);
+        expect(override.step).toBe(lightResolved.step);
+    });
+    it("theme.color infers usage and surface from role", () => {
+        const inferred = theme.color("bg.app");
+        const explicit = theme.resolve({ role: "bg.app", usage: "bg", surface: "app" });
+        expect(inferred.step).toBe(explicit.step);
+        expect(inferred.seedUsed).toBe(explicit.seedUsed);
+    });
+    it("theme.color throws in strict mode when inference is missing", () => {
+        expect(() => theme.color("custom.role", {
+            output: { strict: true },
+        })).toThrow(/Usage is required for role/i);
+        expect(() => theme.color("text.custom", {
+            output: { strict: true },
+        })).toThrow(/Surface is required for role/i);
+    });
+});

package/dist/core/index.d.ts

@@ -0,0 +1,2 @@
+export { createTheme } from "./createTheme.js";
+export { resolveToken, resolveTokenRegistry, validateTokenDefinition, validateTokenRegistry, } from "./tokenRegistry.js";

package/dist/core/index.js

@@ -0,0 +1,2 @@
+export { createTheme } from "./createTheme.js";
+export { resolveToken, resolveTokenRegistry, validateTokenDefinition, validateTokenRegistry, } from "./tokenRegistry.js";

package/dist/core/onSolid.test.d.ts

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