@3driseai/3drise-core 1.0.1

package/dist/utils/handleTransformMouseMove.js

@@ -0,0 +1,49 @@
+// =============================================================================
+// HANDLE TRANSFORM MOUSE MOVE — pointer-driven transform property updates
+// =============================================================================
+//
+// Sibling of handleEdgesMouseMove / handleMaterialMouseMove / handleLightMouseMove.
+// Mutates object.position / rotation / scale based on pointer + min/max settings
+// stored in each MouseMoveProperty.
+//
+import { interpolateMouseMoveProperty } from './mouseMoveUtils.js';
+export const TRANSFORM_PROPS = ['position', 'rotation', 'scale'];
+export function isTransformProperty(property) {
+    const head = property.split('.')[0];
+    return TRANSFORM_PROPS.includes(head);
+}
+function applyTransformProperty(object, property, value) {
+    const [prop, axis] = property.split('.');
+    const target = object[prop];
+    if (!target)
+        return;
+    if (axis) {
+        target[axis] = value;
+        return;
+    }
+    if (Array.isArray(value) && value.length >= 3) {
+        target.set(value[0], value[1], value[2]);
+        return;
+    }
+    if (typeof value === 'number') {
+        target.set(value, value, value);
+    }
+}
+export function handleTransformMouseMove(ctx, properties, pointer) {
+    if (!properties.length)
+        return;
+    const { object, meshSettings } = ctx;
+    for (const { property, enabled, propertySettings } of properties) {
+        if (!property || !enabled)
+            continue;
+        if (!isTransformProperty(property))
+            continue;
+        const { axis = 'both', sensitivity = 1, inverted = false, min, max } = propertySettings || {};
+        const head = property.split('.')[0];
+        const baseValue = meshSettings?.[property] ?? object[head];
+        if (baseValue === undefined)
+            continue;
+        const next = interpolateMouseMoveProperty(baseValue, min, max, pointer, axis, sensitivity, inverted);
+        applyTransformProperty(object, property, next);
+    }
+}

package/dist/utils/idUtils.d.ts

@@ -0,0 +1,4 @@
+export declare function createUuid(): string;
+export declare function createTempId(): string;
+export declare function isUuid(id: string): boolean;
+//# sourceMappingURL=idUtils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"idUtils.d.ts","sourceRoot":"","sources":["../../src/utils/idUtils.ts"],"names":[],"mappings":"AAAA,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AACD,wBAAgB,YAAY,IAAI,MAAM,CAErC;AACD,wBAAgB,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAG1C"}

package/dist/utils/idUtils.js

