@3driseai/3drise-core 1.0.1

package/dist/utils/getAnimatableProperties.js

@@ -0,0 +1,170 @@
+// =============================================================================
+// getAnimatableProperties — canonical per-domain property discovery
+// =============================================================================
+//
+// Single source of truth for "what properties can the animations / mouseMove
+// system target on a given domain?". Both *PropsSection (keyframe animations UI)
+// and *MouseMoveSection (mouse-move UI) read from here, so the two systems
+// never drift.
+//
+// Accepts any AnimatableTarget — CreatedObjectSettings, CloudsSettings, and
+// future env components (Sky/Ocean/...) all satisfy the structural interface.
+//
+// Domain rules:
+//   - transform: hardcoded ['position', 'rotation', 'scale']
+//   - material : keys of settings.materialSettings minus an excluded list
+//   - edges    : geometry props by edgesSettings.type + filtered material keys
+//   - light    : per-light-type allowlist driven by settings.config.type
+//   - clouds   : ['speed'] when settings.config.type === 'clouds'
+//
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+const TRANSFORM_PROPS = [
+    { value: 'position', label: 'Position' },
+    { value: 'rotation', label: 'Rotation' },
+    { value: 'scale', label: 'Scale' },
+];
+const EXCLUDED_MATERIAL_KEYS = new Set([
+    'materialType', 'materialVariant', 'side',
+    'u_time', 'u_mouse',
+    'apply', 'visible', 'map', 'uHasTexture',
+]);
+const LIGHT_COMMON = [
+    { value: 'intensity', label: 'Intensity' },
+    { value: 'color', label: 'Color' },
+];
+const LIGHT_POINT_EXTRA = [
+    { value: 'distance', label: 'Distance' },
+    { value: 'decay', label: 'Decay' },
+];
+const LIGHT_SPOT_EXTRA = [
+    ...LIGHT_POINT_EXTRA,
+    { value: 'angle', label: 'Angle' },
+    { value: 'penumbra', label: 'Penumbra' },
+];
+const CLOUDS_PROPS = [
+    { value: 'speed', label: 'Speed' },
+];
+const RAIN_PROPS = [
+    { value: 'color', label: 'Color' },
+    { value: 'size', label: 'Size' },
+    { value: 'opacity', label: 'Opacity' },
+    { value: 'speed', label: 'Speed' },
+    { value: 'windStrength', label: 'Wind Strength' },
+    { value: 'windDirection', label: 'Wind Direction' },
+    { value: 'turbulence', label: 'Turbulence' },
+];
+// =============================================================================
+// HELPERS
+// =============================================================================
+/** camelCase / kebab-ish → "Title Case". */
+export function toAnimatableLabel(key) {
+    return key
+        .replace(/([A-Z])/g, ' $1')
+        .replace(/^./, s => s.toUpperCase())
+        .trim();
+}
+function getMaterialProperties(materialSettings) {
+    if (!materialSettings)
+        return [];
+    return Object.keys(materialSettings)
+        .filter(k => !EXCLUDED_MATERIAL_KEYS.has(k))
+        .map(k => ({ value: k, label: k }));
+}
+function getEdgesProperties(edgesSettings) {
+    if (!edgesSettings)
+        return [];
+    const props = [];
+    if (edgesSettings.type === 'tube')
+        props.push({ value: 'tubeRadius', label: 'Tube Radius' });
+    if (edgesSettings.type === 'cube')
+        props.push({ value: 'cubeSize', label: 'Cube Size' });
+    if (edgesSettings.materialSettings) {
+        for (const k of Object.keys(edgesSettings.materialSettings)) {
+            if (EXCLUDED_MATERIAL_KEYS.has(k))
+                continue;
+            props.push({ value: k, label: toAnimatableLabel(k) });
+        }
+    }
+    return props;
+}
+function getLightProperties(config) {
+    switch (config?.type) {
+        case 'point':
+            return [...LIGHT_COMMON, ...LIGHT_POINT_EXTRA];
+        case 'spot':
+            return [...LIGHT_COMMON, ...LIGHT_SPOT_EXTRA];
+        case 'ambient':
+        case 'directional':
+        default:
+            return [...LIGHT_COMMON];
+    }
+}
+function getCloudsProperties() {
+    return [...CLOUDS_PROPS];
+}
+function getRainProperties() {
+    return [...RAIN_PROPS];
+}
+function isLightConfig(config) {
+    const t = config?.type;
+    return t === 'ambient' || t === 'directional' || t === 'point' || t === 'spot';
+}
+function isCloudsConfig(config) {
+    return config?.type === 'clouds';
+}
+function isRainConfig(config) {
+    return config?.type === 'rain';
+}
+// =============================================================================
+// MAIN
+// =============================================================================
+export function getAnimatableProperties(settings, domain) {
+    switch (domain) {
+        case 'transform':
+            return [...TRANSFORM_PROPS];
+        case 'material':
+            return getMaterialProperties(settings.materialSettings);
+        case 'edges':
+            return getEdgesProperties(settings.edgesSettings);
+        case 'light':
+            return isLightConfig(settings.config) ? getLightProperties(settings.config) : [];
+        case 'clouds':
+            return isCloudsConfig(settings.config) ? getCloudsProperties() : [];
+        case 'rain':
+            return isRainConfig(settings.config) ? getRainProperties() : [];
+        default:
+            return [];
+    }
+}
+/**
+ * Detect which domain a property name belongs to, for a given target. Used by
+ * the runtime + UI to migrate flat MouseMove arrays into the new per-domain
+ * shape, and to route the runtime's combined dispatch.
+ */
+export function detectAnimatableDomain(settings, propertyName) {
+    const head = propertyName.split('.')[0];
+    if (head === 'position' || head === 'rotation' || head === 'scale') {
+        return 'transform';
+    }
+    const edges = getEdgesProperties(settings.edgesSettings).map(p => p.value);
+    if (edges.includes(propertyName))
+        return 'edges';
+    if (isLightConfig(settings.config)) {
+        if (getLightProperties(settings.config).some(p => p.value === propertyName))
+            return 'light';
+    }
+    if (isCloudsConfig(settings.config)) {
+        if (getCloudsProperties().some(p => p.value === propertyName))
+            return 'clouds';
+    }
+    if (isRainConfig(settings.config)) {
+        if (getRainProperties().some(p => p.value === propertyName))
+            return 'rain';
+    }
+    const material = getMaterialProperties(settings.materialSettings).map(p => p.value);
+    if (material.includes(propertyName))
+        return 'material';
+    return null;
+}

