@clhaas/palette-kit 0.3.0 → 0.4.0

package/dist/presets/presets.js

@@ -0,0 +1,308 @@
+import { defaultLevelCurves, } from '../engine/level/curves.js';
+import { assertLevel, LEVELS } from '../engine/level/level.js';
+import { defaultStateDeltas, } from '../engine/state/state.js';
+export const RESOLVER_PRESETS = Object.freeze([
+    'soft',
+    'neutral',
+    'strong',
+]);
+const DEFAULT_CONTRAST_TARGET = 60;
+const DEFAULT_MAX_LUMINANCE_SHIFT = 60;
+const DEFAULT_CHROMA_MAX_REDUCTION = 1;
+const DEFAULT_CHROMA_REDUCTION_STEP = 0.01;
+const presetList = RESOLVER_PRESETS.join(', ');
+const formatInvalidResolverPresetError = (value) => `Unknown resolver preset "${String(value)}". Expected one of: ${presetList}.`;
+const assertFiniteConfigNumber = (name, value) => {
+    if (!Number.isFinite(value)) {
+        throw new Error(`${name} must be a finite number.`);
+    }
+};
+const assertNonNegativeConfigNumber = (name, value) => {
+    assertFiniteConfigNumber(name, value);
+    if (value < 0) {
+        throw new Error(`${name} must be greater than or equal to 0.`);
+    }
+};
+const resolveContextualLightness = (lightness, context) => context === 'dark' ? 100 - lightness : lightness;
+const createNumberLevelCurve = (targets) => Object.freeze((level, context) => {
+    assertLevel(level);
+    return resolveContextualLightness(targets[level], context);
+});
+const createOverlayLevelCurve = (targets) => Object.freeze((level, _context) => {
+    assertLevel(level);
+    return targets[level];
+});
+const createLevelCurveConfig = (fillTargets, linesTargets, overlayTargets) => Object.freeze({
+    fill: createNumberLevelCurve(fillTargets),
+    lines: createNumberLevelCurve(linesTargets),
+    overlays: createOverlayLevelCurve(overlayTargets),
+});
+const createAlphaTable = (values) => Object.freeze(LEVELS.reduce((table, level) => {
+    const value = values[level];
+    assertNonNegativeConfigNumber(`relation alpha level ${level}`, value);
+    table[level] = value;
+    return table;
+}, {}));
+const mergeAlphaTable = (base, override) => createAlphaTable(LEVELS.reduce((table, level) => {
+    table[level] = override?.[level] ?? base[level];
+    return table;
+}, {}));
+const mergeStateDeltaTable = (base, override) => {
+    const table = {
+        active: override?.active ?? base.active,
+        default: override?.default ?? base.default,
+        disabled: override?.disabled ?? base.disabled,
+        focus: override?.focus ?? base.focus,
+        hover: override?.hover ?? base.hover,
+        selected: override?.selected ?? base.selected,
+    };
+    for (const [state, value] of Object.entries(table)) {
+        assertNonNegativeConfigNumber(`stateDeltas.${state}`, value);
+    }
+    return Object.freeze(table);
+};
+const createRelationParamsConfig = (params) => {
+    assertNonNegativeConfigNumber('relationParams.on.contrastTarget', params.on.contrastTarget);
+    assertNonNegativeConfigNumber('relationParams.on.maxLuminanceShift', params.on.maxLuminanceShift);
+    assertNonNegativeConfigNumber('relationParams.under.luminanceReduction', params.under.luminanceReduction);
+    return Object.freeze({
+        on: Object.freeze({ ...params.on }),
+        over: Object.freeze({
+            baseAlphaByLevel: createAlphaTable(params.over.baseAlphaByLevel),
+        }),
+        under: Object.freeze({
+            baseAlphaByLevel: createAlphaTable(params.under.baseAlphaByLevel),
+            luminanceReduction: params.under.luminanceReduction,
+        }),
+    });
+};
+const createChromaConfig = (config) => {
+    assertNonNegativeConfigNumber('chromaLimits.maxReduction', config.maxReduction);
+    assertNonNegativeConfigNumber('chromaLimits.reductionStep', config.reductionStep);
+    if (config.reductionStep === 0) {
+        throw new Error('chromaLimits.reductionStep must be greater than 0.');
+    }
+    return Object.freeze({ ...config });
+};
+const baseRelationParams = createRelationParamsConfig({
+    on: {
+        contrastTarget: DEFAULT_CONTRAST_TARGET,
+        maxLuminanceShift: DEFAULT_MAX_LUMINANCE_SHIFT,
+    },
+    over: {
+        baseAlphaByLevel: createAlphaTable({
+            1: 0.04,
+            2: 0.08,
+            3: 0.12,
+            4: 0.18,
+            5: 0.24,
+            6: 0.3,
+            7: 0.36,
+            8: 0.42,
+            9: 0.5,
+        }),
+    },
+    under: {
+        baseAlphaByLevel: createAlphaTable({
+            1: 0.06,
+            2: 0.1,
+            3: 0.16,
+            4: 0.22,
+            5: 0.3,
+            6: 0.38,
+            7: 0.46,
+            8: 0.54,
+            9: 0.62,
+        }),
+        luminanceReduction: 8,
+    },
+});
+const baseChromaLimits = createChromaConfig({
+    maxReduction: DEFAULT_CHROMA_MAX_REDUCTION,
+    reductionStep: DEFAULT_CHROMA_REDUCTION_STEP,
+});
+const softFillLevelTargets = Object.freeze({
+    1: 98,
+    2: 97,
+    3: 96,
+    4: 94,
+    5: 92,
+    6: 89,
+    7: 86,
+    8: 82,
+    9: 78,
+});
+const softLinesLevelTargets = Object.freeze({
+    1: 96,
+    2: 95,
+    3: 94,
+    4: 93,
+    5: 92,
+    6: 91,
+    7: 90,
+    8: 89,
+    9: 88,
+});
+const softOverlayLevelTargets = Object.freeze({
+    1: Object.freeze({ luminanceDelta: 0.5 }),
+    2: Object.freeze({ luminanceDelta: 1 }),
+    3: Object.freeze({ luminanceDelta: 1.5 }),
+    4: Object.freeze({ luminanceDelta: 2 }),
+    5: Object.freeze({ luminanceDelta: 2.5 }),
+    6: Object.freeze({ luminanceDelta: 3 }),
+    7: Object.freeze({ luminanceDelta: 3.5 }),
+    8: Object.freeze({ luminanceDelta: 4 }),
+    9: Object.freeze({ luminanceDelta: 4.5 }),
+});
+const strongFillLevelTargets = Object.freeze({
+    1: 99,
+    2: 96,
+    3: 92,
+    4: 87,
+    5: 81,
+    6: 74,
+    7: 66,
+    8: 57,
+    9: 47,
+});
+const strongLinesLevelTargets = Object.freeze({
+    1: 97,
+    2: 95,
+    3: 92,
+    4: 89,
+    5: 85,
+    6: 81,
+    7: 76,
+    8: 70,
+    9: 64,
+});
+const strongOverlayLevelTargets = Object.freeze({
+    1: Object.freeze({ luminanceDelta: 2 }),
+    2: Object.freeze({ luminanceDelta: 4 }),
+    3: Object.freeze({ luminanceDelta: 6 }),
+    4: Object.freeze({ luminanceDelta: 8 }),
+    5: Object.freeze({ luminanceDelta: 10 }),
+    6: Object.freeze({ luminanceDelta: 12 }),
+    7: Object.freeze({ luminanceDelta: 14 }),
+    8: Object.freeze({ luminanceDelta: 16 }),
+    9: Object.freeze({ luminanceDelta: 18 }),
+});
+const softStateDeltas = Object.freeze({
+    alpha: Object.freeze({
+        active: 0,
+        default: 0,
+        disabled: 0,
+        focus: 0,
+        hover: 0,
+        selected: 0,
+    }),
+    luminance: Object.freeze({
+        active: 4,
+        default: 0,
+        disabled: 6,
+        focus: 3,
+        hover: 2,
+        selected: 3,
+    }),
+});
+const strongStateDeltas = Object.freeze({
+    alpha: Object.freeze({
+        active: 0,
+        default: 0,
+        disabled: 0,
+        focus: 0,
+        hover: 0,
+        selected: 0,
+    }),
+    luminance: Object.freeze({
+        active: 8,
+        default: 0,
+        disabled: 14,
+        focus: 5,
+        hover: 4,
+        selected: 7,
+    }),
+});
+const createResolverConfig = (config) => Object.freeze({
+    chromaLimits: createChromaConfig(config.chromaLimits),
+    levelCurves: Object.freeze({ ...config.levelCurves }),
+    relationParams: createRelationParamsConfig(config.relationParams),
+    stateDeltas: Object.freeze({
+        alpha: mergeStateDeltaTable(config.stateDeltas.alpha, undefined),
+        luminance: mergeStateDeltaTable(config.stateDeltas.luminance, undefined),
+    }),
+});
+export const softResolverConfig = createResolverConfig({
+    chromaLimits: baseChromaLimits,
+    levelCurves: createLevelCurveConfig(softFillLevelTargets, softLinesLevelTargets, softOverlayLevelTargets),
+    relationParams: baseRelationParams,
+    stateDeltas: softStateDeltas,
+});
+export const neutralResolverConfig = createResolverConfig({
+    chromaLimits: baseChromaLimits,
+    levelCurves: defaultLevelCurves,
+    relationParams: baseRelationParams,
+    stateDeltas: defaultStateDeltas,
+});
+export const strongResolverConfig = createResolverConfig({
+    chromaLimits: baseChromaLimits,
+    levelCurves: createLevelCurveConfig(strongFillLevelTargets, strongLinesLevelTargets, strongOverlayLevelTargets),
+    relationParams: baseRelationParams,
+    stateDeltas: strongStateDeltas,
+});
+export const defaultResolverConfig = neutralResolverConfig;
+export const resolverPresetConfigs = Object.freeze({
+    neutral: neutralResolverConfig,
+    soft: softResolverConfig,
+    strong: strongResolverConfig,
+});
+export function isResolverPresetName(value) {
+    return (typeof value === 'string' &&
+        RESOLVER_PRESETS.includes(value));
+}
+export function assertResolverPresetName(value) {
+    if (!isResolverPresetName(value)) {
+        throw new Error(formatInvalidResolverPresetError(value));
+    }
+}
+export function getResolverPresetConfig(preset) {
+    assertResolverPresetName(preset);
+    return resolverPresetConfigs[preset];
+}
+export function mergeResolverConfig(base, overrides) {
+    if (overrides === undefined) {
+        return base;
+    }
+    return createResolverConfig({
+        chromaLimits: {
+            maxReduction: overrides.chromaLimits?.maxReduction ?? base.chromaLimits.maxReduction,
+            reductionStep: overrides.chromaLimits?.reductionStep ??
+                base.chromaLimits.reductionStep,
+        },
+        levelCurves: {
+            fill: overrides.levelCurves?.fill ?? base.levelCurves.fill,
+            lines: overrides.levelCurves?.lines ?? base.levelCurves.lines,
+            overlays: overrides.levelCurves?.overlays ?? base.levelCurves.overlays,
+        },
+        relationParams: {
+            on: {
+                contrastTarget: overrides.relationParams?.on?.contrastTarget ??
+                    base.relationParams.on.contrastTarget,
+                maxLuminanceShift: overrides.relationParams?.on?.maxLuminanceShift ??
+                    base.relationParams.on.maxLuminanceShift,
+            },
+            over: {
+                baseAlphaByLevel: mergeAlphaTable(base.relationParams.over.baseAlphaByLevel, overrides.relationParams?.over?.baseAlphaByLevel),
+            },
+            under: {
+                baseAlphaByLevel: mergeAlphaTable(base.relationParams.under.baseAlphaByLevel, overrides.relationParams?.under?.baseAlphaByLevel),
+                luminanceReduction: overrides.relationParams?.under?.luminanceReduction ??
+                    base.relationParams.under.luminanceReduction,
+            },
+        },
+        stateDeltas: {
+            alpha: mergeStateDeltaTable(base.stateDeltas.alpha, overrides.stateDeltas?.alpha),
+            luminance: mergeStateDeltaTable(base.stateDeltas.luminance, overrides.stateDeltas?.luminance),
+        },
+    });
+}