@@ -0,0 +1,10 @@
+export function createUuid() {
+    return crypto.randomUUID();
+}
+export function createTempId() {
+    return `temp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+export function isUuid(id) {
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    return uuidRegex.test(id);
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,34 @@
+export * from './dataUtils';
+export * from './easingUtils';
+export * from './frameAnimations';
+export * from './particleAnimations';
+export * from './galleriesUtils';
+export * from './GalleryCreator';
+export * from './GalleryLayouts';
+export * from './gridUtils';
+export * from './idUtils';
+export * from './loadingManager';
+export * from './materialApplicationUtils';
+export * from './materialUtils';
+export * from './meshUtils';
+export * from './pathUtils';
+export * from './positionsCreatorUtils';
+export * from './sunUtils';
+export * from './utils';
+export * from './edgeUtils';
+export * from './objectTreeUtils';
+export * from './handleTransformEffects';
+export * from './handleEdgesAnimations';
+export * from './handleLightAnimations';
+export * from './handleMaterialEffects';
+export * from './getAnimatableProperties';
+export * from './mouseMoveUtils';
+export * from './handleTransformMouseMove';
+export * from './handleMaterialMouseMove';
+export * from './handleEdgesMouseMove';
+export * from './handleLightMouseMove';
+export * from './sceneQuery';
+export * from './shootingStarHelpers';
+export * from './environmentUtils';
+export * from './MaterialCompiler';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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,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

@@ -0,0 +1,33 @@
+export * from './dataUtils.js';
+export * from './easingUtils.js';
+export * from './frameAnimations.js';
+export * from './particleAnimations.js';
+export * from './galleriesUtils.js';
+export * from './GalleryCreator.js';
+export * from './GalleryLayouts.js';
+export * from './gridUtils.js';
+export * from './idUtils.js';
+export * from './loadingManager.js';
+export * from './materialApplicationUtils.js';
+export * from './materialUtils.js';
+export * from './meshUtils.js';
+export * from './pathUtils.js';
+export * from './positionsCreatorUtils.js';
+export * from './sunUtils.js';
+export * from './utils.js';
+export * from './edgeUtils.js';
+export * from './objectTreeUtils.js';
+export * from './handleTransformEffects.js';
+export * from './handleEdgesAnimations.js';
+export * from './handleLightAnimations.js';
+export * from './handleMaterialEffects.js';
+export * from './getAnimatableProperties.js';
+export * from './mouseMoveUtils.js';
+export * from './handleTransformMouseMove.js';
+export * from './handleMaterialMouseMove.js';
+export * from './handleEdgesMouseMove.js';
+export * from './handleLightMouseMove.js';
+export * from './sceneQuery.js';
+export * from './shootingStarHelpers.js';
+export * from './environmentUtils.js';
+export * from './MaterialCompiler.js';

package/dist/utils/loadingManager.d.ts

@@ -0,0 +1,29 @@
+import { LoadingManager, TextureLoader } from 'three';
+import type { Texture, Object3D } from 'three';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { RGBELoader } from "three/addons/loaders/RGBELoader.js";
+import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
+type LoadCallback = () => void;
+type ProgressCallback = (progress: number) => void;
+type TextureCallback = (texture: Texture) => void;
+interface LoadGLTFResult {
+    mesh: Object3D;
+    diffuseMap: Texture;
+    normalMap: Texture;
+    aoMap: Texture;
+}
+export type { LoadCallback, ProgressCallback, TextureCallback, LoadGLTFResult };
+declare const loadingManager: LoadingManager;
+declare const textureLoader: TextureLoader;
+declare const rgbeLoader: RGBELoader;
+declare const gltfLoader: GLTFLoader;
+declare const dracoLoader: DRACOLoader;
+declare const loadTexture: (src: string, callback?: TextureCallback) => Texture;
+declare const loadTextureAsync: (src: string) => Promise<Texture>;
+declare const loadHdr: (src: string) => Promise<Texture>;
+declare const loadModelGLTF: (src: string) => Promise<Object3D>;
+declare const loadGLTF: (modelSrc: string, diffuseSrc: string, normalSrc: string, aoSrc: string) => Promise<LoadGLTFResult>;
+declare const onLoad: (callback: LoadCallback) => void;
+declare const onProgress: (callback: ProgressCallback) => void;
+export { loadGLTF, loadTexture, loadTextureAsync, onLoad, onProgress, loadModelGLTF, loadHdr, loadingManager, textureLoader, rgbeLoader, gltfLoader, dracoLoader };
+//# sourceMappingURL=loadingManager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"loadingManager.d.ts","sourceRoot":"","sources":["../../src/utils/loadingManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,aAAa,EAAiC,MAAM,OAAO,CAAC;AACrF,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAE/C,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAEhE,OAAO,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC;AAClE,KAAK,YAAY,GAAG,MAAM,IAAI,CAAC;AAE/B,KAAK,gBAAgB,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;AAEnD,KAAK,eAAe,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;AAElD,UAAU,cAAc;IACpB,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;CAClB;AAED,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,cAAc,EAAE,CAAC;AAGhF,QAAA,MAAM,cAAc,EAAE,cAAqC,CAAC;AAC5D,QAAA,MAAM,aAAa,EAAE,aAAiD,CAAC;AACvE,QAAA,MAAM,UAAU,EAAE,UAA6B,CAAC;AAEhD,QAAA,MAAM,UAAU,EAAE,UAA2C,CAAC;AAC9D,QAAA,MAAM,WAAW,EAAE,WAA+B,CAAC;AAyBnD,QAAA,MAAM,WAAW,GAAI,KAAK,MAAM,EAAE,WAAW,eAAe,KAAG,OAU9D,CAAC;AAEF,QAAA,MAAM,gBAAgB,GAAI,KAAK,MAAM,KAAG,OAAO,CAAC,OAAO,CAWtD,CAAC;AAEF,QAAA,MAAM,OAAO,GAAI,KAAK,MAAM,KAAG,OAAO,CAAC,OAAO,CAQ7C,CAAC;AAEF,QAAA,MAAM,aAAa,GAAI,KAAK,MAAM,KAAG,OAAO,CAAC,QAAQ,CAUpD,CAAC;AAEF,QAAA,MAAM,QAAQ,GAAU,UAAU,MAAM,EAAE,YAAY,MAAM,EAAE,WAAW,MAAM,EAAE,OAAO,MAAM,KAAG,OAAO,CAAC,cAAc,CAMtH,CAAC;AAEF,QAAA,MAAM,MAAM,GAAI,UAAU,YAAY,KAAG,IAIxC,CAAC;AAEF,QAAA,MAAM,UAAU,GAAI,UAAU,gBAAgB,KAAG,IAEhD,CAAC;AAEF,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC"}

package/dist/utils/loadingManager.js

@@ -0,0 +1,103 @@
+import { LoadingManager, TextureLoader, RepeatWrapping, HalfFloatType } from 'three';
+// import { TilesRenderer } from "3d-tiles-renderer";
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { RGBELoader } from "three/addons/loaders/RGBELoader.js";
+// import { FontLoader } from 'three/addons/loaders/FontLoader.js';
+import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
+// Initialize loading manager and loaders
+const loadingManager = new LoadingManager();
+const textureLoader = new TextureLoader(loadingManager);
+const rgbeLoader = new RGBELoader();
+rgbeLoader.setDataType(HalfFloatType);
+const gltfLoader = new GLTFLoader(loadingManager);
+const dracoLoader = new DRACOLoader();
+dracoLoader.setDecoderPath('https://www.gstatic.com/draco/versioned/decoders/1.5.6/');
+gltfLoader.setDRACOLoader(dracoLoader);
+// Callback arrays
+const onLoadCallbacks = [];
+const onProgressCallbacks = [];
+// Loading manager event handlers
+loadingManager.onLoad = () => {
+    while (onLoadCallbacks.length) {
+        const callback = onLoadCallbacks.shift();
+        if (callback) {
+            callback.call(null);
+        }
+    }
+};
+loadingManager.onProgress = (item, loaded, total) => {
+    const _onProgressCallbacks = [...onProgressCallbacks];
+    while (_onProgressCallbacks.length) {
+        const callback = _onProgressCallbacks.shift();
+        if (callback) {
+            callback(loaded / total);
+        }
+    }
+};
+// Texture loading function (synchronous - returns texture before image loads)
+const loadTexture = (src, callback) => {
+    // console.log('loadTexture', src);
+    const texture = textureLoader.load(src, () => {
+        if (typeof callback === 'function') {
+            callback(texture);
+        }
+    });
+    texture.wrapS = RepeatWrapping;
+    texture.wrapT = RepeatWrapping;
+    return texture;
+};
+// Async texture loading - resolves when image is fully loaded
+const loadTextureAsync = (src) => {
+    return new Promise((resolve, reject) => {
+        textureLoader.load(src, (texture) => {
+            texture.wrapS = RepeatWrapping;
+            texture.wrapT = RepeatWrapping;
+            resolve(texture);
+        }, undefined, (error) => {
+            console.error('Failed to load texture:', src, error);
+            reject(error);
+        });
+    });
+};
+// HDR loading function
+const loadHdr = (src) => {
+    return new Promise((resolve, reject) => {
+        rgbeLoader.load(src, (texture) => {
+            resolve(texture);
+        }, undefined, (error) => {
+            reject(error);
+        });
+    });
+};
+// GLTF model loading function
+const loadModelGLTF = (src) => {
+    // console.log('loadModelGLTF', src)
+    return new Promise((resolve, reject) => {
+        gltfLoader.load(src, (gltf) => {
+            resolve(gltf.scene);
+        }, undefined, (error) => {
+            console.log('Error loading GLTF model:', src);
+            reject(error);
+        });
+    });
+};
+// Combined GLTF and texture loading function
+const loadGLTF = async (modelSrc, diffuseSrc, normalSrc, aoSrc) => {
+    const mesh = await loadModelGLTF(modelSrc);
+    const diffuseMap = loadTexture(diffuseSrc);
+    const normalMap = loadTexture(normalSrc);
+    const aoMap = loadTexture(aoSrc);
+    return { mesh, diffuseMap, normalMap, aoMap };
+};
+// Register load completion callback
+const onLoad = (callback) => {
+    onLoadCallbacks.push(callback);
+    // Debug reference (consider removing in production)
+    window.aa = loadingManager;
+};
+// Register progress callback
+const onProgress = (callback) => {
+    onProgressCallbacks.push(callback);
+};
+// Export all loading functions and utilities
+export { loadGLTF, loadTexture, loadTextureAsync, onLoad, onProgress, loadModelGLTF, loadHdr, loadingManager, textureLoader, rgbeLoader, gltfLoader, dracoLoader };

package/dist/utils/materialApplicationUtils.d.ts

@@ -0,0 +1,72 @@
+import type { Object3D, Material } from 'three';
+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";
+/**
+ * Traverses obj and its descendants, skipping subtrees whose root is marked
+ * with EDGES_GROUP_KEY or GEREATIVE_EFFECTS_KEY — unless obj itself carries that mark (so an edges group
+ * or generative effects group can still apply its own material via useMaterialApplication).
+ */
+export declare function traverseSkippingEdgesAndEffects(obj: Object3D, isRoot: boolean, callback: (node: Object3D) => void): void;
+/**
+ * Create a fresh material instance for a variant and apply settings to it.
+ */
+export declare function createAndApplyMaterial(variant: string, resolvedSettings: Record<string, any>): MaterialInstance;
+/**
+ * Resolve texture URLs in settings to Three.js Texture objects.
+ * Wraps TextureResolver.resolveSettings() with error handling.
+ */
+export declare function resolveTextures(variant: string, settings: Record<string, any>): Promise<Record<string, any>>;
+export declare function applySingleProperty(material: Material, key: string, value: any): void;
+/**
+ * Apply a color value to a material property.
+ * Converts hex string to Color object and applies correctly.
+ */
+export declare function applyColorProperty(material: Material, key: string, hexValue: string): void;
+/**
+ * Check if a settings key is a color property.
+ */
+export declare function isColorProperty(key: string): boolean;
+/**
+ * Check if a settings key is a texture/map property.
+ */
+export declare function isTextureProperty(key: string): boolean;
+/**
+ * Check if a settings key is a boolean property.
+ */
+export declare function isBooleanProperty(key: string, value: any): boolean;
+/**
+ * Check if a settings key is a numeric property suitable for a slider.
+ */
+export declare function isNumericProperty(key: string, value: any): boolean;
+/**
+ * Internal/meta fields that should never be shown in UI or applied to materials.
+ */
+export declare const INTERNAL_FIELDS: Set<string>;
+/**
+ * Categorize a variant's settings into numeric, color, texture, boolean, and other groups.
+ */
+export declare function categorizeSettings(settings: Record<string, any>): {
+    numeric: Array<{
+        key: string;
+        value: number;
+    }>;
+    colors: Array<{
+        key: string;
+        value: string;
+    }>;
+    textures: Array<{
+        key: string;
+        value: any;
+    }>;
+    booleans: Array<{
+        key: string;
+        value: boolean;
+    }>;
+    other: Array<{
+        key: string;
+        value: any;
+    }>;
+};
+//# sourceMappingURL=materialApplicationUtils.d.ts.map

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

@@ -0,0 +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;;;;GAIG;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

@@ -0,0 +1,169 @@
+// =============================================================================
+// MATERIAL APPLICATION UTILITIES — Shared Pure Functions
+// =============================================================================
+//
+// Core material manipulation functions used by both:
+// - useMaterialApplication (React render cycle, full material replacement)
+// - useMaterialUniforms (direct ref manipulation, live property tweaking)
+//
+// These are pure utility functions — no React hooks, no state.
+//
+import { Color, Vector2 } from 'three';
+import MaterialRegistryAPI from '../services/MaterialRegistry.js';
+import { textureResolver } from '../services/TextureResolver.js';
+import { uniformConverter } from '../services/UniformConverter.js';
+import { getType } from './dataUtils.js';
+// Key stored on userData to track material instances
+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';
+/**
+ * Traverses obj and its descendants, skipping subtrees whose root is marked
+ * with EDGES_GROUP_KEY or GEREATIVE_EFFECTS_KEY — unless obj itself carries that mark (so an edges group
+ * or generative effects group can still apply its own material via useMaterialApplication).
+ */
+export function traverseSkippingEdgesAndEffects(obj, isRoot, callback) {
+    if (!isRoot && (obj.userData[EDGES_GROUP_KEY] || obj.userData[GEREATIVE_EFFECTS_KEY]))
+        return;
+    callback(obj);
+    for (const child of obj.children) {
+        traverseSkippingEdgesAndEffects(child, false, callback);
+    }
+}
+// Known color property names on Three.js materials
+const COLOR_PROPERTIES = new Set([
+    'color', 'emissive', 'specular', 'sheenColor', 'specularColor', 'attenuationColor'
+]);
+/**
+ * Create a fresh material instance for a variant and apply settings to it.
+ */
+export function createAndApplyMaterial(variant, resolvedSettings) {
+    const materialInstance = MaterialRegistryAPI.createMaterial(variant);
+    MaterialRegistryAPI.applySettings(materialInstance.material, resolvedSettings);
+    return materialInstance;
+}
+/**
+ * Resolve texture URLs in settings to Three.js Texture objects.
+ * Wraps TextureResolver.resolveSettings() with error handling.
+ */
+export async function resolveTextures(variant, settings) {
+    try {
+        return await textureResolver.resolveSettings(variant, settings);
+    }
+    catch (error) {
+        console.error('[materialApplicationUtils] Failed to resolve textures:', error);
+        return { ...settings };
+    }
+}
+export function applySingleProperty(material, key, value) {
+    const isShader = !!material.uniforms;
+    if (isShader) {
+        const uniforms = material.uniforms;
+        if (uniforms[key]) {
+            // console.log(`[applySingleProperty] Applying to shader uniform: ${key} =`, value);
+            // For shader uniforms, use uniformConverter for proper type conversion
+            const converted = uniformConverter.convertToUniforms({ [key]: value });
+            // console.log(`[applySingleProperty] Converted uniform value:`, converted[key]);
+            uniforms[key].value = converted[key] ?? value;
+        }
+    }
+    else {
+        // Standard material — need to convert types properly
+        if (COLOR_PROPERTIES.has(key) && typeof value === 'string') {
+            // Color property: must use Color object, not raw string
+            const matProp = material[key];
+            if (matProp && typeof matProp.set === 'function') {
+                matProp.set(value); // Use .set() to preserve the Color instance
+            }
+            else {
+                material[key] = new Color(value);
+            }
+        }
+        else if (key === 'normalScale' && Array.isArray(value) && value.length === 2) {
+            const matProp = material[key];
+            if (matProp && typeof matProp.set === 'function') {
+                matProp.set(value[0], value[1]);
+            }
+            else {
+                material[key] = new Vector2(value[0], value[1]);
+            }
+        }
+        else if (key in material) {
+            material[key] = value;
+        }
+    }
+    material.needsUpdate = true;
+}
+/**
+ * Apply a color value to a material property.
+ * Converts hex string to Color object and applies correctly.
+ */
+export function applyColorProperty(material, key, hexValue) {
+    applySingleProperty(material, key, hexValue);
+}
+/**
+ * Check if a settings key is a color property.
+ */
+export function isColorProperty(key) {
+    return COLOR_PROPERTIES.has(key);
+}
+/**
+ * Check if a settings key is a texture/map property.
+ */
+export function isTextureProperty(key) {
+    const lower = key.toLowerCase();
+    return lower.includes('map') || lower.includes('texture');
+}
+/**
+ * Check if a settings key is a boolean property.
+ */
+export function isBooleanProperty(key, value) {
+    return typeof value === 'boolean';
+}
+/**
+ * Check if a settings key is a numeric property suitable for a slider.
+ */
+export function isNumericProperty(key, value) {
+    return typeof value === 'number';
+}
+/**
+ * Internal/meta fields that should never be shown in UI or applied to materials.
+ */
+export const INTERNAL_FIELDS = new Set([
+    'materialType', 'materialVariant', 'handlers', 'apply',
+    'uHasTexture', 'u_time', 'u_resolution', 'u_mouse',
+]);
+/**
+ * Categorize a variant's settings into numeric, color, texture, boolean, and other groups.
+ */
+export function categorizeSettings(settings) {
+    const result = {
+        numeric: [],
+        colors: [],
+        textures: [],
+        booleans: [],
+        other: [],
+    };
+    for (const [key, value] of Object.entries(settings)) {
+        if (INTERNAL_FIELDS.has(key))
+            continue;
+        const type = getType(key, value);
+        if (type === 'color') {
+            result.colors.push({ key, value });
+        }
+        else if (type === 'texture') {
+            result.textures.push({ key, value });
+        }
+        else if (type === 'checkbox') {
+            result.booleans.push({ key, value });
+        }
+        else if (type === 'number') {
+            result.numeric.push({ key, value });
+        }
+        else {
+            result.other.push({ key, value });
+        }
+    }
+    return result;
+}

package/dist/utils/materialUtils.d.ts

@@ -0,0 +1,79 @@
+import * as THREE from "three";
+import { Color } from "three";
+import type { Object3D } from 'three';
+import type { MaterialSettings } from "../types/materials";
+/**
+ * Updates materials on a mesh to use environment mapping
+ */
+export declare const updateMeshMaterials: (mesh: THREE.Mesh, environment: THREE.Texture | null, envMapIntensity?: number) => void;
+/**
+ * Sets up reflective properties on materials
+ */
+export declare const setupReflectiveMaterial: (material: THREE.Material) => void;
+/**
+ * Traverses scene and updates all materials with environment mapping
+ */
+export declare const updateSceneMaterials: (scene: THREE.Scene, environment: THREE.Texture | null, setupReflective?: boolean) => void;
+/**
+ * Checks if a material supports environment mapping
+ */
+export declare const supportsEnvironmentMapping: (material: THREE.Material) => boolean;
+export declare const settingsToProps: (settings: MaterialSettings) => any;
+export declare const DEBUG_MATERIAL_ANIMATION = false;
+/**
+ * Calculate animation progress with yoyo/loop support.
+ * @param currentTime - Current timestamp (Date.now())
+ * @param duration - Animation duration in milliseconds
+ * @param yoyo - Whether to reverse direction at end
+ * @param loop - Whether to loop continuously
+ * @returns Progress value between 0 and 1
+ */
+export declare const calculateTimeProgress: (currentTime: number, duration: number, yoyo: boolean, loop: boolean) => number;
+/**
+ * Animate system uniforms (u_time, u_mouse, u_camera_position) on children with materials.
+ */
+export declare const animateUniforms: (children: any[], time: number, mouse: {
+    x: number;
+    y: number;
+}, cameraPosition?: {
+    x: number;
+    y: number;
+    z: number;
+}) => void;
+/**
+ * Get current value of a material property from an object.
+ * Traverses children to find first material with the property.
+ */
+export declare function getMaterialPropertyValue(object: Object3D, property: string): any;
+/**
+ * Interpolate between two color values.
+ * Accepts hex strings or Color objects.
+ */
+export declare function interpolateColor(from: string | Color, to: string | Color, progress: number): string;
+/**
+ * Interpolate between two Vector2 values.
+ */
+export declare function interpolateVector2(from: [number, number], to: [number, number], progress: number): [number, number];
+/**
+ * Interpolate between two Vector3 values.
+ */
+export declare function interpolateVector3(from: [number, number, number], to: [number, number, number], progress: number): [number, number, number];
+/**
+ * Interpolate value based on detected type using getType.
+ * @param property - Property name for type detection
+ * @param from - Start value
+ * @param to - End value
+ * @param progress - Interpolation progress (0-1)
+ * @returns Interpolated value
+ */
+export declare function interpolateValue(property: string, from: any, to: any, progress: number): any;
+/**
+ * Apply a material property value to all children with materials.
+ * Uses applySingleProperty from materialApplicationUtils.
+ */
+export declare function applyMaterialPropertyToObject(object: Object3D, property: string, value: any): void;
+/**
+ * Cache all children with materials to avoid traverse() every frame.
+ */
+export declare function cacheChildrenWithMaterials(object: Object3D): any[];
+//# sourceMappingURL=materialUtils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"materialUtils.d.ts","sourceRoot":"","sources":["../../src/utils/materialUtils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,KAAK,EAA+B,MAAM,OAAO,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAGtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,KAAK,CAAC,IAAI,EAAE,aAAa,KAAK,CAAC,OAAO,GAAG,IAAI,EAAE,kBAAiB,MAAU,KAAG,IAUtH,CAAC;AACF;;GAEG;AACH,eAAO,MAAM,uBAAuB,GAAI,UAAU,KAAK,CAAC,QAAQ,KAAG,IAclE,CAAC;AACF;;GAEG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO,KAAK,CAAC,KAAK,EAAE,aAAa,KAAK,CAAC,OAAO,GAAG,IAAI,EAAE,kBAAiB,OAAe,KAAG,IAU9H,CAAC;AACF;;GAEG;AACH,eAAO,MAAM,0BAA0B,GAAI,UAAU,KAAK,CAAC,QAAQ,KAAG,OAGrE,CAAC;AAeF,eAAO,MAAM,eAAe,GAAI,UAAU,gBAAgB,KAAG,GAoB5D,CAAC;AAMF,eAAO,MAAM,wBAAwB,QAAQ,CAAC;AAM9C;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,GAAI,aAAa,MAAM,EAAE,UAAU,MAAM,EAAE,MAAM,OAAO,EAAE,MAAM,OAAO,KAAG,MAW3G,CAAC;AACF;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,GAAG,EAAE,EAAE,MAAM,MAAM,EAAE,OAAO;IAC1D,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACb,EAAE,iBAAiB;IAChB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACb,KAAG,IAqBX,CAAC;AACF;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,GAAG,CA6BhF;AACD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,EAAE,EAAE,EAAE,MAAM,GAAG,KAAK,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAOnG;AACD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAKnH;AACD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAM3I;AACD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,GAAG,GAAG,CAqB5F;AACD;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI,CAOlG;AACD;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,QAAQ,GAAG,GAAG,EAAE,CAQlE"}