af-motion 0.0.0-stage → 1.0.0

package/dist/core/motion-recipe.d.ts

@@ -0,0 +1,171 @@
+import type { ComposableEffect } from "./effect-composer.js";
+import type { MotionChoreographyAction, MotionChoreographyControls } from "./motion-choreography.js";
+/** Registers the choreography engine to eliminate circular module dependencies between recipe and choreography. */
+export declare function registerChoreographyEngine(engine: (actions: readonly MotionChoreographyAction[]) => MotionChoreographyControls): void;
+import type { MotionDNA, MotionDNAOverrides } from "./motion-dna.js";
+import type { AnimateTarget } from "./animate.js";
+import type { MotionPresetOverrides } from "../presets.js";
+export declare const RECIPE_SCHEMA_VERSION = "1.0.0";
+export interface MotionRecipeContext {
+    /** Resolves DNA declared by the recipe with per-use overrides. */
+    motionDNA(name: string, overrides?: MotionDNAOverrides): MotionDNA;
+}
+export interface MotionRecipeDefinition<Parameters extends object> {
+    /** DNA names this recipe is allowed to resolve. */
+    motionDNA?: readonly string[];
+    /** Builds effect entries that run for the recipe's lifetime. */
+    effects?: (parameters: Readonly<Parameters>, context: MotionRecipeContext) => readonly ComposableEffect[];
+    /** Builds the ordered choreography to execute for this recipe. */
+    choreography?: (parameters: Readonly<Parameters>, context: MotionRecipeContext) => readonly MotionChoreographyAction[];
+}
+export interface MotionRecipe<Parameters extends object> {
+    readonly definition: MotionRecipeDefinition<Parameters>;
+}
+export interface MotionRecipeControls {
+    /** Resolves when the recipe's choreography completes; undefined for effect-only recipes. */
+    readonly finished?: Promise<void>;
+    /** Pauses choreography animations and effects that expose pause controls. */
+    pause(): void;
+    /** Resumes choreography animations and effects that expose resume controls. */
+    resume(): void;
+    /** Stops the choreography and cleans up all recipe effects. Safe to repeat. */
+    destroy(): void;
+    /** Alias for destroy(). */
+    cancel(): void;
+    /** Optional play control when underlying engine supports forward playback. */
+    play?(): void;
+    /** Optional reverse control when recipe is a pure reversible sequence. */
+    reverse?(): void;
+    /** Optional seek control when recipe is a pure seekable sequence. */
+    seek?(progress: number): void;
+}
+export interface RecipeStepBase {
+    readonly label?: string;
+    readonly delay?: number;
+}
+export interface RecipePresetStep extends RecipeStepBase {
+    readonly type?: "preset";
+    readonly preset: string;
+    readonly target?: AnimateTarget | string;
+    readonly duration?: number;
+    readonly easing?: string | ((t: number) => number);
+    readonly overrides?: MotionPresetOverrides;
+}
+export interface RecipeParallelStep extends RecipeStepBase {
+    readonly type: "parallel";
+    readonly steps: readonly RecipeStep[];
+}
+export interface RecipeSequenceStep extends RecipeStepBase {
+    readonly type: "sequence";
+    readonly steps: readonly RecipeStep[];
+}
+export interface RecipeNestedStep extends RecipeStepBase {
+    readonly type: "recipe";
+    readonly recipe: string | DeclarativeMotionRecipe;
+    readonly targets?: Record<string, AnimateTarget>;
+    readonly overrides?: MotionPresetOverrides;
+}
+export type RecipeStep = RecipePresetStep | RecipeParallelStep | RecipeSequenceStep | RecipeNestedStep;
+export interface RecipeParameterSchema {
+    readonly name: string;
+    readonly type: string;
+    readonly description: string;
+    readonly required?: boolean;
+    readonly default?: unknown;
+}
+export interface DeclarativeMotionRecipe {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly category?: string;
+    readonly tags?: readonly string[];
+    readonly requiredTargets?: readonly string[];
+    readonly defaultOptions?: MotionPresetOverrides;
+    readonly structure?: "sequence" | "parallel";
+    readonly steps: readonly RecipeStep[];
+    readonly parameters?: readonly RecipeParameterSchema[];
+}
+export type RecipeTargetMap = Record<string, AnimateTarget>;
+export interface RecipeRunOptions {
+    /** Named target bindings or a default fallback target. */
+    readonly targets?: RecipeTargetMap | AnimateTarget;
+    /** Recipe-level timing/animation option overrides. */
+    readonly overrides?: MotionPresetOverrides;
+    /** Step-specific overrides keyed by step label or index string. */
+    readonly stepOverrides?: Record<string, MotionPresetOverrides>;
+}
+export interface RecipeValidationError {
+    readonly parameter?: string;
+    readonly message: string;
+}
+export interface RecipeValidationResult {
+    readonly valid: boolean;
+    readonly errors: readonly RecipeValidationError[];
+}
+export interface RecipesDocument {
+    readonly $schema: string;
+    readonly version: string;
+    readonly totalRecipes: number;
+    readonly recipes: readonly DeclarativeMotionRecipe[];
+}
+export declare const BUILT_IN_MOTION_RECIPES: readonly DeclarativeMotionRecipe[];
+/**
+ * Returns all registered motion recipes (built-in and custom).
+ */
+export declare function listRecipes(): readonly DeclarativeMotionRecipe[];
+/**
+ * Looks up a recipe by its ID or friendly name.
+ */
+export declare function getRecipe(idOrName: string): DeclarativeMotionRecipe | undefined;
+/**
+ * Searches recipes by keyword query matching ID, name, description, category, or tags.
+ */
+export declare function searchRecipes(query: string): readonly DeclarativeMotionRecipe[];
+/**
+ * Registers a new custom declarative recipe. Built-in IDs and names are reserved.
+ */
+export declare function registerRecipe(recipe: DeclarativeMotionRecipe): void;
+/**
+ * Removes a custom motion recipe. Built-in recipes cannot be removed.
+ */
+export declare function removeRecipe(idOrName: string): boolean;
+/**
+ * Validates a declarative recipe definition against structure, preset existence, and circular references.
+ */
+export declare function validateRecipe(recipe: unknown, visitedRecipeIds?: Set<string>): RecipeValidationResult;
+/**
+ * Validates run options against recipe requirements (e.g. required targets).
+ */
+export declare function validateRecipeRunOptions(recipeIdOrRecipe: string | DeclarativeMotionRecipe, options: unknown): RecipeValidationResult;
+/**
+ * Runs a declarative recipe against target bindings and optional overrides.
+ */
+export declare function runRecipe(recipeIdOrRecipe: string | DeclarativeMotionRecipe, options?: RecipeRunOptions): MotionRecipeControls;
+/**
+ * Creates and registers or freezes a declarative motion recipe.
+ */
+export declare function composeRecipe(recipe: DeclarativeMotionRecipe): DeclarativeMotionRecipe;
+/**
+ * Exports a recipe definition as a JSON string.
+ */
+export declare function exportRecipeJson(recipeIdOrRecipe: string | DeclarativeMotionRecipe, pretty?: boolean): string;
+/**
+ * Exports all registered recipes as a versioned document.
+ */
+export declare function exportRecipesDocument(): RecipesDocument;
+/**
+ * Imports and validates a recipe definition from a JSON string.
+ */
+export declare function importRecipeFromJson(json: string): DeclarativeMotionRecipe;
+/**
+ * Overload 1: Programmatic builder recipe with effects/choreography callbacks.
+ * Overload 2: Declarative motion recipe definition.
+ */
+export declare function createMotionRecipe<Parameters extends object>(definition: MotionRecipeDefinition<Parameters>): MotionRecipe<Parameters>;
+export declare function createMotionRecipe(definition: DeclarativeMotionRecipe): DeclarativeMotionRecipe;
+/**
+ * Overload 1: Runs a programmatic recipe with parameter object.
+ * Overload 2: Runs a declarative recipe with target bindings and overrides.
+ */
+export declare function runMotionRecipe<Parameters extends object>(recipe: MotionRecipe<Parameters>, parameters: Parameters): MotionRecipeControls;
+export declare function runMotionRecipe(recipe: DeclarativeMotionRecipe | string, options?: RecipeRunOptions): MotionRecipeControls;

