@3driseai/3drise-viewer 0.1.42 → 0.1.43

package/dist/hooks/useOceanMaterial.js

@@ -4,20 +4,30 @@ import { useFrame } from '@react-three/fiber';
 import { useCloudSun } from './useCloudSun.js';
 import { OCEAN_LIVE_KEY } from './useOceanLive.js';
 import { OceanSurfaceMaterial } from '../shaders/ocean/OceanSurfaceMaterial.js';
-import { applySunUniforms } from '../utils/cloudUniforms.js';
-import { applyTerrainAmbient, applyTerrainFieldUniforms } from '../utils/terrainUniforms.js';
+import { applyTerrainFieldUniforms } from '../utils/terrainUniforms.js';
 import { applyOceanUniforms } from '../utils/oceanUniforms.js';
-import { resolveMoon, moonlightFactor, MOON_LIGHT_COLOR } from '../utils/skyMoon.js';
-/** Moonlight on the water relative to the sun's (sunIntensity 1). The key light
- *  runs the moon at ~0.1 of the sun; the water gets a little more so the glitter
- *  path reads at night. Tuning knob. */
-const MOON_WATER_STRENGTH = 0.15;
+import { applyWaterLight, createWaterLightScratch } from '../utils/waterLight.js';
+import { PlanarReflector, applyWaterReflection, electedWaterSurface, noteWaterViewer, registerWaterSurface, WaterProbe, WaterVisibility, waterProbeSize, waterViewerPosition, isWaterMirrorPass, } from '../utils/waterReflection.js';
 import { getAnimatableProperties } from '@3driseai/3drise-core';
 import { applyConfigKeyframeAnimations, applyConfigMouseMove, } from '../utils/configAnimations.js';
