mbt-3d 0.4.9 → 0.4.11

package/.ai/agent-examples/README.md

@@ -0,0 +1,166 @@
+# Agent Examples
+
+Use these examples when a consumer app needs package-level usage patterns for `mbt-3d`.
+
+## Basic Scene
+
+```tsx
+import { Model, Scene3D } from 'mbt-3d';
+
+function WeaponPreview({ modelUrl }: { modelUrl: string }) {
+  return (
+    <Scene3D
+      camera={{ position: [0, 1.5, 4], fov: 45 }}
+      style={{ width: 420, height: 420 }}
+    >
+      <Model url={modelUrl} />
+    </Scene3D>
+  );
+}
+```
+
+## Scene With HDRI And Custom Lights
+
+```tsx
+<Scene3D
+  camera={{ position: [0, 2, 5], fov: 45 }}
+  lights={[
+    { type: 'ambient', intensity: 0.35 },
+    {
+      type: 'spot',
+      position: [5, 8, 5],
+      intensity: 120,
+      castShadow: true,
+      shadowMapSize: 2048,
+    },
+  ]}
+  environment={{
+    files: '/hdri/studio.hdr',
+    intensity: 1.2,
+    blur: 0.15,
+    background: false,
+  }}
+  renderer={{
+    physicallyCorrectLights: true,
+    outputColorSpace: 'srgb',
+    toneMapping: 'ACESFilmicToneMapping',
+    toneMappingExposure: 1,
+  }}
+  style={{ width: 600, height: 800 }}
+>
+  {children}
+</Scene3D>
+```
+
+## Animated Character
+
+```tsx
+import { AnimatedModel, Scene3D } from 'mbt-3d';
+
+function CharacterPreview({ modelUrl }: { modelUrl: string }) {
+  return (
+    <Scene3D
+      camera={{ position: [0, 1.5, 4], fov: 45 }}
+      style={{ width: 500, height: 700 }}
+    >
+      <AnimatedModel
+        url={modelUrl}
+        defaultAnimation="Idle"
+        position={[0, -1, 0]}
+      />
+    </Scene3D>
+  );
+}
+```
+
+## Bone Attachment
+
+```tsx
+import { AnimatedModel, BoneAttachment, Model } from 'mbt-3d';
+
+<AnimatedModel url={characterUrl} defaultAnimation="Idle">
+  <BoneAttachment bone="hand_r">
+    <Model url={weaponUrl} scale={0.7} />
+  </BoneAttachment>
+</AnimatedModel>;
+```
+
+## Morph Targets
+
+```tsx
+import { MorphableModel } from 'mbt-3d';
+
+<MorphableModel
+  url={characterUrl}
+  morphTargets={{
+    muscular: 0.5,
+    thin: 0.2,
+  }}
+/>;
+```
+
+## Imperative Animation Control
+
+```tsx
+import { AnimatedModel } from 'mbt-3d';
+import { useRef } from 'react';
+import type { AnimatedModelHandle } from 'mbt-3d';
+
+const characterRef = useRef<AnimatedModelHandle>(null);
+
+<AnimatedModel ref={characterRef} url={characterUrl} defaultAnimation="Idle" />;
+
+characterRef.current?.playAnimation('Attack', { loop: false });
+```
+
+## Advanced Hook
+
+```tsx
+import { preloadModel } from 'mbt-3d';
+
+void preloadModel(modelUrl);
+```
+
+## Texture Preload
+
+```tsx
+import { preloadTextures } from 'mbt-3d';
+
+preloadTextures({
+  Metal: {
+    map: resolvedMetalMap,
+    normalMap: resolvedMetalNormalMap,
+  },
+});
+```
+
+## Multiple Character Slots
+
+```tsx
+<Scene3D
+  camera={{ position: [0, 2, 8] }}
+  background="#1a1a2e"
+  style={{ width: '100%', height: '100vh' }}
+>
+  <AnimatedModel
+    url={heroAUrl}
+    defaultAnimation="Idle"
+    position={[-2, -1, 0]}
+  />
+
+  <AnimatedModel url={heroBUrl} defaultAnimation="Idle" position={[0, -1, 0]}>
+    <BoneAttachment bone="hand_r">
+      <Model url={swordUrl} />
+    </BoneAttachment>
+  </AnimatedModel>
+
+  <AnimatedModel url={heroCUrl} defaultAnimation="Idle" position={[2, -1, 0]} />
+</Scene3D>
+```
+
+## Important Notes
+
+- These examples assume the consumer has already resolved or prepared the asset URL.
+- Consumer-specific CDN resolution, local asset servers, and preload orchestration belong in the consumer app docs, not in `mbt-3d`.
+- Prefer package-level examples here over demo-only repo paths like `/models/...` when writing guidance for consumers.
+- Supported source assets are GLB/GLTF, with embedded animations or morph targets when the consumer needs those features.