package/dist/utils/gridUtils.d.ts

@@ -0,0 +1,8 @@
+export declare const gridUtils: {
+    snapToGrid: (position: any, cellSize: any) => any[];
+    worldToGrid: (worldPos: any, cellSize: any) => any[];
+    gridToWorld: (gridPos: any, cellSize: any) => any[];
+    isOnGridIntersection: (position: any, cellSize: any, tolerance?: number) => boolean;
+    isOnSectionLine: (position: any, cellSize: any, sectionSize: any, tolerance?: number) => boolean;
+};
+//# sourceMappingURL=gridUtils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gridUtils.d.ts","sourceRoot":"","sources":["../../src/utils/gridUtils.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,SAAS;;;;;;CAyBrB,CAAC"}

package/dist/utils/gridUtils.js

@@ -0,0 +1,26 @@
+export const gridUtils = {
+    snapToGrid: (position, cellSize) => [
+        Math.round(position[0] / cellSize) * cellSize,
+        position[1],
+        Math.round(position[2] / cellSize) * cellSize,
+    ],
+    worldToGrid: (worldPos, cellSize) => [
+        Math.round(worldPos[0] / cellSize),
+        worldPos[1],
+        Math.round(worldPos[2] / cellSize),
+    ],
+    gridToWorld: (gridPos, cellSize) => [
+        gridPos[0] * cellSize,
+        gridPos[1],
+        gridPos[2] * cellSize,
+    ],
+    isOnGridIntersection: (position, cellSize, tolerance = 0.1) => {
+        const s = gridUtils.snapToGrid(position, cellSize);
+        return Math.sqrt((position[0] - s[0]) ** 2 + (position[2] - s[2]) ** 2) <= tolerance;
+    },
+    isOnSectionLine: (position, cellSize, sectionSize, tolerance = 0.1) => {
+        const sectionCells = sectionSize / cellSize;
+        const g = gridUtils.worldToGrid(position, cellSize);
+        return (g[0] % sectionCells < tolerance) || (g[2] % sectionCells < tolerance);
+    },
+};