-export function useOceanMaterial({ id, config, quality, skySettings, timeSettings, sunIntensity = 1, animations, mouseMove, terrain, onFrame, }) {
+export function useOceanMaterial({ id, config, quality, skySettings, timeSettings, sunIntensity = 1, animations, mouseMove, terrain, onFrame, world = false, }) {
     const { state: sun, update: updateSun } = useCloudSun({ skySettings, timeSettings });
-    const moon = useRef({ direction: new THREE.Vector3(), illumination: 0 });
+    const light = useMemo(createWaterLightScratch, []);
     const material = useMemo(() => new OceanSurfaceMaterial(), []);
+    // A placed body sits just above whatever is under it (a lawn, a plaza, a
+    // basin mesh). Far away the depth buffer cannot separate a few centimetres
+    // (24-bit depth with near 0.1: ~10 cm at 400 m, ~40 cm at 800 m), so water
+    // and ground z-fight — speckle that only raising the water fixed. A depth bias
+    // toward the camera, counted in depth-buffer steps, makes the water win at
+    // every distance without moving it. Bodies only: on the world ocean it would
+    // let the waterline creep up the beaches at distance.
+    useEffect(() => {
+        const body = !world;
+        material.polygonOffset = body;
+        material.polygonOffsetFactor = body ? -2 : 0;
+        material.polygonOffsetUnits = body ? -8 : 0;
+        material.needsUpdate = true;
+    }, [material, world]);
     useEffect(() => () => { material.dispose(); }, [material]);
     // Live controller overrides. A slider drag writes here on every pointer-move
     // and the frame loop reads it on top of the config, so the water responds
@@ -55,25 +65,104 @@ export function useOceanMaterial({ id, config, quality, skySettings, timeSetting
         root.userData[OCEAN_LIVE_KEY] = liveHandle;
         return () => { delete root.userData[OCEAN_LIVE_KEY]; };
     }, [id, liveHandle]);
-    useFrame((state) => {
+    // The reflection election (utils/waterReflection.ts). What this surface
+    // asks for is read from the config it is rendering this frame — live drag
+    // included — so the knob answers at once. The pass itself is created the
+    // first time this surface wins and kept while it is mounted.
+    const frame = useRef({ mode: 'env', elected: false, scale: 0.5, drawn: -1, baked: -1, n: 0 });
+    const reflector = useRef(null);
+    useEffect(() => () => { reflector.current?.dispose(); reflector.current = null; }, []);
+    // 'baked': this surface's own probe (utils/waterReflection.ts WaterProbe).
+    const probe = useRef(null);
+    useEffect(() => () => { probe.current?.dispose(); probe.current = null; }, []);
+    const probeAt = useMemo(() => new THREE.Vector3(), []);
+    // Is any of this body's water actually on screen? (occlusion query; utils/waterReflection.ts)
+    const visibility = useMemo(() => new WaterVisibility(), []);
+    useEffect(() => () => visibility.dispose(), [visibility]);
+    useEffect(() => {
+        const root = rootRef.current;
+        if (!root)
+            return;
+        return registerWaterSurface({
+            id,
+            world,
+            object: root,
+            size: () => config.size,
+            mode: () => frame.current.mode,
+            visible: world ? undefined : () => visibility.isVisible(),
+        });
+    }, [id, world, config.size, visibility]);
+    const planePoint = useMemo(() => new THREE.Vector3(), []);
+    // A placed body's outline on its plane, world space: the mirror renders only
+    // the rectangle it covers (utils/waterReflection.ts).
+    const corners = useMemo(() => [new THREE.Vector3(), new THREE.Vector3(), new THREE.Vector3(), new THREE.Vector3()], []);
+    const sizeRef = useRef([1, 1]);
+    sizeRef.current = config.size;
+    const bodyScale = useMemo(() => new THREE.Vector3(1, 1, 1), []);
+    // Scratch for the current (no per-frame allocation).
+    const [flowLocal, flowWorld, flowVec, flowQuat] = useMemo(() => [new THREE.Vector2(), new THREE.Vector2(), new THREE.Vector3(), new THREE.Quaternion()], []);
+    const onBeforeRender = useMemo(() => (renderer, scene, camera) => {
+        noteWaterViewer(camera);
+        bakeProbe(renderer, scene, camera);
+        renderMirror(renderer, scene, camera);
+        // Last: the query must enclose only this mesh's own draw.
+        if (!world)
+            visibility.begin(renderer);
+    }, [world, visibility]); // eslint-disable-line react-hooks/exhaustive-deps
+    const onAfterRender = useMemo(() => () => { if (!world)
+        visibility.end(); }, [world, visibility]);
+    // One probe face per frame while the capture is stale — only while this water
+    // is actually being drawn (a body behind the city waits until it is seen).
+    function bakeProbe(renderer, scene, camera) {
+        const f = frame.current;
+        const p = probe.current;
+        const root = rootRef.current;
+        if (f.mode !== 'baked' || !p || !root || !p.stale || isWaterMirrorPass())
+            return;
+        if (f.baked === f.n)
+            return;
+        if (!world && !visibility.isVisible())
+            return;
+        f.baked = f.n;
+        p.step(renderer, scene, root, camera.layers.mask);
+        if (p.valid)
+            applyWaterReflection(material.uniforms, 'baked', null, p);
+    }
+    function renderMirror(renderer, scene, camera) {
+        const f = frame.current;
+        const root = rootRef.current;
+        // Never from inside another pass (a probe capture draws this mesh too).
+        if (!f.elected || !root || isWaterMirrorPass())
+            return;
+        // Once per frame, whichever of the host's meshes asks first (the world
+        // ocean has a ring per clipmap level).
+        if (f.drawn === f.n)
+            return;
+        f.drawn = f.n;
+        const r = (reflector.current ??= new PlanarReflector());
+        if (world)
+            planePoint.set(camera.position.x, material.uniforms.u_waterLevel.value, camera.position.z);
+        else
+            root.getWorldPosition(planePoint);
+        let outline = null;
+        if (!world) {
+            const [w, d] = sizeRef.current ?? [1, 1];
+            corners[0].set(-w / 2, 0, -d / 2);
+            corners[1].set(w / 2, 0, -d / 2);
+            corners[2].set(w / 2, 0, d / 2);
+            corners[3].set(-w / 2, 0, d / 2);
+            for (const c of corners)
+                c.applyMatrix4(root.matrixWorld);
+            outline = corners;
+        }
+        r.render(renderer, scene, camera, root, planePoint, f.scale, outline);
+        applyWaterReflection(material.uniforms, 'planar', r);
+    }
+    useFrame((state, delta) => {
         const shader = material;
+        visibility.tick();
         updateSun();
-        applySunUniforms(shader, sun, sunIntensity);
-        // Overwrites the two ambient colours applySunUniforms just set. Those are
-        // the cloud curve, tuned for cloud interiors; water has to be lit by — and
-        // reflect — the sky actually being drawn behind it, or a sunset sea comes
-        // out black under a blazing sky.
-        applyTerrainAmbient(shader, sun);
-        // The moon's glitter path and light on the water, from the same moon
-        // as the key light and the disc (resolveMoon), and the same strength
-        // curve (moonlightFactor), so all three appear and fade together.
-        const m = resolveMoon(timeSettings, sun.direction, moon.current);
-        const sunElevation = THREE.MathUtils.radToDeg(Math.asin(THREE.MathUtils.clamp(sun.direction.y, -1, 1)));
-        const k = MOON_WATER_STRENGTH * moonlightFactor(sunElevation, m) * (skySettings?.sunSystem?.moonIntensity ?? 1);
-        if (shader.uniforms.u_moonDir)
-            shader.uniforms.u_moonDir.value.copy(m.direction);
-        if (shader.uniforms.u_moonColor)
-            shader.uniforms.u_moonColor.value.setRGB(MOON_LIGHT_COLOR.r * k, MOON_LIGHT_COLOR.g * k, MOON_LIGHT_COLOR.b * k);
+        applyWaterLight(shader, sun, sunIntensity, timeSettings, skySettings, light);
         const o = override.current;
         applyConfigKeyframeAnimations(animations?.ocean?.animations, startValues.current, config, o, performance.now() - animStart.current, animatable);
         if (mouseMove?.enabled && mouseMove.ocean?.enabled) {
@@ -103,6 +192,75 @@ export function useOceanMaterial({ id, config, quality, skySettings, timeSetting
             u.u_shadowDistance.value = Math.max(qual.terrainShadowDistance ?? 4000, 1);
         }
         shader.uniforms.u_time.value = state.clock.getElapsedTime();
+        // A placed body is sized by its transform: the shader evaluates the waves
+        // in world metres (local x scale) and divides the displacement back out.
+        if (cfg.host === 'object' && rootRef.current)
+            rootRef.current.getWorldScale(bodyScale);
+        else
+            bodyScale.set(1, 1, 1);
+        u.u_bodyScale.value.copy(bodyScale);
+        // The current. Integrated here, never speed * time in the shader, so a
+        // keyframed or dragged speed changes the rate without moving the water.
+        // The waves live in the field's frame (a body's own axes); the per-fragment
+        // ripple in world XZ, so the direction is rotated by the root's world turn.
+        const speed = Math.max(Number(cfg.flowSpeed) || 0, 0);
+        const bearing = ((Number(cfg.flowDirection) || 0) * Math.PI) / 180;
+        flowLocal.set(Math.sin(bearing), Math.cos(bearing));
+        if (cfg.host === 'object' && rootRef.current) {
+            rootRef.current.getWorldQuaternion(flowQuat);
+            flowVec.set(flowLocal.x, 0, flowLocal.y).applyQuaternion(flowQuat);
+            flowWorld.set(flowVec.x, flowVec.z);
+            if (flowWorld.lengthSq() > 1e-8)
+                flowWorld.normalize();
+            else
+                flowWorld.set(1, 0);
+        }
+        else
+            flowWorld.copy(flowLocal);
+        const step = speed * Math.min(delta, 0.1);
+        u.u_flowOffset.value.addScaledVector(flowLocal, step);
+        u.u_flowOffsetW.value.addScaledVector(flowWorld, step);
+        u.u_flowDirW.value.copy(flowWorld);
+        u.u_flowStretch.value = Math.min(speed * 1.5, 4);
+        // Reflection: ask, and find out whether this surface won this frame. The
+        // sky (or nothing) is set here for everyone; the winner overwrites it
+        // from onBeforeRender once its pass has drawn.
+        const f = frame.current;
+        f.n++;
+        f.mode = (cfg.reflection ?? 'env');
+        f.scale = qual.reflectionScale ?? 0.5;
+        f.elected = f.mode === 'planar' && electedWaterSurface(state) === id;
+        if (f.mode === 'baked') {
+            // The probe sits 1.5 m above the water's centre (a placed body), or
+            // follows the viewer over the world ocean, re-captured every 40 m.
+            const size = waterProbeSize(f.scale);
+            if (probe.current && probe.current.size !== size) {
+                probe.current.dispose();
+                probe.current = null;
+            }
+            const p = (probe.current ??= new WaterProbe(size));
+            const root = rootRef.current;
+            if (world) {
+                const v = waterViewerPosition() ?? state.camera.position;
+                probeAt.set(v.x, u.u_waterLevel.value + 2, v.z);
+                p.radius = 0;
+                p.request(probeAt, sun.direction, 40, state.clock.elapsedTime);
+            }
+            else if (root) {
+                root.getWorldPosition(probeAt);
+                probeAt.y += 1.5;
+                const [w, d] = sizeRef.current ?? [1, 1];
+                const half = 0.5 * Math.hypot(w * bodyScale.x, d * bodyScale.z);
+                // Parallax sphere: the bank and what stands around it.
+                p.radius = Math.max(120, half * 1.5);
+                p.request(probeAt, sun.direction, 0.25, state.clock.elapsedTime);
+            }
+        }
+        else if (probe.current) {
+            probe.current.dispose();
+            probe.current = null;
+        }
+        applyWaterReflection(u, f.mode, null, probe.current);
         // World size of one pixel at unit distance. The detail fade and the
         // specular filtering are both screen-space decisions — whether a ripple
         // is a shape or a shimmer depends on the field of view and the
@@ -115,6 +273,6 @@ export function useOceanMaterial({ id, config, quality, skySettings, timeSetting
         }
         onFrame?.(cfg, qual, state);
     });
-    return { material, rootRef };
+    return { material, rootRef, onBeforeRender, onAfterRender };
 }
 export default useOceanMaterial;

package/dist/hooks/usePathAnimation.d.ts

@@ -9,12 +9,20 @@ export interface PathAnimationOptions {
     faceDirection?: boolean;
     applyRotation?: boolean;
     offset?: Vector3Array;
+    /** Run the path from its end to its start. */
+    reverse?: boolean;
+    /** Seconds to wait at the path's start before the first run (not before each loop). */
+    delay?: number;
+    /** The object's own rotation (radians, XYZ): how the model sits relative to the direction of travel. With 0, its +Z faces forward. */
+    restRotation?: Vector3Array;
     keepOriginalTransform?: boolean;
     onComplete?: () => void;
 }
 export declare const usePathAnimation: () => {
     startPathAnimation: (pathId: string, duration: number, options?: PathAnimationOptions) => boolean;
     stopPathAnimation: () => void;
+    /** Change how the running animation sits on its path (offset, rotation…) without restarting it. */
+    setPathOptions: (options: PathAnimationOptions) => void;
     updatePathAnimation: (delta: number, object: Object3D) => boolean;
     isAnimating: () => boolean;
     getPositionAt: (t: number) => {

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

@@ -1 +1 @@
-{"version":3,"file":"usePathAnimation.d.ts","sourceRoot":"","sources":["../../src/hooks/usePathAnimation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACtC,MAAM,WAAW,oBAAoB;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AAGD,eAAO,MAAM,gBAAgB,QAAO;IAC5B,kBAAkB,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC;IAClG,iBAAiB,EAAE,MAAM,IAAI,CAAC;IAC9B,mBAAmB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,KAAK,OAAO,CAAC;IAClE,WAAW,EAAE,MAAM,OAAO,CAAC;IAC3B,aAAa,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK;QAC1B,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC;QACxB,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC;KAC5B,CAAC;CA6HT,CAAC;AACF,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"usePathAnimation.d.ts","sourceRoot":"","sources":["../../src/hooks/usePathAnimation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACtC,MAAM,WAAW,oBAAoB;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uFAAuF;IACvF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sIAAsI;IACtI,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AAyBD,eAAO,MAAM,gBAAgB,QAAO;IAC5B,kBAAkB,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC;IAClG,iBAAiB,EAAE,MAAM,IAAI,CAAC;IAC9B,mGAAmG;IACnG,cAAc,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,CAAC;IACxD,mBAAmB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,KAAK,OAAO,CAAC;IAClE,WAAW,EAAE,MAAM,OAAO,CAAC;IAC3B,aAAa,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK;QAC1B,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC;QACxB,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC;KAC5B,CAAC;CA8KT,CAAC;AACF,eAAe,gBAAgB,CAAC"}

package/dist/hooks/usePathAnimation.js

@@ -1,12 +1,38 @@
 import { useRef, useCallback, useEffect } from 'react';
 import * as THREE from 'three';
-import { smoothPathCorners, createPathSpline, applyEasing, resolveEasing } from '@3driseai/3drise-core';
+import { applyEasing, resolveEasing, buildPathLine, offsetPathLine, reversePathLine, pathLinePointAt, pathLineDirectionAt, pathLineHeading } from '@3driseai/3drise-core';
 import { AnimationsManager } from '@3driseai/3drise-core';
+// A path animation follows the path's finished line (core pathLine): built once (or taken from
+// the registry entry, which layouts provide), moved by the use's offset once, then each frame only
+// reads the point and direction at a distance along it. No curve is fitted here.
+//
+/** The line a registry entry stands for: its own `line`, or its points taken as the line. */
+function lineOf(cfg) {
+    if (cfg.line)
+        return cfg.line;
+    return buildPathLine({ points: cfg.points, smoothCorners: (cfg.smoothCorners ?? 0) / 100, loop: !!cfg.closed });
+}
+const EULER = new THREE.Euler();
+/** The object's own rotation as a quaternion (identity when none). */
+function setRest(q, r) {
+    if (r && r.length === 3)
+        q.setFromEuler(EULER.set(r[0] || 0, r[1] || 0, r[2] || 0));
+    else
+        q.identity();
+}
+/** Longest frame step the animation takes: a hitch slows the run for a moment instead of jumping it. */
+const MAX_STEP = 1 / 20;
+/** How fast the heading catches up with the path (per second); higher is stiffer. */
+const TURN_RATE = 14;
 export const usePathAnimation = () => {
-    const pointsRef = useRef([]);
+    const pathIdRef = useRef(null);
+    /** The registry entry the line was built from (a new entry = the path changed). */
+    const cfgRef = useRef(null);
+    /** The path's line, and this use's copy of it (offset applied). */
+    const baseLineRef = useRef(null);
+    const lineRef = useRef(null);
     const progressRef = useRef(0);
     const durationRef = useRef(1);
-    const splineRef = useRef(null);
     const activeRef = useRef(false);
     const directionRef = useRef(1);
     const easeRef = useRef(null);
@@ -16,18 +42,32 @@ export const usePathAnimation = () => {
     const faceRef = useRef(true);
     const applyRotRef = useRef(true);
     const offsetRef = useRef(null);
+    const reverseRef = useRef(false);
+    const delayLeftRef = useRef(0);
+    const restQuatRef = useRef(new THREE.Quaternion());
+    const parentQuatRef = useRef(new THREE.Quaternion());
     const onCompleteRef = useRef(null);
+    const snapRef = useRef(true);
+    const posRef = useRef(new THREE.Vector3());
+    const dirRef = useRef(new THREE.Vector3());
+    const aheadRef = useRef(new THREE.Vector3());
     const targetQuatRef = useRef(new THREE.Quaternion());
-    useEffect(() => () => { splineRef.current = null; }, []);
+    const reline = useCallback(() => {
+        const base = baseLineRef.current;
+        // this use's line: reversed and offset once, so the frame loop only reads it
+        lineRef.current = base ? offsetPathLine(reverseRef.current ? reversePathLine(base) : base, offsetRef.current) : null;
+    }, []);
+    useEffect(() => () => { lineRef.current = null; baseLineRef.current = null; }, []);
     const startPathAnimation = useCallback((pathId, duration, options = {}) => {
         const cfg = AnimationsManager.getPath(pathId);
-        if (!cfg || cfg.points.length < 2)
+        if (!cfg || (cfg.points?.length ?? 0) < 2)
+            return false;
+        const base = lineOf(cfg);
+        if (base.count < 2)
             return false;
-        const smooth = cfg.smoothCorners ?? 0;
-        const pts = smooth > 0 && cfg.points.length >= 3
-            ? smoothPathCorners(cfg.points, smooth)
-            : cfg.points;
-        pointsRef.current = pts;
+        pathIdRef.current = pathId;
+        cfgRef.current = cfg;
+        baseLineRef.current = base;
         progressRef.current = 0;
         durationRef.current = duration;
         activeRef.current = true;
@@ -39,42 +79,84 @@ export const usePathAnimation = () => {
         faceRef.current = options.faceDirection ?? true;
         applyRotRef.current = options.applyRotation ?? cfg.applyRotation ?? true;
         offsetRef.current = options.offset ?? cfg.offset ?? null;
+        reverseRef.current = !!options.reverse;
+        delayLeftRef.current = Math.max(0, options.delay ?? 0);
+        setRest(restQuatRef.current, options.restRotation);
         onCompleteRef.current = options.onComplete ?? null;
-        const curve = cfg.curve ?? 1;
-        splineRef.current = createPathSpline(pts, curve);
+        snapRef.current = true;
+        reline();
         return true;
-    }, []);
+    }, [reline]);
     const stopPathAnimation = useCallback(() => {
         activeRef.current = false;
-        splineRef.current = null;
+        lineRef.current = null;
+        baseLineRef.current = null;
         progressRef.current = 0;
         directionRef.current = 1;
     }, []);
-    const getPositionAt = useCallback((t) => {
-        const pts = pointsRef.current;
-        const spline = splineRef.current;
-        const clamped = Math.max(0, Math.min(1, t));
-        if (spline) {
-            return {
-                position: spline.getPointAt(clamped),
-                direction: spline.getTangentAt(clamped).normalize(),
-            };
+    const setPathOptions = useCallback((options = {}) => {
+        const cfg = cfgRef.current;
+        if ('offset' in options) {
+            const next = options.offset ?? cfg?.offset ?? null;
+            const same = JSON.stringify(next) === JSON.stringify(offsetRef.current);
+            offsetRef.current = next;
+            if (!same)
+                reline(); // the whole line moves once
+        }
+        if ('reverse' in options && !!options.reverse !== reverseRef.current) {
+            reverseRef.current = !!options.reverse;
+            reline();
+            progressRef.current = 1 - progressRef.current; // stay where it is, now heading the other way
         }
-        const segs = pts.length - 1;
-        const idx = Math.min(Math.floor(clamped * segs), segs - 1);
-        const sp = clamped * segs - idx;
-        const a = pts[idx], b = pts[idx + 1];
-        return {
-            position: new THREE.Vector3(a[0] + (b[0] - a[0]) * sp, a[1] + (b[1] - a[1]) * sp, a[2] + (b[2] - a[2]) * sp),
-            direction: new THREE.Vector3(b[0] - a[0], b[1] - a[1], b[2] - a[2]).normalize(),
-        };
+        if ('restRotation' in options)
+            setRest(restQuatRef.current, options.restRotation);
+        if ('applyRotation' in options)
+            applyRotRef.current = options.applyRotation ?? cfg?.applyRotation ?? true;
+        if ('faceDirection' in options)
+            faceRef.current = options.faceDirection ?? true;
+        if ('speed' in options)
+            speedRef.current = options.speed ?? 1;
+        if ('loop' in options)
+            loopRef.current = options.loop ?? false;
+        if ('yoyo' in options)
+            yoyoRef.current = options.yoyo ?? false;
+        if ('ease' in options)
+            easeRef.current = options.ease ?? null;
+    }, [reline]);
+    const getPositionAt = useCallback((t) => {
+        const line = lineRef.current;
+        const position = new THREE.Vector3(), direction = new THREE.Vector3();
+        if (!line)
+            return { position, direction };
+        const d = Math.max(0, Math.min(1, t)) * line.length;
+        pathLinePointAt(line, d, position);
+        pathLineDirectionAt(line, d, 0.5, direction);
+        return { position, direction };
     }, []);
     const updatePathAnimation = useCallback((delta, object) => {
         if (!activeRef.current)
             return false;
-        progressRef.current += (delta / durationRef.current) * speedRef.current * directionRef.current;
+        // the path changed in the registry (edited / re-saved): follow the new line from where we are
+        const live = pathIdRef.current ? AnimationsManager.getPath(pathIdRef.current) : undefined;
+        if (live && live !== cfgRef.current && (live.points?.length ?? 0) >= 2) {
+            cfgRef.current = live;
+            baseLineRef.current = lineOf(live);
+            reline();
+        }
+        const line = lineRef.current;
+        if (!line || line.count < 2)
+            return false;
+        const step = Math.min(delta, MAX_STEP);
+        // the delay: held at the start, then the rest of this frame's time moves it
+        let advance = step;
+        if (delayLeftRef.current > 0) {
+            const used = Math.min(delayLeftRef.current, step);
+            delayLeftRef.current -= used;
+            advance = step - used;
+        }
+        progressRef.current += (advance / durationRef.current) * speedRef.current * directionRef.current;
         let p = progressRef.current;
-        if (p >= 1 || p <= 0) {
+        if (advance > 0 && (p >= 1 || p <= 0)) {
             if (yoyoRef.current) {
                 directionRef.current *= -1;
                 p = Math.max(0, Math.min(1, p));
@@ -97,34 +179,33 @@ export const usePathAnimation = () => {
             }
         }
         const eased = easeRef.current ? applyEasing(resolveEasing(easeRef.current), p) : p;
-        const { position, direction } = getPositionAt(eased);
-        if (offsetRef.current) {
-            position.x += offsetRef.current[0];
-            position.y += offsetRef.current[1];
-            position.z += offsetRef.current[2];
-        }
-        // Convert world-space position to parent local space (handles nested groups)
-        // if (object.parent) {
-        //   object.parent.worldToLocal(position);
-        // }
-        object.position.copy(position);
-        if (applyRotRef.current && faceRef.current && direction.lengthSq() > 0.0001) {
-            const up = new THREE.Vector3(0, 1, 0);
-            const mat = new THREE.Matrix4();
-            mat.lookAt(position, new THREE.Vector3().copy(position).add(direction), up);
-            targetQuatRef.current.setFromRotationMatrix(mat);
-            targetQuatRef.current.multiply(new THREE.Quaternion().setFromAxisAngle(new THREE.Vector3(0, 1, 0), Math.PI));
-            // Strip parent's world rotation so quaternion is in local space
-            // if (object.parent) {
-            //   const parentWorldQuat = new THREE.Quaternion();
-            //   object.parent.getWorldQuaternion(parentWorldQuat);
-            //   targetQuatRef.current.premultiply(parentWorldQuat.invert());
-            // }
-            object.quaternion.slerp(targetQuatRef.current, 1);
+        const d = eased * line.length;
+        // the line is in world space (drawn on the scene): put the object on it wherever its parent is
+        const position = pathLinePointAt(line, d, posRef.current);
+        const parent = object.parent;
+        if (parent)
+            parent.updateWorldMatrix(true, false);
+        object.position.copy(parent ? parent.worldToLocal(aheadRef.current.copy(position)) : position);
+        if (applyRotRef.current && faceRef.current) {
+            const dir = pathLineDirectionAt(line, d, 0.5, dirRef.current);
+            if (directionRef.current < 0)
+                dir.negate(); // yoyo back: face the way it goes
+            // heading (core pathLineHeading — shared with clips' curved tracks): +Z along the travel,
+            // pitching with the slope, no roll, the object's own rotation on top; then into the parent's space
+            if (dir.lengthSq() > 1e-8 && pathLineHeading(dir, restQuatRef.current, targetQuatRef.current)) {
+                if (parent)
+                    targetQuatRef.current.premultiply(parent.getWorldQuaternion(parentQuatRef.current).invert());
+                if (snapRef.current) {
+                    object.quaternion.copy(targetQuatRef.current);
+                    snapRef.current = false;
+                }
+                else
+                    object.quaternion.slerp(targetQuatRef.current, 1 - Math.exp(-TURN_RATE * step));
+            }
         }
         return true;
-    }, [getPositionAt]);
+    }, [reline]);
     const isAnimating = useCallback(() => activeRef.current, []);
-    return { startPathAnimation, stopPathAnimation, updatePathAnimation, isAnimating, getPositionAt };
+    return { startPathAnimation, stopPathAnimation, setPathOptions, updatePathAnimation, isAnimating, getPositionAt };
 };
 export default usePathAnimation;

package/dist/hooks/useResolvedLayout.d.ts

@@ -0,0 +1,10 @@
+import { type ResolvedLayout } from '@3driseai/3drise-core';
+/**
+ * Changes when the layout a reference names is registered or edited (core layoutRefs — areas,
+ * paths and grids); 0 and no subscription without a reference, so a mesh with no saved layout never
+ * rebuilds when other layouts load.
+ */
+export declare function useLayoutRefVersion(ref: string | null | undefined): number;
+/** The layout a reference names ('preset:<id>' or a saved layout's asset id), kept current: null until a saved one is registered. */
+export declare function useResolvedLayout(ref: string | null | undefined): ResolvedLayout | null;
+//# sourceMappingURL=useResolvedLayout.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useResolvedLayout.d.ts","sourceRoot":"","sources":["../../src/hooks/useResolvedLayout.ts"],"names":[],"mappings":"AACA,OAAO,EAAmD,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAK7G;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAE1E;AAED,qIAAqI;AACrI,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,cAAc,GAAG,IAAI,CAGvF"}

package/dist/hooks/useResolvedLayout.js

@@ -0,0 +1,17 @@
+import { useMemo, useSyncExternalStore } from 'react';
+import { layoutsVersion, resolveLayout, subscribeLayouts } from '@3driseai/3drise-core';
+const noSubscribe = () => () => { };
+const zero = () => 0;
+/**
+ * Changes when the layout a reference names is registered or edited (core layoutRefs — areas,
+ * paths and grids); 0 and no subscription without a reference, so a mesh with no saved layout never
+ * rebuilds when other layouts load.
+ */
+export function useLayoutRefVersion(ref) {
+    return useSyncExternalStore(ref ? subscribeLayouts : noSubscribe, ref ? layoutsVersion : zero, ref ? layoutsVersion : zero);
+}
+/** The layout a reference names ('preset:<id>' or a saved layout's asset id), kept current: null until a saved one is registered. */
+export function useResolvedLayout(ref) {
+    const version = useLayoutRefVersion(ref);
+    return useMemo(() => resolveLayout(ref), [ref, version]); // eslint-disable-line react-hooks/exhaustive-deps
+}

package/dist/hooks/useTimeLighting.d.ts

@@ -0,0 +1,36 @@
+import { type RefObject } from 'react';
+import * as THREE from 'three';
+import { type RootState } from '@react-three/fiber';
+import { type createLampField } from '../components/urban/urbanCore';
+type Uniforms = Record<string, {
+    value: any;
+}>;
+/** One lamp-gathering target (bounds in the instance's local space): a uniform set to fill with the
+ *  nearest lamps, or a baked lamp field (createLampField) for a large merged surface. */
+export type LampTarget = {
+    u?: Uniforms;
+    field?: ReturnType<typeof createLampField>;
+    bounds: THREE.Box3;
+};
+/** What a time-lit instance exposes. */
+export interface TimeLit {
+    /** The uniform sets that take the sun block (sets without uSunDir are skipped). */
+    uniformSets?: Uniforms[];
+    /** Local-space bounds (the hook applies the object's world matrix). */
+    bounds?(): THREE.Box3;
+    /** Lamp targets; defaults to every uniform set with lamp uniforms (uLamps) at bounds(). */
+    lampTargets?(): LampTarget[];
+}
+export interface TimeLightingOptions {
+    rootRef: RefObject<THREE.Object3D | null>;
+    instance: TimeLit;
+    /** The object's lighting override: 'auto' (follow the time of day) | 'day' | 'night'. */
+    lighting?: string;
+    /** The instance's per-frame work, run after the sun and before the lamp gathering. */
+    update?: (dt: number, state: RootState) => void;
+}
+export declare function useTimeLighting({ rootRef, instance, lighting, update }: TimeLightingOptions): {
+    relight: () => void;
+};
+export {};
+//# sourceMappingURL=useTimeLighting.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useTimeLighting.d.ts","sourceRoot":"","sources":["../../src/hooks/useTimeLighting.ts"],"names":[],"mappings":"AAqBA,OAAO,EAA2C,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAChF,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAY,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE9D,OAAO,EAAsD,KAAK,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAEzH,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,GAAG,CAAA;CAAE,CAAC,CAAC;AAE/C;yFACyF;AACzF,MAAM,MAAM,UAAU,GAAG;IAAE,CAAC,CAAC,EAAE,QAAQ,CAAC;IAAC,KAAK,CAAC,EAAE,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAA;CAAE,CAAC;AAE1G,wCAAwC;AACxC,MAAM,WAAW,OAAO;IACpB,mFAAmF;IACnF,WAAW,CAAC,EAAE,QAAQ,EAAE,CAAC;IACzB,uEAAuE;IACvE,MAAM,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC;IACtB,2FAA2F;IAC3F,WAAW,CAAC,IAAI,UAAU,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,mBAAmB;IAChC,OAAO,EAAE,SAAS,CAAC,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IAC1C,QAAQ,EAAE,OAAO,CAAC;IAClB,yFAAyF;IACzF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sFAAsF;IACtF,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;CACnD;AAID,wBAAgB,eAAe,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,mBAAmB,GAAG;IAAE,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CAkCrH"}