package/dist/types/index.d.ts

@@ -1,187 +1,111 @@
-export type CssColorString = string;
-export type ColorSpace = "srgb" | "p3" | "oklch";
-export type ColorContext = "light" | "dark" | "highContrast" | "dimmed";
-export type SurfaceIntent = "app" | "surface" | "subtle" | "solid" | "overlay" | "data" | "transparent";
-export type ColorState = "default" | "hover" | "active" | "selected" | "focus" | "disabled";
-export type ColorEmphasis = "muted" | "subtle" | "default" | "strong" | "inverted";
-export type SemanticVariant = "neutral" | "accent" | "success" | "warning" | "danger" | "info" | "highlight" | "premium" | `category:${string}` | `chart:${string}`;
-export type ColorRole = string;
-export type ColorUsage = "bg" | "border" | "text" | "icon" | "ring" | "shadow" | "stroke" | "fill";
-/**
- * Token-safe background hints.
- * Tokens must not embed literal colors.
- */
-export type TokenBackgroundHint = {
-    kind: "auto";
-} | {
-    kind: "role";
-    role: ColorRole;
-};
-/**
- * Token-safe query shape (Phase 3).
- * - `output` is forbidden (export/serializer concern)
- * - `on.kind: "color"` is forbidden (no embedded colors)
- * - `state` must not be encoded (states are operators; declare via TokenDefinition.states)
- */
-export type TokenQuery = Omit<ColorQuery, "output" | "on" | "state"> & {
-    output?: never;
-    on?: TokenBackgroundHint;
-    state?: never;
-};
-/**
- * Token-supported interactive states.
- *
- * Note: `"default"` is the base token, so it is intentionally excluded here.
- */
-export type TokenState = Exclude<ColorState, "default">;
-/**
- * Declarative set of supported states for a token.
- * Use `true` to mark a state as supported.
- */
-export type TokenStates = Partial<Record<TokenState, true>>;
-export type BackgroundHint = {
-    kind: "auto";
-} | {
-    kind: "role";
-    role: ColorRole;
-} | {
-    kind: "color";
-    value: CssColorString;
-};
-export type ContrastRequirement = {
-    model: "apca";
-    targetLc: number;
-    minLc?: number;
-    maxLc?: number;
-} | {
-    model: "wcag2";
-    minRatio: number;
-} | {
-    model: "none";
-};
-export type AlphaStrategy = {
-    mode: "none";
-} | {
-    mode: "fixed";
-    alpha: number;
-} | {
-    mode: "solveOnBackground";
-};
-export interface OutputOptions {
-    preferSpace?: ColorSpace;
-    includeSpaces?: ColorSpace[];
-    gamutMapping?: "clip" | "compressChroma" | "preferP3ThenCompress";
-    strict?: boolean;
-    precision?: {
-        l?: number;
-        c?: number;
-        h?: number;
-        alpha?: number;
-    };
-    includeMeta?: boolean;
-    srgbFormat?: "hex" | "rgb" | "rgba";
-}
-export interface RawColor {
-    space: ColorSpace;
-    channels: number[];
-    alpha: number;
-}
-export interface ColorMeta {
-    role?: ColorRole;
-    variant?: SemanticVariant;
-    usage?: ColorUsage;
-    context?: ColorContext;
-    surface?: SurfaceIntent;
-    state?: ColorState;
-    emphasis?: ColorEmphasis;
-    on?: BackgroundHint;
-    contrast?: ContrastRequirement;
-    step?: number;
-    variantUsed?: string;
-    seedUsed?: CssColorString;
-    gamutMapping?: OutputOptions["gamutMapping"];
-    spaceUsed?: ColorSpace;
-    clipped?: boolean;
-    compressed?: boolean;
-    provenance?: string;
-}
-/**
- * Declarative token definition consumed by registries, exporters, CLI and codegen.
- *
- * Rules:
- * - Tokens never carry actual color values.
- * - `query.output` is forbidden; output formatting is decided by serializers/exporters.
- * - Do not encode interactive state in `query.state`; declare supported states via `states`.
- * - Do not embed literal background colors via `query.on: { kind: "color" }`.
- */
-export interface TokenDefinition {
-    name: string;
-    description?: string;
-    query: TokenQuery;
-    category?: string;
-    states?: TokenStates;
-}
-/**
- * Collection of base token definitions keyed by token name.
- */
-export interface TokenRegistry {
-    tokens: Record<string, TokenDefinition>;
-}
-export interface ResolvedColor {
-    /**
-     * Serialized string corresponding to `preferSpace`.
-     * Always present.
-     */
-    value: CssColorString;
-    /**
-     * Auxiliary sRGB representation.
-     * Only present if included via `includeSpaces`.
-     */
-    srgb?: CssColorString;
-    /**
-     * Auxiliary Display-P3 representation.
-     * Only present if included via `includeSpaces`.
-     */
-    p3?: CssColorString;
-    /**
-     * Auxiliary OKLCH representation.
-     * Only present if included via `includeSpaces`.
-     */
-    oklch?: CssColorString;
-    alpha: number;
-    meta?: ColorMeta;
-}
-export interface ColorQuery {
-    role: ColorRole;
-    variant?: SemanticVariant;
-    usage?: ColorUsage;
-    context?: ColorContext;
-    surface?: SurfaceIntent;
-    state?: ColorState;
-    emphasis?: ColorEmphasis;
-    on?: BackgroundHint;
-    contrast?: ContrastRequirement;
-    alpha?: AlphaStrategy;
-    output?: OutputOptions;
-}
-export interface OnSolidQuery {
-    bgRole: ColorRole;
-    usage: "text" | "icon";
-    context?: ColorContext;
-    state?: ColorState;
-    emphasis?: ColorEmphasis;
-    alpha?: AlphaStrategy;
-    contrast?: ContrastRequirement;
-    output?: OutputOptions;
-}
-export interface SemanticColorTheme {
-    resolve(query: ColorQuery): ResolvedColor;
-    resolveMany(queries: ColorQuery[]): ResolvedColor[];
-    color(role: ColorRole, options?: Omit<ColorQuery, "role">): ResolvedColor;
-    onSolid(query: OnSolidQuery): ResolvedColor;
-    withContext(context: ColorContext): SemanticColorTheme;
-    export: {
-        cssVars(): string;
-        json(): unknown;
-    };
-}
+import type { IntentDefinition as InternalIntentDefinition } from '../core/intent-registry.js';
+import type { OklchColor as InternalOklchColor } from '../core/oklch.js';
+import type { Context as InternalContext } from '../engine/context/context.js';
+import type { Level as InternalLevel } from '../engine/level/level.js';
+import type { State as InternalState, StateDeltaDirection } from '../engine/state/state.js';
+import type { Usage as InternalUsage } from '../engine/usage/strategy.js';
+import type { ColorOutput as InternalColorOutput, RgbaColor as InternalRgbaColor, RgbColor as InternalRgbColor, ResolveOutput } from '../export/types.js';
+import type { ChromaConfig, RelationParamsConfig, ResolverConfig, ResolverConfigOverrides, ResolverPresetName } from '../presets/presets.js';
+/** Semantic usage axis used by the resolver. */
+export type Usage = InternalUsage;
+/** Explicit level axis. Valid values are integers from 1 to 9. */
+export type Level = InternalLevel;
+/** Interactive state axis. State deltas are applied only when explicitly requested. */
+export type State = InternalState;
+/** Direction used when applying non-default state deltas. Palette Kit never infers it. */
+export type { StateDeltaDirection };
+/** Environmental context axis. Palette Kit never detects this automatically. */
+export type Context = InternalContext;
+/** Output format applied after OKLCH resolution. */
+export type ColorOutput = InternalColorOutput;
+/** Normalized internal OKLCH color returned by the default public output. */
+export type OklchColor = InternalOklchColor;
+/** RGBA object returned by `output: "rgba"`. */
+export type RgbaColor = InternalRgbaColor;
+/** RGB object returned by `output: "srgb"` and `output: "p3"`. */
+export type RgbColor = InternalRgbColor;
+/** Intent registry entry supplied at palette creation. */
+export type IntentDefinition = InternalIntentDefinition;
+export type { ChromaConfig, RelationParamsConfig, ResolverConfig, ResolverConfigOverrides, ResolverPresetName, };
+/** Public return type for a selected resolver output format. */
+export type PaletteResolveOutput<O extends ColorOutput = 'oklch'> = ResolveOutput<O>;
+/** Configuration for `createPaletteKit`. */
+export type PaletteKitConfig<I extends string = string, PaletteOutput extends ColorOutput | undefined = undefined, SystemDefaultOutput extends ColorOutput | undefined = undefined> = Readonly<{
+    /** Flat intent registry owned by the application. */
+    intents: Record<I, IntentDefinition>;
+    /** Palette-level context used when a resolver call does not override it. */
+    context?: Context;
+    /** Host-provided context fallback. Palette Kit never reads system preferences. */
+    systemDefaultContext?: Context;
+    /** Palette-level output used when a resolver call does not override it. */
+    output?: PaletteOutput;
+    /** Host-provided output fallback. Defaults to `oklch` when omitted. */
+    systemDefaultOutput?: SystemDefaultOutput;
+    /** Public resolver preset. Defaults to `neutral`. */
+    preset?: ResolverPresetName;
+    /** Explicit resolver configuration overrides merged on top of the preset. */
+    resolverConfig?: ResolverConfigOverrides;
+}>;
+export type PaletteDefaultOutput<PaletteOutput extends ColorOutput | undefined, SystemDefaultOutput extends ColorOutput | undefined> = PaletteOutput extends ColorOutput ? PaletteOutput : SystemDefaultOutput extends ColorOutput ? SystemDefaultOutput : 'oklch';
+type RelationTarget = OklchColor;
+type DefaultStateOptions = Readonly<{
+    state?: 'default';
+    stateDirection?: StateDeltaDirection;
+}>;
+type NonDefaultStateOptions = Readonly<{
+    state: Exclude<State, 'default'>;
+    stateDirection: StateDeltaDirection;
+}>;
+type StateOptions = DefaultStateOptions | NonDefaultStateOptions;
+type BaseResolveOptions<I extends string, ResolverOutput extends ColorOutput> = Readonly<{
+    /** Registered semantic intent name. */
+    intent: I;
+    /** Resolver-level context override. */
+    context?: Context;
+    /** Resolver-level output override. */
+    output?: ResolverOutput;
+}>;
+type FillResolveOptions = Readonly<{
+    usage: 'fill';
+    level: Level;
+    on?: RelationTarget;
+    over?: never;
+    under?: never;
+}>;
+type LinesResolveOptions = Readonly<{
+    usage: 'lines';
+    level: Level;
+    on?: RelationTarget;
+    over?: never;
+    under?: never;
+}>;
+type VisualVocabularyResolveOptions = Readonly<{
+    usage: 'visualVocabulary';
+    on: RelationTarget;
+    level?: never;
+    over?: never;
+    under?: never;
+}>;
+type OverlayRelationOptions = Readonly<{
+    over?: RelationTarget;
+    under?: never;
+}> | Readonly<{
+    under?: RelationTarget;
+    over?: never;
+}> | Readonly<{
+    over?: undefined;
+    under?: undefined;
+}>;
+type OverlaysResolveOptions = Readonly<{
+    usage: 'overlays';
+    level: Level;
+    on?: never;
+}> & OverlayRelationOptions;
+type UsageResolveOptions = FillResolveOptions | LinesResolveOptions | VisualVocabularyResolveOptions | OverlaysResolveOptions;
+/** Options accepted by `palette.resolve`. */
+export type PaletteResolveOptions<I extends string = string, ResolverOutput extends ColorOutput = ColorOutput> = BaseResolveOptions<I, ResolverOutput> & UsageResolveOptions & StateOptions;
+/** Immutable public Palette Kit instance. */
+export type PaletteKit<I extends string = string, PaletteOutput extends ColorOutput = 'oklch'> = Readonly<{
+    /** Resolves a color from semantic axes and formats it after OKLCH resolution. */
+    resolve<const ResolverOutput extends ColorOutput = PaletteOutput>(options: PaletteResolveOptions<I, ResolverOutput>): PaletteResolveOutput<ResolverOutput>;
+}>;

