@3driseai/3drise-viewer 0.1.18 → 0.1.20

package/dist/components/particles/TidalStreamParticles.d.ts

@@ -1,11 +1,14 @@
 import React from 'react';
-import type { AnimationOptions, TidalStreamParticlesConfig } from '@3driseai/3drise-core';
+import type { ObjectAnimations, TidalStreamParticlesConfig } from '@3driseai/3drise-core';
 import type { ObjectReadyProps } from '../../types/objectReady';
 export interface TidalStreamParticlesProps extends ObjectReadyProps {
+    /** Scene object id: the controller finds the live-edit handle by it. */
+    id?: string;
     /** World size of the object (units); the object's transform scales it further. */
     size: number;
     config: TidalStreamParticlesConfig;
-    animations?: AnimationOptions[];
+    /** Per-domain keyframes; the `particles` domain drives this object's config knobs. */
+    animations?: ObjectAnimations;
 }
 declare const TidalStreamParticles: React.FC<TidalStreamParticlesProps>;
 export default TidalStreamParticles;

package/dist/components/particles/TidalStreamParticles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TidalStreamParticles.d.ts","sourceRoot":"","sources":["../../../src/components/particles/TidalStreamParticles.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAsD,MAAM,OAAO,CAAC;AAG3E,OAAO,KAAK,EAAE,gBAAgB,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AAK1F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,MAAM,WAAW,yBAA0B,SAAQ,gBAAgB;IAC/D,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,0BAA0B,CAAC;IACnC,UAAU,CAAC,EAAE,gBAAgB,EAAE,CAAC;CACnC;AA6sBD,QAAA,MAAM,oBAAoB,EAAE,KAAK,CAAC,EAAE,CAAC,yBAAyB,CA6B7D,CAAC;AAEF,eAAe,oBAAoB,CAAC"}
+{"version":3,"file":"TidalStreamParticles.d.ts","sourceRoot":"","sources":["../../../src/components/particles/TidalStreamParticles.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAmE,MAAM,OAAO,CAAC;AAIxF,OAAO,KAAK,EAAE,gBAAgB,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AAM1F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,MAAM,WAAW,yBAA0B,SAAQ,gBAAgB;IAC/D,wEAAwE;IACxE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,0BAA0B,CAAC;IACnC,sFAAsF;IACtF,UAAU,CAAC,EAAE,gBAAgB,CAAC;CACjC;AAmtBD,QAAA,MAAM,oBAAoB,EAAE,KAAK,CAAC,EAAE,CAAC,yBAAyB,CAiD7D,CAAC;AAEF,eAAe,oBAAoB,CAAC"}

package/dist/components/particles/TidalStreamParticles.js

@@ -1,11 +1,13 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useEffect, useLayoutEffect, useMemo, useRef } from 'react';
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef } from 'react';
 import * as THREE from 'three';
 import { useFrame } from '@react-three/fiber';
-import { applyGenerativeAnimations } from '../../utils/handleGenerativeEffectsAnimations.js';
+import { GENERATIVE_PARTICLES_ANIMATABLE } from '@3driseai/3drise-core';
+import { applyConfigKeyframeAnimations } from '../../utils/configAnimations.js';
 import { createPointerUniforms, stepPointerField, usePointerField } from '../../utils/pointerField.js';
 import { createTrailUniforms, applyTrailConfig, createCpuTrail } from '../../utils/particleTrails.js';
 import { useObjectReady } from '../../hooks/useObjectReady.js';
+import { useConfigLiveHandle } from '../../hooks/useConfigLive.js';
 /**
  * Tidal Stream — A spiral galaxy shredding dwarf satellites into tidal streams: symplectic orbits, density-wave arms, Doppler-shifted blackbody stars; the cursor is a subhalo, black hole or spectroscope. Use for space scenes.
  */
@@ -762,9 +764,12 @@ const DEFAULTS = {
     trailColor: '#7fa8ff',
     trailShare: 0.25,
 };
