af-motion 0.0.0-stage → 1.0.0

package/dist/core/design-system.d.ts

@@ -0,0 +1,206 @@
+import { type ColorPalette, type PaletteInput } from "./palettes.js";
+import { type MotionDNA } from "./motion-dna.js";
+import { type EasingOption } from "../easing/easings.js";
+export declare const DESIGN_SYSTEM_SCHEMA_VERSION = "1.0.0";
+export interface DesignSystemTypographyTokens {
+    readonly fontFamilies?: {
+        readonly sans?: string;
+        readonly serif?: string;
+        readonly mono?: string;
+        readonly [key: string]: string | undefined;
+    };
+    readonly fontSizes?: {
+        readonly xs?: string | number;
+        readonly sm?: string | number;
+        readonly md?: string | number;
+        readonly lg?: string | number;
+        readonly xl?: string | number;
+        readonly "2xl"?: string | number;
+        readonly [key: string]: string | number | undefined;
+    };
+    readonly lineHeights?: {
+        readonly tight?: number | string;
+        readonly normal?: number | string;
+        readonly loose?: number | string;
+        readonly [key: string]: number | string | undefined;
+    };
+    readonly letterSpacings?: {
+        readonly tight?: string;
+        readonly normal?: string;
+        readonly wide?: string;
+        readonly [key: string]: string | undefined;
+    };
+}
+export interface DesignSystemSpacingTokens {
+    readonly baseUnit?: number;
+    readonly space?: {
+        readonly none?: number;
+        readonly xs?: number;
+        readonly sm?: number;
+        readonly md?: number;
+        readonly lg?: number;
+        readonly xl?: number;
+        readonly "2xl"?: number;
+        readonly [key: string]: number | undefined;
+    };
+    readonly distance?: {
+        readonly subtle?: number;
+        readonly moderate?: number;
+        readonly pronounced?: number;
+        readonly dramatic?: number;
+        readonly [key: string]: number | undefined;
+    };
+}
+export interface DesignSystemMotionTimingTokens {
+    readonly instant?: number;
+    readonly fastest?: number;
+    readonly fast?: number;
+    readonly normal?: number;
+    readonly slow?: number;
+    readonly deliberate?: number;
+    readonly [key: string]: number | undefined;
+}
+export interface DesignSystemEasingTokens {
+    readonly standard?: EasingOption;
+    readonly entrance?: EasingOption;
+    readonly exit?: EasingOption;
+    readonly expressive?: EasingOption;
+    readonly snappy?: EasingOption;
+    readonly bounce?: EasingOption;
+    readonly [key: string]: EasingOption | undefined;
+}
+export interface DesignSystemInteractionTokens {
+    readonly hoverScale?: number;
+    readonly pressScale?: number;
+    readonly focusRingWidth?: number;
+    readonly elevationDistance?: number;
+    readonly transitionDuration?: number;
+    readonly [key: string]: number | undefined;
+}
+export interface DesignSystemMetadata {
+    readonly author?: string;
+    readonly license?: string;
+    readonly description?: string;
+    readonly tags?: readonly string[];
+    readonly [key: string]: unknown;
+}
+export interface DesignSystemDefinition {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    /** Palette name (from built-in or registered custom palettes) or full color palette */
+    readonly palette?: string | ColorPalette | PaletteInput;
+    /** Optional Motion DNA identity name or full MotionDNA object */
+    readonly motionDNA?: string | MotionDNA;
+    /** Typography tokens relevant to motion/transitions */
+    readonly typography?: DesignSystemTypographyTokens;
+    /** Spacing and movement scales */
+    readonly spacing?: DesignSystemSpacingTokens;
+    /** Durations for various timing categories */
+    readonly timing?: DesignSystemMotionTimingTokens;
+    /** Preferred easing curves for interactions and transitions */
+    readonly easings?: DesignSystemEasingTokens;
+    /** Interaction conventions (hover, press, elevation) */
+    readonly interaction?: DesignSystemInteractionTokens;
+    /** Overall motion intensity multiplier (default 1.0) */
+    readonly intensity?: number;
+    /** Machine-readable metadata */
+    readonly metadata?: DesignSystemMetadata;
+}
+export interface DesignSystem extends DesignSystemDefinition {
+    /** Resolved active ColorPalette object if palette was specified */
+    readonly resolvedPalette?: ColorPalette;
+    /** Resolved active MotionDNA object if motionDNA was specified */
+    readonly resolvedMotionDNA?: MotionDNA;
+}
+export interface DesignSystemValidationError {
+    readonly parameter?: string;
+    readonly message: string;
+}
+export interface DesignSystemValidationResult {
+    readonly valid: boolean;
+    readonly errors: readonly DesignSystemValidationError[];
+}
+export interface DesignSystemsDocument {
+    readonly $schema: string;
+    readonly version: string;
+    readonly totalDesignSystems: number;
+    readonly designSystems: readonly DesignSystem[];
+}
+/**
+ * Validates a design system definition against required fields and constraints.
+ */
+export declare function validateDesignSystem(system: unknown): DesignSystemValidationResult;
+/**
+ * Creates and resolves a design system from a definition with deep freeze immutability.
+ */
+export declare function createDesignSystem(definition: DesignSystemDefinition): DesignSystem;
+export declare const BUILT_IN_DESIGN_SYSTEMS: readonly DesignSystem[];
+/**
+ * Registers a user-defined design system in the registry. Built-in names are protected.
+ */
+export declare function registerDesignSystem(name: string, system: DesignSystemDefinition): void;
+/**
+ * Retrieves a registered or built-in design system by ID or name.
+ */
+export declare function getDesignSystem(nameOrId: string): DesignSystem | undefined;
+/**
+ * Lists all registered design systems (built-ins + custom additions).
+ */
+export declare function listDesignSystems(): readonly DesignSystem[];
+/**
+ * Searches design systems by keyword query matching ID, name, description, or tags.
+ */
+export declare function searchDesignSystems(query: string): readonly DesignSystem[];
+/**
+ * Clones a design system and applies overrides without mutating the original.
+ */
+export declare function cloneDesignSystem(source: string | DesignSystem, overrides?: Partial<DesignSystemDefinition>): DesignSystem;
+/**
+ * Removes a custom design system from the registry. Built-in systems cannot be removed.
+ */
+export declare function removeDesignSystem(name: string): boolean;
+/**
+ * Resolves a design system by name or object, applying optional overrides.
+ */
+export declare function resolveDesignSystem(source: string | DesignSystem, overrides?: Partial<DesignSystemDefinition>): DesignSystem;
+/**
+ * Traverses and resolves any nested design system token by dot-notated path with optional fallback.
+ */
+export declare function resolveDesignToken<T = unknown>(system: DesignSystem, tokenPath: string, fallback?: T): T;
+/**
+ * Resolves a motion timing duration from the design system timing scale or fallback.
+ */
+export declare function resolveMotionTiming(system: DesignSystem, keyOrCategory: string, fallback?: number): number;
+/**
+ * Resolves a movement distance from the design system spacing distance scale or fallback.
+ */
+export declare function resolveMovementDistance(system: DesignSystem, keyOrScale: string, fallback?: number): number;
+/**
+ * Returns the currently active design system.
+ */
+export declare function getActiveDesignSystem(): DesignSystem | undefined;
+/**
+ * Sets the active design system, optionally activating its palette, and notifies subscribers.
+ */
+export declare function setActiveDesignSystem(nameOrSystem: string | DesignSystem | undefined): void;
+/**
+ * Subscribes to active design system changes, returning an unsubscribe cleanup function.
+ */
+export declare function subscribeToDesignSystem(listener: (system: DesignSystem | undefined) => void): () => void;
+/**
+ * Resets custom design systems and restores active design system to "default" (for test isolation).
+ */
+export declare function resetDesignSystemRegistry(): void;
+/**
+ * Serializes a design system to formatted JSON.
+ */
+export declare function exportDesignSystemJson(system: DesignSystem, pretty?: boolean): string;
+/**
+ * Exports all registered design systems as a versioned document.
+ */
+export declare function exportDesignSystemsDocument(): DesignSystemsDocument;
+/**
+ * Imports and validates a design system from a JSON string.
+ */
+export declare function importDesignSystemFromJson(json: string): DesignSystem;

