@jgengine/core 0.18.1 → 0.19.0

package/dist/game/toasts.js

@@ -40,5 +40,12 @@ export function createToastQueue(options = {}) {
         clear() {
             toasts = [];
         },
+        snapshot() {
+            return { toasts: toasts.map((toast) => ({ ...toast })), counter };
+        },
+        restore(next) {
+            toasts = next.toasts.map((toast) => ({ ...toast }));
+            counter = next.counter;
+        },
     };
 }

package/dist/game/vfxInstance.d.ts

@@ -115,6 +115,15 @@ export interface VfxInstanceStore {
     tick(nowMs?: number): number;
     /** Dispose every instance (scene change / reset), emitting a `stop` op for each. */
     clear(): void;
+    /** Plain JSON copy of every live instance plus the id counter. */
+    snapshot(): VfxInstanceStoreState;
+    /** Replaces the live set: emits `stop` for each current instance, then `upsert` for each restored one. */
+    restore(next: VfxInstanceStoreState): void;
+}
+/** Plain JSON state of a {@link VfxInstanceStore}. */
+export interface VfxInstanceStoreState {
+    instances: VfxInstanceState[];
+    seq: number;
 }
 /** Options for {@link createVfxInstanceStore}. */
 export interface VfxInstanceStoreOptions {

package/dist/game/vfxInstance.js

@@ -92,5 +92,16 @@ export function createVfxInstanceStore(options = {}) {
         for (const id of [...instances.keys()])
             stop(id);
     }
-    return { upsert, update, stop, get, list, count, tick, clear };
+    function snapshot() {
+        return { instances: structuredClone([...instances.values()]), seq };
+    }
+    function restore(next) {
+        clear();
+        seq = next.seq;
+        for (const state of structuredClone(next.instances)) {
+            instances.set(state.id, state);
+            emit({ op: "upsert", id: state.id, instance: state });
+        }
+    }
+    return { upsert, update, stop, get, list, count, tick, clear, snapshot, restore };
 }

package/dist/game/viewports.d.ts

