@jgengine/shell 0.10.0 → 0.12.0

package/dist/camera/rigMath.d.ts

@@ -6,12 +6,19 @@ export interface CameraPose {
     lookAt: Vec3;
     fov: number;
 }
+/** @internal */
 export declare function rtsPanKeysConflict(input: ActionCodesMap | undefined): boolean;
+/** @internal */
 export declare function clamp(value: number, min: number, max: number): number;
+/** @internal */
 export declare function lerp(from: number, to: number, blend: number): number;
+/** @internal */
 export declare function smoothstep(t: number): number;
+/** @internal */
 export declare function forwardVector(yaw: number): Vec3;
-/** Screen-right of a yaw: `forward × up` with up = +Y. */
+/** Screen-right of a yaw: `forward × up` with up = +Y.
+ * @internal
+ */
 export declare function rightVector(yaw: number): Vec3;
 export interface ResolvedTopDown {
     height: number;
@@ -20,15 +27,19 @@ export interface ResolvedTopDown {
     offset: Vec3;
     followSmoothing: number;
 }
+/** @internal */
 export declare function resolveTopDown(config: TopDownCameraConfig | undefined): ResolvedTopDown;
 /**
  * Camera pose for a fixed top-down / isometric rig. `pitch` is the elevation of
  * the camera→target ray above the ground (PI/2 = straight down); `yaw` is the
  * fixed azimuth (PI/4 reads isometric). Height sets zoom; horizontal boom is
  * derived so the look angle stays constant as height changes.
- */
+  * @internal
+  */
 export declare function topDownPose(follow: Vec3, resolved: ResolvedTopDown, fov: number): CameraPose;
-/** Exponential spring-arm approach toward a desired point (frame-rate independent). */
+/** Exponential spring-arm approach toward a desired point (frame-rate independent).
+ * @internal
+ */
 export declare function springArmStep(current: Vec3, desired: Vec3, damping: number, dt: number): Vec3;
 export interface ResolvedSideScroll {
     axis: "x" | "z";
@@ -37,26 +48,38 @@ export interface ResolvedSideScroll {
     lookHeight: number;
     followSmoothing: number;
 }
+/** @internal */
 export declare function resolveSideScroll(config: SideScrollCameraConfig | undefined): ResolvedSideScroll;
-/** Frame-rate independent follow blend for the side-scroll rig; `followSmoothing <= 0` hard-locks (blend 1) instead of freezing. */
+/** Frame-rate independent follow blend for the side-scroll rig; `followSmoothing <= 0` hard-locks (blend 1) instead of freezing.
+ * @internal
+ */
 export declare function sideScrollFollowBlend(followSmoothing: number, dt: number): number;
 /**
  * Fixed lateral 2.5D follow pose: the camera sits perpendicular to the travel
  * axis at `distance`, above the entity by `height`, and looks at the entity
  * raised by `lookHeight`. Axis "x" watches from +z; axis "z" watches from +x.
- */
+  * @internal
+  */
 export declare function resolveSideScrollPose(entityPos: Vec3, resolved: ResolvedSideScroll, fov: number): CameraPose;
-/** Speed→FOV curve: FOV climbs from base to max as speed rises to `speedForMax`. */
+/** Speed→FOV curve: FOV climbs from base to max as speed rises to `speedForMax`.
+ * @internal
+ */
 export declare function speedToFov(speed: number, curve: {
     base?: number;
     max?: number;
     speedForMax?: number;
 } | undefined): number;
-/** Yaw that points from `from` toward `to` on the XZ plane (matches shell forward = (sin, cos)). */
+/** Yaw that points from `from` toward `to` on the XZ plane (matches shell forward = (sin, cos)).
+ * @internal
+ */
 export declare function yawTo(from: Vec3, to: Vec3): number;
-/** Shortest signed angular delta from `a` to `b`, wrapped to (-PI, PI]. */
+/** Shortest signed angular delta from `a` to `b`, wrapped to (-PI, PI].
+ * @internal
+ */
 export declare function angleDelta(a: number, b: number): number;
-/** Exponential yaw smoothing that respects wrap-around. */
+/** Exponential yaw smoothing that respects wrap-around.
+ * @internal
+ */
 export declare function smoothYaw(current: number, desired: number, speed: number, dt: number): number;
 export interface ResolvedShoulder {
     shoulderOffset: number;
@@ -64,20 +87,25 @@ export interface ResolvedShoulder {
     distance: number;
     fov: number;
 }
+/** @internal */
 export declare function resolveShoulder(config: ShoulderCameraConfig | undefined, aiming: boolean): ResolvedShoulder;
-/** Blend two shoulder framings by an ADS factor in [0,1]. */
+/** Blend two shoulder framings by an ADS factor in [0,1].
+ * @internal
+ */
 export declare function blendShoulder(hip: ResolvedShoulder, ads: ResolvedShoulder, t: number): ResolvedShoulder;
 /**
  * Over-the-shoulder camera pose. The boom sits behind the follow point along
  * `yaw`, raised by `heightOffset`, and pushed sideways by `shoulderOffset`
  * (sign set by `sideSign`: +1 right, -1 left). `pitch` tilts the look point.
- */
+  * @internal
+  */
 export declare function shoulderPose(follow: Vec3, yaw: number, pitch: number, sideSign: number, shoulder: ResolvedShoulder): CameraPose;
 /**
  * Lock-on pose: camera sits behind the player along the player→target vector so
  * the target stays framed. The look point is biased between player and target
  * by `framingBias`.
- */
+  * @internal
+  */
 export declare function lockOnPose(player: Vec3, target: Vec3, config: LockOnCameraConfig | undefined, fov: number): {
     pose: CameraPose;
     yaw: number;
@@ -93,11 +121,22 @@ 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;
-/** Velocity-lead the follow point (#286.9): aim `leadTime` seconds along the target's frame velocity, clamped to `leadMax`. */
+/** Velocity-lead the follow point (#286.9): aim `leadTime` seconds along the target's frame velocity, clamped to `leadMax`.
+ * @internal
+ */
 export declare function leadFollowPoint(follow: Vec3, previous: Vec3, dt: number, resolved: ResolvedChase): Vec3;
-/** One smoothing step of the chase rig's turn-bank roll (#286.10): roll opposes yaw rate, clamped and exponentially damped. */
+/** One smoothing step of the chase rig's turn-bank roll (#286.10): roll opposes yaw rate, clamped and exponentially damped.
+ * @internal
+ */
 export declare function bankRollStep(currentRoll: number, yaw: number, previousYaw: number, dt: number, resolved: ResolvedChase): number;
 export interface ResolvedObserver {
     distance: number;
@@ -105,14 +144,37 @@ export interface ResolvedObserver {
     lookHeight: number;
     orbitSpeed: number;
 }
+/** @internal */
 export declare function resolveObserver(config: ObserverCameraConfig | undefined): ResolvedObserver;
-/** Detached spectator pose: orbits `subject` at a fixed distance/height, never reading player input. */
+/** Detached spectator pose: orbits `subject` at a fixed distance/height, never reading player input.
+ * @internal
+ */
 export declare function observerPose(subject: Vec3, angle: number, resolved: ResolvedObserver, fov: number): CameraPose;
-/** Desired chase-camera position behind a vehicle facing `yaw` (before spring smoothing). */
+/** Desired chase-camera position behind a vehicle facing `yaw` (before spring smoothing).
+ * @internal
+ */
 export declare function chaseDesiredPosition(follow: Vec3, yaw: number, resolved: ResolvedChase): Vec3;
-/** Look point ahead of / above a chased vehicle. */
+/** Look point ahead of / above a chased vehicle.
+ * @internal
+ */
 export declare function chaseLookAt(follow: Vec3, yaw: number, resolved: ResolvedChase): Vec3;
-/** World-space seat pose (cockpit/hood/rear) rigidly attached to the vehicle. */
+/**
+ * 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
+ */
 export declare function seatPose(follow: Vec3, yaw: number, local: {
     x?: number;
     y?: number;
@@ -122,10 +184,15 @@ export interface TraumaState {
     trauma: number;
     time: number;
 }
+/** @internal */
 export declare function createTrauma(): TraumaState;
-/** Add trauma (0..1) and clamp; larger hits raise the ceiling toward 1. */
+/** Add trauma (0..1) and clamp; larger hits raise the ceiling toward 1.
+ * @internal
+ */
 export declare function addTrauma(state: TraumaState, amount: number): void;
-/** Decay trauma linearly toward 0 and advance the shake clock. */
+/** Decay trauma linearly toward 0 and advance the shake clock.
+ * @internal
+ */
 export declare function stepTrauma(state: TraumaState, decayPerSecond: number, dt: number): void;
 export interface ShakeOffset {
     x: number;
@@ -136,14 +203,35 @@ export interface ShakeOffset {
  * Positional + roll shake for the current trauma. Shake magnitude is
  * `trauma^exponent` so small hits stay subtle; the oscillation is deterministic
  * per-seed pseudo-noise (no per-frame RNG, so identical inputs reproduce).
- */
+  * @internal
+  */
 export declare function shakeOffset(state: TraumaState, config: {
     maxOffset?: number;
     maxRoll?: number;
     exponent?: number;
     frequency?: number;
 } | undefined): ShakeOffset;
-/** Linear cross-fade between two full camera poses (position, lookAt, fov). */
+/** Calibrated trauma decay for `traumaShake`/`impactPresets` (trauma/second). */
+export declare const CALIBRATED_TRAUMA_SHAKE_DECAY_PER_SECOND = 1.4;
+/** Calibrated positional shake amplitude at full trauma (world units) for `traumaShake`. */
+export declare const CALIBRATED_TRAUMA_SHAKE_MAX_OFFSET = 0.55;
+/** Calibrated rotational shake amplitude at full trauma (radians) for `traumaShake`. */
+export declare const CALIBRATED_TRAUMA_SHAKE_MAX_ROLL = 0.1;
+/** Calibrated shake noise frequency (Hz) for `traumaShake`. */
+export declare const CALIBRATED_TRAUMA_SHAKE_FREQUENCY = 32;
+/**
+ * Calibrated trauma² camera shake: offset scales with `trauma` squared using
+ * game-feel defaults (decay 1.4/s, max offset 0.55, max roll 0.1 rad, noise
+ * freq 32×t) — the curve `impactPresets` trauma values are calibrated
+ * against, so an impact "just looks right" without hand-tuning `shakeOffset`.
+ *
+ * @capability camera-shake calibrated trauma² camera kick with zero tuning
+  * @internal
+  */
+export declare function traumaShake(trauma: number, time?: number): ShakeOffset;
+/** Linear cross-fade between two full camera poses (position, lookAt, fov).
+ * @internal
+ */
 export declare function crossfadePose(from: CameraPose, to: CameraPose, t: number): CameraPose;
 export interface DirectorCameraValues {
     /** `undefined` = no runtime override (fall back to static); `null` = explicitly follow nothing. */
@@ -164,7 +252,8 @@ export interface ResolvedDirectedCamera {
  * (#196.2). `director` omitted, or its fields `undefined`/`null`, is a pure
  * passthrough to `staticConfig` so mounting a director with no active override
  * changes nothing.
- */
+  * @internal
+  */
 export declare function resolveDirectedCamera(director: DirectorCameraValues | undefined, staticConfig: StaticCameraValues): ResolvedDirectedCamera;
 export interface CinematicSample {
     pose: CameraPose;
@@ -175,5 +264,6 @@ export interface CinematicSample {
  * travel time from the previous keyframe into it; segment easing is per the
  * destination keyframe. Reports `done` once past the final keyframe (unless
  * looping, which wraps `elapsed` into the total path duration).
- */
+  * @internal
+  */
 export declare function cinematicSample(keyframes: readonly CameraKeyframe[], elapsed: number, loop: boolean, fallbackFov: number): CinematicSample;

package/dist/camera/rigMath.js

@@ -6,28 +6,36 @@ function actionCodeList(codes) {
     const modes = codes;
     return [...(modes.hold ?? []), ...(modes.toggle ?? [])];
 }
+/** @internal */
 export function rtsPanKeysConflict(input) {
     if (input === undefined)
         return false;
     return Object.values(input).some((codes) => actionCodeList(codes).some((code) => RTS_WASD_CODES.includes(code)));
 }
+/** @internal */
 export function clamp(value, min, max) {
     return value < min ? min : value > max ? max : value;
 }
+/** @internal */
 export function lerp(from, to, blend) {
     return from + (to - from) * blend;
 }
+/** @internal */
 export function smoothstep(t) {
     const clamped = clamp(t, 0, 1);
     return clamped * clamped * (3 - 2 * clamped);
 }
+/** @internal */
 export function forwardVector(yaw) {
     return { x: Math.sin(yaw), y: 0, z: Math.cos(yaw) };
 }
-/** Screen-right of a yaw: `forward × up` with up = +Y. */
+/** Screen-right of a yaw: `forward × up` with up = +Y.
+ * @internal
+ */
 export function rightVector(yaw) {
     return { x: -Math.cos(yaw), y: 0, z: Math.sin(yaw) };
 }
+/** @internal */
 export function resolveTopDown(config) {
     return {
         height: config?.height ?? 18,
@@ -46,7 +54,8 @@ export function resolveTopDown(config) {
  * the camera→target ray above the ground (PI/2 = straight down); `yaw` is the
  * fixed azimuth (PI/4 reads isometric). Height sets zoom; horizontal boom is
  * derived so the look angle stays constant as height changes.
- */
+  * @internal
+  */
 export function topDownPose(follow, resolved, fov) {
     const lookAt = {
         x: follow.x + resolved.offset.x,
@@ -65,10 +74,13 @@ export function topDownPose(follow, resolved, fov) {
         fov,
     };
 }
-/** Exponential spring-arm approach toward a desired point (frame-rate independent). */
+/** Exponential spring-arm approach toward a desired point (frame-rate independent).
+ * @internal
+ */
 export function springArmStep(current, desired, damping, dt) {
     return lerpVec3(current, desired, smoothBlend(dt, damping));
 }
+/** @internal */
 export function resolveSideScroll(config) {
     return {
         axis: config?.axis ?? "x",
@@ -78,7 +90,9 @@ export function resolveSideScroll(config) {
         followSmoothing: config?.followSmoothing ?? 8,
     };
 }
-/** Frame-rate independent follow blend for the side-scroll rig; `followSmoothing <= 0` hard-locks (blend 1) instead of freezing. */
+/** Frame-rate independent follow blend for the side-scroll rig; `followSmoothing <= 0` hard-locks (blend 1) instead of freezing.
+ * @internal
+ */
 export function sideScrollFollowBlend(followSmoothing, dt) {
     return followSmoothing <= 0 ? 1 : smoothBlend(dt, followSmoothing);
 }
@@ -86,7 +100,8 @@ export function sideScrollFollowBlend(followSmoothing, dt) {
  * Fixed lateral 2.5D follow pose: the camera sits perpendicular to the travel
  * axis at `distance`, above the entity by `height`, and looks at the entity
  * raised by `lookHeight`. Axis "x" watches from +z; axis "z" watches from +x.
- */
+  * @internal
+  */
 export function resolveSideScrollPose(entityPos, resolved, fov) {
     const perpendicular = resolved.axis === "x" ? { x: 0, y: 0, z: 1 } : { x: 1, y: 0, z: 0 };
     return {
@@ -99,7 +114,9 @@ export function resolveSideScrollPose(entityPos, resolved, fov) {
         fov,
     };
 }
-/** Speed→FOV curve: FOV climbs from base to max as speed rises to `speedForMax`. */
+/** Speed→FOV curve: FOV climbs from base to max as speed rises to `speedForMax`.
+ * @internal
+ */
 export function speedToFov(speed, curve) {
     const base = curve?.base ?? 55;
     const max = curve?.max ?? 78;
@@ -108,11 +125,15 @@ export function speedToFov(speed, curve) {
         return base;
     return lerp(base, max, clamp(speed / speedForMax, 0, 1));
 }
-/** Yaw that points from `from` toward `to` on the XZ plane (matches shell forward = (sin, cos)). */
+/** Yaw that points from `from` toward `to` on the XZ plane (matches shell forward = (sin, cos)).
+ * @internal
+ */
 export function yawTo(from, to) {
     return Math.atan2(to.x - from.x, to.z - from.z);
 }
-/** Shortest signed angular delta from `a` to `b`, wrapped to (-PI, PI]. */
+/** Shortest signed angular delta from `a` to `b`, wrapped to (-PI, PI].
+ * @internal
+ */
 export function angleDelta(a, b) {
     let delta = (b - a) % (Math.PI * 2);
     if (delta > Math.PI)
@@ -121,10 +142,13 @@ export function angleDelta(a, b) {
         delta += Math.PI * 2;
     return delta;
 }
-/** Exponential yaw smoothing that respects wrap-around. */
+/** Exponential yaw smoothing that respects wrap-around.
+ * @internal
+ */
 export function smoothYaw(current, desired, speed, dt) {
     return current + angleDelta(current, desired) * smoothBlend(dt, speed);
 }
+/** @internal */
 export function resolveShoulder(config, aiming) {
     const hip = {
         shoulderOffset: config?.shoulderOffset ?? 0.6,
@@ -142,7 +166,9 @@ export function resolveShoulder(config, aiming) {
         fov: ads?.fov ?? hip.fov * 0.75,
     };
 }
-/** Blend two shoulder framings by an ADS factor in [0,1]. */
+/** Blend two shoulder framings by an ADS factor in [0,1].
+ * @internal
+ */
 export function blendShoulder(hip, ads, t) {
     return {
         shoulderOffset: lerp(hip.shoulderOffset, ads.shoulderOffset, t),
@@ -155,7 +181,8 @@ export function blendShoulder(hip, ads, t) {
  * Over-the-shoulder camera pose. The boom sits behind the follow point along
  * `yaw`, raised by `heightOffset`, and pushed sideways by `shoulderOffset`
  * (sign set by `sideSign`: +1 right, -1 left). `pitch` tilts the look point.
- */
+  * @internal
+  */
 export function shoulderPose(follow, yaw, pitch, sideSign, shoulder) {
     const forward = forwardVector(yaw);
     const right = rightVector(yaw);
@@ -181,7 +208,8 @@ export function shoulderPose(follow, yaw, pitch, sideSign, shoulder) {
  * Lock-on pose: camera sits behind the player along the player→target vector so
  * the target stays framed. The look point is biased between player and target
  * by `framingBias`.
- */
+  * @internal
+  */
 export function lockOnPose(player, target, config, fov) {
     const distance = config?.distance ?? 5;
     const height = config?.height ?? 2.4;
@@ -201,6 +229,7 @@ export function lockOnPose(player, target, config, fov) {
     };
     return { pose: { position, lookAt: focus, fov }, yaw };
 }
+/** @internal */
 export function resolveChase(config) {
     return {
         distance: config?.distance ?? 6,
@@ -213,9 +242,14 @@ export function resolveChase(config) {
         bankPerYawRate: config?.bank?.perYawRate ?? 0,
         bankMax: config?.bank?.max ?? 0.35,
         bankDamping: config?.bank?.damping ?? 8,
+        velocityYawBlend: config?.velocityYaw === undefined ? 0 : config.velocityYaw.blend ?? 0.65,
+        velocityYawMinSpeed: config?.velocityYaw?.minSpeed ?? 4,
+        velocityYawResponse: config?.velocityYaw?.response ?? 6,
     };
 }
-/** Velocity-lead the follow point (#286.9): aim `leadTime` seconds along the target's frame velocity, clamped to `leadMax`. */
+/** Velocity-lead the follow point (#286.9): aim `leadTime` seconds along the target's frame velocity, clamped to `leadMax`.
+ * @internal
+ */
 export function leadFollowPoint(follow, previous, dt, resolved) {
     if (resolved.leadTime <= 0 || dt <= 0)
         return follow;
@@ -236,7 +270,9 @@ function wrapAngle(angle) {
         wrapped += Math.PI * 2;
     return wrapped;
 }
-/** One smoothing step of the chase rig's turn-bank roll (#286.10): roll opposes yaw rate, clamped and exponentially damped. */
+/** One smoothing step of the chase rig's turn-bank roll (#286.10): roll opposes yaw rate, clamped and exponentially damped.
+ * @internal
+ */
 export function bankRollStep(currentRoll, yaw, previousYaw, dt, resolved) {
     if (resolved.bankPerYawRate <= 0)
         return 0;
@@ -244,6 +280,7 @@ export function bankRollStep(currentRoll, yaw, previousYaw, dt, resolved) {
     const target = clamp(-yawRate * resolved.bankPerYawRate, -resolved.bankMax, resolved.bankMax);
     return currentRoll + (target - currentRoll) * Math.min(1, resolved.bankDamping * dt);
 }
+/** @internal */
 export function resolveObserver(config) {
     return {
         distance: config?.distance ?? 8,
@@ -252,7 +289,9 @@ export function resolveObserver(config) {
         orbitSpeed: config?.orbitSpeed ?? 0.2,
     };
 }
-/** Detached spectator pose: orbits `subject` at a fixed distance/height, never reading player input. */
+/** Detached spectator pose: orbits `subject` at a fixed distance/height, never reading player input.
+ * @internal
+ */
 export function observerPose(subject, angle, resolved, fov) {
     const position = {
         x: subject.x + Math.sin(angle) * resolved.distance,
@@ -265,7 +304,9 @@ export function observerPose(subject, angle, resolved, fov) {
         fov,
     };
 }
-/** Desired chase-camera position behind a vehicle facing `yaw` (before spring smoothing). */
+/** Desired chase-camera position behind a vehicle facing `yaw` (before spring smoothing).
+ * @internal
+ */
 export function chaseDesiredPosition(follow, yaw, resolved) {
     const back = forwardVector(yaw);
     return {
@@ -274,7 +315,9 @@ export function chaseDesiredPosition(follow, yaw, resolved) {
         z: follow.z - back.z * resolved.distance,
     };
 }
-/** Look point ahead of / above a chased vehicle. */
+/** Look point ahead of / above a chased vehicle.
+ * @internal
+ */
 export function chaseLookAt(follow, yaw, resolved) {
     const forward = forwardVector(yaw);
     return {
@@ -283,7 +326,35 @@ export function chaseLookAt(follow, yaw, resolved) {
         z: follow.z + forward.z * 2,
     };
 }
-/** World-space seat pose (cockpit/hood/rear) rigidly attached to the vehicle. */
+/**
+ * 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 function velocityYawTarget(heading, velocity, resolved) {
+    if (resolved.velocityYawBlend <= 0)
+        return heading;
+    const speed = Math.hypot(velocity.x, velocity.z);
+    if (speed < resolved.velocityYawMinSpeed)
+        return heading;
+    const forward = forwardVector(heading);
+    if (forward.x * velocity.x + forward.z * velocity.z < 0)
+        return heading;
+    const slip = angleDelta(heading, Math.atan2(velocity.x, velocity.z));
+    const slipFraction = clamp(Math.abs(slip) / (Math.PI / 2), 0, 1);
+    return heading + slip * resolved.velocityYawBlend * slipFraction;
+}
+/** World-space seat pose (cockpit/hood/rear) rigidly attached to the vehicle.
+ * @internal
+ */
 export function seatPose(follow, yaw, local, fov) {
     const forward = forwardVector(yaw);
     const right = rightVector(yaw);
@@ -301,14 +372,19 @@ export function seatPose(follow, yaw, local, fov) {
         fov,
     };
 }
+/** @internal */
 export function createTrauma() {
     return { trauma: 0, time: 0 };
 }
-/** Add trauma (0..1) and clamp; larger hits raise the ceiling toward 1. */
+/** Add trauma (0..1) and clamp; larger hits raise the ceiling toward 1.
+ * @internal
+ */
 export function addTrauma(state, amount) {
     state.trauma = clamp(state.trauma + amount, 0, 1);
 }
-/** Decay trauma linearly toward 0 and advance the shake clock. */
+/** Decay trauma linearly toward 0 and advance the shake clock.
+ * @internal
+ */
 export function stepTrauma(state, decayPerSecond, dt) {
     state.time += dt;
     state.trauma = clamp(state.trauma - decayPerSecond * dt, 0, 1);
@@ -321,7 +397,8 @@ function hashNoise(seed, time, frequency) {
  * Positional + roll shake for the current trauma. Shake magnitude is
  * `trauma^exponent` so small hits stay subtle; the oscillation is deterministic
  * per-seed pseudo-noise (no per-frame RNG, so identical inputs reproduce).
- */
+  * @internal
+  */
 export function shakeOffset(state, config) {
     const maxOffset = config?.maxOffset ?? 0.5;
     const maxRoll = config?.maxRoll ?? 0.06;
@@ -336,7 +413,33 @@ export function shakeOffset(state, config) {
         roll: maxRoll * shake * hashNoise(3, state.time, frequency),
     };
 }
-/** Linear cross-fade between two full camera poses (position, lookAt, fov). */
+/** Calibrated trauma decay for `traumaShake`/`impactPresets` (trauma/second). */
+export const CALIBRATED_TRAUMA_SHAKE_DECAY_PER_SECOND = 1.4;
+/** Calibrated positional shake amplitude at full trauma (world units) for `traumaShake`. */
+export const CALIBRATED_TRAUMA_SHAKE_MAX_OFFSET = 0.55;
+/** Calibrated rotational shake amplitude at full trauma (radians) for `traumaShake`. */
+export const CALIBRATED_TRAUMA_SHAKE_MAX_ROLL = 0.1;
+/** Calibrated shake noise frequency (Hz) for `traumaShake`. */
+export const CALIBRATED_TRAUMA_SHAKE_FREQUENCY = 32;
+/**
+ * Calibrated trauma² camera shake: offset scales with `trauma` squared using
+ * game-feel defaults (decay 1.4/s, max offset 0.55, max roll 0.1 rad, noise
+ * freq 32×t) — the curve `impactPresets` trauma values are calibrated
+ * against, so an impact "just looks right" without hand-tuning `shakeOffset`.
+ *
+ * @capability camera-shake calibrated trauma² camera kick with zero tuning
+  * @internal
+  */
+export function traumaShake(trauma, time = 0) {
+    return shakeOffset({ trauma: clamp(trauma, 0, 1), time }, {
+        maxOffset: CALIBRATED_TRAUMA_SHAKE_MAX_OFFSET,
+        maxRoll: CALIBRATED_TRAUMA_SHAKE_MAX_ROLL,
+        frequency: CALIBRATED_TRAUMA_SHAKE_FREQUENCY,
+    });
+}
+/** Linear cross-fade between two full camera poses (position, lookAt, fov).
+ * @internal
+ */
 export function crossfadePose(from, to, t) {
     const blend = clamp(t, 0, 1);
     return {
@@ -350,7 +453,8 @@ export function crossfadePose(from, to, t) {
  * (#196.2). `director` omitted, or its fields `undefined`/`null`, is a pure
  * passthrough to `staticConfig` so mounting a director with no active override
  * changes nothing.
- */
+  * @internal
+  */
 export function resolveDirectedCamera(director, staticConfig) {
     const directedFollow = director?.followEntityId;
     const followEntityId = directedFollow === undefined ? staticConfig.followEntityId : directedFollow;
@@ -363,7 +467,8 @@ export function resolveDirectedCamera(director, staticConfig) {
  * travel time from the previous keyframe into it; segment easing is per the
  * destination keyframe. Reports `done` once past the final keyframe (unless
  * looping, which wraps `elapsed` into the total path duration).
- */
+  * @internal
+  */
 export function cinematicSample(keyframes, elapsed, loop, fallbackFov) {
     if (keyframes.length === 0) {
         const zero = { x: 0, y: 0, z: 0 };

package/dist/camera/rigResolve.d.ts

@@ -6,10 +6,12 @@ import type { CameraRigKind, GameCameraConfig } from "@jgengine/core/game/playab
  * of a rig's own config block selects that rig, checked in the fixed order below
  * (#207.8) so a config carrying more than one block resolves deterministically
  * instead of depending on object key order. Set `rig` explicitly to break a tie.
- */
+  * @internal
+  */
 export declare function resolveRigKind(config: GameCameraConfig | undefined): CameraRigKind;
 /**
  * The turntable rig is a flat facade over the observer's point-orbit mode: map
  * its `target`/`distance`/… onto an observer block so ObserverRig runs unchanged.
- */
+  * @internal
+  */
 export declare function turntableAsObserver(config: GameCameraConfig | undefined): GameCameraConfig;

package/dist/camera/rigResolve.js

@@ -5,7 +5,8 @@
  * of a rig's own config block selects that rig, checked in the fixed order below
  * (#207.8) so a config carrying more than one block resolves deterministically
  * instead of depending on object key order. Set `rig` explicitly to break a tie.
- */
+  * @internal
+  */
 export function resolveRigKind(config) {
     if (config?.rig !== undefined)
         return config.rig;
@@ -34,7 +35,8 @@ export function resolveRigKind(config) {
 /**
  * The turntable rig is a flat facade over the observer's point-orbit mode: map
  * its `target`/`distance`/… onto an observer block so ObserverRig runs unchanged.
- */
+  * @internal
+  */
 export function turntableAsObserver(config) {
     const t = config?.turntable;
     if (t === undefined)

package/dist/camera/shakeChannel.d.ts

@@ -8,8 +8,12 @@ export { createCameraShakeChannel } from "./shakeChannelMath.js";
  * default channel directly.
  */
 export declare const defaultCameraShakeChannel: CameraShakeChannel;
-/** Feed the default camera-shake channel from anywhere (see G7 hitstop cross-cut). */
+/** Feed the default camera-shake channel from anywhere (see G7 hitstop cross-cut).
+ * @internal
+ */
 export declare function cameraShake(amplitude: number, decayPerSecond?: number): void;
 export declare const CameraShakeContext: import("react").Context<CameraShakeChannel>;
-/** The active rig's shake channel — call `.shake(...)` to add trauma from React UI. */
+/** The active rig's shake channel — call `.shake(...)` to add trauma from React UI.
+ * @internal
+ */
 export declare function useCameraShake(): CameraShakeChannel;

package/dist/camera/shakeChannel.js

@@ -8,12 +8,16 @@ export { createCameraShakeChannel } from "./shakeChannelMath.js";
  * default channel directly.
  */
 export const defaultCameraShakeChannel = createCameraShakeChannel();
-/** Feed the default camera-shake channel from anywhere (see G7 hitstop cross-cut). */
+/** Feed the default camera-shake channel from anywhere (see G7 hitstop cross-cut).
+ * @internal
+ */
 export function cameraShake(amplitude, decayPerSecond) {
     defaultCameraShakeChannel.shake(amplitude, decayPerSecond);
 }
 export const CameraShakeContext = createContext(defaultCameraShakeChannel);
-/** The active rig's shake channel — call `.shake(...)` to add trauma from React UI. */
+/** The active rig's shake channel — call `.shake(...)` to add trauma from React UI.
+ * @internal
+ */
 export function useCameraShake() {
     return useContext(CameraShakeContext);
 }