package/dist/core/design-to-motion/design-analyzer.d.ts

@@ -0,0 +1,13 @@
+/**
+ * AF Motion Design-to-Motion Analysis Engine (Prompt 142)
+ *
+ * Evaluates element hierarchy, visual importance, interactive capabilities,
+ * repeated groupings, accessibility constraints, and maps design characteristics
+ * to semantic motion intent using Prompt 141 AI Motion Intelligence.
+ */
+import type { NormalizedDesignInput } from "./input-parser.js";
+import type { DesignAnalysisResult } from "./types.js";
+/**
+ * Analyzes the normalized design specification and infers motion requirements.
+ */
+export declare function analyzeDesignSpecification(normalized: NormalizedDesignInput): DesignAnalysisResult;

package/dist/core/design-to-motion/engine.d.ts

@@ -0,0 +1,34 @@
+/**
+ * AF Motion Design-to-Motion Master Engine (Prompt 142)
+ *
+ * Coordinates the full Design-to-Motion pipeline:
+ * Input Parsing → Design Analysis → Motion Intent → Motion Planning →
+ * Configuration Generation → Validation → Export Artifact Generation.
+ *
+ * Deterministic, offline, zero external LLM API requirement.
+ */
+import type { DesignToMotionInput, DesignToMotionOptions, GeneratedMotionResult, IDesignToMotionProvider } from "./types.js";
+export declare class DesignToMotionEngine implements IDesignToMotionProvider {
+    readonly id = "af-motion-design-to-motion-engine";
+    readonly name = "AF Motion Design-to-Motion Engine";
+    private readonly cache;
+    private readonly maxCacheSize;
+    constructor(options?: {
+        maxCacheSize?: number;
+    });
+    /**
+     * Generates production-ready motion configurations synchronously.
+     */
+    generateSync(input: DesignToMotionInput, options?: DesignToMotionOptions): GeneratedMotionResult;
+    /**
+     * Generates production-ready motion configurations asynchronously with timeout/abort support.
+     */
+    generate(input: DesignToMotionInput, options?: DesignToMotionOptions): Promise<GeneratedMotionResult>;
+    /**
+     * Clears engine cache.
+     */
+    clearCache(): void;
+    private computeCacheKey;
+    private putCache;
+}
+export declare const designToMotionEngine: DesignToMotionEngine;

