af-motion 0.0.0-stage → 1.0.0

package/dist/3d/assets/cache.d.ts

@@ -0,0 +1,71 @@
+/**
+ * AF Motion 3D Asset Cache
+ *
+ * In-flight request deduplication, LRU cache eviction, reference counting,
+ * and memory-conscious disposal for 3D assets.
+ */
+import type { Asset3DEntry, AssetCacheConfig } from "./types.js";
+export declare class AssetCache3D {
+    private readonly entries;
+    private readonly inFlight;
+    private readonly maxEntries;
+    private readonly disposeOnEvict;
+    private readonly ttlMs;
+    constructor(config?: AssetCacheConfig);
+    /**
+     * Checks if an asset exists in cache and is loaded.
+     */
+    has(idOrUrl: string): boolean;
+    /**
+     * Retrieves an asset from cache if present and not expired.
+     */
+    get<T = unknown>(idOrUrl: string): Asset3DEntry<T> | undefined;
+    /**
+     * Checks for an active in-flight loading promise to prevent duplicate network calls.
+     */
+    getInFlight<T = unknown>(idOrUrl: string): Promise<Asset3DEntry<T>> | undefined;
+    /**
+     * Registers an in-flight loading promise for deduplication.
+     */
+    setInFlight<T = unknown>(idOrUrl: string, promise: Promise<Asset3DEntry<T>>): void;
+    /**
+     * Clears an in-flight loading promise once complete.
+     */
+    clearInFlight(idOrUrl: string): void;
+    /**
+     * Stores a loaded or errored entry into the cache and evicts old entries if necessary.
+     */
+    set<T = unknown>(id: string, entry: Asset3DEntry<T>): void;
+    /**
+     * Increments the reference count of an asset.
+     */
+    retain(idOrUrl: string): number;
+    /**
+     * Decrements reference count and disposes if 0 and not cached.
+     */
+    release(idOrUrl: string): number;
+    /**
+     * Removes and optionally disposes an asset from the cache.
+     */
+    evict(idOrUrl: string): boolean;
+    /**
+     * Evicts the least recently used entry that is not actively referenced.
+     */
+    private evictOldest;
+    /**
+     * Clears the entire cache and disposes loaded assets.
+     */
+    clear(): void;
+    /**
+     * Returns cache stats.
+     */
+    getStats(): {
+        size: number;
+        inFlightCount: number;
+        maxEntries: number;
+    };
+    /**
+     * Returns all entries currently in cache.
+     */
+    getAllEntries(): readonly Asset3DEntry[];
+}

package/dist/3d/assets/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * AF Motion 3D Assets Module
+ */
+export * from "./types.js";
+export * from "./validation.js";
+export * from "./inspection.js";
+export * from "./loaders.js";
+export * from "./cache.js";
+export * from "./manager.js";
+export * from "./scene-integration.js";

package/dist/3d/assets/inspection.d.ts

@@ -0,0 +1,19 @@
+/**
+ * AF Motion 3D Scene Graph Inspection & Resource Disposal
+ *
+ * Framework-independent inspection and deep resource cleanup for 3D model
+ * scene graphs, geometries, materials, animations, and textures.
+ */
+import type { ModelInspectionMetadata } from "./types.js";
+/**
+ * Traverses a 3D scene graph or object tree and extracts comprehensive metadata.
+ */
+export declare function inspectModelGraph(root: unknown): ModelInspectionMetadata;
+/**
+ * Deeply disposes a 3D model, its geometries, materials, and textures.
+ */
+export declare function deepDisposeModel(root: unknown): void;
+/**
+ * Clones a 3D model for independent scene-graph placement without sharing transforms.
+ */
+export declare function instantiateModel<T = unknown>(model: T): T;

package/dist/3d/assets/loaders.d.ts