-const TidalStreamParticles = ({ size, config, animations, onObjectReady, onObjectDispose }) => {
+/** Knobs that rebuild the simulation: they change on commit, never through the live path. */
+const ANIMATABLE = new Set(GENERATIVE_PARTICLES_ANIMATABLE.tidalStream.map((p) => p.value));
+/** Knobs that rebuild the simulation: they change on commit, never through the live path. */
+const STRUCTURAL = ['particleCount', 'satelliteCount', 'orbitEccentricity', 'streamAge', 'discStars'];
+const TidalStreamParticles = ({ id, size, config, animations, onObjectReady, onObjectDispose }) => {
     const rootRef = useRef(null);
-    const animCache = useRef({});
     useObjectReady(rootRef, config, onObjectReady, onObjectDispose);
     const s = size > 0 ? size : 1;
     const cfg = useMemo(() => ({ ...DEFAULTS, ...config }), [config]);
@@ -777,11 +782,28 @@ const TidalStreamParticles = ({ size, config, animations, onObjectReady, onObjec
         applyConfig(uniforms, cfg, s);
         instance.apply(cfg);
     }, [instance, uniforms, cfg, s]);
+    // Slider drags and keyframe animations are both overrides on the committed config.
+    // This is the one place they are merged and pushed, so they compose instead of
+    // overwriting each other; the animation wins, because it is the active driver.
+    const keyframes = animations?.particles?.animations;
+    const animOverride = useRef({});
+    const animFrom = useRef({});
+    const animStart = useRef(0);
+    // Editing a keyframe restarts its cycle rather than dropping the user mid-way.
+    useEffect(() => { animStart.current = performance.now(); animFrom.current = {}; }, [keyframes]);
+    const push = useCallback((overrides) => {
+        const merged = { ...cfg, ...overrides, ...animOverride.current };
+        const z = merged.size;
+        applyConfig(uniforms, merged, z && z > 0 ? z : s);
+    }, [cfg, uniforms, s]);
+    const live = useConfigLiveHandle(rootRef, id, 'particles', cfg, STRUCTURAL, push);
     const pointer = usePointerField();
     useFrame((state, delta) => {
         instance.update(Math.min(delta, 0.1), state.camera, pointer);
-        if (animations?.length)
-            applyGenerativeAnimations(instance.materials, animations, animCache.current, Date.now(), false);
+        if (keyframes?.length) {
+            applyConfigKeyframeAnimations(keyframes, animFrom.current, cfg, animOverride.current, performance.now() - animStart.current, ANIMATABLE);
+            push(live.current);
+        }
     });
     return (_jsx("group", { ref: rootRef, children: _jsx("primitive", { object: instance.object }) }));
 };

package/dist/components/particles/index.d.ts

@@ -8,4 +8,10 @@ export { default as ElectronOrbitalsParticles } from './ElectronOrbitalsParticle
 export type { ElectronOrbitalsParticlesProps } from './ElectronOrbitalsParticles';
 export { default as GrinderSparksParticles } from './GrinderSparksParticles';
 export type { GrinderSparksParticlesProps } from './GrinderSparksParticles';
+export { default as ChladniSandParticles } from './ChladniSandParticles';
+export type { ChladniSandParticlesProps } from './ChladniSandParticles';
+export { default as FaradayPowderParticles } from './FaradayPowderParticles';
+export type { FaradayPowderParticlesProps } from './FaradayPowderParticles';
+export { default as NeonRainParticles } from './NeonRainParticles';
+export type { NeonRainParticlesProps } from './NeonRainParticles';
 //# sourceMappingURL=index.d.ts.map

package/dist/components/particles/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/particles/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,IAAI,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACzE,YAAY,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AACxE,OAAO,EAAE,OAAO,IAAI,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAC3E,YAAY,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,EAAE,OAAO,IAAI,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AACvF,YAAY,EAAE,gCAAgC,EAAE,MAAM,+BAA+B,CAAC;AACtF,OAAO,EAAE,OAAO,IAAI,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AACnF,YAAY,EAAE,8BAA8B,EAAE,MAAM,6BAA6B,CAAC;AAClF,OAAO,EAAE,OAAO,IAAI,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAC7E,YAAY,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/particles/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,IAAI,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACzE,YAAY,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AACxE,OAAO,EAAE,OAAO,IAAI,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAC3E,YAAY,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,EAAE,OAAO,IAAI,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AACvF,YAAY,EAAE,gCAAgC,EAAE,MAAM,+BAA+B,CAAC;AACtF,OAAO,EAAE,OAAO,IAAI,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AACnF,YAAY,EAAE,8BAA8B,EAAE,MAAM,6BAA6B,CAAC;AAClF,OAAO,EAAE,OAAO,IAAI,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAC7E,YAAY,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAC5E,OAAO,EAAE,OAAO,IAAI,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACzE,YAAY,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AACxE,OAAO,EAAE,OAAO,IAAI,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAC7E,YAAY,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAC5E,OAAO,EAAE,OAAO,IAAI,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACnE,YAAY,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/components/particles/index.js

@@ -4,3 +4,6 @@ export { default as BrownianDustParticles } from './BrownianDustParticles.js';
 export { default as BioluminescentWakeParticles } from './BioluminescentWakeParticles.js';
 export { default as ElectronOrbitalsParticles } from './ElectronOrbitalsParticles.js';
 export { default as GrinderSparksParticles } from './GrinderSparksParticles.js';
+export { default as ChladniSandParticles } from './ChladniSandParticles.js';
+export { default as FaradayPowderParticles } from './FaradayPowderParticles.js';
+export { default as NeonRainParticles } from './NeonRainParticles.js';

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,gBAAgB,oCAA2B,CAAC;AACzD,eAAO,MAAM,qBAAqB,aAchC,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,gBAAgB,oCAA2B,CAAC;AACzD,eAAO,MAAM,qBAAqB,aAehC,CAAC"}

package/dist/constants.js

@@ -12,10 +12,11 @@ export const SELF_MANAGED_MATERIAL = new Set([
     'effect',
     'space',
     'grid',
+    'particles',
     // The water surface owns its shader — one material for both hosts, built
     // around the wave field. Left out of this set, useMaterialApplication
     // overwrites it with whatever the registry has under materialType, which for
     // a legacy ocean is the old flat-plane water material.
-    'ocean',
+    // 'ocean',
     // 'moon'
 ]);

package/dist/hooks/index.d.ts

@@ -17,6 +17,8 @@ export { useClipmap } from './useClipmap';
 export type { OceanLiveHandle } from './useOceanLive';
 export { OCEAN_LIVE_KEY, useOceanLive } from './useOceanLive';
 export { useOceanMaterial } from './useOceanMaterial';
+export type { ConfigLiveHandle, ConfigLiveValue, ConfigLiveFamily } from './useConfigLive';
+export { CONFIG_LIVE_KEY, useConfigLive, useConfigLiveHandle } from './useConfigLive';
 export type { UseOceanMaterialOptions, OceanMaterialHandle } from './useOceanMaterial';
 export type { UseContinuousEffectsOptions, UseContinuousEffectsResult } from './useContinuousEffects';
 export { useContinuousEffects } from './useContinuousEffects';
@@ -55,6 +57,7 @@ export { useObjectEdges } from './useObjectEdges';
 export type { ObjectEffectsFunctions, ObjectEffectsState, UseObjectEffectsReturn } from './useObjectEffects';
 export { useObjectEffects } from './useObjectEffects';
 export { useModelObject } from './useModelObject';
+export { useNodeOverrides, reconcileNodeOverrides, restoreNodeOverrides } from './useNodeOverrides';
 export { useObjectReady, useObjectReadyReporter } from './useObjectReady';
 export type { GridSurfaceOptions, GridSurfaceUniforms } from './useGridSurface';
 export { useGridSurface } from './useGridSurface';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"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"}