package/dist/utils/errors/errors.d.ts

@@ -0,0 +1,17 @@
+export type PaletteKitErrorCategory = 'configuration' | 'resolver-input' | 'resolution' | 'serialization';
+export type PaletteKitErrorCode = 'CONTRAST_UNSATISFIABLE' | 'UNKNOWN_INTENT' | 'MISSING_REQUIRED_AXIS' | 'FORBIDDEN_AXIS_COMBINATION' | 'INVALID_RELATION_TARGET' | 'MULTIPLE_RELATIONS' | 'UNRESOLVED_CONTEXT' | 'UNSUPPORTED_OUTPUT';
+export type PaletteKitErrorDetails = Readonly<Record<string, unknown>>;
+export declare class PaletteKitError extends Error {
+    readonly code: PaletteKitErrorCode;
+    readonly category: PaletteKitErrorCategory;
+    readonly details?: PaletteKitErrorDetails;
+    constructor(code: PaletteKitErrorCode, category: PaletteKitErrorCategory, message: string, details?: PaletteKitErrorDetails);
+}
+export declare const createUnknownIntentError: (intent: string) => PaletteKitError;
+export declare const createMissingRequiredAxisError: (axis: string, usage: string, message?: string) => PaletteKitError;
+export declare const createForbiddenAxisCombinationError: (axis: string, usage: string, message?: string) => PaletteKitError;
+export declare const createInvalidRelationTargetError: (relation: string, message?: string) => PaletteKitError;
+export declare const createMultipleRelationsError: (relations: readonly string[]) => PaletteKitError;
+export declare const createUnresolvedContextError: () => PaletteKitError;
+export declare const createUnsupportedOutputError: (output: string, message?: string) => PaletteKitError;
+export declare const createContrastUnsatisfiableError: (contrast: number, target: number) => PaletteKitError;