@@ -0,0 +1,30 @@
+/**
+ * AF Motion 3D Asset Loaders
+ *
+ * Pluggable loader implementations including mock loaders for testing and
+ * optional Three.js loaders (GLTFLoader, OBJLoader) with cancellation and progress.
+ */
+import type { Asset3DDefinition, AssetLoader3D } from "./types.js";
+/**
+ * Creates a mock asset loader for testing, simulation, and SSR environments.
+ */
+export declare function createMockAssetLoader(options?: {
+    delayMs?: number;
+    mockDataFactory?: (def: Asset3DDefinition) => unknown;
+    mockError?: string;
+}): AssetLoader3D;
+/**
+ * Creates an optional Three.js GLTF/GLB loader adapter.
+ */
+export declare function createThreeGLTFLoader(options?: {
+    threeInstance?: any;
+    gltfLoaderConstructor?: any;
+    dracoDecoderPath?: string;
+}): AssetLoader3D;
+/**
+ * Creates an optional Three.js OBJ loader adapter.
+ */
+export declare function createThreeOBJLoader(options?: {
+    threeInstance?: any;
+    objLoaderConstructor?: any;
+}): AssetLoader3D;

package/dist/3d/assets/manager.d.ts

@@ -0,0 +1,69 @@
+/**
+ * AF Motion 3D Asset Manager
+ *
+ * Central coordinator for 3D asset loading, caching, deduplication,
+ * lifecycle management, progress tracking, and memory cleanup.
+ */
+import type { Asset3DDefinition, Asset3DEntry, Asset3DLoadOptions, AssetLoader3D, AssetManagerStats } from "./types.js";
+import { AssetCache3D } from "./cache.js";
+export declare class AssetManager3D {
+    private readonly cache;
+    private readonly loaders;
+    constructor(options?: {
+        cache?: AssetCache3D;
+    });
+    /**
+     * Registers a 3D asset loader. Newly registered loaders take precedence.
+     */
+    registerLoader(loader: AssetLoader3D): void;
+    /**
+     * Unregisters a loader by name.
+     */
+    unregisterLoader(name: string): boolean;
+    /**
+     * Finds a suitable loader for the given asset definition.
+     */
+    findLoader(definition: Asset3DDefinition): AssetLoader3D | undefined;
+    /**
+     * Loads a 3D asset with caching, deduplication, and cancellation support.
+     */
+    load<T = unknown>(definitionOrUrl: Asset3DDefinition | string, options?: Asset3DLoadOptions): Promise<Asset3DEntry<T>>;
+    /**
+     * Retrieves an asset from cache if available.
+     */
+    get<T = unknown>(idOrUrl: string): Asset3DEntry<T> | undefined;
+    /**
+     * Returns a clone/instance of a loaded model so scene transformations are independent.
+     */
+    instantiate<T = unknown>(idOrUrl: string): T | undefined;
+    /**
+     * Increments reference count.
+     */
+    retain(idOrUrl: string): number;
+    /**
+     * Decrements reference count.
+     */
+    release(idOrUrl: string): number;
+    /**
+     * Unloads and disposes a single asset.
+     */
+    unload(idOrUrl: string): boolean;
+    /**
+     * Clears all assets and disposers.
+     */
+    clear(): void;
+    /**
+     * Returns asset manager statistics.
+     */
+    getStats(): AssetManagerStats;
+    /**
+     * Configures optional Three.js model loaders (GLTF and OBJ).
+     */
+    enableThreeLoaders(options?: {
+        threeInstance?: any;
+        gltfLoaderConstructor?: any;
+        objLoaderConstructor?: any;
+    }): void;
+}
+export declare function getDefaultAssetManager(): AssetManager3D;
+export declare function resetDefaultAssetManager(): void;

package/dist/3d/assets/scene-integration.d.ts