package/dist/core/motion-states.d.ts

@@ -0,0 +1,43 @@
+import type { AnimateTarget, AnimationValue, DOMAnimationOptions } from "./animate.js";
+import type { MotionDNAOverrides } from "./motion-dna.js";
+export interface MotionStateDefinition {
+    /** CSS property values that define this state. */
+    readonly values: Readonly<Record<string, AnimationValue>>;
+    /** Per-state animation options. */
+    readonly options?: DOMAnimationOptions;
+    /** Optional Motion DNA identity for transitions to this state. */
+    readonly motionDNA?: {
+        name: string;
+        overrides?: MotionDNAOverrides;
+    };
+}
+export type MotionStateDefinitions = Readonly<Record<string, MotionStateDefinition>>;
+export interface MotionStateTransitionOptions extends DOMAnimationOptions {
+    /** Optional Motion DNA identity applied to this transition. */
+    motionDNA?: {
+        name: string;
+        overrides?: MotionDNAOverrides;
+    };
+}
+export interface MotionStateTransitionControls {
+    readonly finished: Promise<void>;
+    cancel(): void;
+}
+export interface MotionStateControls {
+    readonly currentState: string | undefined;
+    /** Transitions from the currently rendered styles to a named state. */
+    transitionTo(name: string, options?: MotionStateTransitionOptions): MotionStateTransitionControls;
+    /** Cancels an active transition, restores styles captured at creation, and destroys the controller. */
+    destroy(): void;
+}
+/**
+ * Creates a named visual-state controller. Each transition starts at the current rendered CSS
+ * value and delegates interpolation, reduced-motion handling, and scheduling to `animate()`.
+ */
+export declare function createMotionStates(target: AnimateTarget, definitions: MotionStateDefinitions, options?: {
+    initialState?: string;
+    motionDNA?: {
+        name: string;
+        overrides?: MotionDNAOverrides;
+    };
+}): MotionStateControls;

