@jgengine/core 0.8.0 → 0.9.0

package/dist/input/axisInput.js

@@ -1,3 +1,4 @@
+import { pointerAxisValue } from "./pointerAxis.js";
 export const NEUTRAL_AXIS = { throttle: 0, brake: 0, steer: 0, handbrake: 0 };
 export const AXIS_RANGE = {
     throttle: { min: 0, max: 1 },
@@ -25,8 +26,9 @@ function digitalTarget(binding, isDown) {
 /**
  * Analog control channel — distinct from the digital action bindings. Throttle/brake/steer/handbrake
  * are continuous values ramped from held keys (a keyboard feels like a pedal) or driven directly from
- * a gamepad axis via `setAnalog`. `sample(dt, isDown)` folds the current held-key state into the
- * smoothed value; a `setAnalog` override replaces the digital target for that axis until cleared.
+ * a gamepad axis via `setAnalog`. `sample(dt, isDown, pointer?)` folds the current held-key state into
+ * the smoothed value; a binding's `pointer` source takes over from its keys while a pointer is active,
+ * and a `setAnalog` override replaces both for that axis until cleared.
  */
 export class AxisChannel {
     bindings;
@@ -52,11 +54,15 @@ export class AxisChannel {
     get value() {
         return this.current;
     }
-    sample(dt, isDown) {
+    sample(dt, isDown, pointer) {
         for (const axis of Object.keys(this.bindings)) {
             const range = AXIS_RANGE[axis];
             const override = this.overrides[axis];
-            const target = override !== undefined ? override : clampAxis(digitalTarget(this.bindings[axis], isDown), range);
+            const binding = this.bindings[axis];
+            const fromPointer = binding.pointer === undefined ? null : pointerAxisValue(binding.pointer, pointer);
+            const target = override !== undefined
+                ? override
+                : clampAxis(fromPointer ?? digitalTarget(binding, isDown), range);
             this.current[axis] = clampAxis(rampToward(this.current[axis], target, this.smoothing, dt), range);
         }
         return this.current;
@@ -68,3 +74,37 @@ export const DRIVE_AXIS_BINDINGS = {
     steer: { positive: ["KeyD", "ArrowRight"], negative: ["KeyA", "ArrowLeft"] },
     handbrake: { positive: ["Space"] },
 };
+const BIPOLAR_RANGE = { min: -1, max: 1 };
+export function createAxisChannel(config) {
+    const axes = Object.keys(config.bindings);
+    const smoothing = config.smoothing ?? 6;
+    const current = Object.fromEntries(axes.map((axis) => [axis, 0]));
+    const overrides = {};
+    function rangeOf(axis) {
+        return config.ranges?.[axis] ?? BIPOLAR_RANGE;
+    }
+    return {
+        value: current,
+        setAnalog(axis, value) {
+            overrides[axis] = clampAxis(value, rangeOf(axis));
+        },
+        clearAnalog(axis) {
+            delete overrides[axis];
+        },
+        reset() {
+            for (const axis of axes)
+                current[axis] = 0;
+        },
+        sample(dt, isDown, pointer) {
+            for (const axis of axes) {
+                const range = rangeOf(axis);
+                const override = overrides[axis];
+                const binding = config.bindings[axis];
+                const fromPointer = binding.pointer === undefined ? null : pointerAxisValue(binding.pointer, pointer);
+                const target = override !== undefined ? override : clampAxis(fromPointer ?? digitalTarget(binding, isDown), range);
+                current[axis] = clampAxis(rampToward(current[axis], target, smoothing, dt), range);
+            }
+            return current;
+        },
+    };
+}

package/dist/input/bindingOverrides.d.ts

@@ -0,0 +1,25 @@
+import type { ActionCodes, ActionCodesMap } from "./actionBindings.js";
+/**
+ * Player-rebound keys, keyed by action name. Values mirror an `ActionCodes`
+ * entry so hold/toggle/repeat semantics survive a rebind — the settings menu
+ * only swaps which physical codes drive the action.
+ */
+export type BindingOverrides = Record<string, ActionCodes>;
+export declare const BINDING_OVERRIDES_STORAGE_PREFIX = "jgengine:keybinds:";
+interface WebStorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+export declare function bindingOverridesStorageKey(gameId: string): string;
+export declare function loadBindingOverrides(gameId: string, storage?: Pick<WebStorageLike, "getItem"> | null | undefined): BindingOverrides;
+export declare function saveBindingOverride(gameId: string, action: string, codes: ActionCodes, storage?: Pick<WebStorageLike, "getItem" | "setItem" | "removeItem"> | null | undefined): BindingOverrides;
+export declare function clearBindingOverride(gameId: string, action: string, storage?: Pick<WebStorageLike, "getItem" | "setItem" | "removeItem"> | null | undefined): BindingOverrides;
+export declare function clearAllBindingOverrides(gameId: string, storage?: Pick<WebStorageLike, "removeItem"> | null | undefined): void;
+/**
+ * Merge player rebinds over a game's authored `input` map. Only actions the
+ * game already declares can be overridden; unknown override keys are ignored so
+ * a stale localStorage entry can't inject phantom actions.
+ */
+export declare function applyBindingOverrides<TAction extends string, TCode extends string>(input: ActionCodesMap<TAction, TCode>, overrides: BindingOverrides): ActionCodesMap<TAction, TCode>;
+export {};

package/dist/input/bindingOverrides.js

@@ -0,0 +1,95 @@
+export const BINDING_OVERRIDES_STORAGE_PREFIX = "jgengine:keybinds:";
+export function bindingOverridesStorageKey(gameId) {
+    return `${BINDING_OVERRIDES_STORAGE_PREFIX}${gameId}`;
+}
+function defaultStorage() {
+    try {
+        if (typeof globalThis !== "undefined" && "localStorage" in globalThis) {
+            return globalThis.localStorage ?? null;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+function isActionCodes(value) {
+    if (Array.isArray(value))
+        return value.every((code) => typeof code === "string");
+    if (value === null || typeof value !== "object")
+        return false;
+    const modes = value;
+    const okList = (list) => list === undefined || (Array.isArray(list) && list.every((code) => typeof code === "string"));
+    return okList(modes.hold) && okList(modes.toggle);
+}
+export function loadBindingOverrides(gameId, storage = defaultStorage()) {
+    if (storage == null)
+        return {};
+    try {
+        const raw = storage.getItem(bindingOverridesStorageKey(gameId));
+        if (raw === null)
+            return {};
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== "object")
+            return {};
+        const result = {};
+        for (const [action, codes] of Object.entries(parsed)) {
+            if (isActionCodes(codes))
+                result[action] = codes;
+        }
+        return result;
+    }
+    catch {
+        return {};
+    }
+}
+function persist(gameId, overrides, storage) {
+    if (storage == null)
+        return;
+    try {
+        if (Object.keys(overrides).length === 0)
+            storage.removeItem(bindingOverridesStorageKey(gameId));
+        else
+            storage.setItem(bindingOverridesStorageKey(gameId), JSON.stringify(overrides));
+    }
+    catch {
+        /* ignore quota / private-mode failures */
+    }
+}
+export function saveBindingOverride(gameId, action, codes, storage = defaultStorage()) {
+    const overrides = { ...loadBindingOverrides(gameId, storage ?? undefined), [action]: codes };
+    persist(gameId, overrides, storage);
+    return overrides;
+}
+export function clearBindingOverride(gameId, action, storage = defaultStorage()) {
+    const overrides = { ...loadBindingOverrides(gameId, storage ?? undefined) };
+    delete overrides[action];
+    persist(gameId, overrides, storage);
+    return overrides;
+}
+export function clearAllBindingOverrides(gameId, storage = defaultStorage()) {
+    if (storage == null)
+        return;
+    try {
+        storage.removeItem(bindingOverridesStorageKey(gameId));
+    }
+    catch {
+        /* ignore */
+    }
+}
+/**
+ * Merge player rebinds over a game's authored `input` map. Only actions the
+ * game already declares can be overridden; unknown override keys are ignored so
+ * a stale localStorage entry can't inject phantom actions.
+ */
+export function applyBindingOverrides(input, overrides) {
+    if (Object.keys(overrides).length === 0)
+        return input;
+    const result = { ...input };
+    for (const action of Object.keys(input)) {
+        const override = overrides[action];
+        if (override !== undefined)
+            result[action] = override;
+    }
+    return result;
+}

package/dist/input/pointerAxis.d.ts

@@ -0,0 +1,30 @@
+export interface PointerAxisState {
+    /** Horizontal pointer position over the play surface in `[-1, 1]`: `-1` at the left edge, `+1` at the right. */
+    x: number;
+    /** Vertical pointer position over the play surface in `[-1, 1]`, screen convention: `-1` at the top edge, `+1` at the bottom — negate for aim-up. */
+    y: number;
+    /** `false` after the pointer leaves the surface; the last position is retained. */
+    active: boolean;
+}
+/** Maps one pointer axis onto an analog axis target — the pointer-backed counterpart of an `AxisBinding`'s key lists. */
+export interface PointerAxisBinding {
+    source: "x" | "y";
+    invert?: boolean;
+    /** Fraction of the half-range around center treated as zero; the remainder rescales to the full `[-1, 1]`. */
+    deadzone?: number;
+    /** Response-curve exponent on the magnitude: `1` linear (default), `>1` finer control near center. */
+    curve?: number;
+}
+export interface PointerSurfaceRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/** Normalize client coordinates against a surface rect into a `PointerAxisState`, clamped to `[-1, 1]` per axis. */
+export declare function normalizePointerToAxis(clientX: number, clientY: number, rect: PointerSurfaceRect): PointerAxisState;
+/**
+ * Resolve a pointer binding against the current pointer state: `null` when no pointer is active
+ * (callers fall back to their digital target), otherwise the deadzone/curve-shaped value in `[-1, 1]`.
+ */
+export declare function pointerAxisValue(binding: PointerAxisBinding, state: PointerAxisState | null | undefined): number | null;

package/dist/input/pointerAxis.js

@@ -0,0 +1,31 @@
+/** Normalize client coordinates against a surface rect into a `PointerAxisState`, clamped to `[-1, 1]` per axis. */
+export function normalizePointerToAxis(clientX, clientY, rect) {
+    const width = rect.width > 0 ? rect.width : 1;
+    const height = rect.height > 0 ? rect.height : 1;
+    return {
+        x: clampUnit(((clientX - rect.left) / width) * 2 - 1),
+        y: clampUnit(((clientY - rect.top) / height) * 2 - 1),
+        active: true,
+    };
+}
+/**
+ * Resolve a pointer binding against the current pointer state: `null` when no pointer is active
+ * (callers fall back to their digital target), otherwise the deadzone/curve-shaped value in `[-1, 1]`.
+ */
+export function pointerAxisValue(binding, state) {
+    if (state === null || state === undefined || !state.active)
+        return null;
+    let value = binding.source === "x" ? state.x : state.y;
+    if (binding.invert === true)
+        value = -value;
+    const deadzone = binding.deadzone ?? 0;
+    const magnitude = Math.abs(value);
+    if (magnitude <= deadzone)
+        return 0;
+    const scaled = (magnitude - deadzone) / (1 - deadzone);
+    const curved = Math.pow(Math.min(scaled, 1), binding.curve ?? 1);
+    return Math.sign(value) * curved;
+}
+function clampUnit(value) {
+    return value < -1 ? -1 : value > 1 ? 1 : value;
+}

package/dist/input/touchScheme.d.ts

@@ -36,6 +36,8 @@ export interface TouchButtonSpec {
     label?: string;
     /** Glyph name from the capture layer's icon catalog (`@jgengine/react/gameIcons` `GameIconName`); unset derives one from the action name, `false` forces the text label. */
     icon?: string | false;
+    /** Overrides the derived classification: `primary` renders as a large thumb button, `utility` as a small chip away from the thumb zones. */
+    kind?: TouchButtonKind;
 }
 export interface TouchControlsConfig {
     /** `false` removes the virtual joystick even when movement actions are bound. */
@@ -57,11 +59,14 @@ export interface TouchJoystick {
     left: string | null;
     right: string | null;
 }
+export type TouchButtonKind = "primary" | "utility";
 export interface TouchButton {
     action: string;
     label: string;
     /** Glyph hint for the capture layer: a name to render, `false` to force text, null to derive from the action name. */
     icon: string | false | null;
+    /** `primary` = frequent gameplay verb, rendered as a large thumb button; `utility` = meta action (start, restart, pause, toggles), rendered as a small chip. */
+    kind: TouchButtonKind;
 }
 export interface TouchScheme {
     joystick: TouchJoystick | null;
@@ -70,6 +75,7 @@ export interface TouchScheme {
     look: boolean;
     lookSensitivity: number;
 }
+export declare function touchButtonKind(action: string): TouchButtonKind;
 export declare function touchActionLabel(action: string): string;
 export interface DeriveTouchSchemeOptions {
     reserved: ReadonlySet<string>;

package/dist/input/touchScheme.js

@@ -33,12 +33,45 @@ export function withTouchCodes(map) {
 }
 const DEFAULT_LOOK_SENSITIVITY = 0.005;
 const JOYSTICK_AXES = {
-    up: ["moveForward"],
-    down: ["moveBack"],
-    left: ["moveLeft", "turnLeft"],
-    right: ["moveRight", "turnRight"],
+    up: ["moveForward", "moveUp", "forward", "accelerate", "throttleUp", "pitchUp", "climb"],
+    down: ["moveBack", "moveBackward", "moveDown", "backward", "reverse", "brake", "throttleDown", "pitchDown", "dive"],
+    left: ["moveLeft", "turnLeft", "steerLeft", "yawLeft", "strafeLeft", "bankLeft", "rollLeft"],
+    right: ["moveRight", "turnRight", "steerRight", "yawRight", "strafeRight", "bankRight", "rollRight"],
 };
 const BUTTONABLE_RESERVED = new Set(["jump", "sprint", "interact", "useAbility"]);
+const UTILITY_ACTIONS = new Set([
+    "start",
+    "restart",
+    "reset",
+    "retry",
+    "pause",
+    "resume",
+    "menu",
+    "quit",
+    "exit",
+    "mute",
+    "unmute",
+    "help",
+    "settings",
+    "options",
+    "map",
+    "inventory",
+    "scoreboard",
+    "leaderboard",
+]);
+const UTILITY_PREFIXES = ["toggle", "cycle", "switch", "open", "close", "show", "hide", "zoom"];
+export function touchButtonKind(action) {
+    if (UTILITY_ACTIONS.has(action))
+        return "utility";
+    for (const prefix of UTILITY_PREFIXES) {
+        if (!action.startsWith(prefix))
+            continue;
+        const next = action.charAt(prefix.length);
+        if (next !== "" && next === next.toUpperCase())
+            return "utility";
+    }
+    return "primary";
+}
 export function touchActionLabel(action) {
     const spaced = action.replace(/([a-z0-9])([A-Z])/g, "$1 $2");
     return spaced.charAt(0).toUpperCase() + spaced.slice(1);
@@ -90,8 +123,13 @@ export function deriveTouchScheme(input, { reserved, firstPerson, config }) {
     let buttons;
     if (config?.buttons !== undefined) {
         buttons = config.buttons.map((spec) => typeof spec === "string"
-            ? { action: spec, label: touchActionLabel(spec), icon: null }
-            : { action: spec.action, label: spec.label ?? touchActionLabel(spec.action), icon: spec.icon ?? null });
+            ? { action: spec, label: touchActionLabel(spec), icon: null, kind: touchButtonKind(spec) }
+            : {
+                action: spec.action,
+                label: spec.label ?? touchActionLabel(spec.action),
+                icon: spec.icon ?? null,
+                kind: spec.kind ?? touchButtonKind(spec.action),
+            });
     }
     else {
         buttons = actions
@@ -100,7 +138,7 @@ export function deriveTouchScheme(input, { reserved, firstPerson, config }) {
             .filter((action) => !consumedByGestures.has(action))
             .filter((action) => !hidden.has(action))
             .filter((action) => !reserved.has(action) || BUTTONABLE_RESERVED.has(action))
-            .map((action) => ({ action, label: touchActionLabel(action), icon: null }));
+            .map((action) => ({ action, label: touchActionLabel(action), icon: null, kind: touchButtonKind(action) }));
     }
     const look = config?.look ?? firstPerson;
     if (joystick === null && buttons.length === 0 && gestures === null && !look)

package/dist/meta/changelog.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.8.0";
+export declare const VERSION = "0.9.0";
 export interface ChangelogEntry {
     migrate: readonly string[];
     added: readonly string[];

package/dist/meta/changelog.js

@@ -1,5 +1,24 @@
-export const VERSION = "0.8.0";
+export const VERSION = "0.9.0";
 export const CHANGELOG = {
+    "0.9.0": {
+        migrate: [
+            "Bump every @jgengine/* dependency to ^0.9.0 (the eight packages version in lockstep).",
+            "Mobile HUD fit is now on by default: design-resolution HUD scaling applies to every game with no config change. A desktop-only game that must keep the legacy fixed 0.85 compact zoom declares platforms: [\"web\"] (without \"mobile\").",
+            "Everything else is additive — VisibilitySystem defaults are enabled automatically but only affect renderers that read the policy, and existing games keep every 0.8.0 API unchanged.",
+            "Assets now resolve from this repo's self-hosted mirror (DEFAULT_RELEASE_BASE); games that pinned the previous base can override releaseBase if they need the old host.",
+        ],
+        added: [
+            "Mobile HUD fit — design-resolution UI scaling applies to every game by default: HudCanvas scales the whole HUD from PlayableGame.hudFit.designSize (default 1600×900, clamps minScale/maxScale 0.4–1) so desktop-authored layouts shrink to fit a phone; pure math in @jgengine/core/ui/hudScale (hudScaleForViewport, resolveHudFit, rectOverflow, overflowingPanels), wired by @jgengine/react's HudViewportProvider.",
+            "Graphics → UI scale — a player-facing graphics.uiScale slider (0.5–1.5, default 1) multiplies the computed HUD scale on every platform.",
+            "HUD overflow gate — HudCanvas reports panels that escape the viewport on a data-hud-overflow attribute; bun run shoot <game> --device mobile|both exits non-zero naming the offenders.",
+            "Automatic visibility & streaming defaults — VisibilitySystem (exported from @jgengine/core) gives every scene renderer-agnostic culling and asset-streaming policy with no per-object wiring: distance culling, preload margins, hysteresis, delayed unloading, multi-camera awareness, and per-object overrides.",
+            "Self-hosted asset mirror — DEFAULT_RELEASE_BASE points at this repo's rolling packs release; a catalog-driven mirror-assets workflow (weekly cron + dispatch) keeps it in sync.",
+        ],
+        changed: [
+            "Mobile HUD fit is on by default — design-resolution HUD scaling now applies to every game with no config change (was opt-in via platforms: [\"web\", \"mobile\"]); a desktop-only game keeps the legacy fixed 0.85 compact zoom via platforms: [\"web\"].",
+        ],
+        removed: [],
+    },
     "0.8.0": {
         migrate: [
             "Bump every @jgengine/* dependency to ^0.8.0 (the eight packages version in lockstep).",
@@ -30,6 +49,9 @@ export const CHANGELOG = {
             "Object spatial queries + entity patching — ctx.scene.object.at/inBox/raycast/raycastAll over unit-box objects; ctx.scene.entity.update(id, patch) for name/position/rotation/role/movement/behaviors/meta; per-instance renderObject/objectStyles overrides; pointerService.worldHitCenter() + pointer-lock center-ray aiming (#165).",
             "Controller movement config — PlayerMovementConfig (mode: free/axis/grid, axis, cellSize, collideObjects, beforeCommit pre-commit hook) for the shell-driven walk controller; defineGame.physics.gravity/jumpVelocity are honored by the built-in walk controller (distinct from the standalone physics/physicsWorld rigid-body sim); ctx.player.motion.impulse/setVerticalVelocity/setY/takePending (MotionIntents); entity.spawnPoseOf/resetToSpawn/resetAllToSpawn (#162).",
             "Model material/animation + paint — ModelConfig.tint/metalness/roughness/animation (GLTF clip playback, paused pose holds); PointerHit.uv + pointerService.sampleSurface() for material-aware picking; ctx.scene.entity.paint runtime paint layer, auto-rendered via a per-instance canvas texture with no per-game wiring; remote-player appearance tint recolors the shell's default capsule (#151).",
+            "Factions & reputation — faction/factions (createFactionGraph faction-vs-faction relation matrix, createFactionRoster entity membership + relationBetweenEntities/isHostile/hostilesOf) turns 'who is my enemy' into a data lookup feeding scene/targeting and ai/threat instead of a per-game role-string check; faction/reputation (createReputationLedger, DEFAULT_REPUTATION_TIERS Hated→Exalted, tierForStanding, effectiveRelation) tracks per-actor standing and overlays it on the base faction relation for at-war reputation grinds.",
+            "Threat taunt — ai/threat gained taunt(source, durationSeconds)/forcedTarget(): a taunt forces the mob onto a tank for its window (overriding highest) and lifts the taunter to the current top threat so aggro holds afterward; decay(dt) counts the window down.",
+            "Devtools discovery covers every game variable — discover.scanTable recurses nested plain objects and arrays into dotted paths (camera.chase.distance, waves.0.speed; 5 levels, 512 entries per scan, dedupes a value reachable through two tables), tunableDiscoveryPlugin rewrites annotated and derived single-line export consts (Math.sqrt(...), PLAYER_HEIGHT - 0.15) not just literals, DevtoolsOverlay self-scans the PlayableGame and core MOVEMENT_TUNING so physics/camera/movement/world config tune with zero exports in any host, resolvePhysicsTuning reads gravity/jumpVelocity live per frame, and the Tune tab gained a filter box.",
         ],
         changed: [],
         removed: [

package/dist/movement/dash.d.ts

@@ -24,7 +24,9 @@ export interface DashBurst {
 }
 export declare function iframeActive(config: DashConfig, elapsedMs: number): boolean;
 export declare function dashEase(t: number): number;
+export declare function dashDisplacement(config: DashConfig, dir: DashDirection, elapsedMs: number): [number, number, number];
 export declare function dashOffset(config: DashConfig, dir: DashDirection, elapsedMs: number): [number, number, number];
+export declare function dashFrameDelta(config: DashConfig, dir: DashDirection, previousElapsedMs: number, elapsedMs: number): [number, number, number];
 export interface DashState {
     tryDash(direction: DashDirection, nowMs: number): DashRejection | DashBurst;
     tick(dtSeconds: number, nowMs: number): void;
@@ -32,6 +34,7 @@ export interface DashState {
     staminaFraction(): number;
     isDashing(nowMs: number): boolean;
     isInvulnerable(nowMs: number): boolean;
+    displacement(nowMs: number): [number, number, number];
     offset(nowMs: number): [number, number, number];
 }
 export declare function createDashState(config: DashConfig): DashState;

package/dist/movement/dash.js

@@ -5,13 +5,21 @@ export function dashEase(t) {
     const clamped = Math.max(0, Math.min(1, t));
     return 1 - (1 - clamped) * (1 - clamped);
 }
-export function dashOffset(config, dir, elapsedMs) {
+export function dashDisplacement(config, dir, elapsedMs) {
     const traveled = dashEase(elapsedMs / config.durationMs) * config.distance;
     const len = Math.hypot(dir.x, dir.z);
     if (len === 0)
         return [0, 0, 0];
     return [(dir.x / len) * traveled, 0, (dir.z / len) * traveled];
 }
+export function dashOffset(config, dir, elapsedMs) {
+    return dashDisplacement(config, dir, elapsedMs);
+}
+export function dashFrameDelta(config, dir, previousElapsedMs, elapsedMs) {
+    const previous = dashDisplacement(config, dir, previousElapsedMs);
+    const current = dashDisplacement(config, dir, elapsedMs);
+    return [current[0] - previous[0], current[1] - previous[1], current[2] - previous[2]];
+}
 export function createDashState(config) {
     let stamina = config.staminaMax;
     let dashStartMs = null;
@@ -23,6 +31,12 @@ export function createDashState(config) {
         const dt = nowMs - dashStartMs;
         return dt >= 0 && dt < config.durationMs ? dt : null;
     }
+    function displacementAt(nowMs) {
+        const dt = elapsed(nowMs);
+        if (dt === null)
+            return [0, 0, 0];
+        return dashDisplacement(config, dashDir, dt);
+    }
     return {
         tryDash(direction, nowMs) {
             if (elapsed(nowMs) !== null)
@@ -55,11 +69,11 @@ export function createDashState(config) {
             const dt = elapsed(nowMs);
             return dt !== null && iframeActive(config, dt);
         },
+        displacement(nowMs) {
+            return displacementAt(nowMs);
+        },
         offset(nowMs) {
-            const dt = elapsed(nowMs);
-            if (dt === null)
-                return [0, 0, 0];
-            return dashOffset(config, dashDir, dt);
+            return displacementAt(nowMs);
         },
     };
 }

package/dist/movement/glideModel.d.ts

@@ -0,0 +1,44 @@
+export type GlideVec3 = readonly [number, number, number];
+export interface GlideModelConfig {
+    /** Fraction of gravity felt while gliding; default `0.25`. */
+    gravityScale?: number;
+    /** Gravity used before scaling; default `20`. */
+    gravity?: number;
+    /** Forward cruise acceleration toward `forwardSpeed`; default `10`. */
+    thrustAccel?: number;
+    /** Cruise speed the glider settles toward along its heading; default `12`. */
+    forwardSpeed?: number;
+    /** Yaw radians/s at full steer input; default `1.6`. */
+    yawRate?: number;
+    /** Vertical thrust (units/s²) at full throttle — powered climb; default `0` (unpowered glide). */
+    climbAccel?: number;
+    /** Terminal fall speed; default `8`. */
+    maxFallSpeed?: number;
+    /** Control softness in `[0, 1]` — `1` full authority, lower values (turbulence) blunt steering and thrust; default `1`. */
+    control?: number;
+}
+export interface GlideInput {
+    /** Steering in `[-1, 1]` (positive turns toward +x when facing +z). */
+    yaw?: number;
+    /** Powered climb in `[0, 1]` (needs `climbAccel`). */
+    throttle?: number;
+    /** Runtime control-authority override in `[0, 1]` — schedule-varying turbulence; overrides the config `control`. */
+    control?: number;
+}
+export interface GlideStep {
+    position: GlideVec3;
+    velocity: GlideVec3;
+    heading: number;
+}
+/**
+ * A kinematic glider (#282.6) — the walk-controller-compatible sibling of `physics/traversal`'s
+ * rigid-body `Glide`, with the yaw and powered-climb authority that one lacks. External flows —
+ * `physics/flowTube` corridors, `world/windZones` schedules — compose per tick through
+ * `externalVelocity`, and turbulence degrades control through the `control` scalar.
+ */
+export interface GlideModel {
+    step(dt: number, input?: GlideInput, externalVelocity?: GlideVec3): GlideStep;
+    pose(): GlideStep;
+    launch(position: GlideVec3, heading: number, initialSpeed?: number): void;
+}
+export declare function createGlideModel(config?: GlideModelConfig): GlideModel;

package/dist/movement/glideModel.js

@@ -0,0 +1,54 @@
+export function createGlideModel(config = {}) {
+    const gravity = (config.gravity ?? 20) * (config.gravityScale ?? 0.25);
+    const thrustAccel = config.thrustAccel ?? 10;
+    const forwardSpeed = config.forwardSpeed ?? 12;
+    const yawRate = config.yawRate ?? 1.6;
+    const climbAccel = config.climbAccel ?? 0;
+    const maxFallSpeed = config.maxFallSpeed ?? 8;
+    const baseControl = config.control ?? 1;
+    let x = 0;
+    let y = 0;
+    let z = 0;
+    let heading = 0;
+    let vx = 0;
+    let vy = 0;
+    let vz = 0;
+    function snapshot() {
+        return { position: [x, y, z], velocity: [vx, vy, vz], heading };
+    }
+    return {
+        launch(position, nextHeading, initialSpeed = forwardSpeed) {
+            x = position[0];
+            y = position[1];
+            z = position[2];
+            heading = nextHeading;
+            vx = Math.sin(heading) * initialSpeed;
+            vy = 0;
+            vz = Math.cos(heading) * initialSpeed;
+        },
+        pose: snapshot,
+        step(dt, input = {}, externalVelocity) {
+            if (dt <= 0)
+                return snapshot();
+            const control = Math.max(0, Math.min(1, input.control ?? baseControl));
+            heading += (input.yaw ?? 0) * yawRate * control * dt;
+            const fx = Math.sin(heading);
+            const fz = Math.cos(heading);
+            const along = vx * fx + vz * fz;
+            const cruise = (forwardSpeed - along) * Math.min(1, (thrustAccel / Math.max(1, forwardSpeed)) * dt);
+            vx += fx * cruise * control;
+            vz += fz * cruise * control;
+            vy -= gravity * dt;
+            const throttle = Math.max(0, Math.min(1, input.throttle ?? 0));
+            if (climbAccel > 0 && throttle > 0)
+                vy += climbAccel * throttle * control * dt;
+            if (vy < -maxFallSpeed)
+                vy = -maxFallSpeed;
+            const [ex, ey, ez] = externalVelocity ?? [0, 0, 0];
+            x += (vx + ex) * dt;
+            y += (vy + ey) * dt;
+            z += (vz + ez) * dt;
+            return snapshot();
+        },
+    };
+}

package/dist/movement/grappleSwing.d.ts

@@ -0,0 +1,34 @@
+export type SwingVec3 = readonly [number, number, number];
+export interface GrappleSwingConfig {
+    /** Rope shortens by this many units/s while `reeling`. Default `0` (fixed length). */
+    reelSpeed?: number;
+    minLength?: number;
+    /** Extra spring pull toward the anchor when the rope is taut (elastic feel); default `0` (hard constraint only). */
+    stiffness?: number;
+    /** Velocity damping per second while attached; default `0.1`. */
+    damping?: number;
+}
+export interface GrappleSwingState {
+    attached: boolean;
+    anchor: SwingVec3 | null;
+    ropeLength: number;
+}
+export interface GrappleSwingStep {
+    position: SwingVec3;
+    velocity: SwingVec3;
+}
+/**
+ * A rope-swing constraint for kinematic controllers (#282.5) — the walk-controller-compatible
+ * sibling of `physics/traversal`'s rigid-body `Grapple`. Fire at an anchor, feed each frame's
+ * integrated position/velocity through `step`, and commit what comes back (via `beforeCommit`
+ * or `setPose`): positions beyond the rope clamp to its sphere and velocity loses its outward
+ * radial component, which is exactly a pendulum swing.
+ */
+export interface GrappleSwing {
+    fire(anchor: SwingVec3, from: SwingVec3): void;
+    release(): void;
+    state(): GrappleSwingState;
+    /** Constrain one frame. `reeling` shortens the rope; returns the corrected position/velocity. */
+    step(position: SwingVec3, velocity: SwingVec3, dt: number, reeling?: boolean): GrappleSwingStep;
+}
+export declare function createGrappleSwing(config?: GrappleSwingConfig): GrappleSwing;