@nikkory/vibe-engine 4.0.0

package/dist/resolution/core/resolver-core.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Resolution Orchestrator - Core Logic (A)
+ *
+ * Pure 5-level resolution without validation, debug, or defaults.
+ * Implements the priority system: Level 1 > Level 2 > Level 3 > Level 4 > Level 5
+ * Used by all tiers (basic, standard, enterprise).
+ *
+ * @composition Core = A (resolution only)
+ *
+ * @packageDocumentation
+ * @module resolution/core/resolver-core
+ * @since 3.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { ShorthandPropsCore } from './shorthands-core';
+import type { Factor24Config, MultiLevelProps, FactorGroups, SemanticIntent, SemanticMood } from './types-core';
+/**
+ * Extract Level 1 (raw factors) from MultiLevelProps (core logic).
+ * No validation - assumes props are well-formed.
+ *
+ * @param props - The multi-level props
+ * @returns Partial Factor24Config with Level 1 factors
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const level1 = extractLevel1FactorsCore({
+ *   size: 'lg',
+ *   variant: 'filled',
+ *   colorScheme: 'primary'
+ * });
+ * // { size: 'lg', variant: 'filled', colorScheme: 'primary' }
+ * ```
+ */
+export declare function extractLevel1FactorsCore(props: MultiLevelProps): Partial<Factor24Config>;
+/**
+ * Extract Level 2 (groups) from MultiLevelProps (core logic).
+ * No validation - assumes props are well-formed.
+ *
+ * @param props - The multi-level props
+ * @returns FactorGroups
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const level2 = extractLevel2GroupsCore({
+ *   visual: { shape: 'lg', elevation: 'md' },
+ *   motion: { animation: 'smooth' }
+ * });
+ * // { visual: { shape: 'lg', elevation: 'md' }, motion: { animation: 'smooth' } }
+ * ```
+ */
+export declare function extractLevel2GroupsCore(props: MultiLevelProps): FactorGroups;
+/**
+ * Extract Level 3 (shorthands) from MultiLevelProps (core logic).
+ * No validation - assumes props are well-formed.
+ *
+ * @param props - The multi-level props
+ * @returns ShorthandPropsCore
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const level3 = extractLevel3ShorthandsCore({
+ *   look: 'bold',
+ *   feel: 'snappy',
+ *   surface: 'raised'
+ * });
+ * // { look: 'bold', feel: 'snappy', surface: 'raised' }
+ * ```
+ */
+export declare function extractLevel3ShorthandsCore(props: MultiLevelProps): ShorthandPropsCore;
+/**
+ * Extract Level 4 (preset) from MultiLevelProps (core logic).
+ * No validation - assumes props are well-formed.
+ *
+ * @param props - The multi-level props
+ * @returns Preset ID or undefined
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const level4 = extractLevel4PresetCore({ preset: 'button-primary' });
+ * // 'button-primary'
+ * ```
+ */
+export declare function extractLevel4PresetCore(props: MultiLevelProps): string | undefined;
+/**
+ * Extract Level 5 (intent + mood) from MultiLevelProps (core logic).
+ * No validation - assumes props are well-formed.
+ *
+ * @param props - The multi-level props
+ * @returns Object with intent and mood IDs
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const level5 = extractLevel5IntentCore({
+ *   intent: 'cta',
+ *   mood: 'professional'
+ * });
+ * // { intent: 'cta', mood: 'professional' }
+ * ```
+ */
+export declare function extractLevel5IntentCore(props: MultiLevelProps): {
+    intent?: SemanticIntent;
+    mood?: SemanticMood;
+};
+/**
+ * Merge multiple Factor24Configs (core logic).
+ * Later configs override earlier ones.
+ * No validation.
+ *
+ * @param configs - Configs to merge in priority order (lowest to highest)
+ * @returns Merged configuration
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const merged = mergeConfigsCore(
+ *   { variant: 'filled', size: 'md' },
+ *   { size: 'lg', colorScheme: 'primary' }
+ * );
+ * // { variant: 'filled', size: 'lg', colorScheme: 'primary' }
+ * //   size from second config overrides first
+ * ```
+ */
+export declare function mergeConfigsCore(...configs: Array<Partial<Factor24Config>>): Partial<Factor24Config>;
+/**
+ * Resolve MultiLevelProps to Factor24Config (core logic).
+ *
+ * Implements 5-level priority system:
+ * - Level 1 (raw factors): HIGHEST priority
+ * - Level 2 (groups): High priority
+ * - Level 3 (shorthands): Medium priority
+ * - Level 4 (presets): Low priority
+ * - Level 5 (intents+moods): LOWEST priority
+ *
+ * No validation - assumes all inputs are well-formed.
+ * No debug info - pure resolution only.
+ * No defaults - returns only what was specified.
+ *
+ * @param props - MultiLevelProps to resolve
+ * @returns Resolved Partial Factor24Config
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * // Using Level 5 (Intent + Mood)
+ * const config1 = resolvePropsCore({
+ *   intent: 'cta',
+ *   mood: 'professional'
+ * });
+ *
+ * // Using Level 3 (Shorthands) with Level 1 override
+ * const config2 = resolvePropsCore({
+ *   look: 'bold',
+ *   feel: 'snappy',
+ *   size: 'lg' // Level 1 overrides shorthand
+ * });
+ *
+ * // Mixing all levels
+ * const config3 = resolvePropsCore({
+ *   intent: 'primary',          // Level 5 (lowest priority)
+ *   preset: 'button-cta',       // Level 4
+ *   look: 'elevated',           // Level 3
+ *   visual: { shape: 'lg' },    // Level 2
+ *   colorScheme: 'secondary',   // Level 1 (highest priority, overrides all)
+ * });
+ * ```
+ */
+export declare function resolvePropsCore(props: MultiLevelProps): Partial<Factor24Config>;
+/**
+ * Detect which levels are present in MultiLevelProps (core logic).
+ * No validation.
+ *
+ * @param props - The multi-level props to analyze
+ * @returns Object indicating which levels are present
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const detected = detectLevelsCore({
+ *   intent: 'cta',
+ *   look: 'bold',
+ *   size: 'lg'
+ * });
+ * // {
+ * //   hasLevel5: true,
+ * //   hasLevel4: false,
+ * //   hasLevel3: true,
+ * //   hasLevel2: false,
+ * //   hasLevel1: true,
+ * //   levels: [5, 3, 1]
+ * // }
+ * ```
+ */
+export declare function detectLevelsCore(props: MultiLevelProps): {
+    hasLevel5: boolean;
+    hasLevel4: boolean;
+    hasLevel3: boolean;
+    hasLevel2: boolean;
+    hasLevel1: boolean;
+    levels: number[];
+};
+//# sourceMappingURL=resolver-core.d.ts.map