package/dist/hooks/index.js

@@ -13,6 +13,7 @@ export { useTerrainClipmap } from './useTerrainClipmap.js';
 export { useClipmap } from './useClipmap.js';
 export { OCEAN_LIVE_KEY, useOceanLive } from './useOceanLive.js';
 export { useOceanMaterial } from './useOceanMaterial.js';
+export { CONFIG_LIVE_KEY, useConfigLive, useConfigLiveHandle } from './useConfigLive.js';
 export { useContinuousEffects } from './useContinuousEffects.js';
 export { useCubeCamera } from './useCubeCamera.js';
 export { useEnvironmentProbe } from './useEnvironmentProbe.js';
@@ -39,6 +40,7 @@ export { useObjectAnimation } from './useObjectAnimation.js';
 export { useObjectEdges } from './useObjectEdges.js';
 export { useObjectEffects } from './useObjectEffects.js';
 export { useModelObject } from './useModelObject.js';
+export { useNodeOverrides, reconcileNodeOverrides, restoreNodeOverrides } from './useNodeOverrides.js';
 export { useObjectReady, useObjectReadyReporter } from './useObjectReady.js';
 export { useGridSurface } from './useGridSurface.js';
 export { useOrbitControls } from './useOrbitControls.js';

package/dist/hooks/useConfigLive.d.ts

