@konitif/viewer-3d 0.285.4 → 0.285.6

package/dist/renderer/Viewer3DRenderer.js

@@ -5,6 +5,7 @@ import { resolvePhysicsSourceString, resolvePhysicsSourceStringListMap, resolveP
 import { createClockGraph, createInvalidationController, createTemporalTransport } from '@konitif/temporal';
 import { createViewerTemporalScheduler } from './ViewerTemporalScheduler.js';
 import { copyViewerMetadata } from './ViewerMetadata.js';
+import { IncarnationMaterialProjector, normalizeIncarnationMaterialProjection } from './IncarnationMaterialProjection.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, 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';
@@ -17,7 +18,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';
@@ -30,6 +31,8 @@ import { resolveViewerIncarnationHealth } from './ViewerIncarnationHealth.js';
 import { PerformanceMonitor } from './PerformanceMonitor.js';
 import { ViewerTemporalProjectionBuffer } from './TemporalProjectionModel.js';
 import { ObservedRobotPresentationBuffer } from './ObservedRobotPresentationBuffer.js';
+import { ObservedSoleAnchors, projectBoundedSoleCorrection } from './ObservedSoleStabilization.js';
+import { ConvexHull } from 'three/examples/jsm/math/ConvexHull.js';
 import { resolveViewerFrameSignalIntervalMs, VIEWER_FRAME_SIGNAL_CATALOG } from './ViewerFrameSignals.js';
 import { DEFAULT_DISPLAY_FRAME_RATE_HZ, normalizeConfiguredDisplayFrameRate, observeDisplayFrameRateCeiling, resolveDisplayFrameRateTarget } from './displayFrameRate.js';
 import { ViewerTemporalProjectionExperimentAdapter } from './ViewerTemporalProjectionExperimentAdapter.js';
@@ -219,6 +222,8 @@ export class Viewer3D {
     poseControlTarget = 'simulated';
     observedPoseLiveControlEnabled = false;
     robotMaterialBaselines = new Map();
+    incarnationMaterialProjector = new IncarnationMaterialProjector();
+    incarnationMaterialProjections = {};
     observedRobotGhostMaterialBaselines = new Map();
     observedRobotGhostRenderOrderBaselines = new Map();
     observedRobotGhostShadowMaterials = new Map();
@@ -229,6 +234,11 @@ export class Viewer3D {
     observedRobotGhostBaseQuaternion = new Quaternion();
     observedRobotGhostBaseScale = new Vector3(1, 1, 1);
     observedRobotTemporalSupportAnchorState = null;
+    observedSoleAnchors = new ObservedSoleAnchors();
+    observedSoleConnectionId = '';
+    observedSoleStrength = 0;
+    observedSoleBaseline = new Map();
+    observedSoleSurfaceVertices = new WeakMap();
     observedRobotGrounding = resolveObservedRobotGroundingProjection({
         enabled: false,
         floorY: ROBOT_VIEWER_SUPPORT_FLOOR_Y,
@@ -296,6 +306,7 @@ export class Viewer3D {
     projectilePointerInside = false;
     trajectoryAnimation = null;
     trajectorySignature = '';
+    trajectoryProjectionRevision = 0;
     trajectoryAnchors = new Map();
     themeObserver = null;
     animationLoop;
@@ -1050,11 +1061,17 @@ export class Viewer3D {
             sampleId: input.frameId,
             connectionId: input.connectionId,
             sourceObservedAtSeconds: input.observedAtSeconds,
+            sourceClock: input.sourceClock,
             receivedAtMs,
             jointValues: input.jointValues
         });
         if (!accepted)
             return false;
+        if (this.observedSoleConnectionId !== input.connectionId) {
+            this.restoreObservedSoleBaseline();
+            this.observedSoleAnchors.reset();
+            this.observedSoleConnectionId = input.connectionId;
+        }
         const frame = this.observedRobotPresentation.project(receivedAtMs);
         if (frame)
             this.applyObservedRobotGhostJointValues(frame.jointValues);
@@ -1062,14 +1079,35 @@ export class Viewer3D {
         return true;
     }
     resetObservedRobotGhostJointObservation() {
+        this.restoreObservedSoleBaseline();
+        this.observedSoleAnchors.reset();
         this.observedRobotPresentation.reset('discontinuity');
     }
+    setObservedRobotSoleStabilizationStrength(value) {
+        this.observedSoleAnchors ??= new ObservedSoleAnchors();
+        const strength = Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : 0;
+        if (strength === this.observedSoleStrength)
+            return;
+        this.restoreObservedSoleBaseline();
+        this.observedSoleAnchors.reset();
+        this.observedSoleStrength = strength;
+        this.applyObservedRobotGhostGrounding();
+        this.requestRender();
+    }
+    restoreObservedSoleBaseline() {
+        this.observedSoleBaseline ??= new Map();
+        for (const [joint, value] of this.observedSoleBaseline)
+            joint.setJointValue(value);
+        this.observedSoleBaseline.clear();
+    }
     getObservedRobotPresentationStatus() {
         return this.observedRobotPresentation.getStatus();
     }
     applyObservedRobotGhostJointValues(values) {
         if (!this.observedRobotGhost)
             return false;
+        const hadSoleCorrection = (this.observedSoleBaseline?.size ?? 0) > 0;
+        this.restoreObservedSoleBaseline();
         const joints = this.observedRobotGhost.joints ?? {};
         let changed = false;
         for (const [target, value] of Object.entries(values)) {
@@ -1081,7 +1119,7 @@ export class Viewer3D {
                 continue;
             changed = joint.setJointValue(value) !== false || changed;
         }
-        if (changed) {
+        if (changed || hadSoleCorrection) {
             this.applyObservedRobotGhostGrounding();
             if (this.poseControlTarget === 'observed') {
                 this.refreshPoseHandleProjection();
@@ -1144,10 +1182,28 @@ export class Viewer3D {
         // invalidate that anchor.
         if (spatialLayoutChanged) {
             this.observedRobotTemporalSupportAnchorState = null;
+            this.observedSoleAnchors?.reset();
         }
         this.applyRobotComparisonAppearance();
         this.requestRender();
     }
+    /** Tune one visual incarnation independently; source meshes and telemetry remain unchanged. */
+    setIncarnationMaterialProjection(target, projection) {
+        if (target !== 'simulated' && target !== 'observed')
+            throw new Error('Invalid material incarnation target');
+        this.incarnationMaterialProjections[target] = normalizeIncarnationMaterialProjection(projection);
+        this.applyIncarnationMaterialProjections();
+        this.requestRender();
+    }
+    applyIncarnationMaterialProjections() {
+        for (const target of ['simulated', 'observed']) {
+            const projection = this.incarnationMaterialProjections[target];
+            if (!projection)
+                continue;
+            const materials = target === 'simulated' ? this.robotMaterialBaselines : this.observedRobotGhostMaterialBaselines;
+            this.incarnationMaterialProjector.apply(materials.keys(), projection);
+        }
+    }
     async setPhysicsEngine(physicsEngine, physicsEnabled = physicsEngine !== 'none') {
         if (this.destroyed)
             return;
@@ -1178,6 +1234,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();
             }
@@ -1203,6 +1260,7 @@ export class Viewer3D {
         }
         this.options.physicsMotorsCoupled = physicsMotorsCoupled;
         this.physicsVisualRootToRobotMatrix = null;
+        this.invalidateTrajectoryPreviewProjection();
         this.resetPhysicsPostureCompensation();
         if (!physicsMotorsCoupled) {
             this.robot?.updateMatrixWorld(true);
@@ -1235,6 +1293,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;
@@ -1272,6 +1331,7 @@ export class Viewer3D {
         this.scrubPreviewState = null;
         this.playbackSyncSignature = '';
         this.physicsVisualRootToRobotMatrix = null;
+        this.invalidateTrajectoryPreviewProjection();
         this.physicsAuthoredJointTargets.clear();
         this.resetPhysicsPostureCompensation();
         this.comparisonViewerSample = null;
@@ -1283,6 +1343,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();
@@ -2032,7 +2093,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;
@@ -2056,6 +2122,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;
@@ -2385,6 +2452,9 @@ export class Viewer3D {
             this.playbackState?.isPlaying &&
             this.playbackState.animation === animation &&
             this.playbackSyncSignature === syncSignature) {
+            if (this.options.showTrajectories && animation) {
+                this.rebuildTrajectoryPreview();
+            }
             return;
         }
         const nextPlaybackState = {
@@ -2438,6 +2508,7 @@ export class Viewer3D {
                     this.alignUnbufferedPlaybackPoseToSupportFloor();
                 }
             }
+            this.rebuildTrajectoryPreview();
             this.updateTrajectoryCurrentMarkers();
             if (nextPlaybackState.clockMode === 'realtime') {
                 this.scheduleLoop();
@@ -2467,6 +2538,7 @@ export class Viewer3D {
                     this.alignUnbufferedPlaybackPoseToSupportFloor();
                 }
             }
+            this.rebuildTrajectoryPreview();
             this.updateTrajectoryCurrentMarkers();
             if (shouldStartViewerPlaybackCompletionTransition({
                 isPlaying,
@@ -3971,12 +4043,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;
@@ -4031,6 +4103,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;
@@ -5123,6 +5205,10 @@ export class Viewer3D {
                 return;
             const ghostMaterials = sourceMaterials.map((source) => {
                 const material = source.clone();
+                // Three material cloning does not retain consumer-owned shader hooks.
+                // Preserve the observed model's own hooks, never the simulated state.
+                material.onBeforeCompile = source.onBeforeCompile;
+                material.customProgramCacheKey = source.customProgramCacheKey;
                 this.captureMaterialBaseline(material, this.observedRobotGhostMaterialBaselines);
                 return material;
             });
@@ -5162,6 +5248,8 @@ export class Viewer3D {
         }
     }
     clearObservedRobotGhost() {
+        this.restoreObservedSoleBaseline();
+        this.observedSoleAnchors?.reset();
         this.cancelRobotComparisonVisibilityTransition();
         this.observedRobotPresentation.reset('discontinuity');
         this.simulatedRobotPresentationRoot.position.x = 0;
@@ -5205,6 +5293,7 @@ export class Viewer3D {
         this.applyBalanceDebugPresentationOffset();
     }
     applyRobotComparisonAppearance() {
+        this.applyIncarnationMaterialProjections();
         this.applyMaterialAppearance(this.robotMaterialBaselines, this.robotComparisonAppearance.simulated);
         this.applyMaterialAppearance(this.observedRobotGhostMaterialBaselines, this.robotComparisonAppearance.observed);
         this.applyObservedRobotGhostRenderOrder(this.robotComparisonAppearance.observed.opacity < 0.999);
@@ -5241,6 +5330,7 @@ export class Viewer3D {
         }
     }
     applyObservedRobotGhostGrounding() {
+        this.restoreObservedSoleBaseline();
         if (this.comparisonProfileId) {
             this.projectComparisonSimulation();
             return;
@@ -5268,6 +5358,12 @@ export class Viewer3D {
         robot.updateMatrixWorld(true);
         const supportContacts = this.resolveObservedRobotSupportContacts(robot);
         const supportPoints = supportContacts.supportPoints;
+        const lowestRawSupport = Math.min(...supportPoints.map(point => point.y));
+        const soleEligible = new Map();
+        for (const group of new Set(supportContacts.supportGroupIds)) {
+            const minimum = Math.min(...supportPoints.filter((_, index) => supportContacts.supportGroupIds[index] === group).map(point => point.y));
+            soleEligible.set(group, minimum - lowestRawSupport <= 0.008);
+        }
         const activeSupport = resolveObservedRobotActiveSupportProjection({
             supportPoints,
             contactIds: supportContacts.contactIds,
@@ -5316,18 +5412,134 @@ export class Viewer3D {
         robot.position.x += temporalSupportAnchor.offsetX;
         robot.position.z += temporalSupportAnchor.offsetZ;
         robot.updateMatrixWorld(true);
+        const stabilizedSurfaceMinimumY = this.applyObservedSoleStabilization(robot, soleEligible, footSupportEligibility.eligible);
         const observedSupport = this.resolveObservedRobotSupport(robot, activeSupport.activeContactCount);
         this.observedRobotGrounding = resolveObservedRobotGroundingProjection({
             enabled: this.options.groundObservedRobotGhost,
             floorY: ROBOT_VIEWER_SUPPORT_FLOOR_Y,
-            supportMinimumY: observedSupport.supportMinimumY,
+            supportMinimumY: stabilizedSurfaceMinimumY ?? observedSupport.supportMinimumY,
             supportContactCount: observedSupport.supportContactCount,
-            source: observedSupport.source
+            source: stabilizedSurfaceMinimumY === null || stabilizedSurfaceMinimumY === undefined ? observedSupport.source : 'foot-geometry'
         });
         robot.position.y += this.observedRobotGrounding.offsetY;
         robot.updateMatrixWorld(true);
         this.applyNavigationPreviewPresentationTransform();
     }
+    applyObservedSoleStabilization(robot, eligible, supportEligible) {
+        if (!(this.observedSoleStrength > 0) || !supportEligible)
+            return null;
+        const status = this.observedRobotPresentation?.getStatus();
+        if (status?.mode === 'raw' || status?.fallbackReason === 'sample_gap') {
+            this.observedSoleAnchors.reset();
+            return null;
+        }
+        const chains = this.options.supportDefinition?.soleStabilizationChains ?? [];
+        const joints = robot.joints ?? {};
+        const pose = (groupId, foot) => {
+            const contacts = this.resolveObservedRobotSupportContacts(robot);
+            const points = contacts.supportPoints.filter((_, index) => contacts.supportGroupIds[index] === groupId);
+            const center = points.reduce((sum, point) => sum.add(point), new Vector3()).multiplyScalar(1 / Math.max(1, points.length));
+            const rotation = foot.getWorldQuaternion(new Quaternion());
+            const supportMinimumY = this.resolvePreciseObservedSoleMinimumY(foot) ?? Math.min(...points.map(point => point.y));
+            return { position: [center.x, center.y, center.z], orientation: [rotation.x, rotation.y, rotation.z, rotation.w], supportMinimumY };
+        };
+        const candidates = chains.flatMap(chain => {
+            const selected = chain.jointNames.map(name => joints[name]);
+            const foot = selected[selected.length - 1];
+            if (!foot || typeof foot.getWorldQuaternion !== 'function' || selected.some(joint => !joint || joint.mimicJoint))
+                return [];
+            const baseline = selected.map(joint => this.readJointValue(joint));
+            if (baseline.some(value => typeof value !== 'number' || !Number.isFinite(value)))
+                return [];
+            return [{ chain, selected: selected, foot, baseline: baseline, raw: pose(chain.groupId, foot) }];
+        });
+        const targets = this.observedSoleAnchors.resolve(this.observedSoleConnectionId, candidates.map(candidate => ({
+            id: candidate.chain.groupId, position: candidate.raw.position,
+            eligible: this.options.groundObservedRobotGhost && supportEligible && eligible.get(candidate.chain.groupId) === true
+        })), this.observedSoleStrength);
+        // Both eligible soles share a surface before the final root grounding.
+        // Preserve lifted/released feet rather than treating every chain as contact.
+        const supportPlaneY = Math.min(...candidates.filter(candidate => targets.some(target => target.id === candidate.chain.groupId)).map(candidate => candidate.raw.supportMinimumY));
+        for (const target of targets) {
+            const candidate = candidates.find(entry => entry.chain.groupId === target.id);
+            const verticalOffset = supportPlaneY - candidate.raw.supportMinimumY;
+            const targetPosition = [target.target[0], candidate.raw.position[1] + verticalOffset, target.target[2]];
+            if (Math.hypot(...targetPosition.map((value, index) => value - candidate.raw.position[index])) < 0.00001)
+                continue;
+            const apply = (values) => {
+                candidate.selected.forEach((joint, index) => joint.setJointValue(values[index]));
+                robot.updateMatrixWorld(true);
+            };
+            try {
+                const correction = projectBoundedSoleCorrection({
+                    values: candidate.baseline,
+                    limits: candidate.selected.map(joint => [joint.limit?.lower ?? -Math.PI, joint.limit?.upper ?? Math.PI]),
+                    targetPosition, targetOrientation: candidate.raw.orientation,
+                    targetSupportMinimumY: supportPlaneY,
+                    evaluate: values => { apply(values); return pose(target.id, candidate.foot); }
+                });
+                apply(correction.values);
+                candidate.selected.forEach((joint, index) => this.observedSoleBaseline.set(joint, candidate.baseline[index]));
+            }
+            catch {
+                // Invalid/unreachable authored chains must leave the observed copy intact.
+                apply(candidate.baseline);
+            }
+        }
+        if (!targets.length)
+            return null;
+        // An unanchored foot must still not be pushed through the floor by root grounding.
+        const visibleMinima = candidates.map(candidate => this.resolvePreciseObservedSoleMinimumY(candidate.foot))
+            .filter((value) => value !== null);
+        const minimum = Math.min(...visibleMinima);
+        return Number.isFinite(minimum) ? minimum : null;
+    }
+    /** Exact directional support of rigid visible meshes, with cached convex vertices. */
+    resolvePreciseObservedSoleMinimumY(foot) {
+        this.observedSoleSurfaceVertices ??= new WeakMap();
+        let minimum = Infinity;
+        foot.traverse(node => {
+            const mesh = node;
+            if (!mesh.isMesh || mesh.isURDFCollider || !mesh.geometry)
+                return;
+            const attribute = mesh.geometry.getAttribute('position');
+            if (!attribute)
+                return;
+            const version = 'version' in attribute ? Number(attribute.version) : attribute.data.version;
+            let cached = this.observedSoleSurfaceVertices.get(mesh.geometry);
+            if (!cached || cached.attribute !== attribute || cached.version !== version) {
+                const points = [];
+                for (let index = 0; index < attribute.count; index++) {
+                    const point = new Vector3().fromBufferAttribute(attribute, index);
+                    if ([point.x, point.y, point.z].every(Number.isFinite))
+                        points.push(point);
+                }
+                let vertices = points;
+                if (points.length > 4) {
+                    try {
+                        const hull = new ConvexHull().setFromPoints(points);
+                        const unique = new Set();
+                        for (const face of hull.faces) {
+                            let edge = face.edge;
+                            do {
+                                unique.add(edge.vertex.point);
+                                edge = edge.next;
+                            } while (edge !== face.edge);
+                        }
+                        if (unique.size)
+                            vertices = [...unique];
+                    }
+                    catch { /* Degenerate meshes retain their exact original vertices. */ }
+                }
+                cached = { attribute, version, points: vertices };
+                this.observedSoleSurfaceVertices.set(mesh.geometry, cached);
+            }
+            const matrix = mesh.matrixWorld.elements;
+            for (const point of cached.points)
+                minimum = Math.min(minimum, matrix[1] * point.x + matrix[5] * point.y + matrix[9] * point.z + matrix[13]);
+        });
+        return Number.isFinite(minimum) ? minimum : null;
+    }
     resolveObservedRobotSupportContacts(robot) {
         const supportPoints = [];
         const contactIds = [];
@@ -6029,6 +6241,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;
@@ -8420,6 +8633,7 @@ export class Viewer3D {
         if (!rootTransform)
             return;
         this.physicsVisualRootToRobotMatrix = this.resolvePhysicsVisualRootToRobotMatrix(this.createPhysicsBodyViewerWorldMatrix(rootTransform), bodyTransforms);
+        this.invalidateTrajectoryPreviewProjection();
     }
     projectProjectilePhysicsObservation() {
         const bodyTransforms = this.physicsService.getBodyTransforms();
@@ -10315,6 +10529,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;
@@ -10322,7 +10540,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() {
@@ -10371,18 +10589,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) {
@@ -10392,26 +10623,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 ?? [])
@@ -10502,9 +10807,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) {
@@ -10583,10 +10891,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;
@@ -10880,6 +11188,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)}°`;