package/dist/resolution/core/shorthands-core.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Shorthands Resolution - Core Logic (A)
+ *
+ * Pure shorthand expansion without validation.
+ * Used by all tiers (basic, standard, enterprise).
+ *
+ * @composition Core = A (resolution only)
+ *
+ * @packageDocumentation
+ * @module resolution/core/shorthands-core
+ * @since 3.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { Factor24Config, LookShorthand, FeelShorthand, SurfaceShorthand, SpacingShorthand } from '../types';
+/**
+ * Look shorthand to Factor24Config mappings (core).
+ *
+ * @since 3.0.0
+ */
+export declare const LOOK_MAPPINGS_CORE: Record<LookShorthand, Partial<Factor24Config>>;
+/**
+ * Expand look shorthand to Factor24Config (core logic).
+ * No validation - assumes input is well-formed.
+ *
+ * @param look - The look shorthand value
+ * @returns Partial Factor24Config with look-related factors
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const config = expandLookCore('bold');
+ * // { variant: 'filled', elevation: 'md', opacity: 'full', ... }
+ * ```
+ */
+export declare function expandLookCore(look: LookShorthand): Partial<Factor24Config>;
+/**
+ * Feel shorthand to Factor24Config mappings (core).
+ *
+ * @since 3.0.0
+ */
+export declare const FEEL_MAPPINGS_CORE: Record<FeelShorthand, Partial<Factor24Config>>;
+/**
+ * Expand feel shorthand to Factor24Config (core logic).
+ * No validation - assumes input is well-formed.
+ *
+ * @param feel - The feel shorthand value
+ * @returns Partial Factor24Config with feel-related factors
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const config = expandFeelCore('snappy');
+ * // { animation: 'standard', transition: 'fast', cursor: 'pointer' }
+ * ```
+ */
+export declare function expandFeelCore(feel: FeelShorthand): Partial<Factor24Config>;
+/**
+ * Surface shorthand to Factor24Config mappings (core).
+ *
+ * @since 3.0.0
+ */
+export declare const SURFACE_MAPPINGS_CORE: Record<SurfaceShorthand, Partial<Factor24Config>>;
+/**
+ * Expand surface shorthand to Factor24Config (core logic).
+ * No validation - assumes input is well-formed.
+ *
+ * @param surface - The surface shorthand value
+ * @returns Partial Factor24Config with surface-related factors
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const config = expandSurfaceCore('raised');
+ * // { elevation: 'sm', border: 'none', zIndex: 'raised' }
+ * ```
+ */
+export declare function expandSurfaceCore(surface: SurfaceShorthand): Partial<Factor24Config>;
+/**
+ * Spacing shorthand to Factor24Config mappings (core).
+ *
+ * @since 3.0.0
+ */
+export declare const SPACING_MAPPINGS_CORE: Record<SpacingShorthand, Partial<Factor24Config>>;
+/**
+ * Expand spacing shorthand to Factor24Config (core logic).
+ * No validation - assumes input is well-formed.
+ *
+ * @param spacing - The spacing shorthand value
+ * @returns Partial Factor24Config with spacing-related factors
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const config = expandSpacingShorthandCore('normal');
+ * // { spacing: 'normal', density: 'normal' }
+ * ```
+ */
+export declare function expandSpacingShorthandCore(spacing: SpacingShorthand): Partial<Factor24Config>;
+/**
+ * Shorthand props interface (core).
+ *
+ * @since 3.0.0
+ */
+export interface ShorthandPropsCore {
+    /** Visual appearance shorthand */
+    look?: LookShorthand;
+    /** Interaction feel shorthand */
+    feel?: FeelShorthand;
+    /** Surface/elevation shorthand */
+    surface?: SurfaceShorthand;
+    /** Spacing shorthand */
+    spacingPreset?: SpacingShorthand;
+}
+/**
+ * Expand all shorthands to Factor24Config (core logic).
+ * Merges all shorthand configurations. Later shorthands override earlier ones.
+ * No validation - assumes input is well-formed.
+ *
+ * @param shorthands - The shorthand props to expand
+ * @returns Partial Factor24Config with all shorthand factors
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const config = expandShorthandsCore({
+ *   look: 'bold',
+ *   feel: 'snappy',
+ *   surface: 'raised',
+ *   spacingPreset: 'normal',
+ * });
+ * // {
+ * //   variant: 'filled',
+ * //   elevation: 'sm',  // 'raised' overrides 'bold'
+ * //   animation: 'standard',
+ * //   transition: 'fast',
+ * //   spacing: 'normal',
+ * //   density: 'normal',
+ * //   ...
+ * // }
+ * ```
+ */
+export declare function expandShorthandsCore(shorthands: ShorthandPropsCore): Partial<Factor24Config>;
+//# sourceMappingURL=shorthands-core.d.ts.map