@@ -0,0 +1,54 @@
+import { type MutableRefObject, type RefObject } from 'react';
+import type { Object3D } from 'three';
+/**
+ * Live config editing for the generative families (particles now, effects next),
+ * the counterpart to `useOceanLive` / `useTerrainLive`.
+ *
+ * A slider drag fires on every pointer-move. Routing that through Redux hands the
+ * component a new config sixty times a second; every continuous knob only touches
+ * uniforms, so the controller writes straight into them instead, and Redux only
+ * hears about it on slider end.
+ *
+ *   const live = useConfigLive(settings.id);
+ *   <ParticlesControllerUi onLiveChange={live.set} onSettingsChange={dispatch} ... />
+ *
+ * The renderer side registers the handle and owns the merge:
+ *
+ *   const liveRef = useConfigLiveHandle(rootRef, id, 'particles', STRUCTURAL, push);
+ *   // push(overrides) -> applyConfig(uniforms, { ...config, ...overrides, ...animated }, size)
+ *
+ * Structural knobs rebuild the object, so the handle ignores them: they change on
+ * release, through the committed config, exactly once.
+ *
+ * The handle is found by the object's id, resolved at call time (see the note on
+ * useOceanLive: an object resolved once while the panel opens before the object
+ * exists stays null forever). It lives on its own userData key and carries its own
+ * id, so it never competes with the scene's `userData.id` used by selection.
+ */
+/** Where a generative component stashes its handle on its root group's userData. */
+export declare const CONFIG_LIVE_KEY = "__configLive";
+export type ConfigLiveValue = number | string | boolean;
+/** Generative families that support live config editing. */
+export type ConfigLiveFamily = 'particles' | 'effects';
+export interface ConfigLiveHandle {
+    id: string;
+    family: ConfigLiveFamily;
+    /** False once the component has unmounted or re-registered. */
+    alive: boolean;
+    set(key: string, value: ConfigLiveValue): void;
+}
+/** Client side: a stable `set(key, value)` for the generative object with this id. */
+export declare function useConfigLive(id?: string | null): {
+    set(key: string, value: ConfigLiveValue): void;
+};
+/**
+ * Renderer side: registers the live handle and returns the ref holding everything
+ * dragged since the last commit. `apply` is called with that ref's contents on every
+ * live change; the component owns the merge, so keyframe animations compose with it.
+ *
+ * Pass `config` so a committed config drops the drag state — the commit *is* the
+ * same value, and keeping the override would pin the knob against later edits.
+ */
+export declare function useConfigLiveHandle(rootRef: RefObject<Object3D | null>, id: string | undefined, family: ConfigLiveFamily, config: object, structural: readonly string[], apply: (overrides: Record<string, ConfigLiveValue>) => void): MutableRefObject<Record<string, ConfigLiveValue>>;
+export default useConfigLive;
+//# sourceMappingURL=useConfigLive.d.ts.map

package/dist/hooks/useConfigLive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useConfigLive.d.ts","sourceRoot":"","sources":["../../src/hooks/useConfigLive.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,KAAK,gBAAgB,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAChG,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAGtC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,oFAAoF;AACpF,eAAO,MAAM,eAAe,iBAAiB,CAAC;AAE9C,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAExD,4DAA4D;AAC5D,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,SAAS,CAAC;AAEvD,MAAM,WAAW,gBAAgB;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,gBAAgB,CAAC;IACzB,+DAA+D;IAC/D,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;CAClD;AAgBD,sFAAsF;AACtF,wBAAgB,aAAa,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG;IAAE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,IAAI,CAAA;CAAE,CAYpG;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAC/B,OAAO,EAAE,SAAS,CAAC,QAAQ,GAAG,IAAI,CAAC,EACnC,EAAE,EAAE,MAAM,GAAG,SAAS,EACtB,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,KAAK,IAAI,GAC5D,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CA8BnD;AAED,eAAe,aAAa,CAAC"}

package/dist/hooks/useConfigLive.js