package/dist/core/design-to-motion/generator.d.ts

@@ -0,0 +1,16 @@
+/**
+ * AF Motion Design-to-Motion Configuration Generator (Prompt 142)
+ *
+ * Generates structured, validated MotionComposition instances, element animations,
+ * and multi-format export code artifacts (React, Vanilla TS/JS, JSON).
+ */
+import type { DesignAnalysisResult, MotionPlan, DesignTokenContext, DesignToMotionInput, DesignToMotionExportArtifacts } from "./types.js";
+import { type MotionComposition } from "../composition.js";
+/**
+ * Builds a valid MotionComposition instance from analysis, plan, and tokens.
+ */
+export declare function generateMotionComposition(analysis: DesignAnalysisResult, plan: MotionPlan, tokens: Required<DesignTokenContext>, sourceInput: DesignToMotionInput): MotionComposition;
+/**
+ * Generates multi-format code export artifacts (React, Vanilla TS, Composition JSON, CSS).
+ */
+export declare function generateExportArtifacts(composition: MotionComposition, plan: MotionPlan, tokens: Required<DesignTokenContext>): DesignToMotionExportArtifacts;

package/dist/core/design-to-motion/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * AF Motion Design-to-Motion Subsystem (Prompt 142)
+ *
+ * Transforms visual design specifications, natural-language briefs, and design tokens
+ * into production-ready AF Motion configurations with validation, pattern matching,
+ * and multi-format code export.
+ */
+export * from "./types.js";
+export * from "./input-parser.js";
+export * from "./design-analyzer.js";
+export * from "./motion-planner.js";
+export * from "./generator.js";
+export * from "./validator.js";
+export * from "./presets.js";
+export * from "./engine.js";

package/dist/core/design-to-motion/input-parser.d.ts

