@jgengine/core 0.10.0 → 0.12.0

package/dist/input/axisInput.d.ts

@@ -23,7 +23,9 @@ export interface AxisRange {
     max: number;
 }
 export declare const AXIS_RANGE: Record<AxisName, AxisRange>;
+/** @internal */
 export declare function clampAxis(value: number, range: AxisRange): number;
+/** @internal */
 export declare function rampToward(current: number, target: number, rate: number, dt: number): number;
 /**
  * Analog control channel — distinct from the digital action bindings. Throttle/brake/steer/handbrake
@@ -31,7 +33,8 @@ export declare function rampToward(current: number, target: number, rate: number
  * 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.
- */
+  * @internal
+  */
 export declare class AxisChannel {
     private readonly bindings;
     private readonly smoothing;
@@ -68,6 +71,8 @@ export interface GenericAxisChannel<TAxes extends string> {
  * `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]`.
- */
+  * @internal
+  */
 export declare function sampleAxisBindings<TAxes extends string>(bindings: Record<TAxes, AxisBinding>, isDown: (code: string) => boolean, pointer?: PointerAxisState | null, ranges?: Partial<Record<TAxes, AxisRange>>): Record<TAxes, number>;
+/** @internal */
 export declare function createAxisChannel<TAxes extends string>(config: GenericAxisConfig<TAxes>): GenericAxisChannel<TAxes>;

package/dist/input/axisInput.js

@@ -6,9 +6,11 @@ export const AXIS_RANGE = {
     steer: { min: -1, max: 1 },
     handbrake: { min: 0, max: 1 },
 };
+/** @internal */
 export function clampAxis(value, range) {
     return value < range.min ? range.min : value > range.max ? range.max : value;
 }
+/** @internal */
 export function rampToward(current, target, rate, dt) {
     if (!Number.isFinite(rate))
         return target;
@@ -29,7 +31,8 @@ function digitalTarget(binding, isDown) {
  * 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.
- */
+  * @internal
+  */
 export class AxisChannel {
     bindings;
     smoothing;
@@ -80,7 +83,8 @@ const BIPOLAR_RANGE = { min: -1, max: 1 };
  * `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]`.
- */
+  * @internal
+  */
 export function sampleAxisBindings(bindings, isDown, pointer, ranges) {
     const out = {};
     for (const axis of Object.keys(bindings)) {
@@ -91,6 +95,7 @@ export function sampleAxisBindings(bindings, isDown, pointer, ranges) {
     }
     return out;
 }
+/** @internal */
 export function createAxisChannel(config) {
     const axes = Object.keys(config.bindings);
     const smoothing = config.smoothing ?? 6;

package/dist/input/controlGroups.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Optional RTS binding composition over the genre-agnostic selection-bookmark
+ * store (`@jgengine/core/scene/selectionBookmarks`). It maps the classic control-
+ * group idiom — Ctrl+digit binds, digit recalls, a second digit tap within a
+ * window focuses — onto opaque bookmark keys, without pulling input mapping into
+ * the store. Games that want a different scheme (named bookmarks, gamepad, touch)
+ * skip this and call the store directly.
+ *
+ * The resolver is pure: it turns a decoded key event plus the last-recall memory
+ * into an intent, so the same logic works under any capture layer and stays
+ * replay-safe. The caller owns actually binding/recalling and the focus hook.
+ */
+/** What a control-group key press means once modifiers and double-tap timing are resolved. */
+export type ControlGroupIntent = 
+/** Ctrl+digit: save the current selection under `key`. */
+{
+    kind: "bind";
+    key: string;
+}
+/** Digit: recall the set saved under `key` into the active selection. */
+ | {
+    kind: "recall";
+    key: string;
+}
+/** Second digit tap within the double-tap window: recall and focus the camera on `key`. */
+ | {
+    kind: "focus";
+    key: string;
+};
+/** A decoded control-group key press plus the memory needed to detect a double-tap. */
+export interface ControlGroupInput {
+    /** The pressed group digit, 0–9. */
+    digit: number;
+    /** True when a bind modifier (Ctrl by default) was held. */
+    bindModifier: boolean;
+    /** Monotonic time of this press, same clock as `lastRecall`. */
+    now: number;
+    /** The previous recall (its key and time), or null if none — drives double-tap focus detection. */
+    lastRecall: {
+        key: string;
+        at: number;
+    } | null;
+}
+/** Tuning for the control-group idiom: the double-tap focus window and the bookmark-key namespace. */
+export interface ControlGroupOptions {
+    /** Max gap (ms) between two recalls of the same group that counts as a focus double-tap. Default 300. */
+    doubleTapMs?: number;
+    /** Prefix for the generated bookmark key, so control groups can share a store with other bookmarks. Default `""` (bare digit). */
+    keyPrefix?: string;
+}
+/**
+ * The stable bookmark key for a control-group `digit` under `options.keyPrefix` —
+ * the key a caller passes to `SelectionBookmarks.bind`/`recall` to store a group
+ * without going through {@link resolveControlGroupIntent}.
+ *
+ * @capability rts-control-groups map Ctrl+digit / digit / double-tap presses onto selection-bookmark bind / recall / focus intents
+ */
+export declare function controlGroupKey(digit: number, options?: ControlGroupOptions): string;
+/**
+ * Resolve a control-group key press into a {@link ControlGroupIntent}: Ctrl+digit
+ * binds, a bare digit recalls, and a second recall of the same group within
+ * `doubleTapMs` focuses. Pure — the caller applies the intent against the store
+ * and its own focus hook, and records the returned recall for the next call.
+ *
+ * @capability rts-control-groups map Ctrl+digit / digit / double-tap presses onto selection-bookmark bind / recall / focus intents
+ */
+export declare function resolveControlGroupIntent(input: ControlGroupInput, options?: ControlGroupOptions): ControlGroupIntent;

package/dist/input/controlGroups.js

@@ -0,0 +1,41 @@
+/**
+ * Optional RTS binding composition over the genre-agnostic selection-bookmark
+ * store (`@jgengine/core/scene/selectionBookmarks`). It maps the classic control-
+ * group idiom — Ctrl+digit binds, digit recalls, a second digit tap within a
+ * window focuses — onto opaque bookmark keys, without pulling input mapping into
+ * the store. Games that want a different scheme (named bookmarks, gamepad, touch)
+ * skip this and call the store directly.
+ *
+ * The resolver is pure: it turns a decoded key event plus the last-recall memory
+ * into an intent, so the same logic works under any capture layer and stays
+ * replay-safe. The caller owns actually binding/recalling and the focus hook.
+ */
+/**
+ * The stable bookmark key for a control-group `digit` under `options.keyPrefix` —
+ * the key a caller passes to `SelectionBookmarks.bind`/`recall` to store a group
+ * without going through {@link resolveControlGroupIntent}.
+ *
+ * @capability rts-control-groups map Ctrl+digit / digit / double-tap presses onto selection-bookmark bind / recall / focus intents
+ */
+export function controlGroupKey(digit, options = {}) {
+    if (!Number.isInteger(digit) || digit < 0 || digit > 9) {
+        throw new Error(`controlGroupKey: digit must be an integer in [0, 9], got ${digit}`);
+    }
+    return `${options.keyPrefix ?? ""}${digit}`;
+}
+/**
+ * Resolve a control-group key press into a {@link ControlGroupIntent}: Ctrl+digit
+ * binds, a bare digit recalls, and a second recall of the same group within
+ * `doubleTapMs` focuses. Pure — the caller applies the intent against the store
+ * and its own focus hook, and records the returned recall for the next call.
+ *
+ * @capability rts-control-groups map Ctrl+digit / digit / double-tap presses onto selection-bookmark bind / recall / focus intents
+ */
+export function resolveControlGroupIntent(input, options = {}) {
+    const key = controlGroupKey(input.digit, options);
+    if (input.bindModifier)
+        return { kind: "bind", key };
+    const doubleTapMs = options.doubleTapMs ?? 300;
+    const isDoubleTap = input.lastRecall !== null && input.lastRecall.key === key && input.now - input.lastRecall.at <= doubleTapMs;
+    return { kind: isDoubleTap ? "focus" : "recall", key };
+}

package/dist/input/touchScheme.d.ts

@@ -3,9 +3,11 @@
  * capture layer renders a virtual joystick, on-screen buttons, and a gesture
  * surface, and feeds synthetic `touch:<action>` codes into the same
  * ActionStateTracker the keyboard uses, so games gain touch play without any
- * per-game input code. Games refine the derived defaults through
- * TouchControlsConfig (gesture bindings, button curation) or opt out entirely
- * with `touch: false`.
+ * per-game input code. Session-lifecycle actions (start/restart/pause/menu/…)
+ * are left off the derived dock — they live in the start screen, pause menu, or
+ * settings sheet, never as a chip over live play. Games refine the derived
+ * defaults through TouchControlsConfig (gesture bindings, button curation) or
+ * opt out entirely with `touch: false`.
  */
 import { type ActionCodesMap } from "./actionBindings.js";
 export declare const TOUCH_CODE_PREFIX = "touch:";
@@ -31,6 +33,50 @@ export interface TouchGestureBindings {
     /** Continuous drag: repeats the directional action every `stepPx` of travel. Wins over swipes on its axis, except a flick can still fire the swipe binding for a direction the drag leaves unbound. */
     drag?: TouchDragBinding;
 }
+/**
+ * Physical silhouette a touch button wears. The capture layer draws each as its
+ * own shape — a `pedal` reads as a foot pedal, a `lever` as a pull handle, a
+ * `trigger` as a firing paddle — so a control looks like the thing it does
+ * instead of a labelled circle. `circle`/`square` are the neutral fallbacks.
+ */
+export type TouchButtonShape = "circle" | "square" | "pedal" | "lever" | "trigger" | "wheel" | "tab";
+/**
+ * Screen zone a touch cluster or button docks to. The four corners plus the
+ * mid `left`/`right` rails (vertical stacks, MMO-style hotbars) and the
+ * `bottom-center` / `top-center` strips let controls use the whole viewport
+ * instead of piling into one bottom bar.
+ */
+export type TouchAnchor = "bottom-left" | "bottom-center" | "bottom-right" | "left" | "right" | "top-left" | "top-center" | "top-right";
+/**
+ * Player-selectable skin for the whole touch layer. A style is a material +
+ * geometry preset (not just colours), chosen in Settings → Controls and
+ * persisted; `glass` is the translucent default, the rest are opt-in looks.
+ */
+export type TouchStyle = "glass" | "arcade" | "mechanical" | "minimal";
+/** Every touch skin id, in menu order. */
+export declare const TOUCH_STYLES: readonly TouchStyle[];
+/** Touch skins as `{ value, label }` rows for the Settings → Controls selector. */
+export declare const TOUCH_STYLE_OPTIONS: readonly {
+    value: TouchStyle;
+    label: string;
+}[];
+/** Skin used when neither the game nor the player picks one. */
+export declare const DEFAULT_TOUCH_STYLE: TouchStyle;
+/** Where each touch cluster docks; unset falls back to the classic bottom layout. */
+export interface TouchLayoutConfig {
+    /** Virtual joystick / movement zone. Default `bottom-left`. */
+    movement?: TouchAnchor;
+    /** Primary action cluster. Default `bottom-right`. */
+    actions?: TouchAnchor;
+    /** Utility chip row. Default `bottom-center`. */
+    utility?: TouchAnchor;
+}
+/** The dock zone each cluster resolved to, after applying game config over the bottom-layout defaults. */
+export interface ResolvedTouchLayout {
+    movement: TouchAnchor;
+    actions: TouchAnchor;
+    utility: TouchAnchor;
+}
 export interface TouchButtonSpec {
     action: string;
     label?: string;
@@ -38,11 +84,21 @@ export interface TouchButtonSpec {
     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;
+    /** Physical silhouette; unset derives one from the action name (`brake`→pedal, `handbrake`→lever, `fire`→trigger, …). */
+    shape?: TouchButtonShape;
+    /** Docks this button on its own instead of joining its cluster — e.g. a brake pedal pinned to the right rail. */
+    anchor?: TouchAnchor;
+    /** Custom art drawn as the button face instead of the built-in silhouette — any image URL or `data:image/svg+xml` URI (a slot frame, spell plate, …); the icon/label still sits on top. */
+    image?: string;
+}
+/** Restricts the virtual joystick to one axis — a `horizontal` zone reads as a steering control, freeing throttle/brake to become pedal buttons. */
+export interface TouchMovementConfig {
+    axis?: "both" | "horizontal" | "vertical";
 }
 export interface TouchControlsConfig {
-    /** `false` removes the virtual joystick even when movement actions are bound. */
-    movement?: false;
-    /** Curated on-screen buttons (order preserved); omit to derive one button per remaining action. */
+    /** `false` removes the virtual joystick even when movement actions are bound; an object restricts it to one axis. */
+    movement?: false | TouchMovementConfig;
+    /** Curated on-screen buttons (order preserved); omit to derive one button per remaining action. Derivation skips session-lifecycle actions (start/restart/pause/menu/…); list one here to dock it anyway. */
     buttons?: readonly (string | TouchButtonSpec)[];
     /** Play-surface gestures; actions consumed here stop appearing as derived buttons. */
     gestures?: TouchGestureBindings;
@@ -52,6 +108,10 @@ export interface TouchControlsConfig {
     lookSensitivity?: number;
     /** Actions to leave off the derived button cluster. */
     hidden?: readonly string[];
+    /** Dock each cluster to a screen zone; omit for the classic bottom layout. */
+    layout?: TouchLayoutConfig;
+    /** Suggested default skin; the player's Settings choice overrides it. Default `glass`. */
+    style?: TouchStyle;
 }
 export interface TouchJoystick {
     up: string | null;
@@ -67,6 +127,12 @@ export interface TouchButton {
     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;
+    /** Physical silhouette to draw. */
+    shape: TouchButtonShape;
+    /** Per-button dock override; null joins the cluster's anchor. */
+    anchor: TouchAnchor | null;
+    /** Custom face art (image/SVG URL); null draws the built-in silhouette. */
+    image: string | null;
 }
 export interface TouchScheme {
     joystick: TouchJoystick | null;
@@ -74,7 +140,17 @@ export interface TouchScheme {
     gestures: TouchGestureBindings | null;
     look: boolean;
     lookSensitivity: number;
+    /** Resolved dock zones for the three clusters. */
+    layout: ResolvedTouchLayout;
+    /** Game-suggested default skin; the shell swaps in the player's choice when set. */
+    style: TouchStyle;
 }
+/**
+ * Default silhouette for an action; `circle` when nothing more specific fits.
+ *
+ * @capability touch-controls default on-screen button silhouette for a touch action
+ */
+export declare function touchButtonShape(action: string): TouchButtonShape;
 export declare function touchButtonKind(action: string): TouchButtonKind;
 export declare function touchActionLabel(action: string): string;
 export interface DeriveTouchSchemeOptions {

package/dist/input/touchScheme.js

@@ -3,9 +3,11 @@
  * capture layer renders a virtual joystick, on-screen buttons, and a gesture
  * surface, and feeds synthetic `touch:<action>` codes into the same
  * ActionStateTracker the keyboard uses, so games gain touch play without any
- * per-game input code. Games refine the derived defaults through
- * TouchControlsConfig (gesture bindings, button curation) or opt out entirely
- * with `touch: false`.
+ * per-game input code. Session-lifecycle actions (start/restart/pause/menu/…)
+ * are left off the derived dock — they live in the start screen, pause menu, or
+ * settings sheet, never as a chip over live play. Games refine the derived
+ * defaults through TouchControlsConfig (gesture bindings, button curation) or
+ * opt out entirely with `touch: false`.
  */
 import { isHotbarSlotAction } from "./actionBindings.js";
 export const TOUCH_CODE_PREFIX = "touch:";
@@ -31,7 +33,68 @@ export function withTouchCodes(map) {
     }
     return result;
 }
+/** Every touch skin id, in menu order. */
+export const TOUCH_STYLES = ["glass", "arcade", "mechanical", "minimal"];
+/** Touch skins as `{ value, label }` rows for the Settings → Controls selector. */
+export const TOUCH_STYLE_OPTIONS = [
+    { value: "glass", label: "Glass" },
+    { value: "arcade", label: "Arcade" },
+    { value: "mechanical", label: "Mechanical" },
+    { value: "minimal", label: "Minimal" },
+];
+/** Skin used when neither the game nor the player picks one. */
+export const DEFAULT_TOUCH_STYLE = "glass";
 const DEFAULT_LOOK_SENSITIVITY = 0.005;
+const DEFAULT_TOUCH_LAYOUT = {
+    movement: "bottom-left",
+    actions: "bottom-right",
+    utility: "bottom-center",
+};
+const SHAPE_BY_ACTION = new Map([
+    ["brake", "pedal"],
+    ["accelerate", "pedal"],
+    ["throttle", "pedal"],
+    ["throttleUp", "pedal"],
+    ["throttleDown", "pedal"],
+    ["gas", "pedal"],
+    ["clutch", "pedal"],
+    ["handbrake", "lever"],
+    ["gearUp", "lever"],
+    ["gearDown", "lever"],
+    ["shift", "lever"],
+    ["boost", "lever"],
+    ["fire", "trigger"],
+    ["shoot", "trigger"],
+    ["attack", "trigger"],
+    ["primaryFire", "trigger"],
+    ["secondaryFire", "trigger"],
+    ["steer", "wheel"],
+    ["inventory", "square"],
+    ["bag", "square"],
+    ["spellbook", "square"],
+]);
+const WHEEL_PREFIXES = ["steer"];
+/** Slot-like verbs read as square tiles (inventory, spell/item/ability slots). */
+const SQUARE_PREFIXES = ["spell", "slot", "item"];
+/**
+ * Default silhouette for an action; `circle` when nothing more specific fits.
+ *
+ * @capability touch-controls default on-screen button silhouette for a touch action
+ */
+export function touchButtonShape(action) {
+    const direct = SHAPE_BY_ACTION.get(action);
+    if (direct !== undefined)
+        return direct;
+    for (const prefix of WHEEL_PREFIXES) {
+        if (action.startsWith(prefix))
+            return "wheel";
+    }
+    for (const prefix of SQUARE_PREFIXES) {
+        if (action.startsWith(prefix))
+            return "square";
+    }
+    return "circle";
+}
 const JOYSTICK_AXES = {
     up: ["moveForward", "moveUp", "forward", "accelerate", "throttleUp", "pitchUp", "climb"],
     down: ["moveBack", "moveBackward", "moveDown", "backward", "reverse", "brake", "throttleDown", "pitchDown", "dive"],
@@ -60,6 +123,27 @@ const UTILITY_ACTIONS = new Set([
     "leaderboard",
 ]);
 const UTILITY_PREFIXES = ["toggle", "cycle", "switch", "open", "close", "show", "hide", "zoom"];
+/**
+ * Session-lifecycle and menu-chrome actions never auto-derive an on-screen
+ * touch button: they belong to the start screen, pause menu, or settings sheet
+ * (surfaced via `settings.actions` plus a `<SettingsTrigger>`), not the live
+ * control dock — a `restart` chip stapled over play is the anti-pattern, and a
+ * mis-tap on it wrecks the match. A game that truly wants one docked lists it
+ * explicitly in `touch.buttons`, which bypasses derivation entirely.
+ */
+const LIFECYCLE_ACTIONS = new Set([
+    "start",
+    "restart",
+    "reset",
+    "retry",
+    "pause",
+    "resume",
+    "menu",
+    "quit",
+    "exit",
+    "settings",
+    "options",
+]);
 export function touchButtonKind(action) {
     if (UTILITY_ACTIONS.has(action))
         return "utility";
@@ -103,17 +187,20 @@ export function deriveTouchScheme(input, { reserved, firstPerson, config }) {
     const joystickMapped = new Set();
     let joystick = null;
     if (config?.movement !== false) {
-        const resolveAxis = (candidates) => {
+        const axis = config?.movement?.axis ?? "both";
+        const resolveAxis = (candidates, enabled) => {
+            if (!enabled)
+                return null;
             const action = candidates.find((candidate) => bound.has(candidate)) ?? null;
             if (action !== null)
                 joystickMapped.add(action);
             return action;
         };
         const axes = {
-            up: resolveAxis(JOYSTICK_AXES.up),
-            down: resolveAxis(JOYSTICK_AXES.down),
-            left: resolveAxis(JOYSTICK_AXES.left),
-            right: resolveAxis(JOYSTICK_AXES.right),
+            up: resolveAxis(JOYSTICK_AXES.up, axis !== "horizontal"),
+            down: resolveAxis(JOYSTICK_AXES.down, axis !== "horizontal"),
+            left: resolveAxis(JOYSTICK_AXES.left, axis !== "vertical"),
+            right: resolveAxis(JOYSTICK_AXES.right, axis !== "vertical"),
         };
         joystick = axes.up === null && axes.down === null && axes.left === null && axes.right === null ? null : axes;
     }
@@ -123,12 +210,23 @@ 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, kind: touchButtonKind(spec) }
+            ? {
+                action: spec,
+                label: touchActionLabel(spec),
+                icon: null,
+                kind: touchButtonKind(spec),
+                shape: touchButtonShape(spec),
+                anchor: null,
+                image: null,
+            }
             : {
                 action: spec.action,
                 label: spec.label ?? touchActionLabel(spec.action),
                 icon: spec.icon ?? null,
                 kind: spec.kind ?? touchButtonKind(spec.action),
+                shape: spec.shape ?? touchButtonShape(spec.action),
+                anchor: spec.anchor ?? null,
+                image: spec.image ?? null,
             });
     }
     else {
@@ -137,8 +235,17 @@ export function deriveTouchScheme(input, { reserved, firstPerson, config }) {
             .filter((action) => !isHotbarSlotAction(action))
             .filter((action) => !consumedByGestures.has(action))
             .filter((action) => !hidden.has(action))
+            .filter((action) => !LIFECYCLE_ACTIONS.has(action))
             .filter((action) => !reserved.has(action) || BUTTONABLE_RESERVED.has(action))
-            .map((action) => ({ action, label: touchActionLabel(action), icon: null, kind: touchButtonKind(action) }));
+            .map((action) => ({
+            action,
+            label: touchActionLabel(action),
+            icon: null,
+            kind: touchButtonKind(action),
+            shape: touchButtonShape(action),
+            anchor: null,
+            image: null,
+        }));
     }
     const look = config?.look ?? firstPerson;
     if (joystick === null && buttons.length === 0 && gestures === null && !look)
@@ -149,5 +256,11 @@ export function deriveTouchScheme(input, { reserved, firstPerson, config }) {
         gestures,
         look,
         lookSensitivity: config?.lookSensitivity ?? DEFAULT_LOOK_SENSITIVITY,
+        layout: {
+            movement: config?.layout?.movement ?? DEFAULT_TOUCH_LAYOUT.movement,
+            actions: config?.layout?.actions ?? DEFAULT_TOUCH_LAYOUT.actions,
+            utility: config?.layout?.utility ?? DEFAULT_TOUCH_LAYOUT.utility,
+        },
+        style: config?.style ?? DEFAULT_TOUCH_STYLE,
     };
 }

package/dist/interaction/lockpick.d.ts

@@ -0,0 +1,61 @@
+/** One discrete pick move: how far the pick drives into the lock this step. */
+export type LockAction = "hardSet" | "set" | "steady" | "ease" | "drop";
+/** Vertical row delta applied to the pick for each action. Row 0 is the shallow/top row. */
+export declare const LOCK_ACTION_DELTA: Readonly<Record<LockAction, number>>;
+/** The five pick actions, in display order (shallow → deep). */
+export declare const LOCK_ACTIONS: readonly LockAction[];
+/** Difficulty dials for one lock: board size, forgiveness band, gates, fog window, traps. */
+export interface LockTierSpec {
+    cols: number;
+    rows: number;
+    width: number;
+    gateCount: number;
+    visibilityWindow: number;
+    allowedActions: readonly LockAction[];
+    trapCount?: number;
+}
+/** A generated lock board. `open[col]` holds every enterable row in that column. */
+export interface LockSpec {
+    seed: string | number;
+    tier: LockTierSpec;
+    open: readonly (readonly number[])[];
+    gates: readonly number[];
+    traps: readonly (readonly number[])[];
+    startRow: number;
+    seatRow: number;
+}
+/** Outcome of one {@link stepLock} call: `advanced`/`success` move the pick, `slip`/`bind`/`trap`
+ * do not and should cost a life. */
+export type LockStepResult = "advanced" | "slip" | "bind" | "trap" | "success";
+/** What a revealed cell renders as: a plain open notch, an exact tumbler gate, the bolt seat
+ * (win condition), or a ward-trap that looks open but jams on contact. */
+export type LockCellKind = "open" | "gate" | "seat" | "trap";
+/** One cell inside the fogged {@link visibleCells} window: its board position and kind. */
+export interface LockCell {
+    col: number;
+    row: number;
+    kind: LockCellKind;
+}
+/**
+ * Generate a solvable depth-puzzle lock: a "Tumbler's Path" board with a guaranteed solution
+ * path carved first, an open-row forgiveness band wrapped around it, tumbler gate columns that
+ * pinch to a single exact row, and optional ward-traps that look open but jam on contact.
+ * Deterministic: the same (seed, tier) always yields the same board.
+ *
+ * @capability lockpick a solvable grid depth-puzzle with fog-of-war, gates, and hidden traps
+ */
+export declare function generateLock(seed: string | number, tier: LockTierSpec): LockSpec;
+/** Return a concrete row-per-column solution, or null if the board is unsolvable. */
+export declare function solveLockPath(spec: LockSpec): number[] | null;
+/** Whether the board has a path from the start row to the bolt seat at all. */
+export declare function solveLock(spec: LockSpec): boolean;
+/** Authoritative single step. The caller owns the lives economy: a slip/bind/trap does not
+ * advance the pick and should cost a life; advanced/success move the pick. */
+export declare function stepLock(spec: LockSpec, col: number, row: number, action: LockAction): {
+    result: LockStepResult;
+    col: number;
+    row: number;
+};
+/** The render-safe slice: every open cell in columns [0, col + window]. The single source of
+ * truth for fog and the anti-cheat boundary — never serialize the full spec to a client. */
+export declare function visibleCells(spec: LockSpec, col: number, window: number): LockCell[];