af-motion 0.0.0-stage → 1.0.0

package/dist/3d/schemas/ai-integration.d.ts

@@ -0,0 +1,201 @@
+/**
+ * AF Motion 3D Scene Specification AI Integration
+ *
+ * Exposes machine-readable scene querying, natural-language inspection,
+ * and AI Motion Registry capability metadata.
+ */
+import type { Scene3DSpecification, SceneObjectSpec, SceneObjectType } from "./types.js";
+/**
+ * Traverse scene hierarchy and collect all objects matching optional criteria.
+ */
+export declare function querySceneObjects(spec: Scene3DSpecification, filter?: {
+    readonly type?: SceneObjectType;
+    readonly parentId?: string;
+}): readonly SceneObjectSpec[];
+/**
+ * Find an object anywhere in the scene hierarchy by its ID.
+ */
+export declare function findSceneObject(spec: Scene3DSpecification, objectId: string): SceneObjectSpec | undefined;
+/**
+ * Produce an inspectable structured summary for AI models and generation agents.
+ */
+export declare function describeSceneSpecification(spec: Scene3DSpecification): string;
+/**
+ * AI Motion Capability for 3D Scene Specifications.
+ */
+export declare const SCENE_SPECIFICATION_CAPABILITY: {
+    id: string;
+    name: string;
+    category: "composition";
+    description: string;
+    tags: string[];
+    version: string;
+    parameters: ({
+        name: string;
+        kind: "positional";
+        type: string;
+        required: boolean;
+        description: string;
+    } | {
+        name: string;
+        kind: "option";
+        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;
+        requiresDom: boolean;
+    };
+    react: {
+        available: boolean;
+        componentName: string;
+        hookName: string;
+        importPath: string;
+    };
+    schema: {
+        readonly $schema: "http://json-schema.org/draft-07/schema#";
+        readonly title: "Scene3DSpecification";
+        readonly version: "1.0.0";
+        readonly type: "object";
+        readonly required: readonly ["id", "version", "objects"];
+        readonly properties: {
+            readonly id: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+            readonly name: {
+                readonly type: "string";
+            };
+            readonly version: {
+                readonly type: "string";
+                readonly default: "1.0.0";
+            };
+            readonly coordinateSystem: {
+                readonly type: "string";
+                readonly enum: readonly ["right-handed-y-up", "left-handed-y-up"];
+                readonly default: "right-handed-y-up";
+            };
+            readonly camera: {
+                readonly type: "object";
+            };
+            readonly lighting: {
+                readonly type: "object";
+            };
+            readonly environment: {
+                readonly type: "object";
+            };
+            readonly renderer: {
+                readonly type: "object";
+            };
+            readonly objects: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "object";
+                    readonly required: readonly ["id", "type"];
+                    readonly properties: {
+                        readonly id: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                        };
+                        readonly name: {
+                            readonly type: "string";
+                        };
+                        readonly type: {
+                            readonly type: "string";
+                            readonly enum: readonly ["group", "mesh", "primitive", "light", "camera", "environment", "model", "interactive", "custom"];
+                        };
+                        readonly transform: {
+                            readonly type: "object";
+                            readonly properties: {
+                                readonly position: {
+                                    readonly type: "array";
+                                    readonly items: {
+                                        readonly type: "number";
+                                    };
+                                    readonly minItems: 3;
+                                    readonly maxItems: 3;
+                                    readonly default: readonly [0, 0, 0];
+                                };
+                                readonly rotation: {
+                                    readonly type: "array";
+                                    readonly items: {
+                                        readonly type: "number";
+                                    };
+                                    readonly minItems: 3;
+                                    readonly maxItems: 3;
+                                    readonly default: readonly [0, 0, 0];
+                                };
+                                readonly quaternion: {
+                                    readonly type: "array";
+                                    readonly items: {
+                                        readonly type: "number";
+                                    };
+                                    readonly minItems: 4;
+                                    readonly maxItems: 4;
+                                };
+                                readonly scale: {
+                                    readonly type: "array";
+                                    readonly items: {
+                                        readonly type: "number";
+                                    };
+                                    readonly minItems: 3;
+                                    readonly maxItems: 3;
+                                    readonly default: readonly [1, 1, 1];
+                                };
+                            };
+                        };
+                        readonly visible: {
+                            readonly type: "boolean";
+                            readonly default: true;
+                        };
+                        readonly castShadow: {
+                            readonly type: "boolean";
+                            readonly default: false;
+                        };
+                        readonly receiveShadow: {
+                            readonly type: "boolean";
+                            readonly default: false;
+                        };
+                        readonly parentId: {
+                            readonly type: "string";
+                        };
+                        readonly userData: {
+                            readonly type: "object";
+                        };
+                    };
+                };
+            };
+            readonly animations: {
+                readonly type: "array";
+            };
+            readonly metadata: {
+                readonly type: "object";
+            };
+            readonly autoStart: {
+                readonly type: "boolean";
+                readonly default: true;
+            };
+            readonly respectReducedMotion: {
+                readonly type: "boolean";
+                readonly default: true;
+            };
+        };
+    };
+};
+/**
+ * Dynamically register the Scene Specification capability with an AI Motion Registry.
+ */
+export declare function registerSceneSchemaCapability(registry: {
+    registerCapability: (cap: any, opts?: any) => void;
+}): void;