package/dist/core/motion-validation/consistency.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AF Motion Consistency Intelligence Engine
+ *
+ * Evaluates motion consistency across durations, easings, Visual Style,
+ * Motion DNA, and cross-system choreography.
+ */
+import type { MotionConsistencyReport } from "./types.js";
+/**
+ * Evaluates holistic motion consistency across multiple components, transitions, or scenes.
+ */
+export declare function evaluateMotionConsistency(configs?: readonly any[]): MotionConsistencyReport;

package/dist/core/motion-validation/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AF Motion Motion Validation & Optimization Module
+ *
+ * Unified validation engine, accessibility intelligence, performance optimization,
+ * consistency analysis, and AI capability discovery.
+ */
+export * from "./types.js";
+export * from "./validator.js";
+export * from "./optimizer.js";
+export * from "./consistency.js";
+export * from "./schema.js";

package/dist/core/motion-validation/optimizer.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AF Motion Performance & Accessibility Optimizer
+ *
+ * Safe, behavior-preserving optimization engine converting layout-triggering styles
+ * into GPU-accelerated transforms, dampening excessive filters, and ensuring accessibility.
+ */
+import type { MotionOptimizationOptions, MotionOptimizationResult } from "./types.js";
+/**
+ * Optimizes a motion configuration according to the specified safety level.
+ */
+export declare function optimizeMotion<T = any>(config: T, options?: MotionOptimizationOptions): MotionOptimizationResult<T>;

