@3driseai/3drise-core 1.0.8 → 1.0.10

package/dist/utils/galleriesUtils.js

@@ -90,7 +90,7 @@ export const updateCurrentLayoutSettings = (currentSettings, newSettings) => {
         ? currentSettings.imageUrls
         : createNumberOfDefaultImages(galleryState.numImages ?? 20), galleryState);
     const layoutSettings = getLayoutSettings(currentSettings.layout, galleryState);
-    return { frames, layoutSettings };
+    return { frames, layoutSettings: galleryState };
 };
 // =============================================================================
 // DEFAULT STATE

package/dist/utils/index.d.ts

@@ -8,6 +8,7 @@ export * from './GalleryLayouts';
 export * from './gridUtils';
 export * from './idUtils';
 export * from './loadingManager';
+export * from './modelCache';
 export * from './materialApplicationUtils';
 export * from './materialUtils';
 export * from './meshUtils';

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC"}

package/dist/utils/index.js

@@ -8,6 +8,7 @@ export * from './GalleryLayouts.js';
 export * from './gridUtils.js';
 export * from './idUtils.js';
 export * from './loadingManager.js';
+export * from './modelCache.js';
 export * from './materialApplicationUtils.js';
 export * from './materialUtils.js';
 export * from './meshUtils.js';

package/dist/utils/materialApplicationUtils.d.ts

@@ -3,6 +3,7 @@ import { MaterialInstance } from '../services/MaterialRegistry';
 export declare const MATERIAL_INSTANCE_KEY = "_3driseMaterialInstance";
 export declare const EDGES_GROUP_KEY = "__isEdgesGroup";
 export declare const GEREATIVE_EFFECTS_KEY = "__isGenerativeEffectsGroup";