package/dist/resolution/core/types-core.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Core Resolution Types
+ *
+ * Shared types for all tier levels (basic, standard, enterprise).
+ * Single source of truth for resolution type definitions.
+ *
+ * @packageDocumentation
+ * @module resolution/core/types-core
+ * @since 3.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { Factor24Config, MultiLevelProps } from '../types';
+export type { Factor24Config, MultiLevelProps, SemanticIntent, SemanticMood, IntentDefinition, MoodModifierDefinition, PresetCategory, PresetDefinition, LookShorthand, FeelShorthand, SurfaceShorthand, SpacingShorthand, ShorthandMappings, VisualGroup, MotionGroup, LayoutGroup, ExperienceGroup, FactorGroups, FactorShape, FactorPosition, FactorIconPosition, FactorState, FactorAnimation, FactorElevation, FactorA11y, FactorAlignment, FactorOrientation, FactorDensity, FactorLoadingState, FactorResponsiveConfig, FactorTheme, FactorSpacing, FactorTypography, FactorBorder, FactorOpacity, FactorOverflow, FactorCursor, FactorZIndex, FactorTransition, ComponentSize, ColorScheme, } from '../types';
+/**
+ * Core Resolution Result
+ *
+ * Minimal result from core resolution logic (Pattern A).
+ * No validation, no metrics, just the resolved configuration.
+ *
+ * @since 3.0.0
+ */
+export interface ResolutionCoreResult {
+    /** Resolved 24-factor configuration */
+    readonly config: Factor24Config;
+}
+/**
+ * Standard Resolution Result
+ *
+ * Extends core result with validation and error handling (Pattern A+a).
+ * Includes detailed error messages and warnings.
+ *
+ * @since 3.0.0
+ */
+export interface ResolutionStandardResult extends ResolutionCoreResult {
+    /** Whether the resolution was valid */
+    readonly valid: boolean;
+    /** Array of validation error messages */
+    readonly errors: string[];
+    /** Optional warning messages (non-blocking) */
+    readonly warnings?: string[];
+    /** Original input props (for debugging) */
+    readonly originalProps?: MultiLevelProps;
+    /** Normalized input props (after preprocessing) */
+    readonly normalizedProps?: MultiLevelProps;
+}
+/**
+ * Enterprise Resolution Result
+ *
+ * Extends standard result with performance metrics and debugging (Pattern A+a+b).
+ * Includes profiling data and optional debug traces.
+ *
+ * @since 3.0.0
+ */
+export interface ResolutionEnterpriseResult extends ResolutionStandardResult {
+    /** Performance metrics for this resolution */
+    readonly metrics: ResolutionMetrics;
+    /** Optional debug trace (if debug mode enabled) */
+    readonly debug?: DebugTrace;
+    /** Whether this result came from cache */
+    readonly cacheHit?: boolean;
+}
+/**
+ * Performance Metrics
+ *
+ * Tracking data for resolution performance.
+ *
+ * @since 3.0.0
+ */
+export interface ResolutionMetrics {
+    /** Start timestamp (performance.now()) */
+    readonly startTime: number;
+    /** End timestamp (performance.now()) */
+    readonly endTime: number;
+    /** Duration in milliseconds */
+    readonly durationMs: number;
+    /** Which levels were resolved (1-5) */
+    readonly levelsResolved: number[];
+    /** Cache size (if caching enabled) */
+    readonly cacheSize?: number;
+    /** Number of factor overwrites */
+    readonly factorOverwrites?: number;
+}
+/**
+ * Debug Trace
+ *
+ * Step-by-step resolution log for debugging.
+ *
+ * @since 3.0.0
+ */
+export interface DebugTrace {
+    /** Array of resolution steps */
+    readonly steps: DebugStep[];
+    /** Final resolved configuration */
+    readonly finalConfig: Factor24Config;
+    /** Intermediate configs at each level */
+    readonly levelConfigs?: Record<number, Partial<Factor24Config>>;
+}
+/**
+ * Debug Step
+ *
+ * Single step in the resolution trace.
+ *
+ * @since 3.0.0
+ */
+export interface DebugStep {
+    /** Resolution level (1-5) */
+    readonly level: number;
+    /** Action performed */
+    readonly action: string;
+    /** Input to this step */
+    readonly input: unknown;
+    /** Output from this step */
+    readonly output: unknown;
+    /** Timestamp when step occurred */
+    readonly timestamp: number;
+    /** Optional description */
+    readonly description?: string;
+}
+/**
+ * Resolution Options (Core)
+ *
+ * Basic options for core resolution.
+ *
+ * @since 3.0.0
+ */
+export interface ResolutionCoreOptions {
+    /** Allow partial resolution (missing required factors) */
+    allowPartial?: boolean;
+    /** Default values to use for missing factors */
+    defaults?: Partial<Factor24Config>;
+}
+/**
+ * Resolution Options (Standard)
+ *
+ * Options for standard resolution with validation.
+ *
+ * @since 3.0.0
+ */
+export interface ResolutionStandardOptions extends ResolutionCoreOptions {
+    /** Enable strict validation */
+    strict?: boolean;
+    /** Stop on first error */
+    failFast?: boolean;
+    /** Include warnings in result */
+    includeWarnings?: boolean;
+}
+/**
+ * Resolution Options (Enterprise)
+ *
+ * Options for enterprise resolution with metrics and debugging.
+ *
+ * @since 3.0.0
+ */
+export interface ResolutionEnterpriseOptions extends ResolutionStandardOptions {
+    /** Enable debug mode (detailed trace) */
+    debug?: boolean;
+    /** Enable performance profiling */
+    profile?: boolean;
+    /** Analytics event name (for tracking) */
+    analyticsEvent?: string;
+    /** Enable caching */
+    cache?: boolean;
+    /** Custom cache key */
+    cacheKey?: string;
+}
+//# sourceMappingURL=types-core.d.ts.map