@@ -0,0 +1,17 @@
+/**
+ * AF Motion Design-to-Motion Input Parser (Prompt 142)
+ *
+ * Validates, normalizes, and synthesizes structured design specifications
+ * from natural-language descriptions, structured inputs, and design tokens.
+ */
+import type { DesignToMotionInput, DesignStructuredSpecification, DesignTokenContext } from "./types.js";
+export interface NormalizedDesignInput {
+    readonly specification: DesignStructuredSpecification;
+    readonly tokens: Required<DesignTokenContext>;
+    readonly rawPrompt?: string;
+    readonly validationIssues: readonly string[];
+}
+/**
+ * Normalizes and validates the incoming DesignToMotionInput into a fully-qualified specification.
+ */
+export declare function parseAndNormalizeDesignInput(input: DesignToMotionInput): NormalizedDesignInput;

package/dist/core/design-to-motion/motion-planner.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AF Motion Design-to-Motion Planning Engine (Prompt 142)
+ *
+ * Converts design analysis, element hierarchy, and Motion DNA personality
+ * into an orchestrated MotionPlan, querying Prompt 141's pattern knowledge base.
+ */
+import type { DesignAnalysisResult, MotionPlan, DesignTokenContext } from "./types.js";
+/**
+ * Plans the motion orchestration for the analyzed design elements.
+ */
+export declare function planMotionFromDesign(analysis: DesignAnalysisResult, tokens: Required<DesignTokenContext>): MotionPlan;

package/dist/core/design-to-motion/presets.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AF Motion Design-to-Motion Presets (Prompt 142)
+ *
+ * 10 battle-tested design-to-motion template presets covering SaaS, portfolios,
+ * landing pages, e-commerce, dashboards, editorial, mobile, interactive cards,
+ * navigation systems, and hero sections.
+ */
+import type { DesignToMotionPreset } from "./types.js";
+export declare const DESIGN_TO_MOTION_PRESETS: readonly DesignToMotionPreset[];
+export declare function listDesignToMotionPresets(): readonly DesignToMotionPreset[];
+export declare function getDesignToMotionPreset(id: string): DesignToMotionPreset | undefined;

package/dist/core/design-to-motion/react.d.ts

@@ -0,0 +1,13 @@
+import type { DesignToMotionInput, DesignToMotionOptions, GeneratedMotionResult } from "./types.js";
+export interface UseDesignToMotionReturn {
+    readonly result: GeneratedMotionResult | null;
+    readonly isGenerating: boolean;
+    readonly error: string | null;
+    readonly input: DesignToMotionInput;
+    readonly setInput: (input: DesignToMotionInput | ((prev: DesignToMotionInput) => DesignToMotionInput)) => void;
+    readonly generate: (overrideInput?: DesignToMotionInput) => Promise<GeneratedMotionResult | null>;
+    readonly applyPreset: (presetId: string) => void;
+    readonly activePresetId: string | null;
+    readonly clear: () => void;
+}
+export declare function useDesignToMotion(initialInput?: DesignToMotionInput, options?: DesignToMotionOptions): UseDesignToMotionReturn;

package/dist/core/design-to-motion/types.d.ts