package/dist/3d/schemas/correction.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AF Motion 3D Scene Specification Auto-Correction
+ *
+ * Sanitizes invalid values, breaks circular hierarchies, inserts safe defaults,
+ * and preserves user extension metadata.
+ */
+import type { Scene3DSpecification } from "./types.js";
+/**
+ * Automatically sanitize, repair, and apply safe defaults to any 3D scene configuration.
+ */
+export declare function correctSceneSchema(raw: unknown): Scene3DSpecification;

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

@@ -0,0 +1,12 @@
+/**
+ * AF Motion 3D Scene Schemas Module
+ *
+ * Typed definitions, JSON schemas, validation, auto-correction,
+ * deterministic serialization, and AI integration for 3D scenes.
+ */
+export * from "./types.js";
+export * from "./schemas.js";
+export * from "./validation.js";
+export * from "./correction.js";
+export * from "./serialization.js";
+export * from "./ai-integration.js";

package/dist/3d/schemas/schemas.d.ts

@@ -0,0 +1,361 @@
+/**
+ * AF Motion Machine-Readable 3D Scene JSON Schemas
+ *
+ * Draft-07 compatible schemas for transforms, objects, materials, and complete scenes.
+ */
+export declare const SCENE_SPECIFICATION_VERSION = "1.0.0";
+export declare const TRANSFORM_3D_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly position: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "number";
+            };
+            readonly minItems: 3;
+            readonly maxItems: 3;
+            readonly default: readonly [0, 0, 0];
+        };
+        readonly rotation: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "number";
+            };
+            readonly minItems: 3;
+            readonly maxItems: 3;
+            readonly default: readonly [0, 0, 0];
+        };
+        readonly quaternion: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "number";
+            };
+            readonly minItems: 4;
+            readonly maxItems: 4;
+        };
+        readonly scale: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "number";
+            };
+            readonly minItems: 3;
+            readonly maxItems: 3;
+            readonly default: readonly [1, 1, 1];
+        };
+    };
+};
+export declare const MATERIAL_SCHEMA: {
+    readonly type: "object";
+    readonly required: readonly ["type"];
+    readonly properties: {
+        readonly id: {
+            readonly type: "string";
+        };
+        readonly type: {
+            readonly type: "string";
+            readonly enum: readonly ["basic", "standard", "physical", "phong", "toon", "shadow", "custom"];
+            readonly default: "standard";
+        };
+        readonly color: {
+            readonly type: "string";
+            readonly default: "#ffffff";
+        };
+        readonly roughness: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly maximum: 1;
+            readonly default: 0.5;
+        };
+        readonly metalness: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly maximum: 1;
+            readonly default: 0;
+        };
+        readonly transmission: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly maximum: 1;
+        };
+        readonly ior: {
+            readonly type: "number";
+            readonly minimum: 1;
+            readonly maximum: 3;
+        };
+        readonly opacity: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly maximum: 1;
+            readonly default: 1;
+        };
+        readonly transparent: {
+            readonly type: "boolean";
+            readonly default: false;
+        };
+        readonly wireframe: {
+            readonly type: "boolean";
+            readonly default: false;
+        };
+        readonly mapUrl: {
+            readonly type: "string";
+        };
+        readonly normalMapUrl: {
+            readonly type: "string";
+        };
+        readonly roughnessMapUrl: {
+            readonly type: "string";
+        };
+    };
+};
+export declare const GEOMETRY_SCHEMA: {
+    readonly type: "object";
+    readonly required: readonly ["type"];
+    readonly properties: {
+        readonly type: {
+            readonly type: "string";
+            readonly enum: readonly ["primitive", "model", "custom"];
+        };
+        readonly primitive: {
+            readonly type: "string";
+            readonly enum: readonly ["box", "sphere", "cylinder", "plane", "torus", "cone", "capsule"];
+        };
+        readonly format: {
+            readonly type: "string";
+            readonly enum: readonly ["gltf", "glb", "obj", "fbx"];
+        };
+        readonly url: {
+            readonly type: "string";
+        };
+        readonly scale: {
+            readonly type: "number";
+            readonly default: 1;
+        };
+        readonly parameters: {
+            readonly type: "object";
+        };
+    };
+};
+export declare const INTERACTION_SCHEMA: {
+    readonly type: "object";
+    readonly required: readonly ["trigger", "action"];
+    readonly properties: {
+        readonly trigger: {
+            readonly type: "string";
+            readonly enum: readonly ["click", "hover", "drag", "pointer-move"];
+        };
+        readonly action: {
+            readonly type: "string";
+            readonly enum: readonly ["animate", "emit-event", "navigate", "highlight", "custom"];
+        };
+        readonly targetId: {
+            readonly type: "string";
+        };
+        readonly parameters: {
+            readonly type: "object";
+        };
+    };
+};
+export declare const SCENE_OBJECT_SCHEMA: {
+    readonly type: "object";
+    readonly required: readonly ["id", "type"];
+    readonly properties: {
+        readonly id: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly name: {
+            readonly type: "string";
+        };
+        readonly type: {
+            readonly type: "string";
+            readonly enum: readonly ["group", "mesh", "primitive", "light", "camera", "environment", "model", "interactive", "custom"];
+        };
+        readonly transform: {
+            readonly type: "object";
+            readonly properties: {
+                readonly position: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "number";
+                    };
+                    readonly minItems: 3;
+                    readonly maxItems: 3;
+                    readonly default: readonly [0, 0, 0];
+                };
+                readonly rotation: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "number";
+                    };
+                    readonly minItems: 3;
+                    readonly maxItems: 3;
+                    readonly default: readonly [0, 0, 0];
+                };
+                readonly quaternion: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "number";
+                    };
+                    readonly minItems: 4;
+                    readonly maxItems: 4;
+                };
+                readonly scale: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "number";
+                    };
+                    readonly minItems: 3;
+                    readonly maxItems: 3;
+                    readonly default: readonly [1, 1, 1];
+                };
+            };
+        };
+        readonly visible: {
+            readonly type: "boolean";
+            readonly default: true;
+        };
+        readonly castShadow: {
+            readonly type: "boolean";
+            readonly default: false;
+        };
+        readonly receiveShadow: {
+            readonly type: "boolean";
+            readonly default: false;
+        };
+        readonly parentId: {
+            readonly type: "string";
+        };
+        readonly userData: {
+            readonly type: "object";
+        };
+    };
+};
+export declare const COMPLETE_SCENE_SCHEMA: {
+    readonly $schema: "http://json-schema.org/draft-07/schema#";
+    readonly title: "Scene3DSpecification";
+    readonly version: "1.0.0";
+    readonly type: "object";
+    readonly required: readonly ["id", "version", "objects"];
+    readonly properties: {
+        readonly id: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly name: {
+            readonly type: "string";
+        };
+        readonly version: {
+            readonly type: "string";
+            readonly default: "1.0.0";
+        };
+        readonly coordinateSystem: {
+            readonly type: "string";
+            readonly enum: readonly ["right-handed-y-up", "left-handed-y-up"];
+            readonly default: "right-handed-y-up";
+        };
+        readonly camera: {
+            readonly type: "object";
+        };
+        readonly lighting: {
+            readonly type: "object";
+        };
+        readonly environment: {
+            readonly type: "object";
+        };
+        readonly renderer: {
+            readonly type: "object";
+        };
+        readonly objects: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly required: readonly ["id", "type"];
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly name: {
+                        readonly type: "string";
+                    };
+                    readonly type: {
+                        readonly type: "string";
+                        readonly enum: readonly ["group", "mesh", "primitive", "light", "camera", "environment", "model", "interactive", "custom"];
+                    };
+                    readonly transform: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly position: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "number";
+                                };
+                                readonly minItems: 3;
+                                readonly maxItems: 3;
+                                readonly default: readonly [0, 0, 0];
+                            };
+                            readonly rotation: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "number";
+                                };
+                                readonly minItems: 3;
+                                readonly maxItems: 3;
+                                readonly default: readonly [0, 0, 0];
+                            };
+                            readonly quaternion: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "number";
+                                };
+                                readonly minItems: 4;
+                                readonly maxItems: 4;
+                            };
+                            readonly scale: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "number";
+                                };
+                                readonly minItems: 3;
+                                readonly maxItems: 3;
+                                readonly default: readonly [1, 1, 1];
+                            };
+                        };
+                    };
+                    readonly visible: {
+                        readonly type: "boolean";
+                        readonly default: true;
+                    };
+                    readonly castShadow: {
+                        readonly type: "boolean";
+                        readonly default: false;
+                    };
+                    readonly receiveShadow: {
+                        readonly type: "boolean";
+                        readonly default: false;
+                    };
+                    readonly parentId: {
+                        readonly type: "string";
+                    };
+                    readonly userData: {
+                        readonly type: "object";
+                    };
+                };
+            };
+        };
+        readonly animations: {
+            readonly type: "array";
+        };
+        readonly metadata: {
+            readonly type: "object";
+        };
+        readonly autoStart: {
+            readonly type: "boolean";
+            readonly default: true;
+        };
+        readonly respectReducedMotion: {
+            readonly type: "boolean";
+            readonly default: true;
+        };
+    };
+};

package/dist/3d/schemas/serialization.d.ts

@@ -0,0 +1,22 @@
+/**
+ * AF Motion 3D Scene Specification Serialization & Migration
+ *
+ * Deterministic JSON serialization, deserialization, round-trip fidelity,
+ * and version migration infrastructure.
+ */
+import type { Scene3DSpecification } from "./types.js";
+export interface SerializationOptions {
+    readonly pretty?: boolean;
+}
+/**
+ * Deterministically serialize a 3D Scene Specification to JSON.
+ */
+export declare function serializeSceneSchema(scene: Scene3DSpecification, options?: SerializationOptions): string;
+/**
+ * Migrate a scene specification across versions to the current standard.
+ */
+export declare function migrateSceneSchema(raw: unknown, fromVersion?: string): Scene3DSpecification;
+/**
+ * Deserialize JSON into a validated, version-migrated Scene3DSpecification.
+ */
+export declare function deserializeSceneSchema(json: string): Scene3DSpecification;