package/dist/core/motion-validation/schema.d.ts

@@ -0,0 +1,81 @@
+/**
+ * AF Motion Motion Validation Schema & AI Motion Registry Integration
+ *
+ * Machine-readable capability definitions and discovery helpers for
+ * motion validation, accessibility checking, and performance optimization.
+ */
+export declare const MOTION_VALIDATION_CAPABILITY: {
+    id: string;
+    name: string;
+    category: "optimization";
+    description: string;
+    tags: string[];
+    version: string;
+    features: string[];
+    parameters: ({
+        name: string;
+        kind: "positional";
+        type: string;
+        required: boolean;
+        description: string;
+    } | {
+        name: string;
+        kind: "optional";
+        type: string;
+        required: boolean;
+        description: string;
+    })[];
+    supportedTargets: string[];
+    signature: {
+        importStatement: string;
+        invocation: string;
+        exampleCode: string;
+    };
+    controls: string[];
+    callbacks: never[];
+    reducedMotion: "static-fallback";
+    compatibility: {
+        browser: boolean;
+        ssr: boolean;
+        requiresCanvas: boolean;
+    };
+};
+export declare function getMotionValidationCapability(): {
+    id: string;
+    name: string;
+    category: "optimization";
+    description: string;
+    tags: string[];
+    version: string;
+    features: string[];
+    parameters: ({
+        name: string;
+        kind: "positional";
+        type: string;
+        required: boolean;
+        description: string;
+    } | {
+        name: string;
+        kind: "optional";
+        type: string;
+        required: boolean;
+        description: string;
+    })[];
+    supportedTargets: string[];
+    signature: {
+        importStatement: string;
+        invocation: string;
+        exampleCode: string;
+    };
+    controls: string[];
+    callbacks: never[];
+    reducedMotion: "static-fallback";
+    compatibility: {
+        browser: boolean;
+        ssr: boolean;
+        requiresCanvas: boolean;
+    };
+};
+export declare function registerMotionValidationCapability(registry: {
+    registerCapability: (cap: any, opts?: any) => void;
+}): void;

package/dist/core/motion-validation/types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * AF Motion Unified Motion Optimization & Validation Contracts
+ *
+ * Framework-independent contracts for validating animation configurations,
+ * accessibility compliance, performance profiling, and consistency analysis.
+ */
+export declare const MOTION_VALIDATION_VERSION = "1.0.0";
+export type ValidationSeverity = "error" | "warning" | "info";
+export type ValidationIssueCategory = "layout-thrashing" | "expensive-filter" | "excessive-duration" | "excessive-intensity" | "reduced-motion-violation" | "accessibility-risk" | "seizure-risk" | "property-conflict" | "timing-inconsistency" | "dna-contradiction" | "unsupported-capability" | "lifecycle-risk";
+export interface MotionValidationIssue {
+    readonly id: string;
+    readonly severity: ValidationSeverity;
+    readonly category: ValidationIssueCategory;
+    readonly property?: string;
+    readonly path?: string;
+    readonly message: string;
+    readonly suggestedFix?: string;
+    readonly autoFixable: boolean;
+}
+export interface MotionValidationResult {
+    readonly valid: boolean;
+    readonly score: number;
+    readonly accessibilityScore: number;
+    readonly performanceScore: number;
+    readonly consistencyScore: number;
+    readonly issues: readonly MotionValidationIssue[];
+    readonly summary: string;
+}
+export type OptimizationLevel = "safe" | "balanced" | "aggressive";
+export interface MotionOptimizationOptions {
+    readonly level?: OptimizationLevel;
+    readonly deviceTier?: "low" | "medium" | "high";
+    readonly reducedMotion?: boolean;
+    readonly targetFPS?: 30 | 60 | 120;
+}
+export interface MotionOptimizationResult<T = any> {
+    readonly optimizedConfig: T;
+    readonly originalConfig: T;
+    readonly level: OptimizationLevel;
+    readonly appliedOptimizations: readonly string[];
+    readonly remainingTradeoffs: readonly string[];
+    readonly validationBefore: MotionValidationResult;
+    readonly validationAfter: MotionValidationResult;
+}
+export interface MotionConsistencyReport {
+    readonly consistencyScore: number;
+    readonly durationHarmonic: boolean;
+    readonly easingAligned: boolean;
+    readonly dnaAligned: boolean;
+    readonly styleAligned: boolean;
+    readonly issues: readonly MotionValidationIssue[];
+    readonly recommendations: readonly string[];
+}

