@jgengine/core 0.8.0 → 0.10.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,53 @@ export const DRIVE_AXIS_BINDINGS = {
     steer: { positive: ["KeyD", "ArrowRight"], negative: ["KeyA", "ArrowLeft"] },
     handbrake: { positive: ["Space"] },
 };
+const BIPOLAR_RANGE = { min: -1, max: 1 };
+/**
+ * Instantaneous (unsmoothed) analog sample of an axis binding map — the per-frame target an
+ * `AxisChannel` ramps toward, exposed as a pure read for `ctx.input.axis` and headless sampling.
+ * Each axis is its binding's positive-minus-negative held state (or its pointer source while a pointer
+ * is active), clamped to the axis range; axes without a listed range default to bipolar `[-1, 1]`.
+ */
+export function sampleAxisBindings(bindings, isDown, pointer, ranges) {
+    const out = {};
+    for (const axis of Object.keys(bindings)) {
+        const binding = bindings[axis];
+        const range = ranges?.[axis] ?? BIPOLAR_RANGE;
+        const fromPointer = binding.pointer === undefined ? null : pointerAxisValue(binding.pointer, pointer ?? null);
+        out[axis] = clampAxis(fromPointer ?? digitalTarget(binding, isDown), range);
+    }
+    return out;
+}
+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/interaction/contextMenu.d.ts

@@ -7,6 +7,7 @@ export interface ContextVerb {
     /** Greyed-out and non-dispatchable when true (e.g. requirement unmet). */
     disabled?: boolean;
 }
+/** Builds a {@link ContextVerb} for a right-click menu entry. */
 export declare function contextVerb(label: string, command: string, args?: Record<string, unknown>): ContextVerb;
 export interface ContextMenu {
     kind: ContextTargetKind;

package/dist/interaction/contextMenu.js

@@ -1,3 +1,4 @@
+/** Builds a {@link ContextVerb} for a right-click menu entry. */
 export function contextVerb(label, command, args) {
     return args === undefined ? { label, command } : { label, command, args };
 }

package/dist/interaction/proximityPrompt.d.ts

@@ -5,6 +5,8 @@ export interface PromptPoint {
 export interface KeybindPromptDisplay {
     kind: "keybind";
     actionId: string;
+    /** What the interaction does, shown beside the key glyph (e.g. `"Open Chest"`, `"Talk"`); omit for key-only. */
+    label?: string;
 }
 export interface GaugePromptDisplay {
     kind: "gauge";
@@ -15,7 +17,7 @@ export interface LabelPromptDisplay {
     text: string;
 }
 export type ProximityPromptDisplay = KeybindPromptDisplay | GaugePromptDisplay | LabelPromptDisplay;
-export declare function keybind(actionId: string): KeybindPromptDisplay;
+export declare function keybind(actionId: string, label?: string): KeybindPromptDisplay;
 export declare function gauge(gaugeId: string): GaugePromptDisplay;
 export declare function label(text: string): LabelPromptDisplay;
 export interface PromptCommand {

package/dist/interaction/proximityPrompt.js

@@ -1,5 +1,5 @@
-export function keybind(actionId) {
-    return { kind: "keybind", actionId };
+export function keybind(actionId, label) {
+    return label === undefined ? { kind: "keybind", actionId } : { kind: "keybind", actionId, label };
 }
 export function gauge(gaugeId) {
     return { kind: "gauge", gaugeId };
@@ -39,7 +39,7 @@ export function promptDisplaysEqual(a, b) {
     if (a === b)
         return true;
     if (a.kind === "keybind")
-        return b.kind === "keybind" && a.actionId === b.actionId;
+        return b.kind === "keybind" && a.actionId === b.actionId && a.label === b.label;
     if (a.kind === "gauge")
         return b.kind === "gauge" && a.gaugeId === b.gaugeId;
     return b.kind === "label" && a.text === b.text;

package/dist/meta/changelog.d.ts

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

package/dist/meta/changelog.js

@@ -1,5 +1,45 @@
-export const VERSION = "0.8.0";
+export const VERSION = "0.10.0";
 export const CHANGELOG = {
+    "0.10.0": {
+        migrate: [
+            "Bump every @jgengine/* dependency to ^0.10.0 (the eight packages version in lockstep).",
+            "Nothing to change for existing games — the shared mobile-composition system (viewport allocation, region collision, --jg-* viewport vars) is wired automatically by the shell; HudPanels inside a HudCanvas register themselves. Legacy orientation: \"landscape\" | \"portrait\" keeps its advisory dismissible-hint behavior.",
+            "Opt a driving/landscape game into the strict gate: replace advisory orientation with the contract form orientation: { mobile: \"landscape-required\" } (rules: any · portrait/landscape advisory · portrait-required/landscape-required · unsupported). In portrait the engine shows a polished RotateDeviceScreen, suppresses input, freezes the sim, and unmounts the HUD/controls until the device is landscape.",
+            "Declare HUD intent where useful: HudPanel gains priority (critical/secondary/tertiary), mobileBehavior (hidden unmounts on phones, transient softens collision), allowOverlapWith, and collisionGroup — all optional; omitting them keeps prior behavior.",
+            "Mobile validation now also fails on overlap: bun run shoot <game> --device mobile|mobile-landscape|both exits non-zero on forbidden inter-element collisions, naming both regions.",
+        ],
+        added: [
+            "Shared mobile layout composition — @jgengine/core/ui/gameLayout (resolveLayoutMode, intersects, overlapArea, detectLayoutCollisions, computeGameplayRect, LayoutRegion, GameViewportLayout) and @jgengine/core/ui/orientation (resolveOrientationRequirement, orientationGateActive, MobileOrientationRule); @jgengine/react adds GameViewportProvider (mounted by the shell), hooks (useGameViewportLayout, useGameLayoutMode, useGameOrientation, useReservedControlZones, useLayoutCollisions, useRegisterLayoutRegion), and a headless RotateDeviceScreen. The provider tracks window.visualViewport, publishes --jg-viewport-*/--jg-visual-viewport-*/--jg-safe-* CSS vars, resolves the explicit layout mode, and detects forbidden region overlaps.",
+            "Mandatory orientation contract — PlayableGame.orientation accepts { mobile: <rule> }; landscape-required/portrait-required render an engine-owned rotate gate that blocks gameplay (input suppressed, simulation frozen, HUD/controls unmounted), self-correcting when the device is turned. Reduced-motion and safe-area respected; visualViewport-sized for mobile Safari/PWA.",
+            "Reserved touch-control zones — the touch dock registers its joystick / action-cluster / utility rectangles (runtime-measured) as control regions, so HUD placement and collision validation know exactly where controls sit.",
+            "HUD placement metadata — HudPanel gains priority, mobileBehavior, allowOverlapWith, collisionGroup, and registers as a collision-tracked layout region.",
+            "Mobile-landscape shoot device — bun run shoot --device mobile-landscape (844×390) plus collision-gate reads that fail mobile validation on forbidden overlaps.",
+            "Canyon Chase migrated as the reference landscape-required game — declares orientation: { mobile: \"landscape-required\" } and composes its HUD through coordinated HudPanel regions instead of independent fixed corners.",
+        ],
+        changed: [
+            "First-person projectile tracers now originate from the weapon muzzle instead of the camera/eye centerline; hit detection is unchanged (still crosshair-accurate), and non-viewmodel games and enemy tracers are unaffected.",
+        ],
+        removed: [],
+    },
+    "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 +70,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;