package/dist/resolution/debugger.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Resolution Debugger - Debug Utilities for Resolution Pipeline
+ *
+ * Provides tools to inspect, trace, and debug the resolution process.
+ * Useful for understanding how props are transformed at each level.
+ *
+ * @packageDocumentation
+ * @module resolution/debugger
+ * @since 2.1.0
+ *
+ * Powered by Nikkory
+ */
+import type { MultiLevelProps, Factor24Config, ResolutionResult } from './types';
+/**
+ * Debug step in the resolution process.
+ *
+ * @since 2.1.0
+ */
+export interface DebugStep {
+    /** Step number */
+    step: number;
+    /** Level being processed */
+    level: 1 | 2 | 3 | 4 | 5;
+    /** Description of what happened */
+    description: string;
+    /** Input at this step */
+    input: unknown;
+    /** Output from this step */
+    output: Partial<Factor24Config>;
+    /** Duration in microseconds */
+    duration: number;
+}
+/**
+ * Complete debug trace of resolution.
+ *
+ * @since 2.1.0
+ */
+export interface DebugTrace {
+    /** Original input props */
+    input: MultiLevelProps;
+    /** Final resolved config */
+    output: Partial<Factor24Config>;
+    /** All resolution steps */
+    steps: DebugStep[];
+    /** Total duration in microseconds */
+    totalDuration: number;
+    /** Detected levels */
+    levels: {
+        hasLevel5: boolean;
+        hasLevel4: boolean;
+        hasLevel3: boolean;
+        hasLevel2: boolean;
+        hasLevel1: boolean;
+    };
+    /** Validation errors if any */
+    validationErrors: string[];
+    /** Source of each factor value */
+    factorSources: Record<string, string>;
+    /** Warnings */
+    warnings: string[];
+}
+/**
+ * Factor change tracking.
+ *
+ * @since 2.1.0
+ */
+export interface FactorChange {
+    /** Factor name */
+    factor: keyof Factor24Config;
+    /** Previous value */
+    previousValue: unknown;
+    /** New value */
+    newValue: unknown;
+    /** Source level */
+    source: string;
+    /** Was it an override */
+    isOverride: boolean;
+}
+/**
+ * Create a detailed debug trace of the resolution process.
+ *
+ * @param props - Input props to trace
+ * @returns Complete debug trace
+ *
+ * @example
+ * ```typescript
+ * const trace = createDebugTrace({
+ *   intent: 'cta',
+ *   look: 'bold',
+ *   shape: 'pill',
+ * });
+ * console.log(trace.steps);
+ * console.log(trace.factorSources);
+ * ```
+ *
+ * @since 2.1.0
+ */
+export declare function createDebugTrace(props: MultiLevelProps): DebugTrace;
+/**
+ * Format debug trace for console output.
+ *
+ * @param trace - Debug trace to format
+ * @returns Formatted string
+ *
+ * @since 2.1.0
+ */
+export declare function formatDebugTrace(trace: DebugTrace): string;
+/**
+ * Track factor changes between two configs.
+ *
+ * @param before - Config before
+ * @param after - Config after
+ * @param source - Source of changes
+ * @returns List of changes
+ *
+ * @since 2.1.0
+ */
+export declare function trackFactorChanges(before: Partial<Factor24Config>, after: Partial<Factor24Config>, source: string): FactorChange[];
+/**
+ * Create a diff between two configs.
+ *
+ * @param config1 - First config
+ * @param config2 - Second config
+ * @returns Diff object
+ *
+ * @since 2.1.0
+ */
+export declare function diffConfigs(config1: Partial<Factor24Config>, config2: Partial<Factor24Config>): {
+    added: Partial<Factor24Config>;
+    removed: Partial<Factor24Config>;
+    changed: Array<{
+        factor: keyof Factor24Config;
+        from: unknown;
+        to: unknown;
+    }>;
+};
+/**
+ * Assert that a resolution produces expected output.
+ *
+ * @param props - Input props
+ * @param expected - Expected output factors
+ * @throws Error if assertion fails
+ *
+ * @example
+ * ```typescript
+ * assertResolution(
+ *   { intent: 'cta' },
+ *   { variant: 'filled', colorScheme: 'primary' }
+ * );
+ * ```
+ *
+ * @since 2.1.0
+ */
+export declare function assertResolution(props: MultiLevelProps, expected: Partial<Factor24Config>): void;
+/**
+ * Debug logger for resolution.
+ *
+ * @since 2.1.0
+ */
+export declare const debugLogger: {
+    /**
+     * Enable/disable debug logging
+     */
+    enabled: boolean;
+    /**
+     * Log a debug message
+     */
+    log: (message: string, data?: unknown) => void;
+    /**
+     * Log a step in the resolution process
+     */
+    step: (level: number, description: string, input: unknown, output: unknown) => void;
+    /**
+     * Log a warning
+     */
+    warn: (message: string) => void;
+    /**
+     * Log an error
+     */
+    error: (message: string, error?: unknown) => void;
+};
+export type { ResolutionResult };
+//# sourceMappingURL=debugger.d.ts.map