package/dist/core/motion-validation/validator.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AF Motion Unified Motion Validator
+ *
+ * Deterministic validation engine detecting layout thrashing, performance bottlenecks,
+ * accessibility hazards (seizures, reduced motion), and Motion DNA contradictions.
+ */
+import type { MotionValidationResult } from "./types.js";
+/**
+ * Validates a motion configuration object, plan, or transition specification.
+ */
+export declare function validateMotionConfig(config: any): MotionValidationResult;

package/dist/core/motion.d.ts

@@ -0,0 +1,7 @@
+/** True when the user prefers reduced motion. Safe where `matchMedia` is missing. */
+export declare function prefersReducedMotion(): boolean;
+/**
+ * Calls `listener` when the reduced-motion preference changes. Returns an unsubscribe
+ * function; both are no-ops where `matchMedia` change events are unavailable.
+ */
+export declare function onReducedMotionChange(listener: (reduced: boolean) => void): () => void;

package/dist/core/natural-motion.d.ts

@@ -0,0 +1,110 @@
+/**
+ * AF Motion Natural-Language-to-Motion Interpretation Engine
+ *
+ * Framework-independent interpretation layer that parses natural-language motion prompts
+ * and produces structured, validated, machine-readable AF Motion specifications.
+ */
+import type { AIMotionRegistry } from "./ai-motion-registry.js";
+import { type ConfigurationValidationResult, type ReducedMotionBehavior, type SchemaCapabilityCategory } from "./schema.js";
+export type MotionTriggerType = "load" | "scroll" | "hover" | "click" | "inView" | "pointer";
+export interface MotionTargetSpecification {
+    readonly selector?: string;
+    readonly semanticRole?: string;
+    readonly description?: string;
+    readonly isCollection: boolean;
+}
+export interface MotionScrollOptions {
+    readonly once?: boolean;
+    readonly threshold?: number | number[];
+    readonly rootMargin?: string;
+    readonly axis?: "y" | "x";
+}
+export interface MotionInteractionOptions {
+    readonly strength?: number;
+    readonly distance?: number;
+    readonly radius?: number;
+    readonly hoverScale?: number;
+    readonly returnSpeed?: number;
+}
+export interface MotionStaggerOptions {
+    readonly delay: number;
+    readonly from?: "start" | "first" | "center" | "end" | "last" | "edges" | "random";
+}
+export interface MotionAccessibilitySpecification {
+    readonly respectReducedMotion: boolean;
+    readonly reducedMotion: ReducedMotionBehavior;
+    readonly fallbackProperties?: Readonly<Record<string, unknown>>;
+    readonly screenReaderAnnounce?: boolean;
+}
+export interface MotionAlternativeRecommendation {
+    readonly capabilityId: string;
+    readonly category: string;
+    readonly name: string;
+    readonly confidence: number;
+    readonly reason: string;
+}
+export interface MotionSpecification {
+    readonly id: string;
+    readonly prompt: string;
+    readonly capabilityId: string;
+    readonly matchedCapabilities: readonly string[];
+    readonly category: SchemaCapabilityCategory;
+    readonly target: MotionTargetSpecification;
+    readonly properties: Readonly<Record<string, unknown>>;
+    readonly duration?: number;
+    readonly delay?: number;
+    readonly easing?: string;
+    readonly stagger?: MotionStaggerOptions;
+    readonly trigger: MotionTriggerType;
+    readonly scroll?: MotionScrollOptions;
+    readonly interaction?: MotionInteractionOptions;
+    readonly motionDNA?: string;
+    readonly designSystem?: string;
+    readonly accessibility: MotionAccessibilitySpecification;
+    readonly schemaId?: string;
+    readonly parameters: Readonly<Record<string, unknown>>;
+    readonly metadata: {
+        readonly extractedModifiers: readonly string[];
+        readonly confidenceScore: number;
+        readonly intent: string;
+        readonly [key: string]: unknown;
+    };
+}
+export interface MotionInterpretationResult {
+    readonly success: boolean;
+    readonly confidence: number;
+    readonly specification?: MotionSpecification;
+    readonly alternatives: readonly MotionAlternativeRecommendation[];
+    readonly validation?: ConfigurationValidationResult;
+    readonly warnings: readonly string[];
+    readonly intent: {
+        readonly action: string;
+        readonly target: string;
+        readonly modifiers: readonly string[];
+        readonly trigger: MotionTriggerType;
+    };
+}
+/**
+ * Registers the global AI Motion Registry resolver to maintain zero circular dependencies with catalogue.
+ */
+export declare function setDefaultRegistryResolver(resolver: () => AIMotionRegistry | undefined): void;
+/**
+ * Resolves the effective registry from options or global resolver.
+ */
+export declare function getEffectiveRegistry(options?: InterpretOptions): AIMotionRegistry | undefined;
+export interface InterpretOptions {
+    readonly registry?: AIMotionRegistry;
+    readonly context?: {
+        readonly defaultTarget?: string;
+        readonly motionDNA?: string;
+        readonly designSystem?: string;
+        readonly preferredCategory?: string;
+    };
+    readonly validate?: boolean;
+    readonly minConfidence?: number;
+    readonly strictTarget?: boolean;
+}
+/**
+ * Interprets a natural-language motion request into a structured AF Motion specification.
+ */
+export declare function interpretMotionPrompt(prompt: string, options?: InterpretOptions): MotionInterpretationResult;