+export declare const IMAGE_KEY = "__isImage";
 /**
  * Set by a renderer that builds and owns its object's material itself — today the
  * points renderers, while shader effects are active. Two writers on one

package/dist/utils/materialApplicationUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"materialApplicationUtils.d.ts","sourceRoot":"","sources":["../../src/utils/materialApplicationUtils.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAChD,OAA4B,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAKrF,eAAO,MAAM,qBAAqB,4BAA4B,CAAC;AAE/D,eAAO,MAAM,eAAe,mBAAmB,CAAC;AAChD,eAAO,MAAM,qBAAqB,+BAA+B,CAAC;AAClE;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,sBAAsB,CAAC;AAC3D;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,GAAG,IAAI,CAOxH;AAKD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,gBAAgB,CAI/G;AACD;;;GAGG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAQlH;AACD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI,CAsCrF;AACD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAE1F;AACD;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEpD;AACD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAGtD;AACD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,OAAO,CAElE;AACD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,OAAO,CAElE;AACD;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,GAAG,CAAC,MAAM,CAGtC,CAAC;AACH;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG;IAC3D,OAAO,EAAE,KAAK,CAAC;QACX,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IACH,MAAM,EAAE,KAAK,CAAC;QACV,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IACH,QAAQ,EAAE,KAAK,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,GAAG,CAAC;KACd,CAAC,CAAC;IACH,QAAQ,EAAE,KAAK,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,OAAO,CAAC;KAClB,CAAC,CAAC;IACH,KAAK,EAAE,KAAK,CAAC;QACT,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,GAAG,CAAC;KACd,CAAC,CAAC;CACN,CA6BJ"}
+{"version":3,"file":"materialApplicationUtils.d.ts","sourceRoot":"","sources":["../../src/utils/materialApplicationUtils.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAChD,OAA4B,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAKrF,eAAO,MAAM,qBAAqB,4BAA4B,CAAC;AAE/D,eAAO,MAAM,eAAe,mBAAmB,CAAC;AAChD,eAAO,MAAM,qBAAqB,+BAA+B,CAAC;AAClE,eAAO,MAAM,SAAS,cAAc,CAAC;AACrC;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,sBAAsB,CAAC;AAC3D;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,GAAG,IAAI,CAOxH;AAKD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,gBAAgB,CAI/G;AACD;;;GAGG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAQlH;AACD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI,CAsCrF;AACD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAE1F;AACD;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEpD;AACD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAGtD;AACD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,OAAO,CAElE;AACD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,OAAO,CAElE;AACD;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,GAAG,CAAC,MAAM,CAGtC,CAAC;AACH;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG;IAC3D,OAAO,EAAE,KAAK,CAAC;QACX,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IACH,MAAM,EAAE,KAAK,CAAC;QACV,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IACH,QAAQ,EAAE,KAAK,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,GAAG,CAAC;KACd,CAAC,CAAC;IACH,QAAQ,EAAE,KAAK,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,OAAO,CAAC;KAClB,CAAC,CAAC;IACH,KAAK,EAAE,KAAK,CAAC;QACT,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,GAAG,CAAC;KACd,CAAC,CAAC;CACN,CA6BJ"}

package/dist/utils/materialApplicationUtils.js

@@ -18,6 +18,7 @@ export const MATERIAL_INSTANCE_KEY = '_3driseMaterialInstance';
 // Key placed on edges group userData to prevent material bleed-through
 export const EDGES_GROUP_KEY = '__isEdgesGroup';
 export const GEREATIVE_EFFECTS_KEY = '__isGenerativeEffectsGroup';
+export const IMAGE_KEY = '__isImage';
 /**
  * Set by a renderer that builds and owns its object's material itself — today the
  * points renderers, while shader effects are active. Two writers on one
@@ -33,7 +34,7 @@ export const SELF_OWNED_MATERIAL_KEY = '__ownsItsMaterial';
  * apply its own material via useMaterialApplication).
  */
 export function traverseSkippingEdgesAndEffects(obj, isRoot, callback) {
-    if (!isRoot && (obj.userData[EDGES_GROUP_KEY] || obj.userData[GEREATIVE_EFFECTS_KEY] || obj.userData[SELF_OWNED_MATERIAL_KEY]))
+    if (!isRoot && (obj.userData[EDGES_GROUP_KEY] || obj.userData[GEREATIVE_EFFECTS_KEY] || obj.userData[SELF_OWNED_MATERIAL_KEY] || obj.userData[IMAGE_KEY]))
         return;
     callback(obj);
     for (const child of obj.children) {

package/dist/utils/modelCache.d.ts

@@ -0,0 +1,78 @@
+import type { AnimationClip, Object3D } from 'three';
+/**
+ * URL-keyed model cache.
+ *
+ * One fetch per URL for the life of the page, shared by every consumer: the project
+ * loaders, the object API, and any model leaf that mounts without a preload pass. The
+ * cached value is the *master* — it is never mounted into a scene. Consumers take a clone.
+ *
+ * Loading goes through the `gltfLoader` singleton in `loadingManager.ts`, so the Draco
+ * decoder configuration and the LoadingManager progress events stay in one place.
+ */
+export interface ModelAsset {
+    /** The master scene. Never mount this — clone it. */
+    scene: Object3D;
+    /** Clips shipped with the GLTF, to bind against a clone's root. */
+    animations: AnimationClip[];
+}
+export interface ModelCacheEntry {
+    url: string;
+    promise: Promise<ModelAsset>;
+    /** Set once the load resolves. */
+    asset?: ModelAsset;
+    /** Set once the load rejects. */
+    error?: unknown;
+}
+export interface ModelInstance {
+    object: Object3D;
+    animations: AnimationClip[];
+}
+/**
+ * Start (or join) the load of a model URL. Safe to call from anywhere, any number of
+ * times — concurrent callers share one request and one master.
+ */
+export declare const loadModelAsset: (url: string) => ModelCacheEntry;
+/**
+ * Suspense-flavoured read: returns the asset if it is already here, otherwise throws the
+ * promise (React suspends) or the error (the nearest error boundary catches it).
+ *
+ * Call this from render, never from an effect.
+ */
+export declare const readModelAsset: (url: string) => ModelAsset;
+/** The resolved asset if the URL is already cached, otherwise null. Never suspends. */
+export declare const peekModelAsset: (url: string) => ModelAsset | null;
+/**
+ * Warm the cache. Never rejects — a model that fails to load is reported by the leaf that
+ * needs it, not by the preload.
+ */
+export declare const preloadModels: (urls: string[]) => Promise<void>;
+/**
+ * Clone a master for mounting.
+ *
+ * `SkeletonUtils.clone` rather than `Object3D.clone` so skinned meshes and their bones are
+ * rebound to the copy. Geometry stays shared with the master — cheap, and never disposed by
+ * an instance. Materials are cloned per instance because `useMaterialApplication` mutates
+ * them per scene object; sharing them would make one object's colour change repaint every
+ * instance of the same URL.
+ */
+export declare const cloneModelAsset: (asset: ModelAsset) => ModelInstance;
+/**
+ * Release what a single mounted instance owns.
+ *
+ * Only the per-instance material clones. Geometry and textures are reached from the cache
+ * master and are shared by every other instance of that URL — disposing them here is how
+ * you make every other copy of the model turn black.
+ */
+export declare const disposeModelInstance: (object: Object3D | null | undefined) => void;
+/** Claim a mounted instance. Cancels a disposal another component scheduled for it. */
+export declare const retainModelInstance: (object: Object3D | null | undefined) => void;
+/** Give up a mounted instance. Frees it a tick later if nothing else claims it first. */
+export declare const releaseModelInstance: (object: Object3D | null | undefined) => void;
+/** Drop cache entries. For tests and debugging — masters are not disposed. */
+export declare const clearModelCache: (url?: string) => void;
+/** Diagnostics: what the cache is holding right now. */
+export declare const modelCacheStats: () => {
+    url: string;
+    state: "loading" | "ready" | "error";
+}[];
+//# sourceMappingURL=modelCache.d.ts.map

package/dist/utils/modelCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"modelCache.d.ts","sourceRoot":"","sources":["../../src/utils/modelCache.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAY,QAAQ,EAAE,MAAM,OAAO,CAAC;AAG/D;;;;;;;;;GASG;AAEH,MAAM,WAAW,UAAU;IACvB,qDAAqD;IACrD,KAAK,EAAE,QAAQ,CAAC;IAChB,mEAAmE;IACnE,UAAU,EAAE,aAAa,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7B,kCAAkC;IAClC,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,iCAAiC;IACjC,KAAK,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC1B,MAAM,EAAE,QAAQ,CAAC;IACjB,UAAU,EAAE,aAAa,EAAE,CAAC;CAC/B;AAOD;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,KAAK,MAAM,KAAG,eAyB5C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,KAAK,MAAM,KAAG,UAK5C,CAAC;AAEF,uFAAuF;AACvF,eAAO,MAAM,cAAc,GAAI,KAAK,MAAM,KAAG,UAAU,GAAG,IACvB,CAAC;AAEpC;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAU,MAAM,MAAM,EAAE,KAAG,OAAO,CAAC,IAAI,CAKhE,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,UAAU,KAAG,aAoBnD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAAI,QAAQ,QAAQ,GAAG,IAAI,GAAG,SAAS,KAAG,IAU1E,CAAC;AAkBF,uFAAuF;AACvF,eAAO,MAAM,mBAAmB,GAAI,QAAQ,QAAQ,GAAG,IAAI,GAAG,SAAS,KAAG,IAQzE,CAAC;AAEF,yFAAyF;AACzF,eAAO,MAAM,oBAAoB,GAAI,QAAQ,QAAQ,GAAG,IAAI,GAAG,SAAS,KAAG,IAgB1E,CAAC;AAEF,8EAA8E;AAC9E,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,KAAG,IAG9C,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,eAAe,QAAO;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,CAAA;CAAE,EAIjF,CAAC"}

package/dist/utils/modelCache.js

@@ -0,0 +1,164 @@
+import { clone as cloneSkeleton } from 'three/addons/utils/SkeletonUtils.js';
+import { gltfLoader } from './loadingManager.js';
+/** Marks a material this instance owns and may dispose. */
+const OWNED_MATERIAL = '__3driseOwnedMaterial';
+const entries = new Map();
+/**
+ * Start (or join) the load of a model URL. Safe to call from anywhere, any number of
+ * times — concurrent callers share one request and one master.
+ */
+export const loadModelAsset = (url) => {
+    const existing = entries.get(url);
+    if (existing)
+        return existing;
+    const entry = {
+        url,
+        promise: gltfLoader
+            .loadAsync(url)
+            .then((gltf) => {
+            const asset = {
+                scene: gltf.scene,
+                animations: gltf.animations ?? [],
+            };
+            entry.asset = asset;
+            return asset;
+        })
+            .catch((error) => {
+            console.error(`[modelCache] Failed to load model: ${url}`, error);
+            entry.error = error;
+            throw error;
+        }),
+    };
+    entries.set(url, entry);
+    return entry;
+};
+/**
+ * Suspense-flavoured read: returns the asset if it is already here, otherwise throws the
+ * promise (React suspends) or the error (the nearest error boundary catches it).
+ *
+ * Call this from render, never from an effect.
+ */
+export const readModelAsset = (url) => {
+    const entry = loadModelAsset(url);
+    if (entry.error)
+        throw entry.error;
+    if (!entry.asset)
+        throw entry.promise;
+    return entry.asset;
+};
+/** The resolved asset if the URL is already cached, otherwise null. Never suspends. */
+export const peekModelAsset = (url) => entries.get(url)?.asset ?? null;
+/**
+ * Warm the cache. Never rejects — a model that fails to load is reported by the leaf that
+ * needs it, not by the preload.
+ */
+export const preloadModels = async (urls) => {
+    const unique = [...new Set(urls.filter(Boolean))];
+    await Promise.all(unique.map(url => loadModelAsset(url).promise.catch(() => undefined)));
+};
+/**
+ * Clone a master for mounting.
+ *
+ * `SkeletonUtils.clone` rather than `Object3D.clone` so skinned meshes and their bones are
+ * rebound to the copy. Geometry stays shared with the master — cheap, and never disposed by
+ * an instance. Materials are cloned per instance because `useMaterialApplication` mutates
+ * them per scene object; sharing them would make one object's colour change repaint every
+ * instance of the same URL.
+ */
+export const cloneModelAsset = (asset) => {
+    const object = cloneSkeleton(asset.scene);
+    object.traverse(child => {
+        const material = child.material;
+        if (!material)
+            return;
+        if (Array.isArray(material)) {
+            child.material = material.map(m => {
+                const copy = m.clone();
+                copy.userData[OWNED_MATERIAL] = true;
+                return copy;
+            });
+        }
+        else {
+            const copy = material.clone();
+            copy.userData[OWNED_MATERIAL] = true;
+            child.material = copy;
+        }
+    });
+    return { object, animations: asset.animations };
+};
+/**
+ * Release what a single mounted instance owns.
+ *
+ * Only the per-instance material clones. Geometry and textures are reached from the cache
+ * master and are shared by every other instance of that URL — disposing them here is how
+ * you make every other copy of the model turn black.
+ */
+export const disposeModelInstance = (object) => {
+    if (!object)
+        return;
+    object.traverse(child => {
+        const material = child.material;
+        if (!material)
+            return;
+        const list = Array.isArray(material) ? material : [material];
+        list.forEach(m => {
+            if (m?.userData?.[OWNED_MATERIAL])
+                m.dispose();
+        });
+    });
+};
+/**
+ * Mount/unmount bookkeeping for cloned instances.
+ *
+ * An instance can be mounted by one component at a time, but the *component* mounting it
+ * changes more often than you would think: React StrictMode double-mounts, a re-parent in
+ * the object tree remounts, and adopting a saved object's real id in place of its temp id
+ * changes the React key, which unmounts one leaf and mounts another around the same
+ * Object3D in a single commit.
+ *
+ * Disposing on the unmount half of any of those turns a model that is still on screen
+ * black. So disposal is refcounted and deferred by a tick: whoever mounts next cancels it,
+ * and only a release that is never followed by a retain actually frees anything.
+ */
+const instanceRefCounts = new Map();
+const pendingDisposals = new Map();
+/** Claim a mounted instance. Cancels a disposal another component scheduled for it. */
+export const retainModelInstance = (object) => {
+    if (!object)
+        return;
+    const pending = pendingDisposals.get(object);
+    if (pending !== undefined) {
+        clearTimeout(pending);
+        pendingDisposals.delete(object);
+    }
+    instanceRefCounts.set(object, (instanceRefCounts.get(object) ?? 0) + 1);
+};
+/** Give up a mounted instance. Frees it a tick later if nothing else claims it first. */
+export const releaseModelInstance = (object) => {
+    if (!object)
+        return;
+    const next = (instanceRefCounts.get(object) ?? 1) - 1;
+    if (next > 0) {
+        instanceRefCounts.set(object, next);
+        return;
+    }
+    instanceRefCounts.delete(object);
+    if (pendingDisposals.has(object))
+        return;
+    pendingDisposals.set(object, setTimeout(() => {
+        pendingDisposals.delete(object);
+        disposeModelInstance(object);
+    }, 0));
+};
+/** Drop cache entries. For tests and debugging — masters are not disposed. */
+export const clearModelCache = (url) => {
+    if (url)
+        entries.delete(url);
+    else
+        entries.clear();
+};
+/** Diagnostics: what the cache is holding right now. */
+export const modelCacheStats = () => [...entries.values()].map(entry => ({
+    url: entry.url,
+    state: entry.error ? 'error' : entry.asset ? 'ready' : 'loading',
+}));

package/dist/utils/utils.d.ts

@@ -8,6 +8,14 @@ export declare const createModelFromUrl: (model: ModelData) => Promise<CreatedRe
 export declare const buildQueryString: (params: Record<string, any>) => string;
 export declare const loadModels: (models: ModelData[]) => Promise<CreatedRef[]>;
 export declare const dontAnimate: (key: string) => boolean;
+/**
+ * Preload a project's models and register one instance per scene object id.
+ *
+ * This is an optimisation, not a precondition: a model leaf that mounts without this
+ * having run loads itself through the same cache under Suspense (see
+ * `useModelObject` in the viewer package). Keep calling it so a scene reveals whole
+ * instead of popping in model by model.
+ */
 export declare const loadAssets: (models: ModelData[]) => Promise<CreatedRef[]>;
 export declare const createUniformsText: (uniforms: any[]) => string;
 /**

package/dist/utils/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils/utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAGtC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvC,eAAO,MAAM,wBAAwB,GAAI,QAAQ,QAAQ,KAAG,WAY3D,CAAC;AACF,eAAO,MAAM,kBAAkB,GAAI,OAAO,QAAQ,EAAE,UAAS,MAAU,KAAG,MAWzE,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAU,OAAO,SAAS,KAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CA8BpF,CAAC;AACF,eAAO,MAAM,gBAAgB,GAAI,QAAQ,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAG,MAQ9D,CAAC;AACF,eAAO,MAAM,UAAU,GAAU,QAAQ,SAAS,EAAE,KAAG,OAAO,CAAC,UAAU,EAAE,CA0C1E,CAAC;AACF,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,OAGzC,CAAC;AACF,eAAO,MAAM,UAAU,GAAU,QAAQ,SAAS,EAAE,KAAG,OAAO,CAAC,UAAU,EAAE,CAqB1E,CAAC;AACF,eAAO,MAAM,kBAAkB,GAAI,UAAU,GAAG,EAAE,KAAG,MAQpD,CAAC;AACF;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,UAAU,GAAG,EAAE,EAAE,cAAc,MAAM,EAAE,gBAAgB,MAAM,KAAG;IACvF,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAOxB,CAAC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils/utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAGtC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvC,eAAO,MAAM,wBAAwB,GAAI,QAAQ,QAAQ,KAAG,WAY3D,CAAC;AACF,eAAO,MAAM,kBAAkB,GAAI,OAAO,QAAQ,EAAE,UAAS,MAAU,KAAG,MAWzE,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAU,OAAO,SAAS,KAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAgCpF,CAAC;AACF,eAAO,MAAM,gBAAgB,GAAI,QAAQ,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAG,MAQ9D,CAAC;AACF,eAAO,MAAM,UAAU,GAAU,QAAQ,SAAS,EAAE,KAAG,OAAO,CAAC,UAAU,EAAE,CA0C1E,CAAC;AACF,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,OAGzC,CAAC;AACF;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,GAAU,QAAQ,SAAS,EAAE,KAAG,OAAO,CAAC,UAAU,EAAE,CAyB1E,CAAC;AACF,eAAO,MAAM,kBAAkB,GAAI,UAAU,GAAG,EAAE,KAAG,MAQpD,CAAC;AACF;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,UAAU,GAAG,EAAE,EAAE,cAAc,MAAM,EAAE,gBAAgB,MAAM,KAAG;IACvF,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAOxB,CAAC"}

package/dist/utils/utils.js

@@ -1,5 +1,5 @@
 import { Box3, Vector3 } from "three";
-import { loadModelGLTF } from "./loadingManager.js";
+import { cloneModelAsset, loadModelAsset, preloadModels } from "./modelCache.js";
 import ObjectManager from "../services/ObjectManager.js";
 export const createDefaultEffectState = (object) => {
     const material = object.material;
@@ -30,8 +30,10 @@ export const calculateAutoScale = (model, maxSize = 5) => {
 export const createModelFromUrl = async (model) => {
     try {
         console.log(`Loading model from model: `, model);
-        const loadedModel = await loadModelGLTF(model.url);
-        // console.log("Model loaded from URL:", loadedModel);
+        // One fetch per URL for the life of the page; this is a per-instance clone of the
+        // cached master, so geometry is shared and materials are this object's own.
+        const asset = await loadModelAsset(model.url).promise;
+        const { object: loadedModel } = cloneModelAsset(asset);
         if (loadedModel) {
             loadedModel.name = model.name || `model_${Date.now()}`;
             loadedModel.scale.set(...(model.scale || [1, 1, 1]));
@@ -114,6 +116,14 @@ export const dontAnimate = (key) => {
     return key.toLowerCase().includes('texture') ||
         key.toLowerCase().includes('noise');
 };
+/**
+ * Preload a project's models and register one instance per scene object id.
+ *
+ * This is an optimisation, not a precondition: a model leaf that mounts without this
+ * having run loads itself through the same cache under Suspense (see
+ * `useModelObject` in the viewer package). Keep calling it so a scene reveals whole
+ * instead of popping in model by model.
+ */
 export const loadAssets = async (models) => {
     console.log(`[loadAssets] Starting to load ${models.length} models`);
     if (models.length === 0) {
@@ -132,6 +142,10 @@ export const loadAssets = async (models) => {
         return true;
     });
     console.log(`[loadAssets] Loading ${cleanedModels.length} valid models (filtered ${models.length - cleanedModels.length})`);
+    // Warm the cache for every URL in parallel first — loadModels then walks the list
+    // sequentially, but each step is a clone of an already-resolved master rather than a
+    // fresh download. Repeated URLs cost one fetch, not one per scene object.
+    await preloadModels(cleanedModels.map(model => model.url));
     const createdObjects = await loadModels(cleanedModels);
     console.log(`[loadAssets] Completed. Loaded ${createdObjects.length}/${cleanedModels.length} models`);
     return createdObjects;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3driseai/3drise-core",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",