package/.ai/agent-reference/README.md

@@ -0,0 +1,74 @@
+# Agent Reference
+
+This folder holds factual package reference for `mbt-3d`.
+
+## Public Components
+
+- `Scene3D`
+- `Model`
+- `AnimatedModel`
+- `MorphableModel`
+- `BoneAttachment`
+
+## Advanced Hooks
+
+- `useClonedModel`
+- `preloadModel`
+- `useAnimationController`
+- `useMorphTargets`
+- `useMeshVisibility`
+- `useMaterialColor`
+- `useMaterialTexture`
+- `preloadTextures`
+- `useEyeAnimation`
+
+## Exported Types
+
+- `Scene3DProps`
+- `RendererConfig`
+- `ToneMappingMode`
+- `ModelProps`
+- `ModelInfo`
+- `AnimatedModelProps`
+- `AnimatedModelInfo`
+- `AnimatedModelHandle`
+- `AnimatedModelAnimationMask`
+- `AnimatedModelAnimationLayer`
+- `AnimatedModelAnimationLayerInput`
+- `MorphableModelProps`
+- `MorphableModelHandle`
+- `BoneAttachmentProps`
+- `MaterialTextures`
+
+## Peer Dependencies
+
+- `react`
+- `react-dom`
+- `three`
+- `@react-three/fiber`
+- `@react-three/drei`
+
+## Important Public Patterns
+
+- `Scene3D` supports `lights`, `environment`, and `renderer` together.
+- `Scene3D` preserves camera state while the same scene stays mounted.
+- `AnimatedModel` supports controlled animation, layered animation, morph targets, and `BoneAttachment` children.
+- `AnimatedModel` auto-plays the first available animation when `defaultAnimation` is omitted.
+- `AnimatedModelHandle.playAnimation()` uses matching logic that can resolve partial animation names.
+- `MorphableModel` exposes morph target discovery and imperative morph updates through its handle.
+- `BoneAttachment` expects a real bone name from the animated parent model.
+
+## Model Requirements
+
+- Source assets must be GLB or GLTF.
+- Embedded animations must be present in the model file for `AnimatedModel` behavior.
+- Morph targets must exist in the source asset for `MorphableModel` features.
+- Bone names must exist in the model for `BoneAttachment` to work.
+
+## Common Bone Name Families
+
+- Blender Rigify: `DEF-handR`, `DEF-handL`, `DEF-spine`
+- Mixamo: `RightHand`, `LeftHand`, `Spine`
+- Custom rigs: `hand_r`, `hand_l`, `spine_upper`
+
+Reference docs should stay factual. Policy and maintenance rules belong in `.ai/agent-rules/`.

package/.ai/agent-rules/README.md