package/dist/utils/handleEdgesAnimations.d.ts

@@ -0,0 +1,20 @@
+import { Object3D } from "three";
+import { AnimationOptions } from "../types";
+export interface EdgesAnimationContext {
+    /** Main scene object � edges group is searched among its direct children */
+    object: Object3D;
+    /** Cache for start values so we only resolve them once per animation */
+    startValuesCache: Record<string, any>;
+}
+export declare const DEBUG_EDGES_ANIMATIONS = false;
+/**
+ * Process all active edge animations for an object.
+ * Finds the edges group on the object and animates material properties on it.
+ *
+ * @param ctx         - Animation context (main object + start-value cache)
+ * @param animations  - Array of AnimationOptions from animations.edges.animations
+ * @param currentTime - Current timestamp (Date.now())
+ * @param hovered     - Whether the object is currently hovered
+ */
+export declare function handleEdgesAnimations(ctx: EdgesAnimationContext, animations: AnimationOptions[], currentTime: number, hovered: boolean): void;
+//# sourceMappingURL=handleEdgesAnimations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"handleEdgesAnimations.d.ts","sourceRoot":"","sources":["../../src/utils/handleEdgesAnimations.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC5C,MAAM,WAAW,qBAAqB;IAClC,4EAA4E;IAC5E,MAAM,EAAE,QAAQ,CAAC;IACjB,wEAAwE;IACxE,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACzC;AAMD,eAAO,MAAM,sBAAsB,QAAQ,CAAC;AA+E5C;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,qBAAqB,EAAE,UAAU,EAAE,gBAAgB,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAkB7I"}

package/dist/utils/handleEdgesAnimations.js