@@ -0,0 +1,23 @@
+/**
+ * AF Motion 3D Scene Schema Asset Integration
+ *
+ * Discovers and preloads assets referenced in Prompt 77 Scene Specifications.
+ */
+import type { Scene3DSpecification } from "../schemas/types.js";
+import type { Asset3DDefinition, Asset3DLoadOptions } from "./types.js";
+import { AssetManager3D } from "./manager.js";
+/**
+ * Scans a scene graph for all model and texture asset references.
+ */
+export declare function discoverSceneAssetReferences(scene: Scene3DSpecification): Asset3DDefinition[];
+/**
+ * Preloads all assets required by a scene specification.
+ */
+export declare function preloadSceneAssets(scene: Scene3DSpecification, options?: {
+    manager?: AssetManager3D;
+    loadOptions?: Asset3DLoadOptions;
+}): Promise<{
+    total: number;
+    loaded: number;
+    errors: Record<string, string>;
+}>;

package/dist/3d/assets/types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * AF Motion 3D Asset Management Types
+ *
+ * Framework-independent definitions for 3D assets, loading lifecycles,
+ * scene graph inspection metadata, caching, and disposal contracts.
+ */
+import type { BoundingBox3D } from "../schemas/types.js";
+export type Asset3DFormat = "gltf" | "glb" | "obj" | "fbx" | "usdz" | "json" | "texture" | "custom";
+export type Asset3DStatus = "idle" | "loading" | "loaded" | "error" | "disposed";
+export interface AnimationClipMetadata {
+    readonly name: string;
+    readonly duration: number;
+    readonly tracksCount: number;
+}
+export interface ModelInspectionMetadata {
+    readonly vertexCount: number;
+    readonly triangleCount: number;
+    readonly meshCount: number;
+    readonly materialCount: number;
+    readonly nodeCount: number;
+    readonly hasAnimations: boolean;
+    readonly animationClips: readonly AnimationClipMetadata[];
+    readonly boundingBox?: BoundingBox3D;
+    readonly meshNames: readonly string[];
+    readonly materialNames: readonly string[];
+    readonly inspectedAt?: number;
+}
+export interface Asset3DDefinition {
+    readonly id: string;
+    readonly url: string;
+    readonly format?: Asset3DFormat;
+    readonly name?: string;
+    readonly sizeBytes?: number;
+    readonly dependencies?: readonly string[];
+    readonly metadata?: Record<string, unknown>;
+}
+export interface Asset3DEntry<T = unknown> {
+    readonly id: string;
+    readonly url: string;
+    readonly format: Asset3DFormat;
+    readonly status: Asset3DStatus;
+    readonly data?: T;
+    readonly progress: number;
+    readonly error?: string;
+    readonly metadata?: ModelInspectionMetadata | Record<string, unknown>;
+    readonly refCount: number;
+    readonly loadedAt?: number;
+    readonly lastAccessedAt: number;
+}
+export interface Asset3DLoadOptions {
+    readonly signal?: AbortSignal;
+    readonly onProgress?: (progress: number) => void;
+    readonly headers?: Record<string, string>;
+    readonly credentials?: "omit" | "same-origin" | "include";
+    readonly forceReload?: boolean;
+    readonly draco?: boolean;
+    readonly customLoader?: AssetLoader3D;
+    readonly loaderOptions?: Record<string, unknown>;
+}
+export interface AssetCacheConfig {
+    readonly maxEntries?: number;
+    readonly maxSizeBytes?: number;
+    readonly ttlMs?: number;
+    readonly disposeOnEvict?: boolean;
+}
+export interface AssetLoader3D<T = unknown> {
+    readonly name: string;
+    readonly formats: readonly Asset3DFormat[];
+    readonly canLoad?: (definition: Asset3DDefinition) => boolean;
+    readonly load: (definition: Asset3DDefinition, options?: Asset3DLoadOptions) => Promise<T>;
+    readonly inspect?: (data: T) => ModelInspectionMetadata;
+    readonly dispose?: (data: T) => void;
+    readonly clone?: (data: T) => T;
+}
+export interface AssetManagerStats {
+    readonly count: number;
+    readonly inFlight: number;
+    readonly loaded: number;
+    readonly error: number;
+}

package/dist/3d/assets/validation.d.ts