@@ -0,0 +1,50 @@
+# Agent Rules
+
+These files are the canonical package-owned rules for `mbt-3d`.
+
+## Rule Map
+
+- `.ai/agent-rules/README.md` - normative usage rules for exported components and hooks.
+- `.ai/agent-rules/maintenance.md` - required rule for keeping package docs in sync with public changes.
+
+## Usage Rules
+
+- Prefer higher-level exported components before using lower-level hooks directly.
+- Use `Scene3D` as the normal scene container for package consumers.
+- Use `Model` for static models, `AnimatedModel` for animation-capable models, and `MorphableModel` when morph targets are required.
+- Use `BoneAttachment` only as a child of `AnimatedModel`.
+- Pass ready-to-use asset URLs into package components; asset downloading, path resolution, and cache orchestration are consumer concerns.
+- Prefer stable props and memoized configuration objects when scenes become configuration-heavy.
+- Use advanced hooks only when the consumer truly needs lower-level control.
+- Use `pnpm` as the package manager for this repo and keep a single lockfile.
+
+## Boundaries
+
+- This package owns scene and model behavior.
+- Consumer apps own where assets come from, how remote URLs are resolved, and when app-specific preload flows run.
+- Do not put app-owned IPC, CDN, asset-server, or resolver workflow rules into package docs.
+
+## Scene Guidance
+
+- `Scene3D` supports mixed lighting through `lights` and `environment` together.
+- `Scene3D` preserves camera state between model changes inside the same mounted scene.
+- Keep `renderer`, `lights`, and `controls` props stable when a consumer already memoizes or stores them outside render.
+- Prefer explicit camera and control configuration in examples instead of relying on implicit defaults when teaching usage.
+
+## Model Guidance
+
+- Resolve model and texture URLs before rendering a component when the asset source is external or dynamic.
+- Use `Model.preload()` or `preloadModel()` only when the consumer already has a real preload step.
+- Use `preloadTextures()` only when the consumer already has a preload stage and texture URLs are known before render.
+- For texture-driven materials, resolve model and texture data together before render to avoid mixed old/new asset states.
+
+## Animation Guidance
+
+- If `AnimatedModel.defaultAnimation` is omitted, the library falls back to the first available animation.
+- `playAnimation(name)` uses name matching that tolerates partial or case-insensitive matches when possible.
+- Prefer explicit animation names in consumer code even though partial matching exists.
+
+## Bone Guidance
+
+- Match bone names to the actual model data; do not guess names.
+- Common families include custom names like `hand_r`, Mixamo-style names like `RightHand`, and Rigify-style names like `DEF-handR`.

package/.ai/agent-rules/maintenance.md

@@ -0,0 +1,22 @@
+# Maintenance Rule
+
+Agents working in `mbt-3d` must review and update package guidance whenever a change affects public behavior.
+
+## Update The Docs When
+
+- exported components, hooks, or types change
+- component props or defaults change
+- animation control expectations change
+- morph-target usage changes
+- attachment behavior changes
+- environment, lighting, or renderer configuration changes
+- canonical examples need to change to stay correct
+
+## Required Files To Review
+
+- `AGENTS.md`
+- `.ai/agent-rules/README.md`
+- `.ai/agent-reference/README.md`
+- `.ai/agent-examples/README.md`
+
+Do not finish public package work without reviewing these files.

package/AGENTS.md

@@ -0,0 +1,36 @@
+# AGENTS.md
+
+## Purpose
+
+- `mbt-3d` is the shared React package for 3D scenes, models, animations, morph targets, and bone attachments.
+- This repo owns the canonical agent guidance for package usage.
+- Consumer apps should read the installed package docs from `node_modules/mbt-3d/...`.
+
+## Package Name
+
+- npm package: `mbt-3d`
+
+## Read This First
+
+1. `.ai/agent-rules/README.md`
+2. `.ai/agent-rules/maintenance.md`
+3. `.ai/agent-reference/README.md`
+4. `.ai/agent-examples/README.md`
+
+## Guidance Map
+
+- `.ai/agent-rules/README.md` - package-owned usage rules and boundaries.
+- `.ai/agent-rules/maintenance.md` - required doc-sync rule.
+- `.ai/agent-reference/README.md` - exported surfaces and peer dependency map.
+- `.ai/agent-examples/README.md` - package-safe usage examples.
+
+## Maintenance Rule
+
+- If a change affects exported components, props, hooks, types, or expected usage patterns, update the guidance docs before considering the work complete.
+
+## Guardrails
+
+- Keep package docs focused on public library behavior.
+- Consumer-specific asset downloading, CDN resolution, or preload orchestration rules belong in the consumer app, not here.
+- Prefer package-safe examples over repo-demo-only examples.
+- Use `pnpm` as the package manager for this repo.

package/README.md

@@ -1,56 +1,67 @@
-# mbt-3d
-
-React components for 3D character viewing with animations and morph targets.
-
-## Installation
-
-```bash
-npm install mbt-3d
-```
-
-### Peer Dependencies
-
-```bash
-npm install react react-dom three @react-three/fiber @react-three/drei
-```
-
-## Requirements
-
-- React >= 18.0.0
-- Three.js >= 0.150.0
-- @react-three/fiber >= 8.0.0
-- @react-three/drei >= 9.0.0
-
+# mbt-3d
+
+React components for 3D character viewing with animations and morph targets.
+
+## Installation
+
+```bash
+pnpm add mbt-3d
+```
+
+## Agent Guidance
+
+- `AGENTS.md` is the package entrypoint for coding agents.
+- Canonical rules live in `.ai/agent-rules/`.
+- Factual reference lives in `.ai/agent-reference/`.
+- Package-safe examples live in `.ai/agent-examples/`.
+
+### Peer Dependencies
+
+```bash
+pnpm add react react-dom three @react-three/fiber @react-three/drei
+```
+
+## Requirements
+
+- React >= 18.0.0
+- Three.js >= 0.150.0
+- @react-three/fiber >= 8.0.0
+- @react-three/drei >= 9.0.0
+
 ## Local Development