@@ -0,0 +1,125 @@
+// =============================================================================
+// HANDLE EDGES ANIMATIONS � Edges Material Animations Handler
+// =============================================================================
+//
+// Pure functions for handling keyframe animations that target the edges group
+// of an object (edge material color, opacity, and other material properties).
+//
+// Property paths use the `materialSettings.` prefix to mirror the UI:
+//   e.g.  "materialSettings.color", "materialSettings.opacity"
+// Geometric properties (tubeRadius, cubeSize) require a geometry rebuild and
+// are intentionally skipped for per-frame animation.
+//
+import { applyEasing, gsapEasingMap } from './animationsUtils.js';
+import { calculateTimeProgress, getMaterialPropertyValue, interpolateValue, applyMaterialPropertyToObject, } from './materialUtils.js';
+import { EDGES_GROUP_KEY } from './materialApplicationUtils.js';
+// =============================================================================
+// DEBUG
+// =============================================================================
+export const DEBUG_EDGES_ANIMATIONS = false;
+const log = (message, ...args) => {
+    if (DEBUG_EDGES_ANIMATIONS) {
+        console.log(`[EdgesAnimations] ${message}`, ...args);
+    }
+};
+// =============================================================================
+// HELPERS
+// =============================================================================
+/**
+ * Strip the "materialSettings." prefix that the UI uses for clarity.
+ * Returns the bare Three.js material property name, or null for non-material
+ * properties that cannot be animated per-frame (tubeRadius, cubeSize).
+ */
+function resolveMaterialKey(property) {
+    if (property.startsWith('materialSettings.')) {
+        return property.slice('materialSettings.'.length);
+    }
+    // Geometric properties require geometry rebuild � skip
+    if (property === 'tubeRadius' || property === 'cubeSize') {
+        return null;
+    }
+    // Bare property name (fallback)
+    return property;
+}
+/**
+ * Find the edges group attached to the main object.
+ */
+function findEdgesGroup(object) {
+    for (const child of object.children) {
+        if (child.userData[EDGES_GROUP_KEY]) {
+            return child;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve start value for an animation.
+ * Priority: animation.from ? startValuesCache ? current edges material value
+ */
+function getStartValue(ctx, matKey, animation) {
+    const cacheKey = `edges.${matKey}`;
+    if (animation.from !== undefined)
+        return animation.from;
+    if (cacheKey in ctx.startValuesCache)
+        return ctx.startValuesCache[cacheKey];
+    const edgesGroup = findEdgesGroup(ctx.object);
+    if (!edgesGroup)
+        return null;
+    const value = getMaterialPropertyValue(edgesGroup, matKey);
+    ctx.startValuesCache[cacheKey] = value;
+    return value;
+}
+// =============================================================================
+// SINGLE PROPERTY ANIMATION
+// =============================================================================
+function animateEdgesProperty(ctx, edgesGroup, matKey, animation, currentTime, hovered) {
+    const { to, duration, ease, loop = false, yoyo = false, active, triggerMode = 'always' } = animation;
+    if (!active || to === undefined)
+        return;
+    if (triggerMode === 'hover' && !hovered)
+        return;
+    const from = getStartValue(ctx, matKey, animation);
+    if (from === null || from === undefined) {
+        log('skipping � no start value', { matKey });
+        return;
+    }
+    let timeProgress = calculateTimeProgress(currentTime, duration, yoyo, loop);
+    if (ease) {
+        const fn = gsapEasingMap[ease] || ease;
+        timeProgress = applyEasing(fn, timeProgress);
+    }
+    const interpolated = interpolateValue(matKey, from, to, timeProgress);
+    applyMaterialPropertyToObject(edgesGroup, matKey, interpolated);
+    log('animated edges property', { matKey, from, to, interpolated, progress: timeProgress });
+}
+// =============================================================================
+// MAIN HANDLER
+// =============================================================================
+/**
+ * Process all active edge animations for an object.
+ * Finds the edges group on the object and animates material properties on it.
+ *
+ * @param ctx         - Animation context (main object + start-value cache)
+ * @param animations  - Array of AnimationOptions from animations.edges.animations
+ * @param currentTime - Current timestamp (Date.now())
+ * @param hovered     - Whether the object is currently hovered
+ */
+export function handleEdgesAnimations(ctx, animations, currentTime, hovered) {
+    if (animations.length === 0)
+        return;
+    const edgesGroup = findEdgesGroup(ctx.object);
+    if (!edgesGroup) {
+        log('no edges group found on object');
+        return;
+    }
+    for (const animation of animations) {
+        if (!animation.active)
+            continue;
+        const matKey = resolveMaterialKey(animation.property);
+        if (!matKey) {
+            log('skipping non-animatable edges property', { property: animation.property });
+            continue;
+        }
+        animateEdgesProperty(ctx, edgesGroup, matKey, animation, currentTime, hovered);
+    }
+}

package/dist/utils/handleEdgesMouseMove.d.ts

@@ -0,0 +1,12 @@
+import { Object3D } from "three";
+import type { MouseMoveProperty } from "../types/objectSettings";
+export interface EdgesMouseMoveContext {
+    object: Object3D;
+    /** Optional pre-resolved edges materialSettings used for base-value lookup. */
+    edgesMaterialSettings?: Record<string, any>;
+}
+export declare function handleEdgesMouseMove(ctx: EdgesMouseMoveContext, properties: MouseMoveProperty[], pointer: {
+    x: number;
+    y: number;
+}): void;
+//# sourceMappingURL=handleEdgesMouseMove.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"handleEdgesMouseMove.d.ts","sourceRoot":"","sources":["../../src/utils/handleEdgesMouseMove.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,MAAM,WAAW,qBAAqB;IAClC,MAAM,EAAE,QAAQ,CAAC;IACjB,+EAA+E;IAC/E,qBAAqB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC/C;AAUD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,qBAAqB,EAAE,UAAU,EAAE,iBAAiB,EAAE,EAAE,OAAO,EAAE;IAC/F,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACb,GAAG,IAAI,CAkBf"}

package/dist/utils/handleEdgesMouseMove.js

@@ -0,0 +1,38 @@
+// =============================================================================
+// HANDLE EDGES MOUSE MOVE — pointer-driven edges material property updates
+// =============================================================================
+//
+// Sibling of handleEdgesAnimations. Finds the edges group attached to the
+// object and applies pointer-interpolated values to its material. Geometric
+// properties (tubeRadius, cubeSize) require a geometry rebuild and are
+// intentionally skipped for per-frame application.
+//
+import { applyMaterialPropertyToObject } from './materialUtils.js';
+import { EDGES_GROUP_KEY } from './materialApplicationUtils.js';
+import { interpolateMouseMoveProperty } from './mouseMoveUtils.js';
+function findEdgesGroup(object) {
+    for (const child of object.children) {
+        if (child.userData?.[EDGES_GROUP_KEY])
+            return child;
+    }
+    return null;
+}
+export function handleEdgesMouseMove(ctx, properties, pointer) {
+    if (!properties.length)
+        return;
+    const edgesGroup = findEdgesGroup(ctx.object);
+    if (!edgesGroup)
+        return;
+    for (const { property, enabled, propertySettings } of properties) {
+        if (!property || !enabled)
+            continue;
+        if (property === 'tubeRadius' || property === 'cubeSize')
+            continue;
+        const { axis = 'both', sensitivity = 1, inverted = false, min, max } = propertySettings || {};
+        const baseValue = ctx.edgesMaterialSettings?.[property];
+        if (baseValue === undefined)
+            continue;
+        const next = interpolateMouseMoveProperty(baseValue, min, max, pointer, axis, sensitivity, inverted);
+        applyMaterialPropertyToObject(edgesGroup, property, next);
+    }
+}

package/dist/utils/handleGenerativeEffectsAnimations.d.ts

@@ -0,0 +1,15 @@
+import * as THREE from 'three';
+import { AnimationOptions } from '../types';
+export declare const DEBUG_GENERATIVE_EFFECTS = false;
+/**
+ * Animate config properties of a generative effect by directly mutating
+ * its ShaderMaterial uniforms — no React re-renders, runs at 60fps.
+ *
+ * @param materials        - All ShaderMaterial instances belonging to this effect.
+ * @param animations       - Keyframe animations from GenerativeEffectSettings.animations.
+ * @param startValuesCache - Ref-backed cache to hold initial values (reset externally when config changes).
+ * @param currentTime      - Milliseconds since epoch (Date.now()), consistent with other handlers.
+ * @param hovered          - Whether the parent object is currently hovered.
+ */
+export declare function applyGenerativeAnimations(materials: THREE.ShaderMaterial[], animations: AnimationOptions[] | undefined, startValuesCache: Record<string, any>, currentTime: number, hovered: boolean): void;
+//# sourceMappingURL=handleGenerativeEffectsAnimations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"handleGenerativeEffectsAnimations.d.ts","sourceRoot":"","sources":["../../src/utils/handleGenerativeEffectsAnimations.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAM5C,eAAO,MAAM,wBAAwB,QAAQ,CAAC;AAgH9C;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,KAAK,CAAC,cAAc,EAAE,EAAE,UAAU,EAAE,gBAAgB,EAAE,GAAG,SAAS,EAAE,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAqE3M"}

package/dist/utils/handleGenerativeEffectsAnimations.js

@@ -0,0 +1,218 @@
+// =============================================================================
+// HANDLE GENERATIVE EFFECTS ANIMATIONS — per-effect utility
+// =============================================================================
+//
+// Called from inside each generative effect component's own useFrame loop.
+// Each effect component holds direct refs to its ShaderMaterials and passes
+// them here, avoiding fragile scene-graph traversal.
+//
+// Usage (inside an effect component's useFrame):
+//
+//   useFrame((state) => {
+//     const t = state.clock.getElapsedTime();
+//     mat.uniforms.u_time.value = t;
+//
+//     if (animations?.length) {
+//       applyGenerativeAnimations([mat], animations, startValuesCacheRef.current, Date.now(), hovered ?? false);
+//     }
+//   });
+//
+import * as THREE from 'three';
+import { MathUtils } from 'three';
+import { calculateTimeProgress } from './materialUtils.js';
+import { applyEasing, gsapEasingMap } from './animationsUtils.js';
+// =============================================================================
+// DEBUG
+// =============================================================================
+export const DEBUG_GENERATIVE_EFFECTS = false;
+const log = (message, ...args) => {
+    if (DEBUG_GENERATIVE_EFFECTS) {
+        console.log(`[GenerativeEffectsAnimations] ${message}`, ...args);
+    }
+};
+// Always-on log: prints once per unique key, not every frame
+const _loggedOnce = new Set();
+const logOnce = (key, message, ...args) => {
+    if (_loggedOnce.has(key))
+        return;
+    _loggedOnce.add(key);
+    console.log(`[GenerativeEffectsAnimations] ${message}`, ...args);
+};
+const warnOnce = (key, message, ...args) => {
+    if (_loggedOnce.has(key))
+        return;
+    _loggedOnce.add(key);
+    console.warn(`[GenerativeEffectsAnimations] ${message}`, ...args);
+};
+// =============================================================================
+// HELPERS
+// =============================================================================
+/**
+ * Returns candidate uniform names for a given config property name.
+ * Handles both conventions found across effect shaders:
+ *   intensity  → uIntensity   (camelCase prefix)
+ *   speed      → u_speed      (underscore prefix, used in several shaders)
+ */
+function candidateUniformNames(property) {
+    const capitalized = property.charAt(0).toUpperCase() + property.slice(1);
+    return [`u${capitalized}`, `u_${property}`];
+}
+/**
+ * Find which uniform name actually exists on the provided materials.
+ */
+function findUniformName(materials, property) {
+    const candidates = candidateUniformNames(property);
+    for (const candidate of candidates) {
+        for (const mat of materials) {
+            if (mat.uniforms[candidate] !== undefined) {
+                return candidate;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Read the current value of a uniform across materials (returns the first match).
+ * For Color / Vector3 uniforms, returns a hex string so it can be used as a start value.
+ */
+function readUniformValue(materials, uniformName) {
+    for (const mat of materials) {
+        const u = mat.uniforms[uniformName];
+        if (u !== undefined) {
+            if (u.value instanceof THREE.Color) {
+                return '#' + u.value.getHexString();
+            }
+            // Vector3 color uniforms (e.g. uColor stored as vec3 r/g/b)
+            if (u.value instanceof THREE.Vector3) {
+                _colorFrom.setRGB(u.value.x, u.value.y, u.value.z);
+                return '#' + _colorFrom.getHexString();
+            }
+            return u.value;
+        }
+    }
+    return undefined;
+}
+// Reusable Color instances — avoid per-frame allocation
+const _colorFrom = new THREE.Color();
+const _colorTo = new THREE.Color();
+/**
+ * Write an animated numeric value to all materials that carry the uniform.
+ */
+function applyNumericToMaterials(materials, uniformName, value) {
+    for (const mat of materials) {
+        const u = mat.uniforms[uniformName];
+        if (u !== undefined) {
+            u.value = value;
+        }
+    }
+}
+/**
+ * Write a linearly interpolated color to all materials that carry the uniform.
+ * Handles both THREE.Color values and Vector3-style uniforms.
+ */
+function applyColorToMaterials(materials, uniformName, from, to, t) {
+    _colorFrom.set(from);
+    _colorTo.set(to);
+    const r = MathUtils.lerp(_colorFrom.r, _colorTo.r, t);
+    const g = MathUtils.lerp(_colorFrom.g, _colorTo.g, t);
+    const b = MathUtils.lerp(_colorFrom.b, _colorTo.b, t);
+    for (const mat of materials) {
+        const u = mat.uniforms[uniformName];
+        if (u !== undefined) {
+            const val = u.value;
+            if (val instanceof THREE.Color) {
+                val.setRGB(r, g, b);
+            }
+            else if (val && typeof val === 'object' && 'x' in val) {
+                // THREE.Vector3 uniform
+                val.set(r, g, b);
+            }
+        }
+    }
+}
+function isColorValue(value) {
+    return typeof value === 'string' && (value.startsWith('#') || value.startsWith('rgb'));
+}
+// =============================================================================
+// MAIN EXPORT
+// =============================================================================
+/**
+ * Animate config properties of a generative effect by directly mutating
+ * its ShaderMaterial uniforms — no React re-renders, runs at 60fps.
+ *
+ * @param materials        - All ShaderMaterial instances belonging to this effect.
+ * @param animations       - Keyframe animations from GenerativeEffectSettings.animations.
+ * @param startValuesCache - Ref-backed cache to hold initial values (reset externally when config changes).
+ * @param currentTime      - Milliseconds since epoch (Date.now()), consistent with other handlers.
+ * @param hovered          - Whether the parent object is currently hovered.
+ */
+export function applyGenerativeAnimations(materials, animations, startValuesCache, currentTime, hovered) {
+    if (!animations || animations.length === 0)
+        return;
+    if (materials.length === 0)
+        return;
+    logOnce('called', `Processing ${animations.length} animation(s) across ${materials.length} material(s)`);
+    for (const animation of animations) {
+        try {
+            const { property, to, duration, ease, loop = false, yoyo = false, active, triggerMode = 'always', } = animation;
+            // active===undefined means not explicitly disabled — treat as active
+            if (active === false) {
+                log(`Skipping "${property}": active=false`);
+                continue;
+            }
+            if (triggerMode === 'hover' && !hovered) {
+                log(`Skipping "${property}": triggerMode=hover but not hovered`);
+                continue;
+            }
+            if (to === undefined) {
+                warnOnce(`no-to-${property}`, `Skipping "${property}": no 'to' value defined`);
+                continue;
+            }
+            // Find the uniform that corresponds to this property
+            const uniformName = findUniformName(materials, property);
+            if (!uniformName) {
+                warnOnce(`no-uniform-${property}`, `No uniform found for property "${property}" (tried: ${candidateUniformNames(property).join(', ')}) — available uniforms on mat[0]: ${Object.keys(materials[0]?.uniforms ?? {}).join(', ')}`);
+                continue;
+            }
+            // Initialize start value from the current uniform value (once per animation lifetime)
+            if (!(property in startValuesCache)) {
+                const currentVal = readUniformValue(materials, uniformName);
+                startValuesCache[property] = animation.from !== undefined ? animation.from : currentVal;
+                log('cached start value', { property, uniformName, startValue: startValuesCache[property] });
+            }
+            const from = startValuesCache[property];
+            if (from === undefined || from === null)
+                continue;
+            // Calculate progress
+            let timeProgress = calculateTimeProgress(currentTime, duration, yoyo, loop);
+            if (ease) {
+                const easingFunctionName = gsapEasingMap[ease] || ease;
+                timeProgress = applyEasing(easingFunctionName, timeProgress);
+            }
+            // Apply — guard against type mismatches between 'from' and the actual uniform
+            if (isColorValue(from)) {
+                if (typeof to !== 'string') {
+                    warnOnce(`bad-to-${property}`, `Color property "${property}" has non-string 'to' value:`, to);
+                    continue;
+                }
+                applyColorToMaterials(materials, uniformName, from, to, timeProgress);
+            }
+            else if (typeof from === 'number') {
+                if (typeof to !== 'number') {
+                    warnOnce(`bad-to-num-${property}`, `Numeric property "${property}" has non-numeric 'to' value:`, to);
+                    continue;
+                }
+                const interpolated = MathUtils.lerp(from, to, timeProgress);
+                applyNumericToMaterials(materials, uniformName, interpolated);
+            }
+            else {
+                warnOnce(`bad-from-${property}`, `Unhandled 'from' type for property "${property}":`, typeof from, from);
+                continue;
+            }
+            log('animated', { property, uniformName, from, to, timeProgress });
+        }
+        catch (err) {
+            console.error(`[GenerativeEffectsAnimations] Error animating property "${animation.property}":`, err);
+        }
+    }
+}