@@ -0,0 +1,221 @@
+/**
+ * AF Motion Design-to-Motion Generation Types (Prompt 142)
+ *
+ * Core data contracts for transforming natural language descriptions,
+ * structured UI specifications, and design tokens into valid, production-ready
+ * AF Motion animation compositions.
+ */
+import type { MotionComposition } from "../composition.js";
+import type { AIMotionIntentType, QualityFinding, IntelligentMotionRecommendation, MotionQualityEvaluationResult } from "../ai-motion-intelligence/types.js";
+export declare const DESIGN_TO_MOTION_SPEC_VERSION = "1.0.0";
+export type DesignElementType = "button" | "card" | "modal" | "dialog" | "navigation" | "header" | "hero" | "section" | "badge" | "icon" | "image" | "input" | "text" | "tooltip" | "drawer" | "list" | "grid" | "container";
+export type DesignInteractionCapability = "hover" | "press" | "focus" | "drag" | "magnetic" | "scroll" | "swipe";
+export type MotionDNAPersonalityOption = "precise" | "playful" | "elegant" | "energetic" | "editorial-flow";
+export interface DesignTransformSpec {
+    readonly translate?: readonly [number, number, number?];
+    readonly rotate?: number;
+    readonly scale?: number | readonly [number, number];
+    readonly skew?: readonly [number, number];
+}
+export interface DesignDimensionsSpec {
+    readonly width?: number | string;
+    readonly height?: number | string;
+    readonly aspectRatio?: number;
+}
+export interface DesignPositionSpec {
+    readonly x?: number;
+    readonly y?: number;
+    readonly z?: number;
+    readonly positionType?: "relative" | "absolute" | "fixed" | "sticky";
+}
+export interface DesignStructuredElement {
+    readonly id: string;
+    readonly type: DesignElementType;
+    readonly name?: string;
+    readonly parentId?: string;
+    readonly childrenIds?: readonly string[];
+    readonly dimensions?: DesignDimensionsSpec;
+    readonly position?: DesignPositionSpec;
+    readonly opacity?: number;
+    readonly transform?: DesignTransformSpec;
+    readonly color?: {
+        readonly background?: string;
+        readonly text?: string;
+        readonly border?: string;
+        readonly accent?: string;
+    };
+    readonly typography?: {
+        readonly fontSize?: number | string;
+        readonly fontWeight?: number | string;
+        readonly lineHeight?: number | string;
+    };
+    readonly layout?: {
+        readonly display?: string;
+        readonly flexDir?: "row" | "column";
+        readonly gap?: number;
+        readonly padding?: number | readonly [number, number];
+    };
+    readonly interactionCapabilities?: readonly DesignInteractionCapability[];
+    readonly importance?: "high" | "medium" | "low" | "background";
+    readonly semanticRole?: "trigger" | "surface" | "content" | "decorative" | "overlay";
+}
+export interface DesignStructuredSpecification {
+    readonly id: string;
+    readonly title: string;
+    readonly elements: readonly DesignStructuredElement[];
+    readonly rootId?: string;
+    readonly viewportContext?: {
+        readonly width: number;
+        readonly height: number;
+        readonly isMobile?: boolean;
+    };
+}
+export interface DesignTokenContext {
+    readonly paletteName?: string;
+    readonly paletteColors?: {
+        readonly primary: string;
+        readonly secondary: string;
+        readonly accent: string;
+        readonly background: string;
+    };
+    readonly motionDNA?: MotionDNAPersonalityOption;
+    readonly timingMultiplier?: number;
+    readonly reducedMotion?: boolean;
+    readonly styleId?: string;
+}
+export interface DesignNaturalLanguageInput {
+    readonly prompt: string;
+    readonly elementContext?: Partial<DesignStructuredElement>;
+    readonly categoryHint?: string;
+    readonly targetStyle?: string;
+}
+export interface DesignToMotionInput {
+    readonly naturalLanguage?: DesignNaturalLanguageInput | string;
+    readonly specification?: DesignStructuredSpecification;
+    readonly tokens?: DesignTokenContext;
+}
+export interface AnalyzedDesignElement {
+    readonly id: string;
+    readonly type: DesignElementType;
+    readonly role: string;
+    readonly visualWeight: number;
+    readonly isInteractive: boolean;
+    readonly isGroupParent: boolean;
+    readonly isRepeated: boolean;
+    readonly suggestedEntrance: string;
+    readonly suggestedExit: string;
+    readonly suggestedInteractions: readonly DesignInteractionCapability[];
+    readonly constraints: readonly string[];
+}
+export interface DesignAnalysisResult {
+    readonly analyzedElements: readonly AnalyzedDesignElement[];
+    readonly hierarchy: {
+        readonly rootIds: readonly string[];
+        readonly depth: number;
+        readonly groups: ReadonlyArray<{
+            readonly parentId: string;
+            readonly childIds: readonly string[];
+            readonly sequenceType: "stagger" | "parallel" | "sequential";
+        }>;
+    };
+    readonly inferredIntent: AIMotionIntentType;
+    readonly intentConfidence: number;
+    readonly evidence: readonly string[];
+    readonly warnings: readonly string[];
+}
+export interface MotionElementPhasePlan {
+    readonly properties: readonly string[];
+    readonly from: Record<string, string | number>;
+    readonly to: Record<string, string | number>;
+    readonly durationMs: number;
+    readonly delayMs: number;
+    readonly easing: string;
+}
+export interface MotionElementInteractionPlan {
+    readonly hover?: {
+        readonly properties: readonly string[];
+        readonly to: Record<string, string | number>;
+        readonly durationMs: number;
+        readonly easing: string;
+    };
+    readonly press?: {
+        readonly properties: readonly string[];
+        readonly to: Record<string, string | number>;
+        readonly durationMs: number;
+        readonly easing: string;
+    };
+    readonly magnetic?: {
+        readonly radius: number;
+        readonly intensity: number;
+    };
+}
+export interface MotionPlanElement {
+    readonly elementId: string;
+    readonly name?: string;
+    readonly entrance?: MotionElementPhasePlan;
+    readonly interaction?: MotionElementInteractionPlan;
+    readonly exit?: MotionElementPhasePlan;
+}
+export interface MotionPlan {
+    readonly id: string;
+    readonly name: string;
+    readonly summary: string;
+    readonly intent: AIMotionIntentType;
+    readonly matchedPatternIds: readonly string[];
+    readonly choreographyType: "sequential" | "staggered" | "parallel" | "parent-child" | "coordinated";
+    readonly elementPlans: readonly MotionPlanElement[];
+    readonly motionDNA: MotionDNAPersonalityOption;
+    readonly durationMs: number;
+    readonly staggerDelayMs: number;
+    readonly easingCurve: string;
+    readonly springConfig?: {
+        readonly stiffness: number;
+        readonly damping: number;
+        readonly mass: number;
+    };
+}
+export interface DesignToMotionValidation {
+    readonly isValid: boolean;
+    readonly qualityScore: number;
+    readonly qualityGrade: string;
+    readonly detailedScore: MotionQualityEvaluationResult;
+    readonly findings: readonly QualityFinding[];
+    readonly recommendations: readonly IntelligentMotionRecommendation[];
+}
+export interface DesignToMotionExportArtifacts {
+    readonly reactCode: string;
+    readonly vanillaCode: string;
+    readonly compositionJson: string;
+    readonly cssVariables: Record<string, string>;
+}
+export interface GeneratedMotionResult {
+    readonly id: string;
+    readonly sourceInput: DesignToMotionInput;
+    readonly analysis: DesignAnalysisResult;
+    readonly plan: MotionPlan;
+    readonly composition: MotionComposition;
+    readonly validation: DesignToMotionValidation;
+    readonly exportArtifacts: DesignToMotionExportArtifacts;
+    readonly generatedAt: number;
+}
+export interface DesignToMotionPreset {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly category: "saas" | "portfolio" | "landing-page" | "ecommerce" | "dashboard" | "editorial" | "mobile" | "cards" | "navigation" | "hero";
+    readonly defaultInput: DesignToMotionInput;
+    readonly defaultDNA: MotionDNAPersonalityOption;
+    readonly capabilities: readonly string[];
+}
+export interface DesignToMotionOptions {
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    readonly fallbackDNA?: MotionDNAPersonalityOption;
+    readonly autoApplyRecommendations?: boolean;
+}
+export interface IDesignToMotionProvider {
+    readonly id: string;
+    readonly name: string;
+    generate(input: DesignToMotionInput, options?: DesignToMotionOptions): Promise<GeneratedMotionResult>;
+    generateSync(input: DesignToMotionInput, options?: DesignToMotionOptions): GeneratedMotionResult;
+}