-
-For local development and testing with another project:
-
-**1. Link the library:**
-```bash
-# In mbt-3d directory
-npm link
-
-# Start watch mode for auto-rebuild on changes
-npm run build:lib:watch
-```
-
-**2. Use in your project:**
-```bash
-# In your project directory
-npm link mbt-3d
-```
-
-**3. When done, unlink:**
-```bash
-# In your project directory
-npm unlink mbt-3d
-
-# In mbt-3d directory
-npm unlink
-```
-
-**Alternative: Use file: protocol**
-```json
+
+For local development and testing with another project:
+
+**1. Link the library:**
+
+```bash
+# In mbt-3d directory
+pnpm link --global
+
+# Start watch mode for auto-rebuild on changes
+pnpm build:lib:watch
+```
+
+**2. Use in your project:**
+
+```bash
+# In your project directory
+pnpm link --global mbt-3d
+```
+
+**3. When done, unlink:**
+
+```bash
+# In your project directory
+pnpm unlink --global mbt-3d
+
+# In mbt-3d directory
+pnpm unlink --global
+```
+
+**Alternative: Use file: protocol**
+
+```json
 {
   "dependencies": {
     "mbt-3d": "file:../path/to/mbt-3d"
@@ -58,6 +69,8 @@ npm unlink
 }
 ```
 
+This repo standardizes on `pnpm` only.
+
 ## Lighting and HDRI
 
 `Scene3D` supports mixed lighting:
@@ -72,19 +85,25 @@ npm unlink
 <Scene3D
   lights={[
     { type: 'ambient', intensity: 0.4 },
-    { type: 'spot', position: [5, 8, 5], intensity: 120, castShadow: true, shadowMapSize: 2048 }
+    {
+      type: 'spot',
+      position: [5, 8, 5],
+      intensity: 120,
+      castShadow: true,
+      shadowMapSize: 2048,
+    },
   ]}
   environment={{
     files: '/hdri/studio.hdr',
     intensity: 1.2,
     blur: 0.15,
-    background: false
+    background: false,
   }}
   renderer={{
     physicallyCorrectLights: true,
     outputColorSpace: 'srgb',
     toneMapping: 'ACESFilmicToneMapping',
-    toneMappingExposure: 1
+    toneMappingExposure: 1,
   }}
 >
   {children}

package/dist/index.d.ts

@@ -458,7 +458,7 @@ declare interface MaterialTextures_2 {
  * />
  * ```
  */
-export declare function Model({ url, position, rotation, scale, meshVisibility, materialColors, materialTextures, materialTextureLogging, onLoad, onError: _onError, }: ModelProps): JSX_2.Element;
+export declare function Model({ url, position, rotation, scale, meshVisibility, materialColors, materialTextures, materialTextureLogging, onLoad, onTexturesLoaded, onError: _onError, }: ModelProps): JSX_2.Element;
 
 export declare namespace Model {
     var preload: (url: string) => void;
@@ -512,6 +512,8 @@ export declare interface ModelProps {
     onLoad?: (info: ModelInfo) => void;
     /** Callback when model fails to load */
     onError?: (error: Error) => void;
+    /** Callback when textures have finished loading and applying */
+    onTexturesLoaded?: () => void;
 }
 
 /**
@@ -927,7 +929,7 @@ declare interface UseClonedModelOptions {
 /**
  * Animates eye bones to follow the mouse cursor.
  *
- * @param scene - The THREE.Group scene containing the eye bones
+ * @param scene - The THREE.Object3D scene subtree containing the eye bones
  * @param eyeNames - Names of eye bone objects to animate. Pass an empty array to disable.
  *
  * @example
@@ -973,6 +975,10 @@ declare interface UseMaterialTextureOptions {
      * Enable verbose texture lifecycle logs (disabled by default).
      */
     enableLogging?: boolean;
+    /**
+     * Callback fired when all textures for the material have finished downloading and applying.
+     */
+    onTexturesLoaded?: () => void;
 }
 
 /**