@jgengine/shell 0.11.0 → 0.13.0

package/dist/audio/audioEngine.js

@@ -1,7 +1,11 @@
 import { distance3, resolveEmitterGain } from "@jgengine/core/audio/audioFalloff";
+import { patchDuration } from "@jgengine/core/audio/synth";
 import { createDisposer } from "@jgengine/core/game/defineGame";
+import { clampLoopGain, clampLoopRate } from "./loopParams.js";
 import { MusicDirector } from "./musicDirector.js";
 import { createNoiseBuffer, realizeSynthPatch } from "./synthEngine.js";
+/** setTargetAtTime time constant (~20 ms) for zipper-free live rate/gain ramps on retained loops (#1051). */
+const LOOP_PARAM_SMOOTH_TC = 0.02;
 function createNoopEngine() {
     return {
         setListenerPose: () => undefined,
@@ -20,6 +24,12 @@ function resolveAudioContextCtor() {
     return (window.AudioContext ??
         window.webkitAudioContext);
 }
+function resolveOfflineAudioContextCtor() {
+    if (typeof window === "undefined")
+        return undefined;
+    return (window.OfflineAudioContext ??
+        window.webkitOfflineAudioContext);
+}
 export function createAudioEngine(config = {}) {
     const sounds = config.sounds ?? {};
     const busDefs = config.buses ?? {};
@@ -74,65 +84,138 @@ export function createAudioEngine(config = {}) {
         }
         return pending;
     }
+    // Retained synth loops render the procedural patch to one cached buffer, then loop it as a plain
+    // BufferSource — so live pitch is `playbackRate` and live gain is a gain node, exactly like sample loops (#1051).
+    const synthBufferCache = new Map();
+    function renderSynthBuffer(soundId, patch) {
+        let pending = synthBufferCache.get(soundId);
+        if (pending === undefined) {
+            const OfflineCtor = resolveOfflineAudioContextCtor();
+            if (OfflineCtor === undefined) {
+                pending = Promise.resolve(null);
+            }
+            else {
+                try {
+                    const seconds = Math.max(patchDuration(patch), 0.05);
+                    const frames = Math.max(1, Math.ceil(seconds * context.sampleRate));
+                    const offline = new OfflineCtor(1, frames, context.sampleRate);
+                    realizeSynthPatch(offline, offline.destination, createNoiseBuffer(offline), patch);
+                    pending = offline.startRendering().catch(() => null);
+                }
+                catch {
+                    pending = Promise.resolve(null);
+                }
+            }
+            synthBufferCache.set(soundId, pending);
+        }
+        return pending;
+    }
     let listenerPosition = { x: 0, y: 0, z: 0 };
     const activeSpatialUpdaters = new Set();
+    const activeLoops = new Set();
+    const NOOP_HANDLE = {
+        setPosition: () => undefined,
+        setRate: () => undefined,
+        setGain: () => undefined,
+        stop: () => undefined,
+    };
     function playInternal(soundId, position, loop) {
         const sound = sounds[soundId];
         if (sound === undefined)
             return null;
         const bus = busGainNode(sound.bus);
-        let currentPosition = position ?? listenerPosition;
-        if (sound.synth !== undefined) {
+        const currentPosition = position ?? listenerPosition;
+        // A one-shot synth cue realises its decaying voices live and is fire-and-forget.
+        if (sound.synth !== undefined && !loop) {
             const cueGain = context.createGain();
             cueGain.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
             cueGain.connect(bus);
             realizeSynthPatch(context, cueGain, sharedNoiseBuffer(), sound.synth);
-            return { setPosition: () => undefined, stop: () => undefined };
+            return NOOP_HANDLE;
         }
-        if (sound.url === undefined)
+        // Everything else resolves to one AudioBuffer we loop/play: sample URL, or a synth patch rendered once.
+        let bufferPromise;
+        if (sound.synth !== undefined)
+            bufferPromise = renderSynthBuffer(soundId, sound.synth);
+        else if (sound.url !== undefined)
+            bufferPromise = loadBuffer(sound.url);
+        else
             return null;
+        return playBufferSource(sound, bus, bufferPromise, currentPosition, loop);
+    }
+    function playBufferSource(sound, bus, bufferPromise, initialPosition, loop) {
         const disposer = createDisposer();
-        let liveGain = null;
-        function updateGain() {
-            if (liveGain !== null) {
-                liveGain.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
+        let currentPosition = initialPosition;
+        // Live control state, applied on source creation so updates that race the async buffer load stick.
+        let currentRate = 1;
+        let currentUserGain = 1;
+        let sourceNode = null;
+        let userGainNode = null;
+        let falloffGain = null;
+        function updateFalloff() {
+            if (falloffGain !== null) {
+                falloffGain.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
             }
         }
-        void loadBuffer(sound.url).then((buffer) => {
+        void bufferPromise.then((buffer) => {
             if (buffer === null)
                 return;
-            const sourceNode = context.createBufferSource();
-            sourceNode.buffer = buffer;
-            sourceNode.loop = loop || (sound.loop ?? false);
-            const gainNode = context.createGain();
-            gainNode.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
-            sourceNode.connect(gainNode);
-            gainNode.connect(bus);
-            sourceNode.start();
-            liveGain = gainNode;
+            const src = context.createBufferSource();
+            src.buffer = buffer;
+            src.loop = loop || (sound.loop ?? false);
+            src.playbackRate.value = currentRate;
+            // source → per-loop user gain (setGain) → distance falloff → bus
+            const uGain = context.createGain();
+            uGain.gain.value = currentUserGain;
+            const fGain = context.createGain();
+            fGain.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
+            src.connect(uGain);
+            uGain.connect(fGain);
+            fGain.connect(bus);
+            src.start();
+            sourceNode = src;
+            userGainNode = uGain;
+            falloffGain = fGain;
             disposer.onDispose(() => {
                 try {
-                    sourceNode.stop();
+                    src.stop();
                 }
                 catch {
                 }
-                sourceNode.disconnect();
-                gainNode.disconnect();
-                liveGain = null;
+                src.disconnect();
+                uGain.disconnect();
+                fGain.disconnect();
+                sourceNode = null;
+                userGainNode = null;
+                falloffGain = null;
             });
         });
         if (loop)
-            activeSpatialUpdaters.add(updateGain);
-        return {
+            activeSpatialUpdaters.add(updateFalloff);
+        const handle = {
             setPosition(next) {
                 currentPosition = next;
-                updateGain();
+                updateFalloff();
+            },
+            setRate(rate) {
+                currentRate = clampLoopRate(rate);
+                if (sourceNode !== null)
+                    sourceNode.playbackRate.setTargetAtTime(currentRate, context.currentTime, LOOP_PARAM_SMOOTH_TC);
+            },
+            setGain(gain) {
+                currentUserGain = clampLoopGain(gain);
+                if (userGainNode !== null)
+                    userGainNode.gain.setTargetAtTime(currentUserGain, context.currentTime, LOOP_PARAM_SMOOTH_TC);
             },
             stop() {
-                activeSpatialUpdaters.delete(updateGain);
+                activeSpatialUpdaters.delete(updateFalloff);
+                activeLoops.delete(handle);
                 disposer.dispose();
             },
         };
+        if (loop)
+            activeLoops.add(handle);
+        return handle;
     }
     return {
         setListenerPose(position) {
@@ -161,6 +244,8 @@ export function createAudioEngine(config = {}) {
             void context.resume().catch(() => undefined);
         },
         dispose() {
+            for (const handle of [...activeLoops])
+                handle.stop();
             activeSpatialUpdaters.clear();
             director?.dispose();
             void context.close().catch(() => undefined);

package/dist/audio/audioWire.d.ts

@@ -7,16 +7,34 @@ type AudioMusicPayload = {
     theme: string | null;
     transpose?: number;
 };
-/** Minimal event bus the shell wires to the audio engine. @internal */
+type AudioLoopStartPayload = {
+    id: string;
+    sound: string;
+    at?: readonly [number, number, number];
+};
+type AudioLoopSetPayload = {
+    id: string;
+    rate?: number;
+    gain?: number;
+    at?: readonly [number, number, number];
+};
+type AudioLoopStopPayload = {
+    id: string;
+};
+/** Minimal event bus the shell wires to the audio engine, including retained id-keyed loops (#1051). @internal */
 export type AudioEventBus = {
     on(event: "audio.play", handler: (payload: AudioPlayPayload) => void): () => void;
     on(event: "audio.music", handler: (payload: AudioMusicPayload) => void): () => void;
     on(event: "audio.resume", handler: () => void): () => void;
+    on(event: "audio.loopStart", handler: (payload: AudioLoopStartPayload) => void): () => void;
+    on(event: "audio.loopSet", handler: (payload: AudioLoopSetPayload) => void): () => void;
+    on(event: "audio.loopStop", handler: (payload: AudioLoopStopPayload) => void): () => void;
 };
 /**
- * Subscribe game audio events to the shell audio engine.
- * Returns a single unsubscribe that tears all three listeners down.
+ * Subscribe game audio events to the shell audio engine. Manages the retained-loop registry
+ * (`audio.loopStart`/`audio.loopSet`/`audio.loopStop`), keyed by stable id. Returns a single
+ * unsubscribe that tears every listener down and stops any loops still playing.
  * @internal
  */
-export declare function attachAudioEventWire(events: AudioEventBus, audioEngine: Pick<AudioEngine, "playOneShot" | "playMusic" | "resume">): () => void;
+export declare function attachAudioEventWire(events: AudioEventBus, audioEngine: Pick<AudioEngine, "playOneShot" | "playLoop" | "playMusic" | "resume">): () => void;
 export {};

package/dist/audio/audioWire.js

@@ -1,19 +1,62 @@
+function toVec(at) {
+    return at === undefined ? undefined : { x: at[0], y: at[1], z: at[2] };
+}
 /**
- * Subscribe game audio events to the shell audio engine.
- * Returns a single unsubscribe that tears all three listeners down.
+ * Subscribe game audio events to the shell audio engine. Manages the retained-loop registry
+ * (`audio.loopStart`/`audio.loopSet`/`audio.loopStop`), keyed by stable id. Returns a single
+ * unsubscribe that tears every listener down and stops any loops still playing.
  * @internal
  */
 export function attachAudioEventWire(events, audioEngine) {
+    const loops = new Map();
     const offPlay = events.on("audio.play", ({ sound, at }) => {
-        audioEngine.playOneShot(sound, at === undefined ? undefined : { x: at[0], y: at[1], z: at[2] });
+        audioEngine.playOneShot(sound, toVec(at));
     });
     const offMusic = events.on("audio.music", ({ theme, transpose }) => {
         audioEngine.playMusic(theme, transpose === undefined ? undefined : { transpose });
     });
     const offResume = events.on("audio.resume", () => audioEngine.resume());
+    const offLoopStart = events.on("audio.loopStart", ({ id, sound, at }) => {
+        const existing = loops.get(id);
+        if (existing !== undefined) {
+            // Same sound: idempotent — keep the running source so a per-tick re-issue never clicks.
+            if (existing.sound === sound)
+                return;
+            existing.handle.stop();
+            loops.delete(id);
+        }
+        const handle = audioEngine.playLoop(sound, toVec(at));
+        if (handle !== null)
+            loops.set(id, { sound, handle });
+    });
+    const offLoopSet = events.on("audio.loopSet", ({ id, rate, gain, at }) => {
+        const entry = loops.get(id);
+        // Unknown id: a live update may race a stop — silently drop it.
+        if (entry === undefined)
+            return;
+        if (rate !== undefined)
+            entry.handle.setRate(rate);
+        if (gain !== undefined)
+            entry.handle.setGain(gain);
+        if (at !== undefined)
+            entry.handle.setPosition({ x: at[0], y: at[1], z: at[2] });
+    });
+    const offLoopStop = events.on("audio.loopStop", ({ id }) => {
+        const entry = loops.get(id);
+        if (entry === undefined)
+            return;
+        entry.handle.stop();
+        loops.delete(id);
+    });
     return () => {
         offPlay();
         offMusic();
         offResume();
+        offLoopStart();
+        offLoopSet();
+        offLoopStop();
+        for (const { handle } of loops.values())
+            handle.stop();
+        loops.clear();
     };
 }

package/dist/audio/loopParams.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Pure clamps for retained-loop live control (#1051). Kept dependency-free so the
+ * playback-rate/gain windows are one testable source of truth the audio engine reads.
+ */
+/** Lowest live playback-rate multiplier (two octaves below authored pitch). */
+export declare const MIN_LOOP_RATE = 0.25;
+/** Highest live playback-rate multiplier (two octaves above authored pitch). */
+export declare const MAX_LOOP_RATE = 4;
+/**
+ * Clamp a loop playback-rate multiplier into the safe pitch window `MIN_LOOP_RATE`–`MAX_LOOP_RATE`
+ * (1 = authored pitch). Non-finite input (NaN/±Infinity) falls back to the authored `1`.
+ * @internal — the audio engine applies this; game code sets rate through `ctx.game.audio.setLoop`.
+ */
+export declare function clampLoopRate(rate: number): number;
+/**
+ * Clamp a loop gain multiplier into `0`–`1`. Non-finite input falls back to `0` (silence) so a
+ * stray NaN never blasts a loop to full volume.
+ * @internal — the audio engine applies this; game code sets gain through `ctx.game.audio.setLoop`.
+ */
+export declare function clampLoopGain(gain: number): number;

package/dist/audio/loopParams.js

@@ -0,0 +1,28 @@
+/**
+ * Pure clamps for retained-loop live control (#1051). Kept dependency-free so the
+ * playback-rate/gain windows are one testable source of truth the audio engine reads.
+ */
+/** Lowest live playback-rate multiplier (two octaves below authored pitch). */
+export const MIN_LOOP_RATE = 0.25;
+/** Highest live playback-rate multiplier (two octaves above authored pitch). */
+export const MAX_LOOP_RATE = 4;
+/**
+ * Clamp a loop playback-rate multiplier into the safe pitch window `MIN_LOOP_RATE`–`MAX_LOOP_RATE`
+ * (1 = authored pitch). Non-finite input (NaN/±Infinity) falls back to the authored `1`.
+ * @internal — the audio engine applies this; game code sets rate through `ctx.game.audio.setLoop`.
+ */
+export function clampLoopRate(rate) {
+    if (!Number.isFinite(rate))
+        return 1;
+    return Math.min(MAX_LOOP_RATE, Math.max(MIN_LOOP_RATE, rate));
+}
+/**
+ * Clamp a loop gain multiplier into `0`–`1`. Non-finite input falls back to `0` (silence) so a
+ * stray NaN never blasts a loop to full volume.
+ * @internal — the audio engine applies this; game code sets gain through `ctx.game.audio.setLoop`.
+ */
+export function clampLoopGain(gain) {
+    if (!Number.isFinite(gain))
+        return 0;
+    return Math.min(1, Math.max(0, gain));
+}

package/dist/camera/GameCameraRig.js

@@ -22,7 +22,12 @@ export function GameCameraRig({ yawRef, pitchRef, config, onDragChange, pointerC
     const followEntityId = directed.followEntityId;
     const rig = (() => {
         if (directed.cinematic !== undefined) {
-            return (_jsx(CinematicRig, { yawRef: yawRef, pitchRef: pitchRef, config: { ...config, cinematic: directed.cinematic }, followEntityId: followEntityId, absoluteFov: true }));
+            // A director-set cinematic auto-clears when its keyframe path completes, so a
+            // one-shot flyover can never strand the camera if a game-side clear timer drifts
+            // (the rig plays in real time; sim-clock timers do not). Static config cinematics
+            // hold their final frame as before.
+            const owner = director !== undefined && director.cinematic() !== null ? director : undefined;
+            return (_jsx(CinematicRig, { yawRef: yawRef, pitchRef: pitchRef, config: { ...config, cinematic: directed.cinematic }, followEntityId: followEntityId, absoluteFov: true, ...(owner === undefined ? {} : { onComplete: () => owner.setCinematic(null) }) }));
         }
         const kind = resolveRigKind(config);
         switch (kind) {

package/dist/camera/GameOrbitCamera.js

@@ -3,6 +3,7 @@ import { OrbitControls } from "@react-three/drei";
 import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useRef } from "react";
 import { MOUSE, PerspectiveCamera, Raycaster, Vector3 } from "three";
+import { isCameraOccluderTransparent } from "./cameraCollision.js";
 import { useGameContext } from "@jgengine/react/provider";
 import { usePlayer } from "@jgengine/react/hooks";
 import { cameraLookPitch, compensatedFov, ORBIT_CAMERA_FRAME_PRIORITY, orbitFollowStep, orbitYawFromCamera, resolveFollowTargetFromPosition, resolveOrbitCameraConfig, seedOrbitFollowState, } from "./orbitCameraMath.js";
@@ -81,6 +82,10 @@ export function GameOrbitCamera({ yawRef, pitchRef, config: configPatch, followE
                 ray.set(collisionOriginRef.current.set(t.x, t.y, t.z), dir);
                 ray.near = config.collision.minTargetDistance;
                 ray.far = dist;
+                // Sprites (VFX, billboards) live in the scene; three's Sprite.raycast
+                // errors every frame unless the raycaster has a camera, even though we
+                // discard sprite hits below. Setting it silences that per-frame log.
+                ray.camera = camera;
                 let blocked = 0;
                 for (const hit of ray.intersectObjects(scene.children, true)) {
                     const obj = hit.object;
@@ -88,7 +93,8 @@ export function GameOrbitCamera({ yawRef, pitchRef, config: configPatch, followE
                         continue;
                     if (obj.isSprite === true)
                         continue;
-                    if (obj.userData.jgCameraTransparent === true)
+                    // Inheritable: decor flags a group jgCameraTransparent and all children pass through.
+                    if (isCameraOccluderTransparent(obj))
                         continue;
                     blocked = hit.distance;
                     break;

package/dist/camera/cameraCollision.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Camera spring-arm occlusion filtering.
+ *
+ * The orbit rig raycasts target→camera each frame and pulls the boom in past
+ * occluders. Author decor mounted through the `WorldOverlay` presentation seam
+ * is dressing, not collision geometry, so it should never yank the camera. A
+ * decor group flags itself camera-transparent once (`jgCameraTransparent`) and
+ * every descendant inherits it — a child can opt back into blocking the camera
+ * with `jgCameraCollide`.
+ */
+/** Minimal structural view of a raycast hit object: its own tags plus a parent link to walk. Keeps this filter free of a three.js import so it stays unit-testable. */
+export interface CameraOccluder {
+    readonly userData?: Record<string, unknown>;
+    readonly parent?: CameraOccluder | null;
+}
+/** userData applied to the group wrapping author `WorldOverlay` decor so the spring-arm ignores it by default. */
+export declare const CAMERA_TRANSPARENT_USERDATA: {
+    readonly jgCameraTransparent: true;
+};
+/**
+ * Should the camera spring-arm ignore this raycast hit? Walks the object up its
+ * `.parent` chain and honors the nearest camera tag: `jgCameraCollide === true`
+ * blocks (opt back in), `jgCameraTransparent === true` passes through. Untagged
+ * geometry blocks as before, so engine-owned ground/entities are unaffected.
+ *
+ * @capability camera-transparent-decor let author decor pass through the orbit spring-arm; a child opts back in with jgCameraCollide
+ */
+export declare function isCameraOccluderTransparent(object: CameraOccluder | null | undefined): boolean;

package/dist/camera/cameraCollision.js

@@ -0,0 +1,34 @@
+/**
+ * Camera spring-arm occlusion filtering.
+ *
+ * The orbit rig raycasts target→camera each frame and pulls the boom in past
+ * occluders. Author decor mounted through the `WorldOverlay` presentation seam
+ * is dressing, not collision geometry, so it should never yank the camera. A
+ * decor group flags itself camera-transparent once (`jgCameraTransparent`) and
+ * every descendant inherits it — a child can opt back into blocking the camera
+ * with `jgCameraCollide`.
+ */
+/** userData applied to the group wrapping author `WorldOverlay` decor so the spring-arm ignores it by default. */
+export const CAMERA_TRANSPARENT_USERDATA = {
+    jgCameraTransparent: true,
+};
+/**
+ * Should the camera spring-arm ignore this raycast hit? Walks the object up its
+ * `.parent` chain and honors the nearest camera tag: `jgCameraCollide === true`
+ * blocks (opt back in), `jgCameraTransparent === true` passes through. Untagged
+ * geometry blocks as before, so engine-owned ground/entities are unaffected.
+ *
+ * @capability camera-transparent-decor let author decor pass through the orbit spring-arm; a child opts back in with jgCameraCollide
+ */
+export function isCameraOccluderTransparent(object) {
+    for (let node = object ?? null; node != null; node = node.parent ?? null) {
+        const data = node.userData;
+        if (data === undefined)
+            continue;
+        if (data.jgCameraCollide === true)
+            return false;
+        if (data.jgCameraTransparent === true)
+            return true;
+    }
+    return false;
+}

package/dist/camera/cameraRigs.d.ts

@@ -26,4 +26,6 @@ export declare function ChaseRig(props: RigProps): null;
  * kill-cam rig. Distinct from every other rig, which drives from mouse/keys.
  */
 export declare function ObserverRig(props: RigProps): null;
-export declare function CinematicRig(props: RigProps): null;
+export declare function CinematicRig(props: RigProps & {
+    onComplete?: () => void;
+}): null;

package/dist/camera/cameraRigs.js

@@ -4,7 +4,7 @@ import { PerspectiveCamera, Quaternion, Vector3 } from "three";
 import { usePlayer } from "@jgengine/react/hooks";
 import { useGameContext } from "@jgengine/react/provider";
 import { ORBIT_CAMERA_FRAME_PRIORITY } from "./orbitCameraMath.js";
-import { bankRollStep, chaseDesiredPosition, chaseLookAt, cinematicSample, clamp, leadFollowPoint, lockOnPose, observerPose, resolveChase, resolveObserver, resolveShoulder, resolveSideScroll, resolveSideScrollPose, resolveTopDown, seatPose, shoulderPose, sideScrollFollowBlend, smoothYaw, speedToFov, springArmStep, topDownPose, } from "./rigMath.js";
+import { bankRollStep, chaseDesiredPosition, chaseLookAt, cinematicSample, clamp, leadFollowPoint, lockOnPose, observerPose, resolveChase, resolveObserver, resolveShoulder, resolveSideScroll, resolveSideScrollPose, resolveTopDown, rtsPanWorldDir, seatPose, shoulderPose, sideScrollFollowBlend, smoothYaw, speedToFov, springArmStep, topDownPose, velocityYawTarget, } from "./rigMath.js";
 import { usePlayerFov } from "./PlayerFov.js";
 import { useCameraShake } from "./shakeChannel.js";
 import { applyCameraBlendStep, captureCameraBlendFrom, createCameraBlendScratch, } from "./cameraBlendMath.js";
@@ -262,13 +262,9 @@ export function RtsRig(props) {
         }
         const center = centerRef.current;
         if (panX !== 0 || panZ !== 0) {
-            const cos = Math.cos(yawRef.current);
-            const sin = Math.sin(yawRef.current);
-            const worldX = panX * cos + panZ * sin;
-            const worldZ = panZ * cos - panX * sin;
-            const len = Math.hypot(worldX, worldZ) || 1;
-            center.x += (worldX / len) * panSpeed * dt;
-            center.z += (worldZ / len) * panSpeed * dt;
+            const dir = rtsPanWorldDir(panX, panZ, yawRef.current);
+            center.x += dir.x * panSpeed * dt;
+            center.z += dir.z * panSpeed * dt;
         }
         else {
             const follow = readFollow(ctx, followId);
@@ -424,6 +420,7 @@ export function ChaseRig(props) {
     const posRef = useRef(null);
     const lastFollowRef = useRef(null);
     const lastYawRef = useRef(null);
+    const anchorYawRef = useRef(null);
     const rollRef = useRef(0);
     const view = config?.view ?? "chase";
     useEffect(beginTransition, [view]);
@@ -454,15 +451,24 @@ export function ChaseRig(props) {
             commit(pose, dt);
             return;
         }
+        let anchorYaw = yaw;
+        if (resolved.velocityYawBlend > 0) {
+            const velocity = dt > 0
+                ? { x: (follow.x - last.x) / dt, y: 0, z: (follow.z - last.z) / dt }
+                : { x: 0, y: 0, z: 0 };
+            const targetYaw = velocityYawTarget(yaw, velocity, resolved);
+            anchorYaw = smoothYaw(anchorYawRef.current ?? targetYaw, targetYaw, resolved.velocityYawResponse, dt);
+            anchorYawRef.current = anchorYaw;
+        }
         const led = leadFollowPoint(follow, last, dt, resolved);
-        const desired = chaseDesiredPosition(led, yaw, resolved);
+        const desired = chaseDesiredPosition(led, anchorYaw, resolved);
         const prev = posRef.current ?? desired;
         const smoothed = springArmStep(prev, desired, resolved.springDamping, dt);
         posRef.current = smoothed;
         if (resolved.shakePerSpeed > 0 && speed > 0) {
             shake.shake(Math.min(resolved.shakePerSpeed * speed * dt, 0.1));
         }
-        const pose = { position: smoothed, lookAt: chaseLookAt(led, yaw, resolved), fov };
+        const pose = { position: smoothed, lookAt: chaseLookAt(led, anchorYaw, resolved), fov };
         commit(pose, dt);
         if (rollRef.current !== 0)
             camera.rotateZ(rollRef.current);
@@ -510,8 +516,12 @@ export function CinematicRig(props) {
     const cinematic = props.config?.cinematic;
     const { camera, commit, beginTransition } = useCameraCommit(props, followId);
     const elapsedRef = useRef(0);
+    const completedRef = useRef(false);
+    const onCompleteRef = useRef(props.onComplete);
+    onCompleteRef.current = props.onComplete;
     useEffect(() => {
         elapsedRef.current = 0;
+        completedRef.current = false;
         beginTransition();
     }, [cinematic]);
     useFrame((_, dt) => {
@@ -520,6 +530,10 @@ export function CinematicRig(props) {
         elapsedRef.current += dt;
         const sample = cinematicSample(cinematic.keyframes, elapsedRef.current, cinematic.loop ?? false, currentFov(camera));
         commit(sample.pose, dt);
+        if (sample.done && !completedRef.current) {
+            completedRef.current = true;
+            onCompleteRef.current?.();
+        }
     }, CAMERA_RIG_FRAME_PRIORITY);
     return null;
 }

package/dist/camera/index.d.ts

@@ -7,3 +7,4 @@ export { PlayerFovProvider, PlayerFovSlider, usePlayerFov, type PlayerFovState,
 export { CameraShakeContext, cameraShake, createCameraShakeChannel, defaultCameraShakeChannel, useCameraShake, type CameraShakeChannel, } from "./shakeChannel.js";
 export { rtsPanKeysConflict } from "./rigMath.js";
 export { GAME_SIM_FRAME_PRIORITY } from "./orbitCameraMath.js";
+export { CAMERA_TRANSPARENT_USERDATA, isCameraOccluderTransparent, type CameraOccluder, } from "./cameraCollision.js";

package/dist/camera/index.js

@@ -7,3 +7,4 @@ export { PlayerFovProvider, PlayerFovSlider, usePlayerFov, } from "./PlayerFov.j
 export { CameraShakeContext, cameraShake, createCameraShakeChannel, defaultCameraShakeChannel, useCameraShake, } from "./shakeChannel.js";
 export { rtsPanKeysConflict } from "./rigMath.js";
 export { GAME_SIM_FRAME_PRIORITY } from "./orbitCameraMath.js";
+export { CAMERA_TRANSPARENT_USERDATA, isCameraOccluderTransparent, } from "./cameraCollision.js";

package/dist/camera/rigMath.d.ts

@@ -37,6 +37,13 @@ export declare function resolveTopDown(config: TopDownCameraConfig | undefined):
   * @internal
   */
 export declare function topDownPose(follow: Vec3, resolved: ResolvedTopDown, fov: number): CameraPose;
+/**
+ * World-space direction for RTS pan input: `panX` slides along screen-right,
+ * `panZ` along the camera's ground-plane forward, for a camera posed by
+ * `topDownPose` at the same yaw. Normalized; zero input returns zero.
+ * @internal
+ */
+export declare function rtsPanWorldDir(panX: number, panZ: number, yaw: number): Vec3;
 /** Exponential spring-arm approach toward a desired point (frame-rate independent).
  * @internal
  */
@@ -121,6 +128,12 @@ export interface ResolvedChase {
     bankPerYawRate: number;
     bankMax: number;
     bankDamping: number;
+    /** Max fraction of the slip angle the anchor yaw follows toward velocity; 0 = drift-lag off (#1051). */
+    velocityYawBlend: number;
+    /** Below this planar speed the drift-lag feature is fully off. */
+    velocityYawMinSpeed: number;
+    /** Exponential smoothing rate toward the blended anchor yaw (1-exp(-response*dt)). */
+    velocityYawResponse: number;
 }
 /** @internal */
 export declare function resolveChase(config: ChaseCameraConfig | undefined): ResolvedChase;
@@ -152,6 +165,20 @@ export declare function chaseDesiredPosition(follow: Vec3, yaw: number, resolved
  * @internal
  */
 export declare function chaseLookAt(follow: Vec3, yaw: number, resolved: ResolvedChase): Vec3;
+/**
+ * Drift-lag (#1051): the yaw the chase anchor should aim before temporal
+ * smoothing. When the target slides, its planar `velocity` diverges from its
+ * `heading`; this rotates the anchor from heading partway toward the velocity
+ * direction so the camera reveals the car's side while travel stays framed. The
+ * traversed fraction is `velocityYawBlend` scaled by how far the slip angle has
+ * opened (0 at straight-line travel, full at a 90° slide), so ordinary driving
+ * is untouched. Returns the raw heading — no swing — when the feature is off,
+ * when planar speed is below `velocityYawMinSpeed`, or when the target is
+ * reversing (velocity opposed to heading forward). Blending is shortest-arc, so
+ * it stays correct across the ±PI wrap seam.
+ * @internal
+ */
+export declare function velocityYawTarget(heading: number, velocity: Vec3, resolved: ResolvedChase): number;
 /** World-space seat pose (cockpit/hood/rear) rigidly attached to the vehicle.
  * @internal
  */