package/dist/core/design-to-motion/validator.d.ts

@@ -0,0 +1,13 @@
+/**
+ * AF Motion Design-to-Motion Validation Pipeline (Prompt 142)
+ *
+ * Validates generated MotionComposition schemas, property compatibility,
+ * timing constraints, accessibility, and integrates Prompt 141's quality evaluator
+ * and recommendation engine.
+ */
+import type { MotionComposition } from "../composition.js";
+import type { DesignToMotionValidation, DesignTokenContext } from "./types.js";
+/**
+ * Validates a generated MotionComposition and produces quality evaluation & recommendations.
+ */
+export declare function validateGeneratedMotion(composition: MotionComposition, tokens: Required<DesignTokenContext>): DesignToMotionValidation;

package/dist/core/device-capabilities/classification.d.ts

@@ -0,0 +1,25 @@
+/**
+ * AF Motion — Deterministic Device Classification
+ *
+ * Multi-signal device categorization (Low/Standard/High Mobile & Desktop, Tablet, Unknown)
+ * balancing hardware concurrency, memory estimates, GPU limits, and touch characteristics.
+ */
+import type { DeviceCategory, CpuCapabilityInfo, MemoryCapabilityInfo, WebGLCapabilitiesInfo, DisplayCapabilityInfo, RuntimeEnvironmentInfo } from "./types.js";
+export interface DeviceClassificationResult {
+    readonly category: DeviceCategory;
+    readonly rationale: string;
+    readonly isMobile: boolean;
+    readonly isTablet: boolean;
+    readonly isDesktop: boolean;
+}
+/**
+ * Classifies a device profile into a deterministic category with explainable rationale.
+ */
+export declare function classifyDevice(signals: {
+    runtime: RuntimeEnvironmentInfo;
+    cpu: CpuCapabilityInfo;
+    memory: MemoryCapabilityInfo;
+    webgl: WebGLCapabilitiesInfo;
+    display: DisplayCapabilityInfo;
+    touchSupport?: boolean;
+}): DeviceClassificationResult;