package/dist/utils/errors/errors.js

@@ -0,0 +1,22 @@
+export class PaletteKitError extends Error {
+    code;
+    category;
+    details;
+    constructor(code, category, message, details) {
+        super(message);
+        this.name = 'PaletteKitError';
+        this.code = code;
+        this.category = category;
+        this.details =
+            details === undefined ? undefined : Object.freeze({ ...details });
+    }
+}
+export const createUnknownIntentError = (intent) => new PaletteKitError('UNKNOWN_INTENT', 'configuration', `Unknown intent "${intent}". Did you forget to register it in the Intent Registry?`, { intent });
+export const createMissingRequiredAxisError = (axis, usage, message) => new PaletteKitError('MISSING_REQUIRED_AXIS', 'resolver-input', message ?? `${axis} is required for usage "${usage}".`, { axis, usage });
+export const createForbiddenAxisCombinationError = (axis, usage, message) => new PaletteKitError('FORBIDDEN_AXIS_COMBINATION', 'resolver-input', message ?? `${axis} is not allowed for usage "${usage}".`, { axis, usage });
+export const createInvalidRelationTargetError = (relation, message) => new PaletteKitError('INVALID_RELATION_TARGET', 'resolver-input', message ??
+    `Relation "${relation}" target must be a normalized OKLCH color.`, { relation });
+export const createMultipleRelationsError = (relations) => new PaletteKitError('MULTIPLE_RELATIONS', 'resolver-input', `Only one relation may be provided. Received: ${relations.join(', ')}.`, { relations: [...relations] });
+export const createUnresolvedContextError = () => new PaletteKitError('UNRESOLVED_CONTEXT', 'resolver-input', 'Context could not be resolved. Provide resolverContext, paletteContext, or systemDefaultContext.');
+export const createUnsupportedOutputError = (output, message) => new PaletteKitError('UNSUPPORTED_OUTPUT', 'serialization', message ?? `Unsupported color output "${output}" in Phase 10 serializer.`, { output });
+export const createContrastUnsatisfiableError = (contrast, target) => new PaletteKitError('CONTRAST_UNSATISFIABLE', 'resolution', `Unable to satisfy APCA contrast target ${target}. Best contrast was ${contrast}.`, { contrast, target });