@@ -0,0 +1,43 @@
+import type { ChaseCameraConfig, TopDownCameraConfig } from "./cameraConfig.js";
+/** A screen region as fractions of the canvas, `[x, y, width, height]` in `0..1` with the origin at the top left. */
+export type ViewportRect = readonly [number, number, number, number];
+/** The follow camera an extra viewport runs; the primary seat keeps the game's main camera rig. */
+export interface ViewportCameraConfig {
+    /** Default: `"topDown"` when the game's main rig is top-down, otherwise `"chase"`. */
+    rig?: "chase" | "topDown";
+    chase?: ChaseCameraConfig;
+    topDown?: TopDownCameraConfig;
+}
+/** One viewport: which local seat it shows and where. */
+export interface ViewportDef {
+    /** Local seat id (`"slot:0"`, `"slot:1"`, …) from `localPlayers(ctx)`. */
+    slot: string;
+    rect: ViewportRect;
+    camera?: ViewportCameraConfig;
+}
+/** `defineGame({ viewports })`: split-screen layout for local seats. */
+export interface ViewportsConfig {
+    /** `"auto"` (default) splits the screen evenly across the seats currently joined; a list pins explicit rects. */
+    layout?: "auto" | readonly ViewportDef[];
+    /** Two-seat split: `"vertical"` puts them side by side (default), `"horizontal"` stacks them. */
+    split?: "vertical" | "horizontal";
+    /** Follow camera for seats whose viewport has none. */
+    camera?: ViewportCameraConfig;
+}
+/** A viewport in canvas pixels with a bottom-left origin, ready for `gl.setViewport`/`setScissor`. */
+export interface ViewportPixels {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Even split-screen rects for seats in order: one fills the screen, two split side by side (or stacked),
+ * three put the first on a full-width top half, four make a 2×2 grid, more fill a grid row by row.
+ * @capability split-screen Split the screen into one viewport per local seat, each with its own follow camera.
+ */
+export declare function splitViewports(slots: readonly string[], split?: "vertical" | "horizontal"): ViewportDef[];
+/** The viewports to draw for the seats currently joined: the explicit layout filtered to joined seats, or an even split. */
+export declare function resolveViewports(config: ViewportsConfig | undefined, slots: readonly string[]): ViewportDef[];
+/** Convert a top-left fractional rect into whole canvas pixels with a bottom-left origin; neighbours share edges exactly. */
+export declare function viewportPixels(rect: ViewportRect, width: number, height: number): ViewportPixels;

package/dist/game/viewports.js

@@ -0,0 +1,46 @@
+function gridRects(count) {
+    const columns = Math.ceil(Math.sqrt(count));
+    const rows = Math.ceil(count / columns);
+    const rects = [];
+    for (let index = 0; index < count; index += 1) {
+        const row = Math.floor(index / columns);
+        const inRow = row === rows - 1 ? count - row * columns : columns;
+        const column = index - row * columns;
+        rects.push([column / inRow, row / rows, 1 / inRow, 1 / rows]);
+    }
+    return rects;
+}
+/**
+ * Even split-screen rects for seats in order: one fills the screen, two split side by side (or stacked),
+ * three put the first on a full-width top half, four make a 2×2 grid, more fill a grid row by row.
+ * @capability split-screen Split the screen into one viewport per local seat, each with its own follow camera.
+ */
+export function splitViewports(slots, split = "vertical") {
+    const count = slots.length;
+    let rects;
+    if (count <= 1)
+        rects = [[0, 0, 1, 1]];
+    else if (count === 2) {
+        rects = split === "vertical" ? [[0, 0, 0.5, 1], [0.5, 0, 0.5, 1]] : [[0, 0, 1, 0.5], [0, 0.5, 1, 0.5]];
+    }
+    else if (count === 3)
+        rects = [[0, 0, 1, 0.5], [0, 0.5, 0.5, 0.5], [0.5, 0.5, 0.5, 0.5]];
+    else
+        rects = gridRects(count);
+    return slots.map((slot, index) => ({ slot, rect: rects[index] }));
+}
+/** The viewports to draw for the seats currently joined: the explicit layout filtered to joined seats, or an even split. */
+export function resolveViewports(config, slots) {
+    const layout = config?.layout ?? "auto";
+    if (layout === "auto")
+        return splitViewports(slots, config?.split);
+    return layout.filter((def) => slots.includes(def.slot));
+}
+/** Convert a top-left fractional rect into whole canvas pixels with a bottom-left origin; neighbours share edges exactly. */
+export function viewportPixels(rect, width, height) {
+    const left = Math.round(rect[0] * width);
+    const right = Math.round((rect[0] + rect[2]) * width);
+    const top = Math.round(rect[1] * height);
+    const bottom = Math.round((rect[1] + rect[3]) * height);
+    return { x: left, y: height - bottom, width: Math.max(1, right - left), height: Math.max(1, bottom - top) };
+}

package/dist/game/worldItem.d.ts

@@ -62,7 +62,6 @@ export declare function selectNearestWorldItem(candidates: readonly {
 /**
  * Spawn and track pickup-able items scattered in the world, including drops that scatter on death.
  *
- * @capability world-drops spawn pickup-able items in the world, including death drops
   * @internal
   */
 export declare function createWorldItemStore(deps: WorldItemStoreDeps): WorldItemStore;
@@ -87,6 +86,11 @@ export interface ResolvedDeathDrops {
   * @internal
   */
 export declare function resolveDeathDrops(drops: readonly Drop[], options: ResolveDeathDropsOptions): ResolvedDeathDrops;
+/**
+ * Per-rarity look of a dropped item: beam, color and label. Set via `defineGame({ worldItem: { rarityStyle } })`.
+ *
+ * @capability loot-beams rarity-colored loot beams and labels on dropped items via defineGame({ worldItem: { rarityStyle, beamHeight } })
+ */
 export interface RarityStyle {
     color?: string;
     beam?: boolean;

package/dist/game/worldItem.js

@@ -39,7 +39,6 @@ export function selectNearestWorldItem(candidates, from, radius) {
 /**
  * Spawn and track pickup-able items scattered in the world, including drops that scatter on death.
  *
- * @capability world-drops spawn pickup-able items in the world, including death drops
   * @internal
   */
 export function createWorldItemStore(deps) {

package/dist/input/actionBindings.d.ts

@@ -34,7 +34,13 @@ export type ActionCodes<TCode extends string = string> = readonly TCode[] | {
     toggle?: readonly TCode[];
     repeatMs?: number;
 };
-/** Maps each game action name to the input codes (hold/toggle keys, repeat rate) that trigger it. */
+/**
+ * Maps each game action name to the input codes (hold/toggle keys, repeat rate) that trigger it. In a
+ * `defineGame({ input })`, pressing an action runs the same-named command with `{ yaw, pitch, aim }`;
+ * `repeatMs` re-fires it while held (automatic weapons).
+ *
+ * @capability fire-input bind a key or mouse button to a named action that runs the same-named command with the aim; repeatMs auto-fires while held
+ */
 export type ActionCodesMap<TAction extends string = string, TCode extends string = string> = Record<TAction, ActionCodes<TCode>>;
 /** @internal */
 export declare function actionRepeatMs(codes: ActionCodes | undefined): number | undefined;
@@ -82,6 +88,14 @@ export interface ActionStateTracker<TAction extends string> {
     wasPressed(action: TAction): boolean;
     endFrame(): void;
     reset(): void;
+    /**
+     * Swap the binding map without dropping what is physically held: a key still down counts toward
+     * whatever action it maps to now, with no fresh press edge. Toggle state survives for actions that
+     * come back later.
+     */
+    rebind(map: ActionStateBindingMap<TAction, string>): void;
+    /** The action names in the current binding map. */
+    actions(): readonly TAction[];
 }
 /** @internal */
 export declare function createActionStateTracker<TAction extends string, TCode extends string = string>(map: ActionStateBindingMap<TAction, TCode>): ActionStateTracker<TAction>;

package/dist/input/actionBindings.js

@@ -179,9 +179,9 @@ function resolveActionBindingModes(config) {
 }
 /** @internal */
 export function createActionStateTracker(map) {
-    const actions = Object.keys(map);
-    const modesByAction = new Map(actions.map((action) => [action, resolveActionBindingModes(map[action])]));
-    const heldCodesByAction = new Map(actions.map((action) => [action, new Set()]));
+    let actions = Object.keys(map);
+    let modesByAction = new Map(actions.map((action) => [action, resolveActionBindingModes(map[action])]));
+    let heldCodesByAction = new Map(actions.map((action) => [action, new Set()]));
     const toggledActions = new Set();
     const pressedThisFrame = new Set();
     const activeCodes = new Set();
@@ -240,5 +240,16 @@ export function createActionStateTracker(map) {
             pressedThisFrame.clear();
             activeCodes.clear();
         },
+        rebind(next) {
+            actions = Object.keys(next);
+            modesByAction = new Map(actions.map((action) => [action, resolveActionBindingModes(next[action])]));
+            heldCodesByAction = new Map(actions.map((action) => [action, new Set()]));
+            for (const code of activeCodes) {
+                const holdAction = findAction(code, (modes) => modes.hold);
+                if (holdAction !== null)
+                    heldCodesByAction.get(holdAction).add(code);
+            }
+        },
+        actions: () => actions,
     };
 }

package/dist/input/actionContexts.d.ts

@@ -1,21 +1,45 @@
 import type { ActionCodesMap } from "./actionBindings.js";
+import type { AxisBinding } from "./axisInput.js";
+import type { AxisShapeConfig } from "./axisShaper.js";
+/** Serializable axis shaping a context may carry: {@link AxisShapeConfig} without the `scale` callback. */
+export type ActionContextAxisShape = Omit<AxisShapeConfig, "scale">;
 /** Named action-binding layer that may optionally expose lower layers. */
 export interface ActionContext {
     id: string;
     codes: ActionCodesMap;
     passthrough: boolean;
+    /** Axis bindings (by action name) this context brings, e.g. `steer` while driving; read with `activeAxes()`. */
+    axes?: Record<string, AxisBinding>;
+    /** Per-axis shaping this context brings; feed it to `createAxisShaper(...).retune` when the stack changes. */
+    shaping?: Record<string, ActionContextAxisShape>;
 }
 /** Serializable state for an action-context stack. */
 export interface ActionContextStackSnapshot {
     contexts: ActionContext[];
 }
+/** Axis bindings and shaping merged across the active contexts. */
+export interface ActiveContextAxes {
+    bindings: Record<string, AxisBinding>;
+    shaping: Record<string, ActionContextAxisShape>;
+}
 /** Mutable layered action-map stack with snapshot and restore support. */
 export interface ActionContextStack {
     push(context: ActionContext): void;
     pop(id: string): boolean;
     active(): ActionCodesMap;
+    /** Axis bindings and shaping of the active contexts, merged top-down like {@link active}. */
+    activeAxes(): ActiveContextAxes;
+    /** Ids of the stacked contexts, bottom first. */
+    ids(): readonly string[];
+    /** Bumps on every push, pop and restore; cheap change detection for per-frame readers. */
+    version(): number;
+    /** Called after every push, pop and restore; returns an unsubscribe. The shell rebinds live input here. */
+    subscribe(listener: () => void): () => void;
     snapshot(): ActionContextStackSnapshot;
     restore(snapshot: ActionContextStackSnapshot): void;
 }
-/** Creates a serializable stack of layered action maps for menus and gameplay modes. */
+/**
+ * Creates a serializable stack of layered action maps for menus and gameplay modes.
+ * @capability action-contexts Swap bindings live for on-foot, driving, menu or build modes by pushing and popping layered action maps.
+ */
 export declare function createActionContextStack(): ActionContextStack;

package/dist/input/actionContexts.js

@@ -12,45 +12,102 @@ function cloneCodes(codes) {
     }
     return result;
 }
-/** Creates a serializable stack of layered action maps for menus and gameplay modes. */
+function cloneAxes(axes) {
+    const result = {};
+    for (const [axis, binding] of Object.entries(axes)) {
+        result[axis] = {
+            ...binding,
+            positive: [...binding.positive],
+            ...(binding.negative === undefined ? {} : { negative: [...binding.negative] }),
+        };
+    }
+    return result;
+}
+function cloneShaping(shaping) {
+    const result = {};
+    for (const [axis, shape] of Object.entries(shaping)) {
+        result[axis] = {
+            ...(shape.digital === undefined ? {} : { digital: { ...shape.digital } }),
+            ...(shape.analog === undefined ? {} : { analog: { ...shape.analog } }),
+            ...(shape.range === undefined ? {} : { range: { ...shape.range } }),
+        };
+    }
+    return result;
+}
+function cloneContext(context) {
+    return {
+        id: context.id,
+        codes: cloneCodes(context.codes),
+        passthrough: context.passthrough,
+        ...(context.axes === undefined ? {} : { axes: cloneAxes(context.axes) }),
+        ...(context.shaping === undefined ? {} : { shaping: cloneShaping(context.shaping) }),
+    };
+}
+function mergeTopDown(contexts, pick) {
+    const merged = {};
+    for (let index = contexts.length - 1; index >= 0; index -= 1) {
+        const context = contexts[index];
+        const layer = pick(context);
+        if (layer !== undefined) {
+            for (const [key, value] of Object.entries(layer)) {
+                if (merged[key] === undefined)
+                    merged[key] = value;
+            }
+        }
+        if (!context.passthrough)
+            break;
+    }
+    return merged;
+}
+/**
+ * Creates a serializable stack of layered action maps for menus and gameplay modes.
+ * @capability action-contexts Swap bindings live for on-foot, driving, menu or build modes by pushing and popping layered action maps.
+ */
 export function createActionContextStack() {
     let contexts = [];
+    let version = 0;
+    const listeners = new Set();
+    const changed = () => {
+        version += 1;
+        for (const listener of [...listeners])
+            listener();
+    };
     return {
         push(context) {
-            contexts = [...contexts.filter((current) => current.id !== context.id), {
-                    id: context.id,
-                    codes: cloneCodes(context.codes),
-                    passthrough: context.passthrough,
-                }];
+            contexts = [...contexts.filter((current) => current.id !== context.id), cloneContext(context)];
+            changed();
         },
         pop(id) {
             const next = contexts.filter((context) => context.id !== id);
-            const changed = next.length !== contexts.length;
+            const removed = next.length !== contexts.length;
             contexts = next;
-            return changed;
+            if (removed)
+                changed();
+            return removed;
         },
         active() {
-            const merged = {};
-            for (let index = contexts.length - 1; index >= 0; index -= 1) {
-                const context = contexts[index];
-                for (const [action, codes] of Object.entries(context.codes)) {
-                    if (merged[action] === undefined)
-                        merged[action] = codes;
-                }
-                if (!context.passthrough)
-                    break;
-            }
-            return merged;
+            return mergeTopDown(contexts, (context) => context.codes);
+        },
+        activeAxes() {
+            return {
+                bindings: mergeTopDown(contexts, (context) => context.axes),
+                shaping: mergeTopDown(contexts, (context) => context.shaping),
+            };
+        },
+        ids: () => contexts.map((context) => context.id),
+        version: () => version,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
         },
         snapshot() {
-            return { contexts: contexts.map((context) => ({ ...context, codes: cloneCodes(context.codes) })) };
+            return { contexts: contexts.map(cloneContext) };
         },
         restore(snapshot) {
-            contexts = snapshot.contexts.map((context) => ({
-                id: context.id,
-                codes: cloneCodes(context.codes),
-                passthrough: context.passthrough,
-            }));
+            contexts = snapshot.contexts.map(cloneContext);
+            changed();
         },
     };
 }

package/dist/input/axisInput.d.ts

@@ -47,6 +47,10 @@ export declare class AxisChannel {
     get value(): AxisInput;
     sample(dt: number, isDown: (code: string) => boolean, pointer?: PointerAxisState | null): AxisInput;
 }
+/**
+ * Car axes bound to raw key codes, for an {@link AxisChannel} sampled with a key-code `isDown`. `ctx.input.axis`
+ * samples action names instead, so bind it to the game's input actions (e.g. `moveForward`), not this map.
+ */
 export declare const DRIVE_AXIS_BINDINGS: AxisBindingMap;
 export interface GenericAxisConfig<TAxes extends string> {
     bindings: Record<TAxes, AxisBinding>;

package/dist/input/axisInput.js

@@ -86,6 +86,10 @@ export class AxisChannel {
         return this.current;
     }
 }
+/**
+ * Car axes bound to raw key codes, for an {@link AxisChannel} sampled with a key-code `isDown`. `ctx.input.axis`
+ * samples action names instead, so bind it to the game's input actions (e.g. `moveForward`), not this map.
+ */
 export const DRIVE_AXIS_BINDINGS = {
     throttle: { positive: ["KeyW", "ArrowUp"] },
     brake: { positive: ["KeyS", "ArrowDown"] },

package/dist/input/axisShaper.d.ts

@@ -0,0 +1,73 @@
+import type { AxisBinding, AxisRange } from "./axisInput.js";
+/**
+ * How one axis responds to one kind of source. Keys want ramps (a held key should feel like a pedal
+ * being pressed, not a switch); sticks want deadzone and curve but no lag.
+ */
+export interface AxisShapeProfile {
+    /** Inner deadzone `0..1`; the remaining travel is rescaled so output still starts at 0 (default `0`). */
+    deadzone?: number;
+    /** Raw magnitude at which output reaches full scale, `0..1` (default `1`). */
+    saturation?: number;
+    /** Response exponent applied after the deadzone: `1` linear, `>1` finer near centre (default `1`). */
+    curve?: number;
+    /** Units/s the output may move away from zero (default `Infinity`: no ramp). */
+    riseRate?: number;
+    /** Units/s the output may move back toward zero while the input keeps its sign (default `riseRate`). */
+    fallRate?: number;
+    /** Units/s the output moves when the input is released or reversed — self-centring (default `fallRate`). */
+    returnRate?: number;
+}
+/** Shaping for one named axis. */
+export interface AxisShapeConfig {
+    /** Profile for keys and buttons (default: pass through). */
+    digital?: AxisShapeProfile;
+    /** Profile for sticks, triggers and other continuous sources (default: pass through). */
+    analog?: AxisShapeProfile;
+    /** Output range (default `[-1, 1]`; use `{ min: 0, max: 1 }` for pedals). */
+    range?: AxisRange;
+    /**
+     * Multiplier from a caller-supplied signal, applied to the target before ramping — speed-sensitive
+     * steering (`speed => 1 / (1 + speed / 30)`), weapon-sway-by-stamina, and similar. Default `1`.
+     */
+    scale?: (signal: number) => number;
+}
+/** Config for {@link createAxisShaper}: one entry per axis. */
+export interface AxisShaperConfig<TAxes extends string> {
+    axes: Record<TAxes, AxisShapeConfig>;
+}
+/** Per-sample options for {@link AxisShaper.shape}. */
+export interface AxisShapeSample<TAxes extends string> {
+    /** Axes whose raw value came from an analog source this frame; unlisted axes use the digital profile. */
+    analog?: Partial<Record<TAxes, boolean>> | ReadonlySet<TAxes>;
+    /** Signal passed to each axis's `scale` callback (speed, stamina, zoom). */
+    signal?: number;
+}
+/** Shaped axis output, one number per axis. */
+export type AxisValues<TAxes extends string> = Record<TAxes, number>;
+/** Stateful per-axis response shaping between raw input and a sim. */
+export interface AxisShaper<TAxes extends string> {
+    /** Shape one frame of raw axis values (as returned by `ctx.input.axis`) and return the shaped output. */
+    shape(dt: number, raw: Readonly<Record<TAxes, number>>, sample?: AxisShapeSample<TAxes>): AxisValues<TAxes>;
+    /** The last shaped output. */
+    value(): Readonly<AxisValues<TAxes>>;
+    /** Replace the shaping config (settings screen, per-vehicle feel) without resetting the current output. */
+    retune(next: AxisShaperConfig<TAxes>): void;
+    snapshot(): AxisValues<TAxes>;
+    restore(state: Readonly<AxisValues<TAxes>>): void;
+    /** Zero every axis. */
+    reset(): void;
+}
+/** Deadzone, saturation and curve applied to one raw value; sign is preserved. */
+export declare function shapeAxisValue(raw: number, profile: AxisShapeProfile | undefined): number;
+/**
+ * Creates an {@link AxisShaper}: deadzone, curve and ramp rates per axis, chosen per frame by whether the
+ * source was a key or a stick. It sits between `ctx.input.axis(...)` and any sim (a vehicle, an aircraft,
+ * aim), so a held key eases in and self-centres while a stick stays direct. Deterministic and serializable.
+ * @capability axis-shaping shape raw input per axis — deadzone, response curve, keyboard ramp, self-centring, speed-sensitive scaling
+ */
+export declare function createAxisShaper<TAxes extends string>(initial: AxisShaperConfig<TAxes>): AxisShaper<TAxes>;
+/**
+ * Which axes an analog source is driving this frame: an axis counts as analog when any action bound to it
+ * has a published analog magnitude (`ctx.input.analog()`). Feed the result to {@link AxisShaper.shape}.
+ */
+export declare function analogAxes<TAxes extends string>(bindings: Readonly<Record<TAxes, AxisBinding>>, analog: Readonly<Record<string, number>> | null): Set<TAxes>;

package/dist/input/axisShaper.js

@@ -0,0 +1,105 @@
+const FULL_RANGE = { min: -1, max: 1 };
+function clampTo(value, range) {
+    return value < range.min ? range.min : value > range.max ? range.max : value;
+}
+/** Deadzone, saturation and curve applied to one raw value; sign is preserved. */
+export function shapeAxisValue(raw, profile) {
+    if (profile === undefined)
+        return raw;
+    const deadzone = Math.min(0.99, Math.max(0, profile.deadzone ?? 0));
+    const saturation = Math.max(deadzone + 0.01, Math.min(1, profile.saturation ?? 1));
+    const magnitude = Math.abs(raw);
+    if (magnitude <= deadzone)
+        return 0;
+    const normalized = Math.min(1, (magnitude - deadzone) / (saturation - deadzone));
+    const curved = normalized ** Math.max(0.1, profile.curve ?? 1);
+    return Math.sign(raw) * curved;
+}
+function rateFor(current, target, profile) {
+    const rise = profile?.riseRate ?? Number.POSITIVE_INFINITY;
+    const fall = profile?.fallRate ?? rise;
+    const back = profile?.returnRate ?? fall;
+    if (target === 0 || (current !== 0 && Math.sign(target) !== Math.sign(current)))
+        return back;
+    return Math.abs(target) >= Math.abs(current) ? rise : fall;
+}
+function isAnalog(axis, analog) {
+    if (analog === undefined)
+        return false;
+    if (analog instanceof Set)
+        return analog.has(axis);
+    return analog[axis] === true;
+}
+/**
+ * Creates an {@link AxisShaper}: deadzone, curve and ramp rates per axis, chosen per frame by whether the
+ * source was a key or a stick. It sits between `ctx.input.axis(...)` and any sim (a vehicle, an aircraft,
+ * aim), so a held key eases in and self-centres while a stick stays direct. Deterministic and serializable.
+ * @capability axis-shaping shape raw input per axis — deadzone, response curve, keyboard ramp, self-centring, speed-sensitive scaling
+ */
+export function createAxisShaper(initial) {
+    let config = initial;
+    const names = Object.keys(config.axes);
+    const current = {};
+    for (const name of names)
+        current[name] = 0;
+    return {
+        shape(dt, raw, sample) {
+            const step = Math.max(0, dt);
+            for (const name of Object.keys(config.axes)) {
+                const axis = config.axes[name];
+                const range = axis.range ?? FULL_RANGE;
+                const profile = isAnalog(name, sample?.analog) ? axis.analog : axis.digital;
+                const scale = axis.scale === undefined ? 1 : axis.scale(sample?.signal ?? 0);
+                const target = clampTo(shapeAxisValue(raw[name] ?? 0, profile) * scale, range);
+                const from = current[name] ?? 0;
+                const rate = rateFor(from, target, profile);
+                let next;
+                if (!Number.isFinite(rate))
+                    next = target;
+                else if (target !== 0 && from !== 0 && Math.sign(target) !== Math.sign(from)) {
+                    // A reversal returns to centre at the return rate, then builds the other way at the rise rate.
+                    const toZero = Math.min(Math.abs(from), rate * step);
+                    const left = step - toZero / Math.max(rate, 1e-9);
+                    next = Math.abs(from) > toZero ? from - Math.sign(from) * toZero : Math.sign(target) * Math.min(Math.abs(target), (profile?.riseRate ?? Number.POSITIVE_INFINITY) * left);
+                }
+                else {
+                    const delta = target - from;
+                    const move = rate * step;
+                    next = Math.abs(delta) <= move ? target : from + Math.sign(delta) * move;
+                }
+                current[name] = clampTo(next, range);
+            }
+            return current;
+        },
+        value: () => current,
+        retune(next) {
+            config = next;
+            for (const name of Object.keys(next.axes))
+                current[name] ??= 0;
+        },
+        snapshot: () => ({ ...current }),
+        restore(state) {
+            Object.assign(current, state);
+        },
+        reset() {
+            for (const name of Object.keys(current))
+                current[name] = 0;
+        },
+    };
+}
+/**
+ * Which axes an analog source is driving this frame: an axis counts as analog when any action bound to it
+ * has a published analog magnitude (`ctx.input.analog()`). Feed the result to {@link AxisShaper.shape}.
+ */
+export function analogAxes(bindings, analog) {
+    const out = new Set();
+    if (analog === null)
+        return out;
+    for (const name of Object.keys(bindings)) {
+        const binding = bindings[name];
+        const codes = binding.negative === undefined ? binding.positive : [...binding.positive, ...binding.negative];
+        if (codes.some((code) => analog[code] !== undefined))
+            out.add(name);
+    }
+    return out;
+}