@@ -0,0 +1,12 @@
+/**
+ * AF Motion 3D Asset Validation and Correction
+ */
+import type { Asset3DDefinition, Asset3DFormat } from "./types.js";
+export declare function inferAssetFormat(url: string): Asset3DFormat;
+export declare function validateAssetDefinition(definition: unknown): {
+    valid: boolean;
+    errors: string[];
+};
+export declare function correctAssetDefinition(definition: Partial<Asset3DDefinition> & {
+    url?: string;
+}): Asset3DDefinition;

package/dist/3d/camera/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * AF Motion 3D Camera Intelligence Module
+ */
+export * from "./types.js";
+export * from "./presets.js";
+export * from "./transitions.js";
+export * from "./validation.js";

package/dist/3d/camera/presets.d.ts

@@ -0,0 +1,8 @@
+/**
+ * AF Motion 3D Camera Presets
+ *
+ * Deterministic camera configurations for standard staging modes.
+ */
+import type { CameraPresetName, IntelligentCameraConfig } from "./types.js";
+export declare const CAMERA_PRESETS: Readonly<Record<CameraPresetName, IntelligentCameraConfig>>;
+export declare function getCameraPreset(name: CameraPresetName): IntelligentCameraConfig;

package/dist/3d/camera/transitions.d.ts

@@ -0,0 +1,19 @@
+/**
+ * AF Motion 3D Camera Transitions & Constraints
+ *
+ * Smooth interpolation, responsive adaptation, and spatial constraint enforcement.
+ */
+import type { Camera3DConfig } from "../types.js";
+import type { CameraConstraints, IntelligentCameraConfig } from "./types.js";
+/**
+ * Interpolate smoothly between two camera states.
+ */
+export declare function interpolateCamera(from: Camera3DConfig, to: Camera3DConfig, progress: number): Camera3DConfig;
+/**
+ * Clamp camera attributes within configured constraints.
+ */
+export declare function applyCameraConstraints(camera: Camera3DConfig, constraints?: CameraConstraints): Camera3DConfig;
+/**
+ * Resolve responsive FOV based on viewport width.
+ */
+export declare function resolveResponsiveFov(config: IntelligentCameraConfig, viewportWidth?: number): number;

package/dist/3d/camera/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * AF Motion 3D Camera Intelligence Contracts
+ *
+ * Types for camera configurations, constraints, follow tracking,
+ * smooth transitions, and responsive presets.
+ */
+import type { Camera3DConfig, Vector3Tuple } from "../types.js";
+export type CameraPresetName = "hero" | "isometric" | "portrait" | "wide" | "top-down" | "cinematic" | "macro";
+export interface CameraConstraints {
+    readonly minFov?: number;
+    readonly maxFov?: number;
+    readonly minDistance?: number;
+    readonly maxDistance?: number;
+    readonly minPitch?: number;
+    readonly maxPitch?: number;
+    readonly minYaw?: number;
+    readonly maxYaw?: number;
+}
+export interface CameraFollowTarget {
+    readonly target: Vector3Tuple;
+    readonly offset?: Vector3Tuple;
+    readonly stiffness?: number;
+}
+export interface CameraTransitionOptions {
+    readonly duration?: number;
+    readonly easing?: string;
+}
+export interface IntelligentCameraConfig extends Camera3DConfig {
+    readonly preset?: CameraPresetName;
+    readonly constraints?: CameraConstraints;
+    readonly followTarget?: CameraFollowTarget;
+    readonly responsiveFov?: {
+        readonly mobile?: number;
+        readonly tablet?: number;
+        readonly desktop?: number;
+    };
+}

package/dist/3d/camera/validation.d.ts

@@ -0,0 +1,9 @@
+/**
+ * AF Motion 3D Camera Validation & Safe Correction
+ */
+import type { IntelligentCameraConfig } from "./types.js";
+export declare function validateCameraConfig(config: unknown): {
+    valid: boolean;
+    errors: string[];
+};
+export declare function correctCameraConfig(raw: unknown): IntelligentCameraConfig;

