talking-head-studio 0.2.9 → 0.3.0

package/dist/filament/faceSqueezeAssets.d.ts

@@ -0,0 +1 @@
+export declare const FACE_SQUEEZE_LOCAL_MODULE: number;

package/dist/filament/faceSqueezeAssets.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FACE_SQUEEZE_LOCAL_MODULE = void 0;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+exports.FACE_SQUEEZE_LOCAL_MODULE = require('../assets/face-squeeze-local.glb');

package/dist/filament/index.d.ts

@@ -0,0 +1,5 @@
+export { FilamentAvatar } from './FilamentAvatar';
+export type { FilamentAvatarRef } from './FilamentAvatar';
+export { useAuthedFilamentUri } from './useAuthedFilamentUri';
+export type { AuthedFileResult } from './useAuthedFilamentUri';
+export * from './morphTables';

package/dist/filament/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useAuthedFilamentUri = exports.FilamentAvatar = void 0;
+var FilamentAvatar_1 = require("./FilamentAvatar");
+Object.defineProperty(exports, "FilamentAvatar", { enumerable: true, get: function () { return FilamentAvatar_1.FilamentAvatar; } });
+var useAuthedFilamentUri_1 = require("./useAuthedFilamentUri");
+Object.defineProperty(exports, "useAuthedFilamentUri", { enumerable: true, get: function () { return useAuthedFilamentUri_1.useAuthedFilamentUri; } });
+__exportStar(require("./morphTables"), exports);

package/dist/filament/morphTables.d.ts

@@ -0,0 +1,5 @@
+export declare const RHUBARB_TO_VISEME: Record<string, string>;
+export declare const VISEME_MORPH_ALIASES: Record<string, string[]>;
+export declare const VISEME_WEIGHTS: Record<string, number>;
+export declare const DEFAULT_VISEME_WEIGHT = 0.35;
+export declare const MOOD_MORPHS: Record<string, Record<string, number>>;

package/dist/filament/morphTables.js

@@ -0,0 +1,93 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// Morph target tables for Filament avatar viseme/mood rendering
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MOOD_MORPHS = exports.DEFAULT_VISEME_WEIGHT = exports.VISEME_WEIGHTS = exports.VISEME_MORPH_ALIASES = exports.RHUBARB_TO_VISEME = void 0;
+// Rhubarb → viseme key mapping (mirrors html.ts)
+exports.RHUBARB_TO_VISEME = {
+    A: 'aa',
+    B: 'PP',
+    C: 'ih',
+    D: 'FF',
+    E: 'ee',
+    F: 'oh',
+    G: 'ou',
+    H: 'nn',
+    X: 'sil',
+};
+// Oculus viseme morph name aliases per viseme key
+exports.VISEME_MORPH_ALIASES = {
+    sil: ['viseme_sil', 'sil', 'mouthClose'],
+    PP: ['viseme_PP', 'viseme_pp', 'mouthPucker'],
+    FF: ['viseme_FF', 'viseme_ff', 'mouthRollLower', 'mouthShrugLower'],
+    TH: ['viseme_TH', 'viseme_th', 'tongueOut'],
+    DD: ['viseme_DD', 'viseme_dd', 'mouthShrugUpper'],
+    kk: ['viseme_kk', 'viseme_k', 'mouthStretchLeft'],
+    CH: ['viseme_CH', 'viseme_ch', 'mouthSmileLeft', 'mouthSmile'],
+    SS: ['viseme_SS', 'viseme_ss', 'mouthStretchRight'],
+    nn: ['viseme_nn', 'viseme_n', 'mouthDimpleLeft'],
+    RR: ['viseme_RR', 'viseme_r', 'mouthDimpleRight'],
+    aa: ['viseme_aa', 'viseme_AA', 'jawOpen', 'mouthOpen'],
+    ee: ['viseme_E', 'viseme_ee', 'mouthSmileLeft'],
+    ih: ['viseme_I', 'viseme_ih', 'mouthSmileRight'],
+    oh: ['viseme_O', 'viseme_oh', 'mouthFunnel'],
+    ou: ['viseme_U', 'viseme_ou', 'mouthRollLower'],
+};
+exports.VISEME_WEIGHTS = {
+    PP: 0.45, FF: 0.40, ee: 0.38, ih: 0.35,
+    oh: 0.35, ou: 0.32, aa: 0.40,
+};
+exports.DEFAULT_VISEME_WEIGHT = 0.35;
+// Mood → baseline morph weights (persistent low-level expression layer)
+exports.MOOD_MORPHS = {
+    neutral: {},
+    happy: {
+        mouthSmileLeft: 0.35, mouthSmileRight: 0.35,
+        cheekSquintLeft: 0.2, cheekSquintRight: 0.2,
+    },
+    sad: {
+        browInnerUp: 0.5, mouthFrownLeft: 0.4, mouthFrownRight: 0.4,
+        eyeLookDownLeft: 0.2, eyeLookDownRight: 0.2,
+    },
+    angry: {
+        browDownLeft: 0.5, browDownRight: 0.5,
+        noseSneerLeft: 0.3, noseSneerRight: 0.3,
+        eyeSquintLeft: 0.2, eyeSquintRight: 0.2,
+    },
+    surprised: {
+        eyeWideLeft: 0.5, eyeWideRight: 0.5,
+        browInnerUp: 0.5, browOuterUpLeft: 0.4, browOuterUpRight: 0.4,
+        jawOpen: 0.1,
+    },
+    excited: {
+        mouthSmileLeft: 0.55, mouthSmileRight: 0.55,
+        eyeWideLeft: 0.3, eyeWideRight: 0.3,
+        cheekSquintLeft: 0.3, cheekSquintRight: 0.3,
+        browOuterUpLeft: 0.3, browOuterUpRight: 0.3,
+    },
+    thinking: {
+        browInnerUp: 0.3,
+        eyeLookUpLeft: 0.2, eyeLookUpRight: 0.2,
+        mouthPucker: 0.15,
+    },
+    concerned: {
+        browInnerUp: 0.45, browDownLeft: 0.25, browDownRight: 0.25,
+        mouthFrownLeft: 0.2, mouthFrownRight: 0.2,
+    },
+    disgust: {
+        noseSneerLeft: 0.6, noseSneerRight: 0.6,
+        browDownLeft: 0.4, browDownRight: 0.4,
+        mouthShrugUpper: 0.3,
+    },
+    fear: {
+        eyeWideLeft: 0.6, eyeWideRight: 0.6,
+        browInnerUp: 0.7, browOuterUpLeft: 0.3, browOuterUpRight: 0.3,
+        mouthStretchLeft: 0.2, mouthStretchRight: 0.2,
+    },
+    exhausted: {
+        eyeBlinkLeft: 0.4, eyeBlinkRight: 0.4,
+        browDownLeft: 0.3, browDownRight: 0.3,
+        mouthFrownLeft: 0.2, mouthFrownRight: 0.2,
+    },
+};

