@konitif/viewer-3d 0.285.3 → 0.285.5

package/dist/renderer/Viewer3DRenderer.js

@@ -6,7 +6,7 @@ import { createClockGraph, createInvalidationController, createTemporalTransport
 import { createViewerTemporalScheduler } from './ViewerTemporalScheduler.js';
 import { copyViewerMetadata } from './ViewerMetadata.js';
 import { resolveInteractionInputActions, resolveInteractionInputBindings } from '@konitif/tools/input';
-import { AxesHelper, Box3, BoxGeometry, BufferGeometry, CanvasTexture, Color, ConeGeometry, CylinderGeometry, DirectionalLight, DoubleSide, Float32BufferAttribute, FogExp2, GridHelper, Group, HalfFloatType, HemisphereLight, Line, LineBasicMaterial, Matrix4, MathUtils, Mesh, MeshBasicMaterial, MeshDepthMaterial, NoToneMapping, Object3D, OrthographicCamera, Plane, PlaneGeometry, PerspectiveCamera, VSMShadowMap, Quaternion, Raycaster, Scene, CircleGeometry, SphereGeometry, Sprite, SpriteMaterial, SRGBColorSpace, Vector2, Vector3, WebGLRenderTarget, WebGLRenderer } from 'three';
+import { AxesHelper, Box3, BoxGeometry, BufferGeometry, CanvasTexture, Color, ConeGeometry, CylinderGeometry, DirectionalLight, DoubleSide, Float32BufferAttribute, FogExp2, GridHelper, Group, HalfFloatType, HemisphereLight, Line, LineBasicMaterial, LineSegments, Matrix4, MathUtils, Mesh, MeshBasicMaterial, MeshDepthMaterial, NoToneMapping, Object3D, OrthographicCamera, Plane, PlaneGeometry, PerspectiveCamera, VSMShadowMap, Quaternion, Raycaster, Scene, CircleGeometry, SphereGeometry, Sprite, SpriteMaterial, SRGBColorSpace, Vector2, Vector3, WebGLRenderTarget, WebGLRenderer } from 'three';
 import { ArcballControls } from 'three/examples/jsm/controls/ArcballControls.js';
 import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
 import { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer.js';
@@ -17,7 +17,7 @@ import { ShaderPass } from 'three/examples/jsm/postprocessing/ShaderPass.js';
 import { SMAAPass } from 'three/examples/jsm/postprocessing/SMAAPass.js';
 import { HorizontalTiltShiftShader } from 'three/examples/jsm/shaders/HorizontalTiltShiftShader.js';
 import { VerticalTiltShiftShader } from 'three/examples/jsm/shaders/VerticalTiltShiftShader.js';
-import { getRobotMotionAnimationDuration, interpolateRobotMotionTrackValueAtTime, toRobotMotionJointValue, resolveRobotMotionPlaybackDuration } from './robotViewerMotion.js';
+import { getRobotMotionAnimationDuration, interpolateRobotMotionTrackValueAtTime, sampleRobotMotionJointValuesAtTime, toRobotMotionJointValue, resolveRobotMotionPlaybackDuration } from './robotViewerMotion.js';
 import { createViewerProjectileLaunchSolution, VIEWER3D_PROJECTILE_PARTICLE_LIMIT, createViewerProjectileTrajectoryPoints, resolveViewerProjectileChargedLaunchProfile, resolveViewerProjectileImpulse, resolveViewerProjectileLauncherWorldScale, resolveViewerSlingshotReleasePull, stepViewerProjectileAgainstGround } from './ProjectileInteraction.js';
 import { createInteractionKeyboardSignal, DEFAULT_VIEWER_INPUT_BINDINGS, VIEWER_PROJECTILE_CHARGE_ACTION_ID, VIEWER_PROJECTILE_LAUNCH_ACTION_ID } from './ViewerInputBindings.js';
 import { ViewerProjectileParticleRenderer } from './ViewerProjectileParticleRenderer.js';
@@ -296,6 +296,7 @@ export class Viewer3D {
     projectilePointerInside = false;
     trajectoryAnimation = null;
     trajectorySignature = '';
+    trajectoryProjectionRevision = 0;
     trajectoryAnchors = new Map();
     themeObserver = null;
     animationLoop;
@@ -376,6 +377,8 @@ export class Viewer3D {
     poseHandleTargetTransitionState = null;
     poseHandleDragStarted = false;
     poseHandleControlsWereEnabled = false;
+    ledStateProjection = { visible: false, zones: {} };
+    ledMeshBaseColors = new WeakMap();
     suppressPoseHandleClickUntil = 0;
     poseEditBaseline = null;
     dirtyPose = false;
@@ -1176,6 +1179,7 @@ export class Viewer3D {
         this.resetTemporalProjection();
         if (this.options.physicsEnabled) {
             this.physicsVisualRootToRobotMatrix = null;
+            this.invalidateTrajectoryPreviewProjection();
             if (!this.syncPhysicsKinematicPoseFromRobotPose({ holdFrames: PHYSICS_RESET_KINEMATIC_HOLD_FRAMES })) {
                 this.syncPhysicsJointTargetsFromRobotPose();
             }
@@ -1201,6 +1205,7 @@ export class Viewer3D {
         }
         this.options.physicsMotorsCoupled = physicsMotorsCoupled;
         this.physicsVisualRootToRobotMatrix = null;
+        this.invalidateTrajectoryPreviewProjection();
         this.resetPhysicsPostureCompensation();
         if (!physicsMotorsCoupled) {
             this.robot?.updateMatrixWorld(true);
@@ -1233,6 +1238,7 @@ export class Viewer3D {
                 resolvePhysicsSourceString(source.metadata?.visualRootBodyName);
         this.physicsVisualBodyObjectNames = visualBodyObjectNames;
         this.physicsVisualRootToRobotMatrix = null;
+        this.invalidateTrajectoryPreviewProjection();
         this.physicsResetPose = null;
         this.physicsResetRobotTransform = null;
         this.physicsResetBaselineCaptureFrames = 0;
@@ -1270,6 +1276,7 @@ export class Viewer3D {
         this.scrubPreviewState = null;
         this.playbackSyncSignature = '';
         this.physicsVisualRootToRobotMatrix = null;
+        this.invalidateTrajectoryPreviewProjection();
         this.physicsAuthoredJointTargets.clear();
         this.resetPhysicsPostureCompensation();
         this.comparisonViewerSample = null;
@@ -1281,6 +1288,7 @@ export class Viewer3D {
         this.lastPhysicsStepAt = 0;
         this.resetTemporalProjection();
         this.physicsVisualRootToRobotMatrix = null;
+        this.invalidateTrajectoryPreviewProjection();
         if (this.options.physicsMotorsCoupled) {
             if (!this.syncPhysicsKinematicPoseFromRobotPose({ holdFrames: PHYSICS_RESET_KINEMATIC_HOLD_FRAMES })) {
                 this.syncPhysicsJointTargetsFromRobotPose();
@@ -1960,7 +1968,7 @@ export class Viewer3D {
             return;
         }
         this.options.showEyeRingDebug = showEyeRingDebug;
-        if (showEyeRingDebug || this.options.showEyeRingMire) {
+        if (showEyeRingDebug || this.options.showEyeRingMire || this.ledStateProjection.visible) {
             this.updateEyeRingDebug();
         }
         else {
@@ -1973,7 +1981,7 @@ export class Viewer3D {
             return;
         }
         this.options.showEyeRingMire = showEyeRingMire;
-        if (showEyeRingMire || this.options.showEyeRingDebug) {
+        if (showEyeRingMire || this.options.showEyeRingDebug || this.ledStateProjection.visible) {
             this.updateEyeRingDebug();
         }
         else {
@@ -1983,11 +1991,38 @@ export class Viewer3D {
     }
     setEyeRingCalibration(eyeRingCalibration) {
         this.options.eyeRingCalibration = eyeRingCalibration;
-        if (this.options.showEyeRingDebug || this.options.showEyeRingMire) {
+        if (this.options.showEyeRingDebug || this.options.showEyeRingMire || this.ledStateProjection.visible) {
             this.updateEyeRingDebug();
         }
         this.requestRender();
     }
+    setLedStateProjection(projection) {
+        this.ledStateProjection = projection
+            ? {
+                visible: projection.visible === true,
+                zones: Object.fromEntries(Object.entries(projection.zones).map(([zoneId, zone]) => [
+                    zoneId,
+                    zone
+                        ? {
+                            color: typeof zone.color === 'string' ? zone.color : undefined,
+                            colors: Array.isArray(zone.colors) ? [...zone.colors] : undefined,
+                            intensity: Number.isFinite(zone.intensity) ? Math.max(0, Math.min(1, zone.intensity ?? 1)) : 1
+                        }
+                        : undefined
+                ]))
+            }
+            : { visible: false, zones: {} };
+        if (this.ledStateProjection.visible || this.options.showEyeRingDebug || this.options.showEyeRingMire) {
+            this.updateEyeRingDebug();
+        }
+        else {
+            const robot = this.getPoseControlRobot();
+            if (robot)
+                this.updateEarMeshDiffusers(robot, []);
+            this.updateEyeRingDebugVisibility();
+        }
+        this.requestRender();
+    }
     setBalanceDebugVisible(showBalanceDebug) {
         if (this.options.showBalanceDebug === showBalanceDebug) {
             return;
@@ -2003,7 +2038,12 @@ export class Viewer3D {
     }
     setTrajectoryPreview(animation) {
         if (this.trajectoryAnimation === animation) {
-            this.updateTrajectoryGroupVisibility();
+            if (this.options.showTrajectories) {
+                this.rebuildTrajectoryPreview();
+            }
+            else {
+                this.updateTrajectoryGroupVisibility();
+            }
             return;
         }
         this.trajectoryAnimation = animation;
@@ -2027,6 +2067,7 @@ export class Viewer3D {
         this.captureMaterialBaselines(robot, this.robotMaterialBaselines);
         this.resetTemporalProjection();
         this.physicsVisualRootToRobotMatrix = null;
+        this.invalidateTrajectoryPreviewProjection();
         this.physicsProjectionMinimumStateRevision = null;
         this.physicsResetPose = null;
         this.physicsResetRobotTransform = null;
@@ -2356,6 +2397,9 @@ export class Viewer3D {
             this.playbackState?.isPlaying &&
             this.playbackState.animation === animation &&
             this.playbackSyncSignature === syncSignature) {
+            if (this.options.showTrajectories && animation) {
+                this.rebuildTrajectoryPreview();
+            }
             return;
         }
         const nextPlaybackState = {
@@ -2409,6 +2453,7 @@ export class Viewer3D {
                     this.alignUnbufferedPlaybackPoseToSupportFloor();
                 }
             }
+            this.rebuildTrajectoryPreview();
             this.updateTrajectoryCurrentMarkers();
             if (nextPlaybackState.clockMode === 'realtime') {
                 this.scheduleLoop();
@@ -2438,6 +2483,7 @@ export class Viewer3D {
                     this.alignUnbufferedPlaybackPoseToSupportFloor();
                 }
             }
+            this.rebuildTrajectoryPreview();
             this.updateTrajectoryCurrentMarkers();
             if (shouldStartViewerPlaybackCompletionTransition({
                 isPlaying,
@@ -3942,12 +3988,12 @@ export class Viewer3D {
                 if (this.lastFrameAt > 0) {
                     const frameMs = now - this.lastFrameAt;
                     this.averageFrameMs = this.averageFrameMs * 0.9 + frameMs * 0.1;
-                    this.tunePixelRatio(this.averageFrameMs);
                 }
                 this.lastFrameAt = now;
                 const renderStartedAt = performance.now();
                 this.render();
                 this.averageRenderMs = this.updateProfilerAverage(this.averageRenderMs, performance.now() - renderStartedAt);
+                this.tunePixelRatio(this.averageRenderMs);
                 this.lastRenderCalls = this.renderer.info.render.calls;
                 this.lastRenderTriangles = this.renderer.info.render.triangles;
                 this.renderFramesSinceReport += 1;
@@ -4002,6 +4048,16 @@ export class Viewer3D {
         if (this.observedRobotGhostMirrorsSimulatedRobot) {
             this.syncObservedRobotGhostFromSimulatedRobot();
         }
+        if (this.options.showTrajectories &&
+            this.trajectoryAnimation?.motion.hasMotion &&
+            this.trajectorySignature === '') {
+            this.rebuildTrajectoryPreview();
+        }
+        // Every pose authority (authored playback, runtime-history replay and
+        // physics projection) converges here. Refreshing the markers immediately
+        // before drawing prevents a solver step or a root presentation offset
+        // from leaving them one frame behind the rendered robot.
+        this.updateTrajectoryCurrentMarkers();
         this.updatePoseHandleScreenScale();
         this.updateProjectileCameraProjection();
         const ground = this.visualGroundLayer;
@@ -6000,6 +6056,7 @@ export class Viewer3D {
         const previousPresentedY = this.robot.position.y + this.simulatedRobotPresentationRoot.position.y;
         if (!this.physicsVisualRootToRobotMatrix) {
             this.physicsVisualRootToRobotMatrix = this.resolvePhysicsVisualRootToRobotMatrix(physicsRootWorldMatrix, bodyTransforms);
+            this.invalidateTrajectoryPreviewProjection();
         }
         const nextRobotWorldMatrix = physicsRootWorldMatrix.clone().multiply(this.physicsVisualRootToRobotMatrix);
         const parent = this.robot.parent;
@@ -6285,7 +6342,7 @@ export class Viewer3D {
         if (this.options.showContactPoints) {
             this.updateContactPoints();
         }
-        if (this.options.showEyeRingDebug || this.options.showEyeRingMire) {
+        if (this.options.showEyeRingDebug || this.options.showEyeRingMire || this.ledStateProjection.visible) {
             this.updateEyeRingDebug();
         }
         if (this.options.showBalanceDebug) {
@@ -8391,6 +8448,7 @@ export class Viewer3D {
         if (!rootTransform)
             return;
         this.physicsVisualRootToRobotMatrix = this.resolvePhysicsVisualRootToRobotMatrix(this.createPhysicsBodyViewerWorldMatrix(rootTransform), bodyTransforms);
+        this.invalidateTrajectoryPreviewProjection();
     }
     projectProjectilePhysicsObservation() {
         const bodyTransforms = this.physicsService.getBodyTransforms();
@@ -9236,7 +9294,7 @@ export class Viewer3D {
             : this.options.showRobot && this.robotComparisonAppearance.mode !== 'observed-only';
         this.eyeRingDebugGroup.visible =
             subjectVisible &&
-                (this.options.showEyeRingDebug || this.options.showEyeRingMire) &&
+                (this.options.showEyeRingDebug || this.options.showEyeRingMire || this.ledStateProjection.visible) &&
                 this.eyeRingDebugGroup.children.length > 0;
     }
     clearEyeRingDebug() {
@@ -9251,27 +9309,34 @@ export class Viewer3D {
     }
     updateEyeRingDebug() {
         const robot = this.getPoseControlRobot();
-        if ((!this.options.showEyeRingDebug && !this.options.showEyeRingMire) || !robot) {
+        if ((!this.options.showEyeRingDebug && !this.options.showEyeRingMire && !this.ledStateProjection.visible) || !robot) {
+            if (robot)
+                this.updateEarMeshDiffusers(robot, []);
             this.updateEyeRingDebugVisibility();
             return;
         }
         robot.updateMatrixWorld(true);
         const calibration = this.resolveEyeRingCalibration();
         const ledRingPoses = this.resolveLedRingPoses(calibration);
+        this.updateEarMeshDiffusers(robot, ledRingPoses.filter((pose) => pose.zoneId === 'ears'));
         if (ledRingPoses.length === 0) {
             this.clearEyeRingDebug();
             return;
         }
         const group = this.ensureEyeRingDebugGroup();
         this.clearEyeRingDebug();
-        if (this.options.showEyeRingDebug) {
+        if (this.options.showEyeRingDebug || this.ledStateProjection.visible) {
             for (const ring of ledRingPoses) {
                 const ledCount = Math.max(ring.calibration.layout === 'strip' ? 1 : 3, Math.min(64, Math.round(ring.calibration.ledCount)));
-                if (ring.calibration.mireVisible) {
+                if (this.options.showEyeRingDebug && ring.calibration.mireVisible) {
                     for (const [index, dimension] of this.resolveEyeRingDebugDimensions(ring.calibration).entries()) {
                         group.add(this.createLedLayoutGuide(ring, dimension, index === 0 ? '#22c55e' : '#67e8f9', index === 0 ? 0.84 : 0.42));
                     }
                 }
+                if (ring.zoneId === 'ears' && this.ledStateProjection.visible) {
+                    group.add(...this.createEarSpeakerGrille(ring));
+                    continue;
+                }
                 for (let index = 0; index < ledCount; index += 1) {
                     group.add(this.createEyeRingLedMarker(ring, index, ledCount, ring.calibration.ledSize));
                 }
@@ -9578,12 +9643,15 @@ export class Viewer3D {
         return line;
     }
     createEyeRingLedMarker(eye, index, count, ledSize) {
-        const color = index % 2 === 0 ? '#22c55e' : '#86efac';
+        const zoneState = this.ledStateProjection.visible ? this.ledStateProjection.zones[eye.zoneId] : undefined;
+        const projectedColor = zoneState?.colors?.[index % Math.max(1, zoneState.colors.length)] ?? zoneState?.color;
+        const color = projectedColor ?? (this.ledStateProjection.visible ? '#111827' : index % 2 === 0 ? '#22c55e' : '#86efac');
+        const intensity = zoneState?.intensity ?? (this.ledStateProjection.visible ? 0.3 : 0.92);
         const markerSize = Math.max(0.001, Math.min(0.02, ledSize));
         const marker = new Mesh(new SphereGeometry(markerSize, 12, 8), new MeshBasicMaterial({
             color,
             transparent: true,
-            opacity: 0.92,
+            opacity: intensity,
             depthTest: false,
             depthWrite: false
         }));
@@ -9596,6 +9664,137 @@ export class Viewer3D {
         marker.renderOrder = 1000;
         return marker;
     }
+    /** The speaker grille stays dark; only its peripheral diffuser receives LED light. */
+    createEarSpeakerGrille(ear) {
+        const normal = new Vector3(0, 1, 0).applyQuaternion(ear.orientation).normalize();
+        const surface = new Mesh(new CircleGeometry(ear.radius * 0.76, 72), new MeshBasicMaterial({
+            color: '#070a0d',
+            transparent: true,
+            opacity: 0.96,
+            depthTest: true,
+            depthWrite: false,
+            side: DoubleSide
+        }));
+        surface.geometry.rotateX(-Math.PI * 0.5);
+        surface.position.copy(ear.center).addScaledVector(normal, 0.00035);
+        surface.quaternion.copy(ear.orientation);
+        surface.name = `${ear.id}-speaker-grille-surface`;
+        surface.renderOrder = 996;
+        const grilleRadius = ear.radius * 0.70;
+        const cellRadius = Math.max(0.0012, ear.radius * 0.082);
+        const columnStep = Math.sqrt(3) * cellRadius;
+        const rowStep = cellRadius * 1.5;
+        const points = [];
+        for (let row = -9; row <= 9; row += 1) {
+            for (let column = -9; column <= 9; column += 1) {
+                const centerX = column * columnStep + (Math.abs(row) % 2) * columnStep * 0.5;
+                const centerZ = row * rowStep;
+                if (Math.hypot(centerX, centerZ) + cellRadius > grilleRadius)
+                    continue;
+                for (let edge = 0; edge < 6; edge += 1) {
+                    const angleA = Math.PI / 6 + edge * Math.PI / 3;
+                    const angleB = Math.PI / 6 + ((edge + 1) % 6) * Math.PI / 3;
+                    points.push(new Vector3(centerX + Math.cos(angleA) * cellRadius, 0, centerZ + Math.sin(angleA) * cellRadius), new Vector3(centerX + Math.cos(angleB) * cellRadius, 0, centerZ + Math.sin(angleB) * cellRadius));
+                }
+            }
+        }
+        const lattice = new LineSegments(new BufferGeometry().setFromPoints(points), new LineBasicMaterial({
+            color: '#59616b',
+            transparent: true,
+            opacity: 0.9,
+            depthTest: true,
+            depthWrite: false
+        }));
+        lattice.position.copy(ear.center).addScaledVector(normal, 0.00055);
+        lattice.quaternion.copy(ear.orientation);
+        lattice.name = `${ear.id}-speaker-grille-lattice`;
+        lattice.renderOrder = 997;
+        return [surface, lattice];
+    }
+    /** Projects the timeline colors onto the authored outer ear diffuser band. */
+    updateEarMeshDiffusers(robot, ears) {
+        const zoneState = this.ledStateProjection.zones.ears;
+        const intensity = Math.max(0, Math.min(1, zoneState?.intensity ?? 0.25));
+        const sourceColors = zoneState?.colors?.length ? zoneState.colors : null;
+        const earFrames = ears.map((ear) => {
+            const count = Math.max(3, Math.min(32, Math.round(ear.calibration.ledCount)));
+            return {
+                ear,
+                inverseOrientation: ear.orientation.clone().invert(),
+                colors: Array.from({ length: count }, (_, index) => new Color(sourceColors?.[index % sourceColors.length] ?? zoneState?.color ?? '#071018'))
+            };
+        });
+        const worldPosition = new Vector3();
+        const localPosition = new Vector3();
+        let found = false;
+        robot.updateMatrixWorld(true);
+        robot.traverse((object) => {
+            const mesh = object;
+            if (!mesh.isMesh)
+                return;
+            // Older hot-reloaded robot instances may still contain the source
+            // speaker bulb that used to be extracted and incorrectly treated as a
+            // segmented LED surface. Retire that legacy projection immediately;
+            // the authored body and the grille projection own the ear appearance.
+            if (mesh.name === 'viewer-led-diffuser-ears' || mesh.userData.viewerLedZone === 'ears') {
+                mesh.visible = false;
+                return;
+            }
+            const positions = mesh.geometry.getAttribute('position');
+            const colors = mesh.geometry.getAttribute('color');
+            if (!positions || !colors || colors.itemSize < 3)
+                return;
+            let baseline = this.ledMeshBaseColors.get(mesh.geometry);
+            if (!baseline || baseline.length !== colors.array.length) {
+                baseline = new Float32Array(colors.array);
+                this.ledMeshBaseColors.set(mesh.geometry, baseline);
+            }
+            for (let index = 0; index < positions.count; index += 1) {
+                const offset = index * colors.itemSize;
+                colors.setXYZ(index, baseline[offset], baseline[offset + 1], baseline[offset + 2]);
+                if (!this.ledStateProjection.visible || earFrames.length === 0)
+                    continue;
+                worldPosition.fromBufferAttribute(positions, index).applyMatrix4(mesh.matrixWorld);
+                let frame = earFrames[0];
+                let distance = worldPosition.distanceToSquared(frame.ear.center);
+                for (let candidateIndex = 1; candidateIndex < earFrames.length; candidateIndex += 1) {
+                    const candidate = earFrames[candidateIndex];
+                    const candidateDistance = worldPosition.distanceToSquared(candidate.ear.center);
+                    if (candidateDistance < distance) {
+                        frame = candidate;
+                        distance = candidateDistance;
+                    }
+                }
+                localPosition.copy(worldPosition).sub(frame.ear.center).applyQuaternion(frame.inverseOrientation);
+                const radialDistance = Math.hypot(localPosition.x, localPosition.z);
+                // Persisted calibrations created before the authored diffuser mapping
+                // used a 16 mm marker radius. Never let that legacy presentation value
+                // select the 25 mm inner speaker bulb again: the light-emitting plastic
+                // is the outer annulus of the authored head shell.
+                const innerRadius = Math.max(0.028, frame.ear.radius * 1.06);
+                const outerRadius = Math.max(0.041, frame.ear.radius * 1.5);
+                const surfaceDepth = Math.max(0.004, frame.ear.radius * 0.48);
+                if (radialDistance < innerRadius ||
+                    radialDistance > outerRadius ||
+                    Math.abs(localPosition.y) > surfaceDepth) {
+                    continue;
+                }
+                found = true;
+                let angle = Math.atan2(localPosition.x, localPosition.z);
+                if (angle < 0)
+                    angle += Math.PI * 2;
+                const colorPosition = angle / (Math.PI * 2) * frame.colors.length;
+                const colorIndex = Math.floor(colorPosition) % frame.colors.length;
+                const nextColorIndex = (colorIndex + 1) % frame.colors.length;
+                const color = frame.colors[colorIndex].clone()
+                    .lerp(frame.colors[nextColorIndex], colorPosition - Math.floor(colorPosition))
+                    .multiplyScalar(intensity);
+                colors.setXYZ(index, color.r, color.g, color.b);
+            }
+            colors.needsUpdate = true;
+        });
+        return found;
+    }
     createEyeRingMireLines(eye) {
         const axisVertical = new Vector3(1, 0, 0).applyQuaternion(eye.orientation).normalize();
         const forward = new Vector3(0, 1, 0).applyQuaternion(eye.orientation).normalize();
@@ -10145,6 +10344,10 @@ export class Viewer3D {
         marker.name = 'balance-center-of-mass-ground-projection';
         return marker;
     }
+    invalidateTrajectoryPreviewProjection() {
+        this.trajectoryProjectionRevision += 1;
+        this.trajectorySignature = '';
+    }
     ensureTrajectoryGroup() {
         if (this.trajectoryGroup) {
             return this.trajectoryGroup;
@@ -10152,7 +10355,7 @@ export class Viewer3D {
         this.trajectoryGroup = new Group();
         this.trajectoryGroup.name = 'AnimationTrajectoryPreview';
         this.trajectoryGroup.visible = false;
-        this.scene.add(this.trajectoryGroup);
+        this.simulatedRobotPresentationRoot.add(this.trajectoryGroup);
         return this.trajectoryGroup;
     }
     updateTrajectoryGroupVisibility() {
@@ -10201,18 +10404,31 @@ export class Viewer3D {
         this.clearTrajectoryPreview();
         this.trajectorySignature = nextSignature;
         const originalPose = this.captureJointPose();
+        const originalRobotTransform = this.captureRobotTransform(this.robot);
+        const temporalSampleResolver = this.playbackState?.animation === animation
+            ? this.playbackState.resolveTemporalProjectionSample
+            : null;
+        let temporalRootAlignment = this.physicsVisualRootToRobotMatrix?.clone() ?? null;
         const previousAnimatedTargets = new Set(this.lastAnimatedJointTargets);
         const sampleCount = Math.max(ROBOT_VIEWER_TRAJECTORY_MIN_SAMPLES, Math.min(ROBOT_VIEWER_TRAJECTORY_MAX_SAMPLES, Math.ceil(duration * ROBOT_VIEWER_TRAJECTORY_SAMPLE_RATE)));
         const pointsByTarget = new Map(targets.map((target) => [target.id, []]));
         for (let sampleIndex = 0; sampleIndex <= sampleCount; sampleIndex += 1) {
             const sampleTime = (sampleIndex / sampleCount) * duration;
-            this.applyRobotPose(animation, sampleTime, [], duration);
+            const temporalSample = temporalSampleResolver?.(sampleTime) ?? null;
+            this.restoreRobotTransform(this.robot, originalRobotTransform);
+            if (temporalSample?.viewer) {
+                temporalRootAlignment = this.applyTrajectoryTemporalSamplePose(temporalSample, temporalRootAlignment);
+            }
+            else {
+                this.applyTrajectorySamplePose(animation, sampleTime, duration);
+            }
             this.robot.updateMatrixWorld(true);
             for (const target of targets) {
-                pointsByTarget.get(target.id)?.push(this.getTrajectoryPoint(target.id));
+                pointsByTarget.get(target.id)?.push(this.getTrajectoryPointInProjectionFrame(target.id));
             }
         }
-        this.restoreJointPose(originalPose);
+        this.restoreRobotTransform(this.robot, originalRobotTransform);
+        this.restoreTrajectorySamplePose(originalPose);
         this.lastAnimatedJointTargets = previousAnimatedTargets;
         this.nextAnimatedJointTargets.clear();
         for (const target of targets) {
@@ -10222,26 +10438,100 @@ export class Viewer3D {
             }
             trajectoryGroup.add(this.createTrajectoryObject(target, points));
         }
-        this.updateTrajectoryCurrentMarkers();
         this.updateTrajectoryGroupVisibility();
+        this.updateTrajectoryCurrentMarkers();
         this.requestRender();
     }
+    applyTrajectorySamplePose(animation, time, duration) {
+        const joints = this.getRobotJoints();
+        for (const { target, value } of sampleRobotMotionJointValuesAtTime(animation, time, duration)) {
+            const joint = joints[target];
+            if (joint)
+                this.applyDesiredProjectionJointValue(joint, value);
+        }
+    }
+    applyTrajectoryTemporalSamplePose(sample, rootAlignment) {
+        const viewer = sample.viewer;
+        const robot = this.robot;
+        if (!viewer || !robot) {
+            return rootAlignment;
+        }
+        const joints = this.getRobotJoints();
+        for (const [target, value] of Object.entries(viewer.joints ?? {})) {
+            const joint = joints[target];
+            if (joint && Number.isFinite(value)) {
+                this.applyDesiredProjectionJointValue(joint, value);
+            }
+        }
+        const bodyTransforms = (viewer.physics?.bodyTransforms ?? []).map((transform) => this.deserializeRuntimeHistoryTransform(transform, false));
+        const rootTransform = bodyTransforms.find((transform) => transform.metadata?.visualRoot === true) ??
+            bodyTransforms.find((transform) => transform.bodyName === this.physicsVisualRootBodyName);
+        let nextRootAlignment = rootAlignment;
+        if (rootTransform) {
+            const physicsRootWorldMatrix = this.createPhysicsBodyViewerWorldMatrix(rootTransform);
+            nextRootAlignment ??= this.resolvePhysicsVisualRootToRobotMatrix(physicsRootWorldMatrix, bodyTransforms);
+            const nextRobotLocalMatrix = physicsRootWorldMatrix.clone().multiply(nextRootAlignment);
+            const parent = robot.parent;
+            if (parent && parent !== this.simulatedRobotPresentationRoot) {
+                parent.updateMatrixWorld(true);
+                nextRobotLocalMatrix.premultiply(parent.matrixWorld.clone().invert());
+            }
+            robot.matrix.copy(nextRobotLocalMatrix);
+            robot.matrix.decompose(robot.position, robot.quaternion, robot.scale);
+        }
+        robot.updateMatrixWorld(true);
+        return nextRootAlignment;
+    }
+    restoreTrajectorySamplePose(pose) {
+        const joints = this.getRobotJoints();
+        for (const [target, value] of Object.entries(pose)) {
+            const joint = joints[target];
+            if (joint)
+                this.applyDesiredProjectionJointValue(joint, value);
+        }
+        this.robot?.updateMatrixWorld(true);
+    }
     getTrajectorySignature(animation, targets, duration) {
         return JSON.stringify({
             duration: Number(duration.toFixed(3)),
+            projectionRevision: this.trajectoryProjectionRevision,
+            playbackProjection: this.getTrajectoryPlaybackProjectionSignature(animation),
             handsOnly: this.options.showHandTrajectoriesOnly,
             targets: targets.map((target) => target.id),
+            temporalProjection: this.getTrajectoryTemporalProjectionSignature(animation, duration),
             tracks: animation.motion.tracks.map((track) => ({
                 target: track.target,
                 property: track.property,
-                keys: track.keys.length,
-                firstTime: track.keys[0]?.time ?? null,
-                lastTime: track.keys[track.keys.length - 1]?.time ?? null,
-                firstValue: track.keys[0]?.value ?? null,
-                lastValue: track.keys[track.keys.length - 1]?.value ?? null
+                interpolation: track.interpolation ?? null,
+                unitKind: track.unitKind ?? null,
+                keys: track.keys.map((key) => [key.time, key.value])
             }))
         });
     }
+    getTrajectoryPlaybackProjectionSignature(animation) {
+        const playback = this.playbackState;
+        if (playback?.animation !== animation) {
+            return null;
+        }
+        return {
+            mutedTargets: [...playback.mutedTrackTargetSet].sort(),
+            startTransitionMinimumDurationSeconds: playback.startTransitionMinimumDurationSeconds,
+            entryPose: this.createPoseSignature(playback.entryPose),
+            endTransitionMinimumDurationSeconds: playback.endTransitionMinimumDurationSeconds,
+            exitPose: this.createPoseSignature(playback.exitPose)
+        };
+    }
+    getTrajectoryTemporalProjectionSignature(animation, duration) {
+        const playback = this.playbackState;
+        const resolver = playback?.animation === animation ? playback.resolveTemporalProjectionSample : null;
+        if (!resolver) {
+            return null;
+        }
+        return [0, duration * 0.5, duration].map((time) => {
+            const sample = resolver(time);
+            return sample ? [sample.id, Number(sample.timeSeconds.toFixed(4))] : null;
+        });
+    }
     getTrajectoryPreviewTargets(animation) {
         if (this.options.showHandTrajectoriesOnly) {
             return (this.options.handTipDefinitions ?? [])
@@ -10332,9 +10622,12 @@ export class Viewer3D {
             if (!target || !currentMarker) {
                 continue;
             }
-            currentMarker.position.copy(this.getTrajectoryPoint(target));
+            currentMarker.position.copy(this.getTrajectoryPointInProjectionFrame(target));
         }
     }
+    getTrajectoryPointInProjectionFrame(target) {
+        return projectViewerTrajectoryPointToFrame(this.getTrajectoryPoint(target), this.simulatedRobotPresentationRoot);
+    }
     getTrajectoryPoint(target) {
         const handTip = (this.options.handTipDefinitions ?? []).find((definition) => definition.id === target);
         if (handTip) {
@@ -10413,10 +10706,10 @@ export class Viewer3D {
             this.trajectoryAnchors.set(target, anchor);
             return anchor;
         }
+        joint.updateMatrixWorld?.(true);
         const jointInverse = joint.matrixWorld.clone().invert();
         const localBounds = new Box3();
         let hasBounds = false;
-        joint.updateMatrixWorld?.(true);
         joint.traverse((node) => {
             if (node !== joint && node.isURDFJoint) {
                 return;
@@ -10710,6 +11003,11 @@ export class Viewer3D {
 function formatNavigationDistance(value) {
     return `${value >= 0 ? '+' : ''}${value.toFixed(2)}m`;
 }
+/** Projects a world-space trajectory sample into the robot presentation frame. */
+export function projectViewerTrajectoryPointToFrame(point, frame) {
+    frame.updateWorldMatrix(true, false);
+    return frame.worldToLocal(new Vector3(point.x, point.y, point.z));
+}
 function formatNavigationAngle(value) {
     const degrees = MathUtils.radToDeg(normalizeNavigationRadians(value));
     return `${degrees >= 0 ? '+' : ''}${degrees.toFixed(0)}°`;