package/dist/3d/capabilities.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AF Motion 3D Capability Detection
+ *
+ * Safe detection of WebGL, WebGL2, WebGPU, GPU limits, and display preferences.
+ */
+import type { Scene3DCapabilities } from "./types.js";
+/**
+ * Detect available 3D rendering capabilities in the current environment.
+ * Safe for SSR, Node, and headless test runners.
+ */
+export declare function detect3DCapabilities(forceRefresh?: boolean): Scene3DCapabilities;

package/dist/3d/composition/fallback.d.ts

@@ -0,0 +1,20 @@
+/**
+ * AF Motion 3D Scene Fallback Engine
+ *
+ * Capability-aware fallback resolution: inspects scene specifications against
+ * rendering capabilities, degrading lighting, materials, models, shadows, and
+ * motion controls safely before rendering.
+ */
+import type { Scene3DCapabilities } from "../types.js";
+import type { Scene3DSpecification } from "../schemas/types.js";
+import type { Scene3DFallbackDecision } from "./types.js";
+export interface FallbackResolutionOptions {
+    readonly capabilities?: Partial<Scene3DCapabilities>;
+    readonly disableShadows?: boolean;
+    readonly disableTransmission?: boolean;
+    readonly allowModels?: boolean;
+    readonly supportedModelFormats?: readonly string[];
+    readonly forceReducedMotion?: boolean;
+    readonly maxObjects?: number;
+}
+export declare function resolve3DSceneFallbacks(spec: Scene3DSpecification, options?: FallbackResolutionOptions): Scene3DFallbackDecision;

package/dist/3d/composition/generation.d.ts

@@ -0,0 +1,24 @@
+/**
+ * AF Motion AI 3D Scene Generation
+ *
+ * Deterministic pipeline for generating complete, validated, capability-safe
+ * 3D scene specifications from natural-language descriptions or structured intents.
+ */
+import type { Scene3DSpecification } from "../schemas/types.js";
+import { type ValidationReport } from "../schemas/validation.js";
+import { type FallbackResolutionOptions } from "./fallback.js";
+import type { Scene3DFallbackDecision, Scene3DIntent } from "./types.js";
+export interface Scene3DGenerationResult {
+    readonly spec: Scene3DSpecification;
+    readonly fallbackDecision: Scene3DFallbackDecision;
+    readonly validationReport: ValidationReport;
+    readonly appliedIntent: Scene3DIntent;
+}
+/**
+ * Extracts structured intent from a natural-language description.
+ */
+export declare function parseNaturalLanguageSceneIntent(description: string): Scene3DIntent;
+/**
+ * Generates a complete, capability-checked, validated 3D scene from an intent or prompt.
+ */
+export declare function generate3DSceneFromIntent(intentOrPrompt: Scene3DIntent | string, options?: FallbackResolutionOptions): Scene3DGenerationResult;

package/dist/3d/composition/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * AF Motion 3D Scene Composition Module
+ *
+ * Public entrypoint for 3D compositions, AI scene generation,
+ * machine-readable recipes, capability-aware fallbacks, and adaptive performance.
+ */
+export * from "./types.js";
+export * from "./quality.js";
+export * from "./fallback.js";
+export * from "./recipes.js";
+export * from "./generation.js";
+export * from "./unified.js";

package/dist/3d/composition/quality.d.ts