package/dist/filament/useAuthedFilamentUri.d.ts

@@ -0,0 +1,11 @@
+export type AuthedFileResult = {
+    uri: string;
+    size: number;
+} | null;
+/**
+ * Downloads a remote URL (with Bearer auth) to the local cache and returns a
+ * `file://` URI suitable for react-native-filament's <Model> source prop.
+ * The native Filament fetcher doesn't send auth headers, so we pre-fetch here.
+ * Also returns the file size in bytes for GPU memory budgeting.
+ */
+export declare function useAuthedFilamentUri(remoteUrl: string | null): AuthedFileResult;

package/dist/filament/useAuthedFilamentUri.js

@@ -0,0 +1,126 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useAuthedFilamentUri = useAuthedFilamentUri;
+const react_1 = require("react");
+const FileSystem = __importStar(require("expo-file-system/legacy"));
+const studioApi_1 = require("../api/studioApi");
+// Module-level set of URLs that returned non-GLB responses — skip retrying them.
+const failedUrls = new Set();
+/**
+ * Downloads a remote URL (with Bearer auth) to the local cache and returns a
+ * `file://` URI suitable for react-native-filament's <Model> source prop.
+ * The native Filament fetcher doesn't send auth headers, so we pre-fetch here.
+ * Also returns the file size in bytes for GPU memory budgeting.
+ */
+function useAuthedFilamentUri(remoteUrl) {
+    const [result, setResult] = (0, react_1.useState)(null);
+    (0, react_1.useEffect)(() => {
+        if (!remoteUrl) {
+            setResult(null);
+            return;
+        }
+        // Skip URLs that previously returned a non-GLB response (e.g. 404)
+        if (failedUrls.has(remoteUrl))
+            return;
+        // Pass through non-HTTP URLs (file://, data:, asset://) without downloading
+        if (!remoteUrl.startsWith('http://') && !remoteUrl.startsWith('https://')) {
+            setResult({ uri: remoteUrl, size: 0 });
+            return;
+        }
+        let cancelled = false;
+        (async () => {
+            try {
+                const token = await (0, studioApi_1.getToken)();
+                // Strip query params (access_token changes per session) so the same GLB is cached across sessions
+                const urlWithoutQuery = remoteUrl.split('?')[0];
+                const key = urlWithoutQuery.replace(/[^a-zA-Z0-9]/g, '_').slice(-100);
+                const dir = `${FileSystem.cacheDirectory}filament/`;
+                // Append .glb so native loaders can identify the format
+                const localPath = `${dir}${key}.glb`;
+                await FileSystem.makeDirectoryAsync(dir, { intermediates: true });
+                const info = await FileSystem.getInfoAsync(localPath);
+                if (info.exists && info.size && info.size > 1000) {
+                    // Verify magic bytes — GLB files start with 0x676C5446 ("glTF")
+                    const header = await FileSystem.readAsStringAsync(localPath, {
+                        encoding: FileSystem.EncodingType.Base64,
+                        length: 4,
+                        position: 0,
+                    });
+                    // base64("glTF") == "Z2xURg=="
+                    if (header === 'Z2xURg==') {
+                        if (!cancelled)
+                            setResult({ uri: localPath, size: info.size });
+                        return;
+                    }
+                    // Cached file isn't a valid GLB — delete and re-download
+                    await FileSystem.deleteAsync(localPath);
+                }
+                const dlResult = await FileSystem.downloadAsync(remoteUrl, localPath, {
+                    headers: token ? { Authorization: `Bearer ${token}` } : {},
+                });
+                // Verify we got a valid GLB — check size and magic bytes ("glTF")
+                const downloaded = await FileSystem.getInfoAsync(dlResult.uri);
+                const downloadedSize = downloaded.size;
+                if (!downloaded.exists || !downloadedSize || downloadedSize < 1000) {
+                    console.error('[useAuthedFilamentUri] Download too small (' + (downloadedSize ?? 0) + 'B), likely an error response');
+                    failedUrls.add(remoteUrl);
+                    await FileSystem.deleteAsync(dlResult.uri);
+                    return;
+                }
+                const dlHeader = await FileSystem.readAsStringAsync(dlResult.uri, {
+                    encoding: FileSystem.EncodingType.Base64,
+                    length: 4,
+                    position: 0,
+                });
+                if (dlHeader !== 'Z2xURg==') {
+                    console.error('[useAuthedFilamentUri] Downloaded file is not a valid GLB (bad magic bytes)');
+                    failedUrls.add(remoteUrl);
+                    await FileSystem.deleteAsync(dlResult.uri);
+                    return;
+                }
+                if (!cancelled)
+                    setResult({ uri: dlResult.uri, size: downloadedSize });
+            }
+            catch (e) {
+                console.error('[useAuthedFilamentUri] Failed to download:', remoteUrl.slice(-60), e);
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [remoteUrl]);
+    return result;
+}

package/dist/index.d.ts

@@ -1,3 +1,10 @@
 export type { TalkingHeadAccessory, TalkingHeadLoadingState, TalkingHeadLoadingStage, TalkingHeadMood, TalkingHeadProps, TalkingHeadRef, TalkingHeadViseme, TalkingHeadVisemeCue, TalkingHeadVisemeSchedule, } from './TalkingHead';
 export { TalkingHead } from './TalkingHead';
-export * from './appearance';
+export { applyAppearanceToObject3D } from './appearance/apply';
+export { pickTargetForMaterialName } from './appearance/matchers';
+export { normalizeAppearance } from './appearance/schema';
+export type { AppearanceTarget } from './appearance/matchers';
+export * from './api';
+export * from './wardrobe';
+export { TalkingHeadVisualization } from './TalkingHeadVisualization';
+export type { TalkingHeadVisualizationRef } from './TalkingHeadVisualization';

package/dist/index.js

@@ -14,7 +14,18 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TalkingHead = void 0;
+exports.TalkingHeadVisualization = exports.normalizeAppearance = exports.pickTargetForMaterialName = exports.applyAppearanceToObject3D = exports.TalkingHead = void 0;
 var TalkingHead_1 = require("./TalkingHead");
 Object.defineProperty(exports, "TalkingHead", { enumerable: true, get: function () { return TalkingHead_1.TalkingHead; } });
-__exportStar(require("./appearance"), exports);
+// Export appearance utilities, but exclude AvatarAppearance — the canonical
+// AvatarAppearance (with equippedAccessories) comes from ./api below.
+var apply_1 = require("./appearance/apply");
+Object.defineProperty(exports, "applyAppearanceToObject3D", { enumerable: true, get: function () { return apply_1.applyAppearanceToObject3D; } });
+var matchers_1 = require("./appearance/matchers");
+Object.defineProperty(exports, "pickTargetForMaterialName", { enumerable: true, get: function () { return matchers_1.pickTargetForMaterialName; } });
+var schema_1 = require("./appearance/schema");
+Object.defineProperty(exports, "normalizeAppearance", { enumerable: true, get: function () { return schema_1.normalizeAppearance; } });
+__exportStar(require("./api"), exports);
+__exportStar(require("./wardrobe"), exports);
+var TalkingHeadVisualization_1 = require("./TalkingHeadVisualization");
+Object.defineProperty(exports, "TalkingHeadVisualization", { enumerable: true, get: function () { return TalkingHeadVisualization_1.TalkingHeadVisualization; } });

package/dist/index.web.d.ts

@@ -1,3 +1,7 @@
 export type { TalkingHeadAccessory, TalkingHeadLoadingState, TalkingHeadMood, TalkingHeadProps, TalkingHeadRef, } from './TalkingHead.web';
 export { TalkingHead } from './TalkingHead.web';
-export * from './appearance';
+export { applyAppearanceToObject3D } from './appearance/apply';
+export { pickTargetForMaterialName } from './appearance/matchers';
+export { normalizeAppearance } from './appearance/schema';
+export type { AppearanceTarget } from './appearance/matchers';
+export * from './api';

package/dist/index.web.js

@@ -14,7 +14,15 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TalkingHead = void 0;
+exports.normalizeAppearance = exports.pickTargetForMaterialName = exports.applyAppearanceToObject3D = exports.TalkingHead = void 0;
 var TalkingHead_web_1 = require("./TalkingHead.web");
 Object.defineProperty(exports, "TalkingHead", { enumerable: true, get: function () { return TalkingHead_web_1.TalkingHead; } });
-__exportStar(require("./appearance"), exports);
+// Export appearance utilities, but exclude AvatarAppearance — the canonical
+// AvatarAppearance (with equippedAccessories) comes from ./api below.
+var apply_1 = require("./appearance/apply");
+Object.defineProperty(exports, "applyAppearanceToObject3D", { enumerable: true, get: function () { return apply_1.applyAppearanceToObject3D; } });
+var matchers_1 = require("./appearance/matchers");
+Object.defineProperty(exports, "pickTargetForMaterialName", { enumerable: true, get: function () { return matchers_1.pickTargetForMaterialName; } });
+var schema_1 = require("./appearance/schema");
+Object.defineProperty(exports, "normalizeAppearance", { enumerable: true, get: function () { return schema_1.normalizeAppearance; } });
+__exportStar(require("./api"), exports);

package/dist/utils/avatarUtils.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Resolves a local Expo asset module into a file:// URI for use with
+ * react-native-filament's useModel(). Never base64-encodes — Filament reads
+ * file:// directly on both iOS and Android.
+ */
+export declare function resolveFilamentAssetUri(module: unknown): Promise<string | null>;
+/**
+ * Resolves a local Expo asset module (from require()) into a usable URL string.
+ * On web, returns an absolute URL.
+ * On Android/iOS, converts to a base64 data URI so the WebView can load it
+ * without a cross-origin file:// fetch (which is blocked on Android).
+ */
+export declare function resolveLocalAssetUrl(module: unknown): Promise<string | null>;

package/dist/utils/avatarUtils.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveFilamentAssetUri = resolveFilamentAssetUri;
+exports.resolveLocalAssetUrl = resolveLocalAssetUrl;
+const expo_asset_1 = require("expo-asset");
+const react_native_1 = require("react-native");
+const expo_file_system_1 = require("expo-file-system");
+/**
+ * Resolves a local Expo asset module into a file:// URI for use with
+ * react-native-filament's useModel(). Never base64-encodes — Filament reads
+ * file:// directly on both iOS and Android.
+ */
+async function resolveFilamentAssetUri(module) {
+    try {
+        const asset = expo_asset_1.Asset.fromModule(module);
+        await asset.downloadAsync();
+        const uri = asset.localUri ?? asset.uri;
+        return uri ?? null;
+    }
+    catch (e) {
+        console.error('[AssetUtils] Failed to resolve Filament asset:', e);
+        return null;
+    }
+}
+/**
+ * Resolves a local Expo asset module (from require()) into a usable URL string.
+ * On web, returns an absolute URL.
+ * On Android/iOS, converts to a base64 data URI so the WebView can load it
+ * without a cross-origin file:// fetch (which is blocked on Android).
+ */
+async function resolveLocalAssetUrl(module) {
+    try {
+        const asset = expo_asset_1.Asset.fromModule(module);
+        await asset.downloadAsync();
+        const uri = asset.localUri ?? asset.uri;
+        if (!uri)
+            return null;
+        if (react_native_1.Platform.OS === 'web') {
+            if (uri.startsWith('/')) {
+                return window.location.origin + uri;
+            }
+            return uri;
+        }
+        // On Android the WebView cannot fetch file:// URIs — convert to data URI.
+        if (react_native_1.Platform.OS === 'android' && uri.startsWith('file://')) {
+            const file = new expo_file_system_1.File(uri);
+            const base64 = await file.base64();
+            return `data:model/gltf-binary;base64,${base64}`;
+        }
+        return uri;
+    }
+    catch (e) {
+        console.error('[AssetUtils] Failed to resolve local asset:', e);
+        return null;
+    }
+}

package/dist/wardrobe/index.d.ts

@@ -0,0 +1,2 @@
+export * from './wardrobeStore';
+export { useAvatarWardrobeHydration } from './useAvatarWardrobeHydration';

package/dist/wardrobe/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useAvatarWardrobeHydration = void 0;
+__exportStar(require("./wardrobeStore"), exports);
+var useAvatarWardrobeHydration_1 = require("./useAvatarWardrobeHydration");
+Object.defineProperty(exports, "useAvatarWardrobeHydration", { enumerable: true, get: function () { return useAvatarWardrobeHydration_1.useAvatarWardrobeHydration; } });

package/dist/wardrobe/useAvatarWardrobeHydration.d.ts

@@ -0,0 +1,7 @@
+import type { EquippedAccessory } from '../api/types';
+type UseAvatarWardrobeHydrationArgs = {
+    avatarId: string | null | undefined;
+    accessories: EquippedAccessory[] | null | undefined;
+};
+export declare function useAvatarWardrobeHydration({ avatarId, accessories, }: UseAvatarWardrobeHydrationArgs): void;
+export {};

package/dist/wardrobe/useAvatarWardrobeHydration.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useAvatarWardrobeHydration = useAvatarWardrobeHydration;
+const react_1 = require("react");
+const studioApi_1 = require("../api/studioApi");
+const wardrobeStore_1 = require("./wardrobeStore");
+function useAvatarWardrobeHydration({ avatarId, accessories, }) {
+    const hydrateFromApi = (0, wardrobeStore_1.useWardrobeStore)((s) => s.hydrateFromApi);
+    const accessorySignature = (0, react_1.useMemo)(() => JSON.stringify(accessories ?? []), [accessories]);
+    (0, react_1.useEffect)(() => {
+        const nextAccessories = accessories ?? [];
+        if (!avatarId || nextAccessories.length === 0) {
+            hydrateFromApi([], {});
+            return;
+        }
+        let cancelled = false;
+        void (0, studioApi_1.listAssets)()
+            .then((allAssets) => {
+            if (cancelled)
+                return;
+            const lookup = {};
+            for (const asset of allAssets) {
+                lookup[asset.id] = asset;
+            }
+            hydrateFromApi(nextAccessories, lookup);
+        })
+            .catch((err) => {
+            console.error('[useAvatarWardrobeHydration] Failed to hydrate wardrobe:', err);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [accessorySignature, avatarId, hydrateFromApi]);
+}

package/dist/wardrobe/wardrobeStore.d.ts

@@ -0,0 +1,30 @@
+import type { WearableAsset, EquippedAccessory } from '../api/types';
+export interface AssetPlacement {
+    bone: string;
+    position: [number, number, number];
+    rotation: [number, number, number];
+    scale: number;
+}
+export type GizmoMode = 'translate' | 'rotate' | 'scale';
+export interface WardrobeState {
+    /** slot -> equipped asset */
+    equipped: Record<string, WearableAsset>;
+    /** assetId -> placement transform */
+    placements: Record<string, AssetPlacement>;
+    /** asset currently being positioned (Filament mode) */
+    activeAssetId: string | null;
+    /** current gizmo operation mode */
+    gizmoMode: GizmoMode;
+    /** ID of the avatar currently synced to avoid redundant fetches */
+    syncedAvatarId: string | null;
+    equip: (slot: string, asset: WearableAsset) => void;
+    unequip: (slot: string) => void;
+    setPlacement: (assetId: string, placement: AssetPlacement) => void;
+    setActiveAsset: (assetId: string | null) => void;
+    setGizmoMode: (mode: GizmoMode) => void;
+    hydrateFromApi: (accessories: EquippedAccessory[], assetLookup: Record<string, WearableAsset>) => void;
+    syncWithAvatar: (avatarUrl: string) => Promise<void>;
+    serializeForApi: () => EquippedAccessory[];
+    reset: () => void;
+}
+export declare const useWardrobeStore: import("zustand").UseBoundStore<import("zustand").StoreApi<WardrobeState>>;

package/dist/wardrobe/wardrobeStore.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useWardrobeStore = void 0;
+const zustand_1 = require("zustand");
+const studioApi_1 = require("../api/studioApi");
+// ---------------------------------------------------------------------------
+// Inline avatar ID extraction (avoids dep on avatarUtils)
+// ---------------------------------------------------------------------------
+const AVATAR_PATH_RE = /\/v1\/avatars\/([^/]+)\/file/;
+function extractAvatarIdFromUrl(url) {
+    if (!url)
+        return null;
+    const match = url.match(AVATAR_PATH_RE);
+    return match ? match[1] : null;
+}
+// ---------------------------------------------------------------------------
+// Store
+// ---------------------------------------------------------------------------
+exports.useWardrobeStore = (0, zustand_1.create)()((set, get) => ({
+    equipped: {},
+    placements: {},
+    activeAssetId: null,
+    gizmoMode: 'translate',
+    syncedAvatarId: null,
+    equip: (slot, asset) => set((state) => ({
+        equipped: { ...state.equipped, [slot]: asset },
+    })),
+    unequip: (slot) => set((state) => {
+        const removed = state.equipped[slot];
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { [slot]: _removed, ...restEquipped } = state.equipped;
+        // Clean up placement data for the removed asset
+        const placements = { ...state.placements };
+        if (removed) {
+            delete placements[removed.id];
+        }
+        return {
+            equipped: restEquipped,
+            placements,
+            activeAssetId: removed && removed.id === state.activeAssetId
+                ? null
+                : state.activeAssetId,
+        };
+    }),
+    setPlacement: (assetId, placement) => set((state) => ({
+        placements: { ...state.placements, [assetId]: placement },
+    })),
+    setActiveAsset: (assetId) => set({ activeAssetId: assetId }),
+    setGizmoMode: (mode) => set({ gizmoMode: mode }),
+    hydrateFromApi: (accessories, assetLookup) => set(() => {
+        const equipped = {};
+        const placements = {};
+        for (const acc of accessories) {
+            const asset = assetLookup[acc.asset_id];
+            if (asset) {
+                equipped[asset.slot] = asset;
+                placements[acc.asset_id] = {
+                    bone: acc.bone,
+                    position: acc.position,
+                    rotation: acc.rotation,
+                    scale: acc.scale,
+                };
+            }
+        }
+        return { equipped, placements };
+    }),
+    syncWithAvatar: async (avatarUrl) => {
+        const avatarId = extractAvatarIdFromUrl(avatarUrl);
+        if (!avatarId)
+            return;
+        if (get().syncedAvatarId === avatarId)
+            return;
+        get().reset();
+        try {
+            const [avatar, allAssets] = await Promise.all([(0, studioApi_1.getAvatar)(avatarId), (0, studioApi_1.listAssets)()]);
+            const lookup = {};
+            for (const a of allAssets)
+                lookup[a.id] = a;
+            const accessories = avatar.appearance?.equippedAccessories ?? [];
+            get().hydrateFromApi(accessories, lookup);
+            set({ syncedAvatarId: avatarId });
+        }
+        catch (e) {
+            console.warn('[WardrobeStore] Failed to load avatar accessories:', e);
+        }
+    },
+    serializeForApi: () => {
+        const { equipped, placements } = get();
+        return Object.values(equipped).map((asset) => {
+            const p = placements[asset.id];
+            return {
+                asset_id: asset.id,
+                bone: p?.bone ?? 'Head',
+                position: p?.position ?? [0, 0, 0],
+                rotation: p?.rotation ?? [0, 0, 0],
+                scale: p?.scale ?? 1,
+            };
+        });
+    },
+    reset: () => set({
+        equipped: {},
+        placements: {},
+        activeAssetId: null,
+        gizmoMode: 'translate',
+    }),
+}));