package/dist/core/palette-colors.d.ts

@@ -0,0 +1,16 @@
+export interface PaletteColorOptions {
+    /** Registered built-in/custom palette to use, or "active" to follow activation changes. */
+    palette?: string | "active";
+    /** Explicit colors take precedence over palette colors. */
+    colors?: readonly string[];
+    /** Colors to use when no active palette is available. */
+    fallback?: readonly string[];
+}
+export type PaletteColorsListener = (colors: readonly string[]) => void;
+/** Resolves explicit colors or a registered palette into an immutable effect-ready color list. */
+export declare function resolvePaletteColors(options: PaletteColorOptions): readonly string[];
+/**
+ * Subscribes to active-palette changes when `palette` is "active".
+ * Named palettes and explicit color lists are static and return an inert unsubscribe function.
+ */
+export declare function subscribeToPaletteColors(options: PaletteColorOptions, listener: PaletteColorsListener): () => void;

package/dist/core/palette-styles.d.ts

@@ -0,0 +1,12 @@
+import type { SemanticColorToken } from "./palettes.js";
+/** CSS custom properties use the stable `--af-motion-color-<token>` naming convention. */
+export declare const PALETTE_CSS_VARIABLES: Readonly<Record<SemanticColorToken, string>>;
+export interface ApplyActivePaletteOptions {
+    /** Update the element whenever the active palette changes. */
+    readonly subscribe?: boolean;
+}
+export type PaletteStyleCleanup = () => void;
+/** Apply a registered palette's semantic tokens as inline CSS custom properties. */
+export declare function applyPalette(target: HTMLElement, name: string): PaletteStyleCleanup;
+/** Apply the active palette, optionally following later active-palette changes. */
+export declare function applyActivePalette(target: HTMLElement, options?: ApplyActivePaletteOptions): PaletteStyleCleanup;