@@ -0,0 +1,100 @@
+import { useLayoutEffect, useMemo, useRef } from 'react';
+import { SceneStore } from '@3driseai/3drise-core';
+/**
+ * Live config editing for the generative families (particles now, effects next),
+ * the counterpart to `useOceanLive` / `useTerrainLive`.
+ *
+ * A slider drag fires on every pointer-move. Routing that through Redux hands the
+ * component a new config sixty times a second; every continuous knob only touches
+ * uniforms, so the controller writes straight into them instead, and Redux only
+ * hears about it on slider end.
+ *
+ *   const live = useConfigLive(settings.id);
+ *   <ParticlesControllerUi onLiveChange={live.set} onSettingsChange={dispatch} ... />
+ *
+ * The renderer side registers the handle and owns the merge:
+ *
+ *   const liveRef = useConfigLiveHandle(rootRef, id, 'particles', STRUCTURAL, push);
+ *   // push(overrides) -> applyConfig(uniforms, { ...config, ...overrides, ...animated }, size)
+ *
+ * Structural knobs rebuild the object, so the handle ignores them: they change on
+ * release, through the committed config, exactly once.
+ *
+ * The handle is found by the object's id, resolved at call time (see the note on
+ * useOceanLive: an object resolved once while the panel opens before the object
+ * exists stays null forever). It lives on its own userData key and carries its own
+ * id, so it never competes with the scene's `userData.id` used by selection.
+ */
+/** Where a generative component stashes its handle on its root group's userData. */
+export const CONFIG_LIVE_KEY = '__configLive';
+/** Keys that never go through the live path, whatever the family. */
+const ALWAYS_COMMIT = ['trailMode', 'trailShare', 'enabled', 'type'];
+function findHandle(id) {
+    if (!id || !SceneStore.scene)
+        return undefined;
+    let found;
+    SceneStore.scene.traverse((o) => {
+        if (found)
+            return;
+        const h = o.userData?.[CONFIG_LIVE_KEY];
+        if (h && h.id === id)
+            found = h;
+    });
+    return found;
+}
+/** Client side: a stable `set(key, value)` for the generative object with this id. */
+export function useConfigLive(id) {
+    return useMemo(() => {
+        let cached;
+        return {
+            set: (key, value) => {
+                if (!id)
+                    return;
+                // one scene traversal per drag, not per pointer-move
+                if (!cached || !cached.alive || cached.id !== id)
+                    cached = findHandle(id);
+                cached?.set(key, value);
+            },
+        };
+    }, [id]);
+}
+/**
+ * Renderer side: registers the live handle and returns the ref holding everything
+ * dragged since the last commit. `apply` is called with that ref's contents on every
+ * live change; the component owns the merge, so keyframe animations compose with it.
+ *
+ * Pass `config` so a committed config drops the drag state — the commit *is* the
+ * same value, and keeping the override would pin the knob against later edits.
+ */
+export function useConfigLiveHandle(rootRef, id, family, config, structural, apply) {
+    const live = useRef({});
+    const applyRef = useRef(apply);
+    applyRef.current = apply;
+    // the committed config supersedes whatever the drag wrote
+    useLayoutEffect(() => { live.current = {}; }, [config]);
+    useLayoutEffect(() => {
+        const root = rootRef.current;
+        if (!root || !id)
+            return;
+        const skip = new Set([...structural, ...ALWAYS_COMMIT]);
+        const handle = {
+            id,
+            family,
+            alive: true,
+            set(key, value) {
+                if (!handle.alive || skip.has(key))
+                    return;
+                live.current = { ...live.current, [key]: value };
+                applyRef.current(live.current);
+            },
+        };
+        root.userData[CONFIG_LIVE_KEY] = handle;
+        return () => {
+            handle.alive = false;
+            if (root.userData[CONFIG_LIVE_KEY] === handle)
+                delete root.userData[CONFIG_LIVE_KEY];
+        };
+    }, [rootRef, id, family, structural]);
+    return live;
+}
+export default useConfigLive;

package/dist/hooks/useMaterialApplication.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useMaterialApplication.d.ts","sourceRoot":"","sources":["../../src/hooks/useMaterialApplication.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAG9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG/D,eAAO,MAAM,sBAAsB,GAAI,QAAQ,cAAc,EAAE,kBAAkB,gBAAgB,EAAE,4BAA4B,OAAO,EAAE,YAAY,MAAM,IAAI,KAAG,IAuIhK,CAAC"}
+{"version":3,"file":"useMaterialApplication.d.ts","sourceRoot":"","sources":["../../src/hooks/useMaterialApplication.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAG9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG/D,eAAO,MAAM,sBAAsB,GAAI,QAAQ,cAAc,EAAE,kBAAkB,gBAAgB,EAAE,4BAA4B,OAAO,EAAE,YAAY,MAAM,IAAI,KAAG,IAwIhK,CAAC"}

package/dist/hooks/useMaterialApplication.js

@@ -93,6 +93,7 @@ export const useMaterialApplication = (source, materialSettings, shouldApply3dri
                         applyMaterialToChild(child, variant, resolvedSettings);
                     }
                 }));