@@ -0,0 +1,35 @@
+/**
+ * AF Motion 3D Scene Performance & Adaptive Quality
+ *
+ * Quality profiles, dynamic DPR scaling, frame-time monitoring,
+ * and visibility suspension for 3D compositions.
+ */
+import type { Scene3DQualityLevel, Scene3DQualityProfile } from "./types.js";
+export declare const SCENE_3D_QUALITY_PROFILES: Record<Scene3DQualityLevel, Scene3DQualityProfile>;
+export declare function resolveScene3DQualityProfile(level?: Scene3DQualityLevel): Scene3DQualityProfile;
+export declare class Scene3DPerformanceMonitor {
+    private profile;
+    private isVisible;
+    private readonly frameDeltas;
+    private lastFrameTime;
+    private readonly windowSize;
+    private consecutiveLowFpsCount;
+    private onQualityDegrade?;
+    constructor(options?: {
+        initialProfile?: Scene3DQualityLevel;
+        onQualityDegrade?: (newLevel: Scene3DQualityLevel) => void;
+    });
+    getProfile(): Scene3DQualityProfile;
+    setProfile(level: Scene3DQualityLevel): void;
+    setVisibility(visible: boolean): void;
+    shouldRender(): boolean;
+    /**
+     * Records a rendered frame timestamp and tracks FPS health.
+     */
+    recordFrame(now?: number): void;
+    getAverageFps(): number;
+    /**
+     * Automatically drops quality level by one step when under performance strain.
+     */
+    private degradeProfile;
+}

package/dist/3d/composition/recipes.d.ts

@@ -0,0 +1,34 @@
+/**
+ * AF Motion 3D Scene Recipes
+ *
+ * Machine-readable, production-grade recipes for 3D scene compositions:
+ * 1. product-showcase
+ * 2. cinematic-hero
+ * 3. abstract-environment
+ * 4. interactive-portfolio
+ * 5. spatial-storytelling
+ * 6. architectural-viz
+ * 7. floating-object
+ * 8. scroll-product-narrative
+ */
+import type { Scene3DSpecification } from "../schemas/types.js";
+export type Scene3DRecipeName = "product-showcase" | "cinematic-hero" | "abstract-environment" | "interactive-portfolio" | "spatial-storytelling" | "architectural-viz" | "floating-object" | "scroll-product-narrative";
+export interface Scene3DRecipeOptions {
+    readonly id?: string;
+    readonly name?: string;
+    readonly primaryColor?: string;
+    readonly secondaryColor?: string;
+    readonly modelUrl?: string;
+    readonly fov?: number;
+}
+export interface RecipeDescriptor {
+    readonly name: Scene3DRecipeName;
+    readonly title: string;
+    readonly description: string;
+    readonly defaultCamera: string;
+    readonly defaultLighting: string;
+}
+export declare const SCENE_3D_RECIPES_META: readonly RecipeDescriptor[];
+export declare const SCENE_3D_RECIPES: Record<Scene3DRecipeName, (options?: Scene3DRecipeOptions) => Scene3DSpecification>;
+export declare function getSceneRecipe(name: Scene3DRecipeName, options?: Scene3DRecipeOptions): Scene3DSpecification;
+export declare function listSceneRecipes(): readonly RecipeDescriptor[];

package/dist/3d/composition/types.d.ts