package/dist/core/device-capabilities/detection.d.ts

@@ -0,0 +1,27 @@
+/**
+ * AF Motion — Consolidated Device Capability Detection Engine
+ *
+ * Core coordinator assembling runtime, hardware, graphics, display, network,
+ * classification, and scoring into a comprehensive DeviceCapabilityProfile.
+ */
+import type { DeviceCapabilityProfile, DeviceDetectionOptions } from "./types.js";
+/**
+ * Builds a consolidated device capability profile synchronously.
+ */
+export declare function detectDeviceCapabilities(options?: DeviceDetectionOptions): DeviceCapabilityProfile;
+/**
+ * Performs asynchronous advanced capability detection (probes WebGPU adapters, battery status, etc.).
+ */
+export declare function detectDeviceCapabilitiesAsync(options?: DeviceDetectionOptions): Promise<DeviceCapabilityProfile>;
+/**
+ * Returns currently cached capability profile, or runs synchronous detection if not yet populated.
+ */
+export declare function getDeviceCapabilityProfile(): DeviceCapabilityProfile;
+/**
+ * Clears cache and re-runs device capability detection.
+ */
+export declare function refreshDeviceCapabilities(options?: DeviceDetectionOptions): DeviceCapabilityProfile;
+/**
+ * Resets cached profile for testing purposes.
+ */
+export declare function resetCachedDeviceProfile(): void;

package/dist/core/device-capabilities/graphics.d.ts

@@ -0,0 +1,22 @@
+/**
+ * AF Motion — 3D & 2D Graphics Capability Detection
+ *
+ * Detailed inspection of WebGL1, WebGL2, WebGPU, shader precision, max texture limits,
+ * extension support, and hardware renderer strings without fabricating hardware specs.
+ */
+import type { RendererBackend } from "../../graphics/types.js";
+import type { WebGLCapabilitiesInfo, WebGPUCapabilitiesInfo, MockEnvironment } from "./types.js";
+export interface DetailedGraphicsReport {
+    readonly webgl: WebGLCapabilitiesInfo;
+    readonly webgpu: WebGPUCapabilitiesInfo;
+    readonly supportedBackends: readonly RendererBackend[];
+    readonly activeBackend: RendererBackend;
+}
+/**
+ * Detects comprehensive WebGL and WebGPU capabilities defensively.
+ */
+export declare function detectDetailedGraphics(options?: {
+    testCanvas?: HTMLCanvasElement | null;
+    mockEnv?: MockEnvironment;
+    probeWebGPUAdapter?: boolean;
+}): DetailedGraphicsReport;