+                onApplied?.();
                 return;
             }
             traverseSkippingEdgesAndEffects(obj, true, (child) => {

package/dist/hooks/useNodeOverrides.d.ts

@@ -0,0 +1,13 @@
+import type { Object3D } from 'three';
+import type { NodeOverrides } from '@3driseai/3drise-core';
+export declare function reconcileNodeOverrides(root: Object3D, overrides: NodeOverrides | undefined, master?: Object3D | null): void;
+/** Put every node this root touched back to its original state and free our materials. */
+export declare function restoreNodeOverrides(root: Object3D, master?: Object3D | null): void;
+/**
+ * @param object  the mounted model clone (one layout slot)
+ * @param overrides  createdObject.config.nodeOverrides (getNodeOverrides)
+ * @param master  the cache master scene (peekModelAsset(url)?.scene) — source of originals
+ */
+export declare function useNodeOverrides(object: Object3D | null, overrides: NodeOverrides | undefined, master?: Object3D | null): void;
+export default useNodeOverrides;
+//# sourceMappingURL=useNodeOverrides.d.ts.map

package/dist/hooks/useNodeOverrides.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useNodeOverrides.d.ts","sourceRoot":"","sources":["../../src/hooks/useNodeOverrides.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAY,QAAQ,EAAE,MAAM,OAAO,CAAC;AAUhD,OAAO,KAAK,EAAwD,aAAa,EAAgB,MAAM,uBAAuB,CAAC;AAiM/H,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,GAAG,SAAS,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,IAAI,GAAG,IAAI,CA0C3H;AAED,0FAA0F;AAC1F,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,IAAI,GAAG,IAAI,CAEnF;AAID;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI,EAAE,SAAS,EAAE,aAAa,GAAG,SAAS,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,IAAI,GAAG,IAAI,CAa9H;AAED,eAAe,gBAAgB,CAAC"}

package/dist/hooks/useNodeOverrides.js

@@ -0,0 +1,254 @@
+// =============================================================================
+// useNodeOverrides — apply per-mesh overrides to a mounted model instance
+// =============================================================================
+//
+// Reconciles `createdObject.config.nodeOverrides` (keyed by node name, or "/i/j" index path for
+// unnamed nodes — see core nodeOverrides.ts) onto one model clone:
+// visibility, local transform, and material (tweak the mesh's own material, or replace it
+// with a full 3drise material).
+//
+// Reconcile, not patch: every run computes the desired state for every node it has ever
+// touched, so removing an override (or one field of it) restores the original value.
+//
+// Originals:
+//   - transform / visibility come from the cache master (the never-mounted GLB scene), so
+//     a gizmo that moved the live node before the override was saved cannot corrupt them.
+//   - material "base" is whatever the model-level pass left on the mesh (GLB material, or
+//     the object's materialSettings when `apply` is on). Materials this hook creates are
+//     tagged so they are never mistaken for a base.
+//
+import { useContext, useEffect } from 'react';
+import { MaterialRegistryAPI, NODE_OVERRIDE_MATERIAL_KEY, applyMaterialTweak, collectOverrideTargets, createAndApplyMaterial, resolveNodeKey, resolveTextures, } from '@3driseai/3drise-core';
+import { ModelMaterialPassContext } from '../components/ModelMaterialPassContext.js';
+const nodeStates = new WeakMap();
+const touchedByRoot = new WeakMap();
+const stateOf = (node) => {
+    let s = nodeStates.get(node);
+    if (!s) {
+        s = {};
+        nodeStates.set(node, s);
+    }
+    return s;
+};
+const isOwn = (material) => {
+    if (!material)
+        return false;
+    const list = Array.isArray(material) ? material : [material];
+    return list.some(m => m?.userData?.[NODE_OVERRIDE_MATERIAL_KEY]);
+};
+const tag = (m) => {
+    m.userData[NODE_OVERRIDE_MATERIAL_KEY] = true;
+    return m;
+};
+const disposeOwn = (s) => {
+    if (s.ownInstance) {
+        try {
+            MaterialRegistryAPI.releaseMaterial(s.ownInstance);
+        }
+        catch { /* ignore */ }
+    }
+    else if (s.ownMaterial) {
+        (Array.isArray(s.ownMaterial) ? s.ownMaterial : [s.ownMaterial]).forEach(m => m?.dispose());
+    }
+    s.ownMaterial = undefined;
+    s.ownInstance = undefined;
+    s.materialKey = undefined;
+};
+/** Original local transform + visibility for `node`: master first, snapshot fallback. */
+const originalOf = (node) => {
+    const m = stateOf(node).masterNode;
+    if (m) {
+        return {
+            position: [m.position.x, m.position.y, m.position.z],
+            rotation: [m.rotation.x, m.rotation.y, m.rotation.z],
+            scale: [m.scale.x, m.scale.y, m.scale.z],
+            visible: m.visible,
+        };
+    }
+    const s = stateOf(node);
+    if (!s.snapshot) {
+        s.snapshot = {
+            position: [node.position.x, node.position.y, node.position.z],
+            rotation: [node.rotation.x, node.rotation.y, node.rotation.z],
+            scale: [node.scale.x, node.scale.y, node.scale.z],
+            visible: node.visible,
+        };
+    }
+    return s.snapshot;
+};
+// ── Transform / visibility ──────────────────────────────────────────────────
+const reconcileTransform = (node, override) => {
+    const s = stateOf(node);
+    const hasTransform = !!(override?.position || override?.rotation || override?.scale);
+    const hasVisible = override?.visible !== undefined;
+    if (!hasTransform && !hasVisible && !s.transformTouched && !s.visibleTouched)
+        return;
+    const orig = originalOf(node);
+    if (hasTransform || s.transformTouched) {
+        node.position.set(...(override?.position ?? orig.position));
+        node.rotation.set(...(override?.rotation ?? orig.rotation));
+        node.scale.set(...(override?.scale ?? orig.scale));
+        s.transformTouched = hasTransform;
+    }
+    if (hasVisible || s.visibleTouched) {
+        node.visible = override?.visible ?? orig.visible;
+        s.visibleTouched = hasVisible;
+    }
+};
+// ── Material ────────────────────────────────────────────────────────────────
+const assign = (mesh, material) => {
+    mesh.material = material;
+};
+const reconcileMaterial = (mesh, desired) => {
+    const current = mesh.material;
+    if (!current)
+        return;
+    const s = stateOf(mesh);
+    // A material that isn't ours is a fresh base (GLB, or the model-level pass replaced
+    // what we had). Ours still on the mesh means the stored base is still valid.
+    if (!isOwn(current)) {
+        if (s.ownMaterial || s.ownInstance) {
+            // Our material was swapped out from under us — release it, it's orphaned.
+            disposeOwn(s);
+        }
+        s.baseMaterial = current;
+    }
+    const base = s.baseMaterial ?? current;
+    if (!desired) {
+        if (isOwn(current)) {
+            assign(mesh, base);
+            disposeOwn(s);
+        }
+        s.token = (s.token ?? 0) + 1; // cancel any in-flight replace
+        return;
+    }
+    const key = JSON.stringify(desired.mode === 'replace' ? { r: desired.settings } : { t: desired.tweak });
+    if (isOwn(current) && s.materialKey === key)
+        return; // already up to date
+    const token = (s.token ?? 0) + 1;
+    s.token = token;
+    if (desired.mode === 'tweak') {
+        const make = (m) => {
+            const copy = tag(m.clone());
+            applyMaterialTweak(copy, desired.tweak);
+            return copy;
+        };
+        const next = Array.isArray(base) ? base.map(make) : make(base);
+        const prev = { ownMaterial: s.ownMaterial, ownInstance: s.ownInstance };
+        assign(mesh, next);
+        disposeOwn({ ...prev });
+        s.ownMaterial = next;
+        s.ownInstance = undefined;
+        s.materialKey = key;
+        return;
+    }
+    // replace — full 3drise material
+    const settings = desired.settings;
+    if (!settings) {
+        if (isOwn(current)) {
+            assign(mesh, base);
+            disposeOwn(s);
+        }
+        return;
+    }
+    const typeDef = MaterialRegistryAPI.getTypeDefinition(settings.materialType);
+    if (!typeDef)
+        return;
+    const variant = settings.materialVariant || Object.keys(typeDef.variants)[0];
+    resolveTextures(variant, settings).then(resolved => {
+        if (stateOf(mesh).token !== token)
+            return; // superseded
+        let instance;
+        try {
+            instance = createAndApplyMaterial(variant, resolved);
+        }
+        catch {
+            return;
+        }
+        tag(instance.material);
+        const prev = { ownMaterial: s.ownMaterial, ownInstance: s.ownInstance };
+        assign(mesh, instance.material);
+        disposeOwn({ ...prev });
+        s.ownInstance = instance;
+        s.ownMaterial = instance.material;
+        s.materialKey = key;
+    });
+};
+/** A named node's material targets: itself if it has one, else every descendant mesh. */
+const materialTargetsOf = (node) => {
+    if (node.material)
+        return [node];
+    const out = [];
+    node.traverse(child => {
+        if (child !== node && child.material)
+            out.push(child);
+    });
+    return out;
+};
+// ── Reconcile / restore ─────────────────────────────────────────────────────
+export function reconcileNodeOverrides(root, overrides, master) {
+    let touched = touchedByRoot.get(root);
+    if (!touched) {
+        touched = new Set();
+        touchedByRoot.set(root, touched);
+    }
+    const targets = collectOverrideTargets(root, overrides);
+    const desiredNode = new Map();
+    const desiredMaterial = new Map();
+    // Parents come first in traversal order, so a child's own material override wins
+    // over one set on its group.
+    targets.forEach((nodes, key) => {
+        const override = overrides[key];
+        // Resolve the master counterpart once per node, by the same key.
+        const masterNodes = master ? resolveNodeKey(master, key) : [];
+        nodes.forEach((node, i) => {
+            const s = stateOf(node);
+            if (master && s.masterNode === undefined)
+                s.masterNode = masterNodes[i] ?? masterNodes[0] ?? null;
+            desiredNode.set(node, override);
+            if (override.material) {
+                materialTargetsOf(node).forEach(mesh => desiredMaterial.set(mesh, override.material));
+            }
+        });
+    });
+    const all = new Set([...touched, ...desiredNode.keys(), ...desiredMaterial.keys()]);
+    all.forEach(node => {
+        reconcileTransform(node, desiredNode.get(node));
+        if (node.material)
+            reconcileMaterial(node, desiredMaterial.get(node));
+    });
+    // Keep tracking only what still differs from the original.
+    const stillTouched = new Set();
+    all.forEach(node => {
+        const s = nodeStates.get(node);
+        if (s && (s.transformTouched || s.visibleTouched || s.ownMaterial || s.ownInstance || desiredMaterial.has(node))) {
+            stillTouched.add(node);
+        }
+    });
+    touchedByRoot.set(root, stillTouched);
+}
+/** Put every node this root touched back to its original state and free our materials. */
+export function restoreNodeOverrides(root, master) {
+    reconcileNodeOverrides(root, {}, master);
+}
+// ── Hook ────────────────────────────────────────────────────────────────────
+/**
+ * @param object  the mounted model clone (one layout slot)
+ * @param overrides  createdObject.config.nodeOverrides (getNodeOverrides)
+ * @param master  the cache master scene (peekModelAsset(url)?.scene) — source of originals
+ */
+export function useNodeOverrides(object, overrides, master) {
+    const materialPass = useContext(ModelMaterialPassContext);
+    useEffect(() => {
+        if (!object)
+            return;
+        reconcileNodeOverrides(object, overrides, master);
+    }, [object, overrides, master, materialPass]);
+    // Unmount / instance swap: leave the instance as the GLB made it.
+    useEffect(() => {
+        if (!object)
+            return;
+        return () => restoreNodeOverrides(object, master);
+    }, [object, master]);
+}
+export default useNodeOverrides;

package/dist/index.d.ts

@@ -30,6 +30,8 @@ export { applyOceanUniforms, buildWaveTable, seaState } from './utils/oceanUnifo
 export type { WaveTable } from './utils/oceanUniforms';
 export { applyCameraUniforms, applyCirrusUniforms, applyDeckUniforms, applySunUniforms, applyThunderUniforms, } from './utils/cloudUniforms';
 export { applyCloudsKeyframeAnimations, applyCloudsMouseMove, resolveDeckConfig, } from './utils/handleCloudsAnimations';
+export { applyConfigKeyframeAnimations, applyConfigMouseMove, hasConfigOverrides, resolveConfig, } from './utils/configAnimations';
+export type { ConfigOverride, ConfigStartValues } from './utils/configAnimations';
 export { volumetricCloudPresets, cirrusPresets, getCloudPresetsForType, getCloudPresetByName, getCirrusPresetByName, searchCloudPresetsByTags, } from './presets/volumetricCloudPresets';
 export type { VolumetricCloudPreset, CirrusPreset } from './presets/volumetricCloudPresets';
 export { terrainPresets, getTerrainPresetsForType, getTerrainPresetByName, searchTerrainPresetsByTags, } from './presets/terrainPresets';