@@ -0,0 +1,88 @@
+/**
+ * AF Motion 3D Scene Composition Types
+ *
+ * Framework-independent contracts for unified 3D scene composition,
+ * hierarchical generation, AI generation intents, recipes, and performance controls.
+ */
+import type { Vector3Tuple } from "../types.js";
+import type { Scene3DSpecification, SceneObjectSpec } from "../schemas/types.js";
+import type { AssetManager3D } from "../assets/manager.js";
+import type { InteractionManager3D } from "../interaction/manager.js";
+import type { CameraControls3D } from "../interaction/camera-controls.js";
+import type { ScrollSceneController } from "../scroll/controller.js";
+import type { CameraPresetName } from "../camera/types.js";
+import type { LightingPresetName } from "../lighting/types.js";
+import type { EnvironmentPresetName } from "../environment/types.js";
+import type { Material3DPresetName } from "../materials/types.js";
+import type { InteractionPresetName } from "../interaction/types.js";
+export type Scene3DQualityLevel = "low" | "medium" | "high" | "ultra";
+export interface Scene3DQualityProfile {
+    readonly level: Scene3DQualityLevel;
+    readonly maxDpr: number;
+    readonly antialias: boolean;
+    readonly shadows: boolean;
+    readonly maxObjects: number;
+    readonly targetFps: number;
+}
+export interface Scene3DPerformanceConfig {
+    readonly qualityProfile?: Scene3DQualityLevel;
+    readonly adaptiveDpr?: boolean;
+    readonly minDpr?: number;
+    readonly maxDpr?: number;
+    readonly suspendWhenHidden?: boolean;
+    readonly targetFps?: number;
+    readonly maxObjects?: number;
+    readonly cullingDistance?: number;
+}
+export interface Scene3DCompositionDefinition {
+    readonly id: string;
+    readonly name?: string;
+    readonly spec: Scene3DSpecification;
+    readonly recipe?: string;
+    readonly performance?: Scene3DPerformanceConfig;
+    readonly metadata?: Record<string, unknown>;
+}
+export interface Scene3DFallbackDecision {
+    readonly originalSpec: Scene3DSpecification;
+    readonly resolvedSpec: Scene3DSpecification;
+    readonly modifications: readonly string[];
+    readonly warnings: readonly string[];
+    readonly degradedFeatures: readonly string[];
+    readonly canRender: boolean;
+}
+export interface Scene3DIntent {
+    readonly description?: string;
+    readonly visualStyle?: string;
+    readonly mood?: string;
+    readonly cameraStaging?: CameraPresetName;
+    readonly lightingPreset?: LightingPresetName;
+    readonly environmentPreset?: EnvironmentPresetName;
+    readonly materialPreset?: Material3DPresetName;
+    readonly interactionMode?: InteractionPresetName;
+    readonly scrollTimelinePreset?: string;
+    readonly objects?: readonly {
+        readonly id?: string;
+        readonly name?: string;
+        readonly type?: string;
+        readonly primitive?: string;
+        readonly modelUrl?: string;
+        readonly materialPreset?: Material3DPresetName;
+        readonly position?: Vector3Tuple;
+        readonly scale?: Vector3Tuple;
+    }[];
+    readonly reducedMotion?: boolean;
+}
+export interface Scene3DCompositionInstance {
+    readonly id: string;
+    readonly definition: Scene3DCompositionDefinition;
+    readonly spec: Scene3DSpecification;
+    readonly assetManager: AssetManager3D;
+    readonly interactionManager?: InteractionManager3D;
+    readonly cameraControls?: CameraControls3D;
+    readonly scrollController?: ScrollSceneController;
+    readonly fallbackDecision?: Scene3DFallbackDecision;
+    readonly updateSpec: (updater: (prev: Scene3DSpecification) => Scene3DSpecification) => Scene3DSpecification;
+    readonly updateObject: (id: string, partial: Partial<SceneObjectSpec>) => void;
+    readonly setQuality: (quality: Scene3DQualityLevel) => void;
+    readonly destroy: () => void;
+}

package/dist/3d/composition/unified.d.ts

@@ -0,0 +1,18 @@
+/**
+ * AF Motion Unified 3D Composition Engine
+ *
+ * Coordinates scene lifecycle, capability-safe fallbacks, asset loading,
+ * interaction controls, scroll timeline synchronization, and adaptive quality.
+ */
+import { AssetManager3D } from "../assets/manager.js";
+import type { Scene3DCapabilities } from "../types.js";
+import type { Scene3DSpecification } from "../schemas/types.js";
+import type { Scene3DCompositionDefinition, Scene3DCompositionInstance, Scene3DQualityLevel } from "./types.js";
+export interface Scene3DCompositionOptions {
+    readonly domElement?: HTMLElement;
+    readonly assetManager?: AssetManager3D;
+    readonly capabilities?: Partial<Scene3DCapabilities>;
+    readonly onQualityDegrade?: (level: Scene3DQualityLevel) => void;
+    readonly onSpecChange?: (spec: Scene3DSpecification) => void;
+}
+export declare function createScene3DComposition(definition: Scene3DCompositionDefinition, options?: Scene3DCompositionOptions): Scene3DCompositionInstance;

package/dist/3d/environment/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * AF Motion 3D Environment Intelligence Module
+ */
+export * from "./types.js";
+export * from "./presets.js";
+export * from "./validation.js";