package/dist/core/palettes.d.ts

@@ -0,0 +1,59 @@
+export interface SemanticColorTokens {
+    readonly primary: string;
+    readonly secondary: string;
+    readonly accent: string;
+    readonly background: string;
+    readonly surface: string;
+    readonly text: string;
+    readonly muted: string;
+    readonly border: string;
+    readonly success: string;
+    readonly warning: string;
+    readonly error: string;
+    readonly info: string;
+}
+export type SemanticColorToken = keyof SemanticColorTokens;
+export interface PaletteColorNames {
+    readonly primary: string;
+    readonly secondary: string;
+    readonly accent: string;
+}
+export interface ColorPalette {
+    readonly name: string;
+    readonly tokens: SemanticColorTokens;
+    readonly colorNames?: PaletteColorNames;
+}
+export interface PaletteInput {
+    readonly name: string;
+    readonly primary: string;
+    readonly secondary: string;
+    readonly accent: string;
+    readonly overrides?: Partial<SemanticColorTokens>;
+    readonly colorNames?: PaletteColorNames;
+}
+export type PaletteDefinition = ColorPalette | PaletteInput;
+export type PaletteChangeListener = (palette: ColorPalette | undefined) => void;
+export interface PaletteRegistryApi {
+    /** Retrieves a registered palette, or undefined when the name is unknown. */
+    get(name: string): ColorPalette | undefined;
+    /** Returns the names of registered custom palettes. */
+    list(): readonly string[];
+    /** Registers a palette. Names must be unique. */
+    register(palette: PaletteDefinition): void;
+    /** Removes a registered custom palette. */
+    remove(name: string): boolean;
+    /** Activates a registered palette and notifies subscribers when it changes. */
+    activate(name: string): void;
+    /** Returns the active palette, or undefined when none is active. */
+    getActive(): ColorPalette | undefined;
+    /** Subscribes to active-palette changes and returns an unsubscribe function. */
+    subscribe(listener: PaletteChangeListener): () => void;
+}
+export declare function registerPalette(palette: PaletteDefinition): void;
+export declare function getPalette(name: string): ColorPalette | undefined;
+export declare function listPalettes(): readonly string[];
+export declare function activatePalette(name: string): void;
+export declare function getActivePalette(): ColorPalette | undefined;
+export declare function subscribeToPaletteChanges(listener: PaletteChangeListener): () => void;
+export declare function removePalette(name: string): boolean;
+export declare const paletteRegistry: Readonly<PaletteRegistryApi>;

package/dist/core/performance-intelligence/conflicts.d.ts

@@ -0,0 +1,21 @@
+/**
+ * AF Motion — Performance Conflict Resolver
+ *
+ * Discovers and resolves competing or contradictory decisions across subsystems,
+ * enforcing stability invariants, cooldown hysteresis, and policy precedence.
+ */
+import type { PerformanceDecision, ConflictResolutionResult } from "./types.js";
+/**
+ * Resolves conflicts between proposed performance decisions.
+ *
+ * Guarantees:
+ * 1. "reduce_quality" and "increase_quality" never co-occur (downgrade wins under distress).
+ * 2. High memory pressure always suppresses "increase_quality".
+ * 3. High-priority safety actions supersede lower-priority cosmetic adjustments.
+ * 4. Deduplicates decisions targeting identical strategies or presets.
+ *
+ * @param decisions Candidate performance decisions
+ * @param precedence Optional resolution precedence ("safety" | "performance" | "quality")
+ * @returns Conflict resolution result with detected conflicts and filtered decisions
+ */
+export declare function resolvePerformanceConflicts(decisions: readonly PerformanceDecision[], precedence?: "safety" | "performance" | "quality"): ConflictResolutionResult;